Using the Function Data Type

Define an expression language function with the following function literal syntax:

function label (arg1 T, arg2 T, ...) -> returnType { body }

Parentheses enclose the list of arguments for this function. Braces enclose the body of the function definition.

The label for the function is its optional internal name. You can use the optional label to document the purpose of the function. The label is only required if the function being defined calls itself recursively. This is the case in the formula to emit the nth member of the Fibonacci series shown here:

function fib (n int) -> int {if n <= 1 then n else fib(n-1) + fib(n-2)}

When used as a recursion name, the label has scope only within that function.

In the usual case, a defined function's return type is the same for all output values. Thus, the usual syntax is without the optional returnType argument:

function label (arg1 T, arg2 T, ...) { body }

If you do specify a return data type prefixed by the two characters "->", that data type must be compatible with the function's output. If you leave out the returnType argument, StreamBase determines the return type based on what the expression body does to its inputs. For further details, see Data Type Coercion and Conversion.

The function body contains a valid StreamBase expression, such as the following, which accepts a double value, the temperature in Celsius degrees, and returns the same temperature on the Fahrenheit scale:

function (c double) { round( c * 9/5 + 32 , 2) }

The names you assign to arguments do not need to be used in the function body, but if so, they must be the exact same names. Do not try to assign different names for the same value as an argument and in the function body. (However, you can @define new names in the function body as described below.)

You can have multiple expressions inside a function body, with each line terminated by a semicolon. A semicolon after the last statement is allowed but ignored. The return value of the function is that of the last expression on the block. For example:

function (a int, b int) {
  /* First define the sq() and 
     sumsq() internal functions */
  @define (function (y int) { y * y } as sq);
  @define (function (c int, d int) { sq(c) + sq(d) } as sumsq);
  sumsq(a, b) --Final semicolon is allowed but not required
} 

As shown above, you can use either C-style comments on one or more lines or legacy StreamBase double-hyphen comments which are valid to the end of their line. These are the standard comment styles for the StreamBase expression language.

The Evaluate StreamBase Expression dialog is especially useful when defining functions. Open the dialog with Help>Evaluate StreamBase Expression to experiment with your function definition syntax until the dialog confirms it is valid. When the Evaluator approves, you can copy your function and paste it into the context where you will define it.

The Evaluator accepts the full multiline syntax for function definitions, and recognizes comments. As an example, copy the entire last example from the previous section into the Evaluator and click Evaluate. When a function definition is valid, the Evaluator shows you a Result line, and it restates the entire expression on a single line, adding return values and other assumed values.

You can provide arguments to expressions in the Evaluator to see your function expression in action, without having to start and run an EventFlow fragment. Just add the number and type of values that the expression expects, enclosed by parentheses and placed after the close-brace of the expression definition. When you click Evaluate, this time the Evaluator runs your expression with the provided values, and shows the calculated result.

For the last example of the previous section copied and pasted into the Evaluator, add (2,3) to the end of the function definition. The Evaluator returns 13. Provide any two other integers to confirm that the function works as expected.

For functions that accept function arguments, you can provide a function literal as an argument within parentheses.

StreamBase maintains function definitions internally as JSON strings. You may see the JSON format for function definitions:

If your application requires it, you can define functions in JSON format. For assistance, see the tojson(), parsejson(), parsejson_loose(), and jsonpath() expression language functions.

For example, the function literal for the Celsius to Fahrenheit function shown earlier could be defined with the following JSON string.

{"function_definition":"function (c double) { round( c * 9/5 + 32 , 2) }"}

You can define functions in the following places in StreamBase Studio:

The Studio Function Data Type Sample provides a module with these definitions that you can load, run, and modify.

By what name do you invoke a defined function to run it? That depends on where you defined it:

Remember that function is a first-class data type in StreamBase. Therefore, anything you can do with a value of any data type you can do with function. You can send it downstream as the value of a tuple field. You can enqueue it and dequeue it. You can send it across local and remote StreamBase container connections. This is why we do not describe functions themselves as having scope. What the function is a value of (a constant, a field, a dynamic variable) can be said to have scope, but the instance of type function itself can flow with any tuple that contains it.

