Skip to content

Commit

Permalink
Moved the functions section to a less obscure place
Browse files Browse the repository at this point in the history
  • Loading branch information
Knetic committed Nov 5, 2016
1 parent b3403e3 commit 0d12d7b
Showing 1 changed file with 28 additions and 29 deletions.
57 changes: 28 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,34 @@ Or you can use backslashes to escape only the minus sign.

Backslashes can be used anywhere in an expression to escape the very next character. Square bracketed parameter names can be used instead of plain parameter names at any time.

Functions
--

You may have cases where you want to call a function on a parameter during execution of the expression. Perhaps you want to aggregate some set of data, but don't know the exact aggregation you want to use until you're writing the expression itself. Or maybe you have a mathematical operation you want to perform, for which there is no operator; like `log` or `tan` or `sqrt`. For cases like this, you can provide a map of functions to `NewEvaluableExpressionWithFunctions`, which will then be able to use them during execution. For instance;

```go
functions := map[string]govaluate.ExpressionFunction {
"strlen": func(args ...interface{}) (interface{}, error) {
length := len(args[0].(string))
return (float64)(length), nil
},
}

expString := "strlen('someReallyLongInputString') <= 16"
expression, _ := govaluate.NewEvaluableExpressionWithFunctions(expString, functions)

result, _ := expression.Evaluate(nil)
// result is now "false", the boolean value
```

Functions can accept any number of arguments, correctly handles nested functions, and arguments can be of any type (even if none of this library's operators support evaluation of that type). For instance, each of these usages of functions in an expression are valid (assuming that the appropriate functions and parameters are given):

```go
"sqrt(x1 ** y1, x2 ** y2)"
"max(someValue, abs(anotherValue), 10 * lastValue)"
```

Functions cannot be passed as parameters, they must be known at the time when the expression is parsed, and are unchangeable after parsing.

What operators and types does this support?
--
Expand Down Expand Up @@ -178,35 +206,6 @@ It may, at first, not make sense why a Date supports all the same things as a nu

Complex types, arrays, and structs are not supported as literals nor parameters. All numeric constants and variables are converted to float64 for evaluation.

Functions
--

You may have cases where you want to call a function on a parameter during execution of the expression. Perhaps you want to aggregate some set of data, but don't know the exact aggregation you want to use until you're writing the expression itself. Or maybe you have a mathematical operation you want to perform, for which there is no operator; like `log` or `tan` or `sqrt`. For cases like this, you can provide a map of functions to `NewEvaluableExpressionWithFunctions`, which will then be able to use them during execution. For instance;

```go
functions := map[string]govaluate.ExpressionFunction {
"strlen": func(args ...interface{}) (interface{}, error) {
length := len(args[0].(string))
return (float64)(length), nil
},
}

expString := "strlen('someReallyLongInputString') <= 16"
expression, _ := govaluate.NewEvaluableExpressionWithFunctions(expString, functions)

result, _ := expression.Evaluate(nil)
// result is now "false", the boolean value
```

Functions can accept any number of arguments, correctly handles nested functions, and arguments can be of any type (even if none of this library's operators support evaluation of that type). For instance, each of these usages of functions in an expression are valid (assuming that the appropriate functions and parameters are given):

```go
"sqrt(x1 ** y1, x2 ** y2)"
"max(someValue, abs(anotherValue), 10 * lastValue)"
```

Functions cannot be passed as parameters, they must be known at the time when the expression is parsed, and are unchangeable after parsing.

Benchmarks
--

Expand Down

0 comments on commit 0d12d7b

Please sign in to comment.