v0.2.6 use ErrorCases; Add comments; Add tests; API changed.

Author: LEXUGE

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "lib_xch"
-version = "0.2.4"
+version = "0.2.6"
 authors = ["LEXUGE <LEXUGEyky@outlook.com>"]
 description = "Crate xch-ceb's official lib"
 license = "GPL-3.0"

Cargo.toml

@@ -19,6 +19,8 @@ use std::vec::Vec;
 use std::i32;
 // inside uses
 use structs::ChemicalEquation;
+use handler::ErrorCases;
+use handler::ErrorCases::I32Overflow;
 
 pub fn xch_try(
     f: i32,
@@ -27,7 +29,7 @@ pub fn xch_try(
     list: &[Vec<i32>],
     chmcl_f_sut: &ChemicalEquation,
     len: usize,
-) -> Result<bool, String> {
+) -> Result<bool, ErrorCases> {
     if f == chmcl_f_sut.sum + 1 {
         match check(traversal, list, chmcl_f_sut, len) {
             Ok(true) => return Ok(true),
@@ -53,7 +55,7 @@ fn check(
     list: &[Vec<i32>],
     chmcl_f_sut: &ChemicalEquation,
     len: usize,
-) -> Result<bool, String> {
+) -> Result<bool, ErrorCases> {
     let mut tmp1: i32;
     let mut tmp2: i32;
     for item in list.iter().take(len + 1).skip(1) {
@@ -63,22 +65,22 @@ fn check(
             let tmp: i32;
             tmp = match item[j].checked_mul(traversal[j - 1]) {
                 Some(s) => s,
-                None => return Err("[ERROR] i32 overflow".to_string()),
+                None => return Err(I32Overflow),
             };
             tmp1 = match tmp1.checked_add(tmp) {
                 Some(s) => s,
-                None => return Err("[ERROR] i32 overflow".to_string()),
+                None => return Err(I32Overflow),
             };
         }
         for j in chmcl_f_sut.left_num as usize + 1..chmcl_f_sut.sum as usize + 1 {
             let tmp: i32;
             tmp = match item[j].checked_mul(traversal[j - 1]) {
                 Some(s) => s,
-                None => return Err("[ERROR] i32 overflow".to_string()),
+                None => return Err(I32Overflow),
             };
             tmp2 = match tmp2.checked_add(tmp) {
                 Some(s) => s,
-                None => return Err("[ERROR] i32 overflow".to_string()),
+                None => return Err(I32Overflow),
             };
         }
         if tmp1 != tmp2 {

src/balancer_mod.rs

@@ -23,9 +23,10 @@ use balancer_mod::xch_try;
 ///
 /// # Panics
 ///
-/// The equation you provided should be a common unbalanced chemical equation which only contains **one** `+`.
-/// In following cases, API will **panic**:
-/// 1.Stack Overflow may cause panic too. Because it is using recusive balancer and regex-based parser.
+/// The equation you provided should be a common unbalanced chemical equation which only contains **one** `=`.
+///
+/// -  Stack Overflow may cause **panic**. Because it is using recusive balancer and regex-based parser.
+///
 /// And in the other failed situation, it'll return a `error_message` and contain `parser_result`(maybe it is empty).
 pub fn handler_api(equation: &str, searching_range: i32) -> Result<Vec<i32>, ErrorHandler> {
     // T is successful traversal vector, E is list vector which parser returned.
@@ -52,7 +53,7 @@ pub fn handler_api(equation: &str, searching_range: i32) -> Result<Vec<i32>, Err
     ) {
         Ok(true) => Ok(traversal),
         Ok(false) => Err(ErrorHandler {
-            error_message: "No answer".to_string(),
+            error_message: ErrorCases::NoAnswer,
             parser_result: list,
         }),
         Err(s) => Err(ErrorHandler {
@@ -65,6 +66,28 @@ pub fn handler_api(equation: &str, searching_range: i32) -> Result<Vec<i32>, Err
 /// `ErrorHandler` returns when `handler::handler_api` failed somehow.
 /// **CAUTION: `parser_result` might empty if parser is failed.**
 pub struct ErrorHandler {
-    pub error_message: String,
+    pub error_message: ErrorCases,
     pub parser_result: Vec<Vec<i32>>,
 }
+
+/// All the Error Types.
+///
+/// -  more or less than 1 `=`; not allowed chars; too many formulas.
+/// -  i32 overflow.
+/// -  brackets are not matched.
+/// -  no formulas to split.
+/// -  no tokens to get.
+/// -  not found in `elements_table`.
+/// -  no answer.
+/// -  Can't parse into i32.
+#[derive(PartialEq, Debug)]
+pub enum ErrorCases {
+    IllegalEquation,
+    I32Overflow,
+    MatchError,
+    SplitError,
+    NoTokens,
+    NotFound,
+    NoAnswer,
+    I32ParseError,
+}

src/handler.rs

@@ -13,6 +13,17 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+// Documentation
+//! This is the official library of xch-ceb.
+//! It can parse and balance *the Chemical Equation*.
+//!
+//! -  Unlimited brackets
+//! -  No Periodic table of the elements needed
+//!
+//! # Getting Started
+//!
+//! Just use the `handler_api`: ``lib_xch::handler::handler_api("H2O=H2+O2", 10);``
+
 // extern crate(s)
 #[macro_use]
 extern crate lazy_static;

src/lib.rs

@@ -15,24 +15,28 @@
 
 // Overall: This is the source code of the Delta-3 Parser.
 
-pub fn legal_check(equation: &str) -> Result<bool, String> {
+// inside uses
+use handler::ErrorCases;
+use handler::ErrorCases::{IllegalEquation, MatchError};
+
+pub fn legal_check(equation: &str) -> Result<bool, ErrorCases> {
     let equation = equation.chars().into_iter().collect::<Vec<_>>();
     let mut tmp = 0;
     for i in equation {
         if check_char(i) == 0 {
-            return Err("[ERROR] Illegal Equation!".to_string());
+            return Err(IllegalEquation);
         }
         if i == '=' {
             tmp += 1;
         }
     }
     if tmp != 1 {
-        return Err("[ERROR] Illegal Equation!".to_string());
+        return Err(IllegalEquation);
     }
     Ok(true)
 }
 
-pub fn legal_check_brackets(formula: &str) -> Result<bool, String> {
+pub fn legal_check_brackets(formula: &str) -> Result<bool, ErrorCases> {
     let formula = formula.chars().into_iter().collect::<Vec<_>>();
     for i in 0..formula.len() {
         if formula[i] == '(' {
@@ -45,7 +49,7 @@ pub fn legal_check_brackets(formula: &str) -> Result<bool, String> {
     Ok(true)
 }
 
-fn brackets_matcher(formula: &[char], pos: usize, mode: bool) -> Result<usize, String> {
+fn brackets_matcher(formula: &[char], pos: usize, mode: bool) -> Result<usize, ErrorCases> {
     let mut fake_stack = 0;
 
     if mode {
@@ -75,7 +79,7 @@ fn brackets_matcher(formula: &[char], pos: usize, mode: bool) -> Result<usize, S
             }
         }
     }
-    Err("[ERROR] Can't match!".to_string())
+    Err(MatchError)
 }
 
 fn check_char(test: char) -> i32 {

src/parser_mod/legal_check_util.rs

@@ -27,8 +27,10 @@ use std::i32;
 use structs::ChemicalEquation;
 use self::parser_struct::{FormulaDesc, TableDesc, TokenDesc};
 use self::legal_check_util::{legal_check, legal_check_brackets};
+use handler::ErrorCases;
+use handler::ErrorCases::{I32Overflow, I32ParseError, IllegalEquation, NoTokens, SplitError};
 
-pub fn xch_parser(equation: &str) -> Result<(ChemicalEquation, usize, Vec<Vec<i32>>), String> {
+pub fn xch_parser(equation: &str) -> Result<(ChemicalEquation, usize, Vec<Vec<i32>>), ErrorCases> {
     legal_check(equation)?;
     let mut chemical_equation_struct = ChemicalEquation {
         left_num: 0,
@@ -68,18 +70,18 @@ pub fn xch_parser(equation: &str) -> Result<(ChemicalEquation, usize, Vec<Vec<i3
     ))
 }
 
-fn parser_get_sum(equation: &str) -> Result<i32, String> {
+fn parser_get_sum(equation: &str) -> Result<i32, ErrorCases> {
     let mut sum: i32 = 0;
     for _ in equation.split('+') {
         sum = match sum.checked_add(1) {
             Some(s) => s,
-            None => return Err("[ERROR] i32 overflow: Illegal Equation!".to_string()),
+            None => return Err(IllegalEquation),
         }
     }
     Ok(sum)
 }
 
-fn part_parser(equation: &str, table: &mut TableDesc, begin: i32) -> Result<i32, String> {
+fn part_parser(equation: &str, table: &mut TableDesc, begin: i32) -> Result<i32, ErrorCases> {
     let mut sum = begin;
     for formula in equation.split('+') {
         sum += 1;
@@ -89,14 +91,14 @@ fn part_parser(equation: &str, table: &mut TableDesc, begin: i32) -> Result<i32,
     Ok(sum - begin)
 }
 
-fn formula_spliter(target: &str) -> Result<Vec<FormulaDesc>, String> {
+fn formula_spliter(target: &str) -> Result<Vec<FormulaDesc>, ErrorCases> {
     let mut v: Vec<FormulaDesc> = Vec::new();
     lazy_static! {
         static ref RE: Regex = Regex::new(r"\((([A-Z][a-z]*(\d+)*)+)\)(\d+)*").unwrap();
     }
 
     if !RE.is_match(target) {
-        return Err("[ERROR] No more to split!".to_string());
+        return Err(SplitError);
     }
     for cap in RE.captures_iter(target) {
         let mut times: i32;
@@ -106,7 +108,7 @@ fn formula_spliter(target: &str) -> Result<Vec<FormulaDesc>, String> {
         } else {
             times = match cap4.trim().parse::<i32>() {
                 Ok(s) => s,
-                Err(_) => return Err("[ERROR] Not a number!".to_string()),
+                Err(_) => return Err(I32ParseError),
             }
         }
         v.push(FormulaDesc {
@@ -118,13 +120,13 @@ fn formula_spliter(target: &str) -> Result<Vec<FormulaDesc>, String> {
     Ok(v)
 }
 
-fn get_token(target: &str) -> Result<Vec<TokenDesc>, String> {
+fn get_token(target: &str) -> Result<Vec<TokenDesc>, ErrorCases> {
     let mut v: Vec<TokenDesc> = Vec::new();
     lazy_static! {
         static ref RE: Regex = Regex::new(r"([A-Z][a-z]*)(\d+)*").unwrap();
     }
     if !RE.is_match(target) {
-        return Err("[ERROR] No tokens!".to_string());
+        return Err(NoTokens);
     }
     for cap in RE.captures_iter(target) {
         let cap2 = cap.get(2).map_or("", |m| m.as_str());
@@ -134,7 +136,7 @@ fn get_token(target: &str) -> Result<Vec<TokenDesc>, String> {
         } else {
             times = match cap2.trim().parse::<i32>() {
                 Ok(s) => s,
-                Err(_) => return Err("[ERROR] Not a number!".to_string()),
+                Err(_) => return Err(I32ParseError),
             }
         }
         v.push(TokenDesc {
@@ -145,12 +147,12 @@ fn get_token(target: &str) -> Result<Vec<TokenDesc>, String> {
     Ok(v)
 }
 
-fn mul_phrase(phrase: &FormulaDesc) -> Result<String, String> {
+fn mul_phrase(phrase: &FormulaDesc) -> Result<String, ErrorCases> {
     let mut v = get_token(&phrase.formula_self)?;
     for token in &mut v {
         token.times = match token.times.checked_mul(phrase.times) {
             Some(s) => s,
-            None => return Err("[ERROR] i32 overflow".to_string()),
+            None => return Err(I32Overflow),
         }
     }
     let mut s: String = String::new();
@@ -170,10 +172,11 @@ fn parser_formula(
     formula: &str,
     table: &mut TableDesc,
     location: usize,
-) -> Result<bool, String> {
+) -> Result<bool, ErrorCases> {
     let formula_backup = formula;
     let mut formula = format!("({})", formula_backup);
 
+    formula_spliter(&formula)?;
     while formula_spliter(&formula).is_ok() {
         for p in formula_spliter(&formula)? {
             formula = replace_phrase(&formula, &p.all, &(mul_phrase(&p)?));

src/parser_mod/mod.rs

@@ -17,7 +17,9 @@
 
 // inside uses
 use structs::ElementStruct;
-use parser_mod::get_token;
+use super::get_token;
+use handler::ErrorCases;
+use handler::ErrorCases::{I32Overflow, NotFound};
 
 pub struct FormulaDesc {
     pub formula_self: String,
@@ -38,7 +40,7 @@ pub struct TableDesc {
 }
 
 impl TableDesc {
-    pub fn store_in_table(&mut self, formula: &str, location: usize) -> Result<bool, String> {
+    pub fn store_in_table(&mut self, formula: &str, location: usize) -> Result<bool, ErrorCases> {
         for t in get_token(formula)? {
             if !self.find_element_in_table(&t.token_name).is_ok() {
                 let len = self.elements_table.len();
@@ -54,7 +56,7 @@ impl TableDesc {
                 let tmp = self.find_element_in_table(&t.token_name)?; // It have been checked.
                 self.list[tmp][location] = match self.list[tmp][location].checked_add(t.times) {
                     Some(s) => s,
-                    None => return Err("[ERROR] i32 overflow".to_string()),
+                    None => return Err(I32Overflow),
                 }
             }
         }
@@ -91,12 +93,12 @@ impl TableDesc {
         v
     }
 
-    fn find_element_in_table(&self, target: &str) -> Result<usize, String> {
+    fn find_element_in_table(&self, target: &str) -> Result<usize, ErrorCases> {
         for i in &(self.elements_table) {
             if i.name == *target {
                 return Ok(i.num);
             }
         }
-        Err("[ERROR] Not found!".to_string())
+        Err(NotFound)
     }
 }