You can use expression language functions within and as arguments to other functions, as long as they accept and emit compatible data types.

You can call most built-in expression language functions as needed in your function body. The following shows Binet's alternative, non-recursive formula to calculate the nth member of the Fibonacci series:

function (n int) {round((1/sqrt(5))*(pow((1+sqrt(5))/2,n)-pow((1-sqrt(5))/2,n)))}

For example, in a module with the constant fib defined with this function literal, you can define a different function to compute the difference between a specified Fibonacci number and its immediate predecessor:

function fibdiff (n int) {fib(n)-fib(n-1)}

You can use the defined function as an argument for a built-in function:

sqrt(fib(n))

For simple data types, declaring the type of arguments or returns is straightforward: just specify the name of the type.

function to_fahrenheit(cels double) -> double { (9/5 * cels) + 32 }

To specify a tuple as an argument, specify its schema in parenthesized name type pairs, separated by commas. (This is the format for defining a schema in the legacy StreamSQL language.) Do not use the AS keyword that would be used with the tuple() constructor. For example:

function foo (tpl (a int, b string)) { tpl.a }

You can use the name of a named schema as an argument of type tuple:

function foo (localname namedschm, n int) {localname.fieldname + n}

To specify a list as an argument, use the keyword list followed by the list's type in parentheses:

function foo (myl list (int)) { myl[0] + myl[1] }

The following example shows a list of tuples, where each tuple has the schema a int, b string:

function foo (myl list ((a int, b string))) { unzip(myl) }

The following argument is a tuple whose schema is a list of int plus an int:

function foo (lint (a list(int), b int)) { lint.a[lint.b] }

In the following, foo()'s argument is a function, one that takes an int and returns a double. The inner function innerf has no body declaration; therefore this argument is expected to be substituted at runtime with the name of a function defined elsewhere that takes an int and returns a double.

function foo (innerf (a int)->double) { double() }

For example, if the Definitions tab defines a constant whose name is doublet and whose value is the line above, and also defines a function named convert() that takes an int and returns a double, then doublet() could be run as:

doublet(convert())

Notice that the difference between specifying a tuple argument and a function argument is that the latter has its return type explicitly defined:

You can chain functions together in a way that can challenge your problem-solving skills. For example:

function noway (arg (a int)->(b double)->(c string)->int)->string {"do-work"}

This very unlikely definition of noway():

In this section, arg is used only an example of an argument name, and is not a keyword in any way.

There are two annotations associated with function definitions, @cacheable and @define.

The following simple functions in the expression language, sometimes called higher order functions, allow or require passing in a function as one of their arguments to manipulate single or multiple lists.

In addition, sort() has a syntax that accepts a custom comparison function to sort a single list.

In the following example, the foldleft() function passes in a function that adds a list of ints to the initial value 10:

foldleft(function addVals(a int, b int) { a+b }, 10, list(1, 2, 3, 4, 5, 6))

This returns 31.

Remember that the label addVals is optional, but can add some clarity. The same invocation of foldleft() works without the label:

foldleft(function (a int, b int) { a+b }, 10, list(1, 2, 3, 4, 5, 6))

The argument of type function can be a built-in function, a field with data type function, a constant whose value is a function from the Definitions tab, or a function literal. Function literals start with the function keyword and use the syntax shown in the first section above. You can pass custom Java functions to these functions using function aliases that you declare in a configuration file.

Input functions to these higher order functions must obey certain rules:

The expression language's compile() function takes a string that defines an expression and a tuple that defines that expression's arguments and emits an executable function at runtime. The return type of compile() is the function data type, which can be passed downstream to other components as described on this page.

The first argument of compile() is equivalent to the {body} of a function literal. Thus, you can use compile() like the following example:

compile( "(fahr_temp - 32) * 1.8", tuple(double() as fahr_temp), double() )

Read more about compile() in its section of the Expression Language Functions page.

Functions are traditionally used anywhere in the middle of an EventFlow module, between the Input Stream and Output Stream (or adapters). However, it is possible to configure an Input Stream having a field with the function data type, and pass a function to it along with other input fields.

Follow the steps of this extended example to configure one field of an input stream with a name and the function data type:

Back to Top ^