Document toplevel functions

Implements #6
This commit is contained in:
Sebastian Schmidt 2019-03-19 20:24:03 +02:00
parent 4a32062089
commit 6fe5a8cdef

View File

@ -222,10 +222,36 @@ pub use function::Function;
pub use tree::Node; pub use tree::Node;
pub use value::Value; pub use value::Value;
/// Evaluate the given expression string.
///
/// # Examples
///
/// ```rust
/// use evalexpr::*;
///
/// assert_eq!(eval("1 + 2 + 3"), Ok(Value::from(6)));
/// ```
///
/// *See the [crate doc](index.html) for more examples and explanations of the expression format.*
pub fn eval(string: &str) -> Result<Value, Error> { pub fn eval(string: &str) -> Result<Value, Error> {
tree::tokens_to_operator_tree(token::tokenize(string)?)?.eval(&EmptyConfiguration) tree::tokens_to_operator_tree(token::tokenize(string)?)?.eval(&EmptyConfiguration)
} }
/// Evaluate the given expression string with the given configuration.
///
/// # Examples
///
/// ```rust
/// use evalexpr::*;
///
/// let mut configuration = HashMapConfiguration::new();
/// configuration.insert_variable("one", 1);
/// configuration.insert_variable("two", 2);
/// configuration.insert_variable("three", 3);
/// assert_eq!(eval_with_configuration("one + two + three", &configuration), Ok(Value::from(6)));
/// ```
///
/// *See the [crate doc](index.html) for more examples and explanations of the expression format.*
pub fn eval_with_configuration( pub fn eval_with_configuration(
string: &str, string: &str,
configuration: &Configuration, configuration: &Configuration,
@ -233,6 +259,30 @@ pub fn eval_with_configuration(
tree::tokens_to_operator_tree(token::tokenize(string)?)?.eval(configuration) tree::tokens_to_operator_tree(token::tokenize(string)?)?.eval(configuration)
} }
/// Build the operator tree for the given expression string.
///
/// The operator tree can later on be evaluated directly.
/// This saves runtime if a single expression should be evaluated multiple times, for example with differing configurations.
///
/// # Examples
///
/// ```rust
/// use evalexpr::*;
///
/// let precomputed = build_operator_tree("one + two + three").unwrap();
///
/// let mut configuration = HashMapConfiguration::new();
/// configuration.insert_variable("one", 1);
/// configuration.insert_variable("two", 2);
/// configuration.insert_variable("three", 3);
///
/// assert_eq!(precomputed.eval(&configuration), Ok(Value::from(6)));
///
/// configuration.insert_variable("three", 5);
/// assert_eq!(precomputed.eval(&configuration), Ok(Value::from(8)));
/// ```
///
/// *See the [crate doc](index.html) for more examples and explanations of the expression format.*
pub fn build_operator_tree(string: &str) -> Result<Node, Error> { pub fn build_operator_tree(string: &str) -> Result<Node, Error> {
tree::tokens_to_operator_tree(token::tokenize(string)?) tree::tokens_to_operator_tree(token::tokenize(string)?)
} }