StreamBase Expression Language Functions

Function syntax:

blob addbson(blob bsonblob-array, T element)

Adds a new field at the end of a BSON array. Accepts a BSON blob that contains an array and an element to be appended to it. element can be of any type compatible with the contents of the array bsonblob-array. Returns a BSON object for the expanded array.

Back to Top ^

Function syntax:

string bsontojson(blob bsonblob)

Converts BSON blob to JSON-formatted string. Accepts one BSON blob and returns its contents as a JSON object of key-value pairs.

Back to Top ^

Function syntax:

blob findbson(blob bsonblob, int index)
blob findbson(blob bsonblob, string fieldname)

Searches a BSON object for a specified array index or field name. Accepts a BSON blob assumed to contain either a BSON array or a BSON object and an index into the array or a string that should match a field name. Returns a blob containing the found field or throws an error if not found or index is out of bounds. index is a zero-based index. fieldname is a string, interpreted as a field name.

Back to Top ^

Function syntax:

T frombson(blob bsonblob, T type)

Converts a BSON blob to the requested StreamBase type. Accepts one BSON blob and returns its contents as the requested StreamBase type. The second argument provides an example of the return type and is not evaluated. If the type does not match, throws an error.

Back to Top ^

Function syntax:

blob joinbson(list(blob) L)

Concatenates a list of BSON fields into a BSON object. Accepts a list of BSON blobs containing fields and concatenates them. If the list argument is empty, returns an empty blob. If the list is null, returns null. To test for null blobs, use the isnull function. You can use splitbson to create a list of BSON fields.

Back to Top ^

Function syntax:

blob jsontobson(string jsonstring)

Converts a JSON string to a BSON blob. Accepts one JSON string and returns its contents as a BSON blob. The argument jsonstring is any JSON string. For example:

jsontobson('{"symbol":"IBM","price":75.91,"quantity":150, "date":"2013-04-28 16:00:00.000-0400"}')

Back to Top ^

Function syntax:

int lenbson(blob bsonblob)

Returns the length of a BSON object or array.

If bsonblob contains an array, returns the number of elements in it.

If bsonblob is an object, returns the number of fields in it.

If bsonblob is any other scalar type, throws an error.

Back to Top ^

Function syntax:

blob listbson(T1 value1, T2 value2, ... Tn valuen)

Accelerator for constructing a (possibly heterogeneous) BSON array, similar to a StreamBase list. Accepts any number of arguments and returns a BSON array containing them. Values are individually interpreted by tobson and can be of any type.

Back to Top ^

Function syntax:

string namebson(blob bsonblob)

Returns the name of a BSON field

If bsonblob is a BSON field, returns the field name, otherwise returns an empty string.

Back to Top ^

Function syntax:

blob putbson(blob bsonblob-object, string name, T value)

Adds a new field to a BSON object. Returns the blob bsonblob-object with added field name having value value. If field name already exists, its current value is replaced with value.

Back to Top ^

Function syntax:

blob removebson(blob bson-list,
                int element-index1, ... int element-indexN)
blob removebson(blob bson-tuple,
                int element-index1|string fieldname1, ...
                int element-index2|string fieldnameN) 

Removes fields or list elements from BSON blobs. The BSON blob can contain an array or an object. A blob is returned with fields or elements that match the specified element-index or fieldname arguments removed. Fields can be removed from objects by index or field name.

The order of indexes and names in arguments does not matter. Any out-of-bounds indexes and non-matching field names are ignored.

Back to Top ^

Function syntax:

list splitbson(blob bsonblob-containing-list)
list splitbson(blob bsonblob-containing-object) 

Returns a list of BSON fields from a BSON object or a list of BSON values from a BSON array. Use frombson to convert individual returned values to StreamBase types.

Back to Top ^

Function syntax:

string stringbson(blob bsonblob-string)

Converts a BSON blob to a string. The BSON blob must contain one string. Unlike the string function, no type conversion is performed.

Back to Top ^

Function syntax:

blob tobson(T arg)

Converts StreamBase values to a BSON blob. Each StreamBase int, long, double, string, timestamp, and blob maps to a respective BSON type, nulls map to nulls, lists map to BSON arrays, and tuples map to BSON objects.

Back to Top ^

Function syntax:

blob tuplebson(AS-expr1, AS-expr2, ... AS-exprN)

Accelerator for constructing a BSON object from comma-separated AS expressions (comma-separated value expressions, each field named with the AS keyword). The resulting blob contains an object having the specified fields and values.

The following example creates a BSON object with three fields:

tuplebson("IBM" AS symbol, 87.3875 AS price, 47 AS quantity)

Back to Top ^

Function syntax:

T catchexception(T arg1 [, ... [, T argn]])

Attempts to evaluate all arguments in order, returning the first one that evaluates without an error, or null if all arguments evaluate to an error. Accepts all data types, but all arguments must have the same type. The returned value has the same data type, T, as the arguments.

For example, the following example attempts to parse str as an interval, but returns a null timestamp if parsing fails:

catchexception(interval(str))

The following example attempts to divide a by b, but returns -1 if the division fails:

catchexception(a/b, -1)

Back to Top ^

Function syntax:

bool error(string message)

Throws an error with message text message that can be caught using the StreamBase error streams mechanism. In the default configuration, this produces an error message on the console, and the server continues processing.

Because error() returns bool, it works well as a predicate expression in operators. For example, use error("Error condition") as the last predicate expression for a Filter operator to produce an error message when no earlier predicate expression was matched.

Back to Top ^

Function syntax:

T throw(string message)

Throws an error with message text message that can be caught using the StreamBase error streams mechanism. In the default configuration, this produces an error message on the console, and the server continues processing.

Because throw() returns an untyped null by default, it works well in if statements. For example: if (test-expr) then (5) else throw("Failed the test")

For the purposes of typechecking, cast the return of this function with one of the casting functions. For example, use bool(throw("Unmatched filter option")) as the last predicate expression of a Filter operator to produce an error message when no earlier predicate expression was matched.

Back to Top ^

Function syntax:

T callcpp(string class [, arg1 , ... [, argn]])

As an alternative to using callcpp(), you can define an alias for your custom functions. See Using Function Aliases.

Use an alias or callcpp() to run a custom C++ function directly from a StreamBase operator that uses an expression. The return type, T, of callcpp() is the same as the return type of the called function. Custom C++ functions are functions you build with the StreamBase C++ Client API. You can use the simple form of callcpp() in any expression except aggregate expressions. (To use callcpp() in aggregate expressions, refer to the aggregate callcpp().)

For callcpp() to locate the function being called, you must specify the location of the containing DLL or .so file, and must register the function with a <custom-function> element in the StreamBase Server configuration file. See C++ Function Overview for details.

To learn about coding custom C++ functions, refer to Creating Custom C++ Functions in the API Guide.

Back to Top ^

Function syntax:

T calljava(string class, string method [, arg1 , ..., argn])

As an alternative to using calljava, you can define an alias for your custom functions. See Using Function Aliases.

Use an alias or calljava() to run a custom Java function directly from a StreamBase operator that uses an expression. The return type, T, of calljava() is the same as the return type of the called function. Custom Java functions are functions you build with the StreamBase Java Client library. You can use the simple form of calljava() in any expression except aggregate expressions. (To use calljava() in aggregate expressions, refer to the aggregate calljava().)

You can also use calljava() (or an alias) to run any public function in any class on StreamBase Server's classpath, including standard library functions.

The calljava() function distinguishes simple from aggregate functions by the number of arguments. For custom simple functions, you must specify both class and method names. For custom aggregate functions, you specify only the class name.

To learn about coding custom Java functions, refer to Using the StreamBase Java Function Wizard in the API Guide. For information on the classpath requirements for custom Java functions, see Java Function Overview.

Function syntax:

double black_scholes(string type, double underlying, double strike, 
    double dividendYield, double riskFreeInterestRate, 
    double Volatility, timestamp exerciseDate [, timestamp dealDate])

The black_scholes function calculates fair-value and risk statistics (delta, gamma, vega) for European style options on securities with continuous dividend yields. This is known as the Black-Scholes Generalized model. It also calculates implied volatility.

The black_scholes function takes eight input arguments; the first seven arguments are required, while the eighth argument, dealDate, is optional.

The arguments are:

Back to Top ^

Function syntax:

double compound_interest(double principalValue, double matureValue, 
    double numberOfPeriods [, double guess])

Returns the compound interest given the principal value, mature value, and number of periods. An optional fourth argument, guess, can be used to set the initial compound interest used by the function. The compound_interest function uses the Newton-Raphson algorithm to compute compound interest rate. This algorithm performs the same calculations repetitively. Each iteration results in a compound interest that is closer to the final result. The number of iterations required to get the results within an acceptable inaccuracy (1.0e-4) depends on the number of periods and the initial compound interest used to start the calculation.

If the guess argument is not provided, the default initial value is 0.01 (1%). If the function returns a NaN (not a number), you can provide the initial compound interest in this fourth argument. If the initial value is closer to the actual rate of the computation, it can be sped up significantly.

Back to Top ^

Function syntax:

long inet_aton(string address)

Takes a string containing an IPv4 address in dotted-quad notation ("nnn.nnn.nnn.nnn") and returns a long containing that address encoded in network byte order.

Back to Top ^

Function syntax:

string inet_ntoa(int address)
string inet_ntoa(long address)

Takes an int or long containing an IPv4 address encoded in network byte order and returns a string containing that address in dotted-quad notation ("nnn.nnn.nnn.nnn").

Back to Top ^

Function syntax:

list(T) append(list(T) L, T e1, T e2, ..., T en)

Returns its argument list, L, with elements e1 through en added to the end of the list in the order specified. The data types of the appended elements e and the element type of list L must be the same, except that element types int and long can be coerced to long and double following the rules in Data Type Coercion and Conversion. The element type of the returned list is the same as the element type of the argument list and of the appended elements.

The function takes any number of element arguments, including zero. That is, append(L) returns list L unchanged. If any list element is null, a null element is appended to the list in the position specified.

Back to Top ^

Function syntax:

double    avg(list(double) L)
int       avg(list(int) L)
long      avg(list(long) L)
timestamp avg(list(timestamp) L)

Given a list, L, of doubles, ints, longs, or timestamps, returns the average of all members of the list. For a returned average of timestamp values to make sense, the list should contain all interval timestamps or all absolute timestamps, but not both. The data type of the returned value is the same as the element type of the argument list.

See also the aggregate version of avg().

Back to Top ^

Function syntax:

list(T) avg_list(list(T) LL(list(T) L1, list(T) L2, ...))

Accepts a list of lists as an argument, where each member list L1, L2, and so on of the containing list LL must have the same element type or a coercible type. Returns a list containing the element-wise average of the elements of each member list in LL. The list element type, T, of the returned list is the same as the element type of the argument lists. For example:

avg_list( [ [1,2,3], [4,5,6] ] )

returns:

[2.5, 3.5, 4.5

The length of component lists can vary. Short lists are padded with nulls to match the length of the longest list seen in the current context. Null values are ignored for the computation of the average.

See also the avg_list() function for aggregates.

Back to Top ^

Function syntax:

list(T) concat(list(T) L1, list(T) L2 [, ..., list(T) Ln])

Returns a list produced by concatenating the elements of its argument lists in the order specified. Takes two or more list arguments, which must have the same element type. The element type, T, of the returned list is the same as the element types of the argument lists.

See also the aggregate version of concat().

Back to Top ^

Function syntax:

bool contains(list(T) L, T item)

Takes two arguments: a list with element type T, and a value, item, of the same type. Returns true if item is a member of the specified list, or false if not.

If the entire list is null, returns null. If a member of the list is null, and item is null, returns true. If no member of the list is null, and item is null, returns false.

If L is a list of strings, item must match an element exactly. Substrings of elements are not matched. Thus, the following expression returns false:

'foo' in ['there','is','food','here']

The string version of contains() does match substrings, so to determine if a substring exists in a list, you can use join() to convert a list of strings to a string. The following expression thus returns true:

'foo' in join(' ',['there','is','food','here'])

The IN infix operator provides an alternate implementation for contains().

Back to Top ^

Function syntax:

int count_distinct_elements(list(T) L)

Returns the number of unique elements in the argument list, L, with any element type, T.

For example:

count_distinct_elements(list(1, 2, 3, 3, 4, 4, 5, 6, 6, 7))

returns 7.

See also the related function, unique() and the aggregate function count_distinct().

Back to Top ^

Function syntax:

list(int) count_list(list(T) LL(list(T) L1, list(T) L2, ...))

Accepts a list of lists as an argument, where each member list L1, L2, and so on of the containing list LL must have the same element type or a coercible type. Returns a list containing an element-wise count of the corresponding elements of each member list in LL. The list element type, T, of the returned list is the same as the element type of the argument lists, or a coerced superset type. For example:

list_list( [ [1,2,3], [4,5,6,7,8] ] )

returns:

[2, 2, 2, 1, 1]

The length of component lists can vary. Short lists are padded with nulls to match the length of the longest list seen in the current context. Null values are ignored for the computation of the sum.

See also the count_list() function for aggregates.

Back to Top ^

Function syntax:

T dotproduct(list(T) L1, list(T) L2, ...)

Returns the sum of the element-wise product of its argument lists, whose element types must be int, double, or long. Accepts any number of lists, but is typically used with two list arguments. The data type of the returned value is the same as the element type of the argument lists. If the element type of the argument lists do not match, they are promoted using the rules in Data Type Coercion and Conversion.

This function produces the dot product, also known as the scalar product, of two or more numeric lists. The function multiplies the elements of each list in element order, L1.first times L2.first, then L1.second times L2.second, and so on. The resulting list of element products is summed and returned. If an argument list is null, the result is null. If any element in any argument list is null, the result is null. If an argument list is shorter than another argument list, the extra positions are filled in with 1 (or 1.0 or 1L), which preserves the extra position elements of the longer list unchanged.

Back to Top ^

Function syntax:

list(T) emptylist(T x)

Returns an empty list with the same element type as the argument. The argument x's value is ignored, and only its type is considered. This function is typically used like these examples:

emptylist(int())

emptylist(string())

You can also use an argument with a literal value, or an expression that resolves to a value, like the following examples. Only the type of the argument is considered:

emptylist(17)

emptylist("IBM")

Back to Top ^

Function syntax:

list(T) filterlist(inputlist(T), 
    inFunction(arg T) {boolean function})

The filterlist function takes a list as its first argument and a function as its second argument. The inputs to that function must be coercible to its declared input types. If the input argument inputlist contains tuples, the number, order, and names of its fields must match exactly, and its field types must be coercible to the field types of the input function's argument fields.

filterlist returns a list composed of only the elements of the argument inputlist for which the function provided in the second argument returns true when applied to elements of inputlist. The element type, T, of the returned list is the same as the element type of the argument inputlist.

The input function inFunction must take in a single argument of the same type as the input list element type, and must output a boolean value. The input function can be a built-in function or one defined using the expression language. Null values in the input list are not treated specially and are included in the output list if the function returns true for nulls.

Examples:

filterlist( [14,22,8,19,38,18,6,28,31,25,6], function myrange(x int) { x > 19 && x < 30} )

Returns:

[22, 28, 25]

In the next example, citytemps is a named schema of daily temperature records with schema {city string, mintemp int, maxtemp int}. We want to filter from this a list of tuples, each containing a city that had a temperature range of more than 20 degrees.

filterlist( list(citytemps("Phoenix", 77, 104), citytemps("Fargo", 58, 89), citytemps("Miami", 82, 96), citytemps("Seattle", 62, 73), citytemps("Boston", 54, 76)), function over20(rec citytemps) { rec.maxtemp - rec.mintemp > 20 } )

Returns:

[{"Phoenix", 77, 104}, {"Fargo", 58, 89}, {"Boston", 54, 76}]

Back to Top ^

Function syntax:

list(T) filternull(list(T) L)

Returns a list composed of the elements of the argument list, L, with any null elements removed. The element type, T, of the returned list is the same as the element type of the argument list.

Back to Top ^

Function syntax:

T firstelement(list(T) L)

Returns the first element of argument list L. The data type, T, of the returned value is the same as the element type of the argument list.

The usage firstelement(L) is the equivalent of L[0].

Back to Top ^

Function syntax (with line breaks added for clarity):

T foldleft(function(arg1 T, arg2 T, arg3 T, ... , argn T) 
    {expression}, arg1_initial, List<arg2> list1, List<arg3> list2, ... , 
    List<argn> listn)
T foldleft(function name (arg1 T, arg2 T, arg3 T, ... , argn T) 
    {expression}, arg1_initial, List<arg2> list1, List<arg3> list2, ... , 
    List<argn> listn)

Executes {expression} to accumulate values on the elements of a set of input lists, working left to right, first to last, through the input list elements, and returns the accumulated result. All the input lists must have the same number of elements, which must be numeric types. Input lists that are null (nulllist(<type>)) are treated as lists of nulls.

Although normally unnamed, the function can be given a name, as the second syntax above and the second example below illustrate.

The number of arguments to the input function must be one more than the number of input lists. The first input argument, arg1, initializes the accumulator. Subsequent arguments must be coercible to arg1's data type, as must be the return data type.

To calculate the output, the function first sets the accumulator to the initial value of arg1. The input function is applied on this accumulator value along with the first elements of the lists (listn[0]) to produce a new accumulator value. The input function is then applied on this new accumulator value and the second element of the lists (listn[1]) to calculate a new accumulator value, which are used with the third elements of the lists (listn[2]) and so on, until the end of the lists is reached. The accumulator value at this point is returned as the output.

Examples:

Sum the elements of one list, starting at 10.

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

This evaluates to 16.

Construct a list of the maximum values of corresponding elements of three lists leftward (line breaks added for clarity):

Evaluates to:

list(890, 90, 78)

using this sequence of operations:

Back to Top ^

Function syntax (line break added for presentation clarity):

T foldright(function(arg1 T, arg2 T, arg3 T, ... , argn T) 
    {expression}, arg1_initial, List<arg2> list1, List<arg3> list2, 
    ... , List<argn> listn)
T foldright(function name(arg1 T, arg2 T, arg3 T, ... , argn T) 
    {expression}, arg1_initial, List<arg2> list1, List<arg3> list2, 
    ... , List<argn> listn)

Executes {expression} to accumulate values on the elements of a set of input lists, working right to left, last to first, through the input list elements, and returns the accumulated result. All the input lists must have the same number of elements, which must be numeric types. Input lists that are null (nulllist(<type>)) are treated as lists of nulls.

Although normally anonymous, the function can be given a name, as the second syntax above and the second example below illustrate.

The number of arguments to the input function must be one more than the number of input lists. The first input argument, arg1, initializes the accumulator. Subsequent arguments must be coercible to arg1's data type, as must be the return data type.

To calculate the output, the function must set the first accumulator value to initial value arg1. The input function is applied on this accumulator value along with the last elements of the lists (listn[n-1]) to produce a new accumulator value. The input function is then applied on this new accumulator value and the second-from-last element of the lists (listn[n-2]) to calculate a new accumulator value, which is used with the third-from-last elements of the lists (listn[n-3]) and so on, until the beginning of the lists is reached. The accumulator value at this point is returned as the output.

Examples:

Sum the elements of two lists:

foldright(function (a int, b list(int), c list(int)) { a+b+c }, 0, list(1, 2, 3), list(4, 5, 6))

This evaluates to 21.

Construct a list of the maximum values of corresponding elements of three lists rightward (with line breaks added for clarity):

Evaluates to:

list(78, 90, 890)

Using this sequence of operations:

Back to Top ^

Function syntax:

bool has_intersection(list(T) L1, list(T) L2)

Returns true if lists L1 and L2, which must have the same type, contain any values in common and false if they do not. The input lists can be of different lengths. For example:

has_intersection([2,4,6,8,10],[1,3,5])

returns false, but

has_intersection([0,],[1,3,5,0])

returns true.

See also the intersect() function, which returns the set of values that two lists have in common.

Function syntax:

int indexof(list(T) L, T e [, int start])

Returns the index of the first element of the list L whose value is e, starting at index start. The argument list can have any element type, T. The element e must have the same element type as the argument list. For list arguments, if e is not found, the function returns a value of null.

If the search is successful, the value returned is always greater than or equal to start. If start is unspecified, it is taken to be 0, which designates the first character of the string or the first element of the list.

See also the indexof() function that operates on strings.

Function syntax:

list(T) insertelement(list(T) L, int index, T e)

Returns a list composed of the elements of the argument list, L, with element e inserted before index position index in the argument list. index is zero-based. The element type, T, of the returned list is the same as the element type of the argument list and of the inserted element, e.

The usage insertelement(L, length(L), e) is the equivalent of append(). The usage insertelement(L, 0, e) is the equivalent of prepend().

Back to Top ^

Function syntax:

list<T> intersect(list(T) L1, list(T) L2)

Returns a list containing the values common to lists L1 and L2, which must have the same type, or an empty list if they share no values in common. The input lists can be of different lengths. For example:

intersect([2,4,6,8,10,12,14,16,18,20],[3,6,9,12,15,18])

returns:

[6,12,18]

See also the has_intersection() function, which determines whether or not two lists have common values.

Function syntax:

string join(list(T) L)
string joinlist(list(T) L)
string join(string separator, list(T) L)
string joinlist(string separator, list(T) L)

Returns a string composed of the elements of list L, having any element type. With a single argument, elements are concatenated. With two arguments, the separator character is inserted between each element. If the list argument is empty, join() returns an empty string. If list is null, join() returns null. If the separator string is null, join() returns null.

You can use joinlist() as an alias for join() in all contexts. In StreamSQL contexts, which has the reserved word JOIN, and in LiveView LiveQL, which borrows its parser from StreamSQL, you must either use the joinlist() alias, or use escaped identifier syntax.

Also see the aggregate function join().

Back to Top ^

Function syntax:

T lastelement(list(T) L)

Returns the last element of argument list L. The data type of the returned value is the same as the element type of the argument list.

The usage lastelement(L) is the equivalent of L[-1].

Back to Top ^

Function syntax:

int lastindexof(list(T) L, T e [, int lastStart])

Returns the index of the last element of the list L whose value is e, for which the index is less than or equal to lastStart. The argument list can have any element type, T. The element e must have the same element type as the argument list. For list arguments, if e is not found, the function returns a value of null.

If the search is successful, the value returned is always less than or equal to lastStart. If lastStart is unspecified, it is taken to be the index of the last grapheme of the string or the last element of the list.

See also the lastindexof() function that operates on strings.

Function syntax:

int length(list L)

Returns the number of elements in a list, including any null elements. If the argument is a null list, the returned value is null.

See also the length() functions that operate on lists and blobs.

Returns a list containing its arguments as elements. See list() in the Simple Functions: Type Conversions section.

Function syntax:

list(T) maplist(function(arg1 T, arg2 T, ... , argn T)
  {function-body}, list1 T, list2 T, ... , listn T)

The maplist function maps the elements of one or more lists onto each other, according to a function() declared as the first argument. The maplist() function takes a declared function() as its first argument and one or more lists as additional arguments. It applies the function to the elements of each argument list, then returns a single list that contains the results of applying the function on each element position, in element order.

To take a simple example, the following maplist() instance declares a function that has two integer arguments and a function body that adds the arguments. When applied to the input list(int) lists, the result is that the first element of the first argument list is added to the first element of the second argument list. Then the second element of the first list is added to the second element of the second list, and so on.

maplist(function(x int, y int) { x + y }, list(1, 2, 3), list(4, 5, 6)))

The result is:

(list(int) [5, 7, 9]

The input function can be defined using the expression language or a built-in function. The number of arguments to the declared function must be at least equal to the number of input argument lists. If the argument lists have more elements than the number of function arguments, the function-body expression continues to be applied.

The inputs to the function — that is, the elements of the input lists — must be coercible to the declared data type of the function arguments. If an input argument is a tuple, the number, order, and names of the fields must match exactly, and the field types of the input arguments must be coercible to the field types of the input function's argument fields.

The element type of the returned list is the same as the element type of the input lists or one that is coercible from them.

Input lists with null elements are valid lists. The result element corresponding to a null element's position can be a null, depending on the operation declared in the function-body. The declared function must handle any nulls; the maplist() function as a whole does not do so. For example:

maplist(function(x int, y int) { x + y }, list(1, 2, 3), list(4, null, 6)))

returns:

(list(int) [5, null, 9]

To take another example:

maplist(function(n1 int, n2 int, n3 int) {n1+n2+n3}, [1,2,3,4], [2,4,6,8], [3,6,9,12])

returns:

(list(int)) [6, 12, 18, 24]

Input lists that are null (nulllist(<type>)) are treated as lists of nulls.

Back to Top ^

Function syntax:

list(T) maplist_loose(function(T1, T2, ... , Tn){...}, list<T1>, list<T2>, ... , list<Tn>)

The maplist_loose() function takes the same function first argument and one or more lists as additional arguments as the maplist() function, and returns a list the same as maplist(). The difference is that this function allows lists of any length, padding shorter lists with nulls to the same length as the longest list encountered.

See maplist() for instructions on using this function.

Back to Top ^

Function syntax:

T maxelement(list(T) L)

This function returns the maximum non-null element value using the greater-than relational operator across all elements in the argument list, L. The data type of the returned value is the same as the element type of the argument list.

StreamBase data types are comparable with relational operators in different ways, as listed in the entry for each data type on StreamBase Data Types.

See also the simple version of max(), the aggregate version of max(), and the aggregate maxn() function. Use the simple function max(list, , list) to determine the larger of two or more lists. In an 2, max(list) returns the maximum list in the aggregate window. By contrast, use maxelement() to compare the element values of a single list.

Back to Top ^

Function syntax:

double median(list(double) L)
double median(list(int) L)
double median(list(long) L)

Given a list, L, of doubles, ints, or longs, returns a double, the median of the elements of L. If the list has an even number of elements, returns the average of the middle two.

See also the aggregate version of median().

Back to Top ^

Function syntax:

list(T) mergelist(list<list<T>> listOfLists)
list(T) mergelist(list<list<T>> listOfLists, bool ascending)
list(T) mergelist(list<list<T>> listOfLists, function(arg1 T, 
    arg2 T) {int compareFunction})
list(T) mergelist(list<list<T>> listOfLists, bool ascending, 
    function(arg1 T, arg2 T) {int compareFunction})

The mergelist function merges a list of sorted input lists into a single sorted output list. It takes one, two, or three arguments:

If a boolean argument is used, it must be the second argument. If absent, the output list is sorted ascending.

When the input lists consist of simple types, default StreamBase expression language comparison operators are normally adequate to obtain properly sorted output.

When the input list elements are tuples, you can provide a compare function if you need to sort on a particular field or fields of input tuples. The compare function can be a built-in function or declared using the expression language. It must accept two input arguments and output an integer. mergelist expects the function's return value to be negative if the first argument is less than the second argument, positive if the first argument is greater than the second argument, and 0 if they are equal. The inner list type must be coercible to the function argument types.

For example, by default a list of lists of tuples with a schema {price int, volume int, symbol string}, would sort on the first field (price). When prices are equal, the second field (volume) is used to resolve any ties, and then the third field (symbol), as needed. If, however, you want to sort only on symbol, you can provide a function to do so, such as the following, where mytuple is the name of a named schema used as a data type:

If the input list of lists contains only one inner list, the output list's elements are the contents of that inner list in the same order. When null values exist in input lists, how they sort in the output list (like other values) is determined by the compare function. For more information see Null Literals.

A call to mergelist that uses the above compare function to sort an enqueued list of lists might take this form (line breaks were added for clarity):

Back to Top ^

Function syntax:

T minelement(list(T) L)

This function returns the minimum non-null value using the less-than relational operator across all elements in the argument list, L. The data type of the returned value is the same as the element type of the argument list.

StreamBase data types are comparable with relational operators in different ways, as listed in the entry for each data type on StreamBase Data Types.

See also the simple version of min(), the aggregate version of min(), and the aggregate minn() function. Use the simple function min(list, , list) to determine the smaller of two lists. In an aggregate context, min(list) returns the minimum list in the aggregate window. By contrast, use minelement() to compare the element values of a single list.

Back to Top ^

Function syntax:

list(T) nulllist(T x)

Notice that the name of the function has three lowercase letter L's. Returns a null list with the same element type as the argument. The argument x's value is ignored, and only its type is considered. This function is typically used like these examples:

nulllist(double())

nulllist(timestamp())

You can also use an argument with a value, or an expression that resolves to a value, like the following examples. Only the type of the argument is considered:

nulllist(17)

nulllist("IBM")

Back to Top ^

Function syntax:

list(T) prepend(list(T) L, T e)

Returns a list containing element e at the start, then all of list L. The data type of element e and the element type of list L must be the same, except that argument types int and long can be coerced to long and double following the rules in Data Type Coercion and Conversion. The element type of the returned list is the same as the element type of the argument list and of the prepended element, e.

Back to Top ^

Function syntax:

double product(list(double) L)
int    product(list(int) L)
long   product(list(long) L)

Given a list, L, of doubles, ints, or longs, returns the product of each member of the list. The data type of the returned value is the same as the element type of the argument list.

See also the aggregate version of product().

Back to Top ^

Function syntax:

list(int) range(int start, int end [, int step])

Returns a list of ints from value start up to (or down to) but not including value end. That is, the range includes the first item in the list and excludes the last item. Thus, range(1, 10) returns a list with nine elements, not ten:

list(int) [1, 2, 3, 4, 5, 6, 7, 8, 9]

The default value for step is 1. step cannot be 0, but you can specify a step value greater than 1 to produce a list with skipped elements. For example, a step of 2 returns every other number:

range(0, 8, 2)

returns

list(int) [0, 2, 4, 6]

If you specify a negative value for step, the list generates in reverse. For example:

range(3, 0, -1)

returns

list(int) [3, 2, 1]

while

range(6, 1, -2)

returns

list(int) [6, 4, 2]

When step is negative and end is greater than start, the result is an empty list. Likewise, an empty list also results when start is greater than end and step is positive.

Back to Top ^

Parses a string into tokens delimited by a character matching a regular expression, and returns a list of strings with the tokens as elements. See regexsplit() in the Simple Functions: Strings section.

Function syntax:

list(T) removeelement(list(T) L, int index)

Returns a list composed of the elements of the argument list, L, with the element at index position index removed. The element type, T, of the returned list is the same as the element type of the argument list.

Back to Top ^

Function syntax:

list(T) replaceelement(list(T) L, int index, T e)
list(T) replaceelement(list(T) L, updatefunction(arg T, index int)->T)
list(T) replaceelement(list(T) L, predicatefunction(arg T)-> bool, 
    replacement T)

Returns a list composed of the elements of the argument list, L, with the element at index position index replaced by element e. The element type of the returned list is the same as the element type of the argument list.

In the second form, instead of specifying an index into the list of interest, specify an updatefunction to be called with every element of the list, which function can return either the current value or some new value determined at runtime.

In the third form, specify a predicatefunction to be called with every element of the list, which returns replacement for all values that match the predicate function.

Back to Top ^

Function syntax:

list(T) reverse(list(T) L)

Returns its argument list, L, in reverse order. The element type, T, of the returned list is the same as the element type of the argument list.

Back to Top ^

Function syntax:

list(T) shuffle(list(T) L)

Returns its argument list, L, with its elements shuffled in random order. Calling shuffle() again on the same list returns a different sort order. The element type, T, of the returned list is the same as the element type of the argument list.

Back to Top ^

Function syntax:

list(T) sort(list(T) L [, bool ascending])
list(T) sort(list(T) L , 
    function compareFunction(arg 1 T, arg2 T)->boolean)
list(T) sort(list(T) L , bool, 
    function compareFunction(arg1 T, arg2 T)->boolean)

Returns its argument list, L, sorted. Sorting occurs in ascending order if the optional ascending argument is true or omitted, or in descending order if ascending is false. If the ascending argument is used, it must be the second argument. The element type, T, of the returned list is the same as the element type of the argument list.

StreamBase data types are comparable with relational operators in different ways, as listed in the entry for each data type on StreamBase Data Types. Null values sort as the lowest possible values for the element type of the list. For doubles, NaN sorts as the highest possible value, which yields the following relations: Null < –Infinity < 0 < +Infinity < NaN.

To exercise control over sorting, especially when list elements are tuples, you can provide your own comparison function that compares two input values and outputs an integer value. The output value must be negative if the first argument is less than the second argument, positive if the first argument is greater than the second argument, and 0 if they are equal.

For further details and an example of using a comparison function, see the description of the mergelist function.

Back to Top ^

Parses a string into tokens delimited by a specified character and returns a list of strings with the tokens as elements. See split() in the Simple Functions: Strings section.

Function syntax:

double    stdev(list(double) L)
double    stdev(list(int) L)
double    stdev(list(long) L)
timestamp stdev(list(timestamp) L)

Given a list, L, of doubles, ints, longs, or timestamps, returns the standard deviation for all members of the list. If the argument list is a list of doubles, ints, or longs, returns a double. If the argument list is a list of timestamps, returns an interval timestamp. For timestamp values, the list should contain all interval timestamps or all absolute timestamps, but not both. For lists of length 1, returns null.

See also the aggregate version of stdev().

Back to Top ^

Function syntax:

double    stdevp(list(double) L)
double    stdevp(list(int) L)
double    stdevp(list(long) L)
timestamp stdevp(list(timestamp) L)

Given a list, L, of doubles, ints, longs, or timestamps, returns the standard deviation for all members of the list. If the argument list is a list of doubles, ints, or longs, returns a double. If the argument list is a list of timestamps, returns an interval timestamp. For timestamp values, the list should contain all interval timestamps or all absolute timestamps, but not both. For lists of length 1, returns 0.

With stdevp() the data provided is the entire population, while with stdev(), the data provided is treated as a random sample. The stdevp() function is calculated using the biased (or n) method. The stdev() function is calculated using the unbiased (or n-1) method.

See also the aggregate version of stdevp().

Back to Top ^

Function syntax:

list(T) sublist(list(T) L, int start [, int end [, int step]])

Returns a list composed of a section of the argument list, L, starting with index start, which is included in the result list. If end is specified, it is not included in the result list. The default value for step is 1. You can supply an alternate step value to skip elements in the argument list. For example, a step of 2 returns every other value in the list. You must specify an end value in order to specify a step value. The element type, T, of the returned list is the same as the element type of the argument list.

In contrast with the range() function, step cannot be negative.

Back to Top ^

Function syntax:

double    sum(list(double) L)
int       sum(list(int) L)
long      sum(list(long) L)
timestamp sum(list(timestamp) L)

Given a list, L, of doubles, ints, longs, or timestamps, returns the sum of all members of the list. The element type of the returned list is the same as the element type of the argument list.

When the list element type is timestamp, summing elements of the list follows the rules for adding timestamps as shown in the table in timestamp Data Type. That is, you cannot sum a list of two or more absolute timestamps. However, you can sum a list composed of all interval timestamps, or one composed of exactly one absolute timestamp plus one or more interval timestamps.

See also the aggregate version of sum().

Back to Top ^

Function syntax:

list(T) sum_list(list(T) LL(list(T) L1, list(T) L2, ...))

Accepts a list of lists as an argument, where each member list L1, L2, and so on of the containing list LL must have the same element type or a coercible type. Returns a list containing the element-wise sum of the elements of each member list in LL. The list element type, T, of the returned list is the same as the element type of the argument lists, or a coerced superset type. For example:

sum_list( [ [1,2,3], [4,5,6] ] )

returns:

[5, 7, 9]

The length of component lists can vary. Short lists are padded with nulls to match the length of the longest list seen in the current context. Null values are ignored for the computation of the sum.

See also the sum_list() function for aggregates.

Back to Top ^

Function syntax:

list(T) unique(list(T) L)

Returns a list composed of the unique elements in the argument list, L, in ascending (lexicographical) order. The element type, T, of the returned list is the same as the element type of the argument list.

For example:

unique([4, 8, 3, 7, 1, 3, 4, 4, 5, 6, 2, 6, 7])

returns:

list(int) [1, 2, 3, 4, 5, 6, 7, 8]

Be aware that lexicographic ordering of strings differs from numeric types. For example, with ints,

unique([400, 8, 3, 7, 1, 3, 4, 5, 400, 6, 6, 7])

returns:

(list(int)) [1, 3, 4, 5, 6, 7, 8, 400]

but given string tokens,

unique(['400', '8', '3', '7', '1', '3', '4', '5', '400', '6', '6', '7'])

returns a list in "dictionary" order:

(list(string)) [1, 3, 4, 400, 5, 6, 7, 8]

To find unique list elements and return them in descending order, use reverse(unique(<list>)).

See also the related function, count_distinct_elements().

Back to Top ^

Function syntax:

tuple unzip(list(tuple) listOfTuples)

Takes a list of tuples and returns a tuple of lists.

An example will clarify the function. Let's say your application extracts a list of symbol and price tuples from a stream. One list might contain the following:

[ {prices: 102.51, symbols: AAPL},
  {prices: 96.52, symbols: IBM},
  {prices: 36.33, symbols: HPQ} ]

You can run this list through unzip(), using an expression like the following:

The returned value is a single tuple whose fields are lists, as follows:

((prices list(double), symbols list(string))) "[102.51,96.82,36.33]","[AAPL,IBM,HPQ]"

Back to Top ^

Function syntax:

double variance(list(double) L)
double variance(list(int) L)
double variance(list(long) L)

Given a list, L, of doubles, ints, or longs, returns a double, the variance for all members of the list. Variance is a measure of the dispersion of a set of data points around their mean value.

For lists of length 1, returns null. See the aggregate version of variance() for more on variance.

Back to Top ^

Function syntax:

double variancep(list(double) L)
double variancep(list(int) L)
double variancep(list(long) L)

Given a list, L, of doubles, ints, or longs, returns a double, the variance for all members of the list. Variance is a measure of the dispersion of a set of data points around their mean value.

The variancep() function is similar to the variance() function: with variancep() the data provided is the entire population, while with variance(), the data provided is treated as a random sample. The variancep() function is calculated using the biased (or n) method. The variance() function is calculated using the unbiased (or n-1) method.

For lists of length 1, returns 0. See also the aggregate version of variancep() for more on variance.

Back to Top ^

Function syntax:

list(tuple) zip(tuple(list(T1), ..., list(Tn)) tupleOfLists)

In the spirit of the zip function in Python, zip() takes a tuple of lists, collates it, and returns it as a list of tuples, where the nth tuple contains the nth element from each of the argument lists. The element types of the lists in the argument tuple can be of any type, and do not need to be the same.

An example will clarify the function. Let's say you have a stream whose schema accepts lists of securities price data: { prices list(double), symbols list(string) }. One tuple might contain the following:

{ 
  prices:  [102.51, 96.82, 36.33], 
  symbols: [AAPL, IBM, HPQ]
}

You can run this tuple through zip(), using an expression like the following:

The returned value is a list of tuples:

(list((prices double, symbols string))) [102.51,AAPL, 96.82,IBM, 36.33,HPQ]

Back to Top ^

Function syntax:

int    abs(int e)
double abs(double e)
long   abs(long e)

Returns the absolute value of an int, double, or long expression e. The return type is the same as the expression's type.

Back to Top ^

Function syntax:

double acos(int x)
double acos(double x)
double acos(long x)

Returns in radians the arc cosine of x, which is the value whose cosine is x. Undefined outside of the range –1 to 1.

Back to Top ^

Function syntax:

bool andall(bool b1, bool b2, ...)

Takes two or more values of type boolean, or expressions that resolve to type boolean, and returns the results of a logical AND operation on all arguments. For example, andall(true, true, false, true, false) returns false. Use andall() as a truth detector function.

Null arguments have special handling. A null argument does not change the result of the evaluation if a false value is among the arguments: andall(null, true, false, null, true) still returns false. However, if one or more arguments is null while all other arguments are true, the function returns null: andall(null, true, true, null, true) returns null.

The andall() function follows the logic expressed in this statement:

See also the orall() simple function and the aggregate versions of andall() and orall().

Back to Top ^

Function syntax:

double asin(int x)
double asin(double x)
double asin(long x)

Returns in radians the arc sine of x, which is the value whose sine is x. Undefined outside of the range –1 to 1.

Back to Top ^

Function syntax:

double atan(int x)
double atan(double x)
double atan(long x)

Returns in radians the arc tangent of x, which is the value whose tangent is x.

Back to Top ^

Function syntax:

double atan2(int x, int y)
double atan2(double x, double y)
double atan2(long x, long y)

Returns in radians the arc tangent of two numeric variables, x and y, either of which can be int, long, or double. This is similar to calculating the arc tangent of (y/x), except that the signs of both arguments are used to determine the quadrant of the result tangent is x.

Back to Top ^

int  bitand(int x, int y)
long bitand(long x, long y)

Returns the result of a bitwise AND operation on values x and y. Compares each bit in x to the corresponding bit in y. If both bits are 1, sets the corresponding result bit to 1. Thus, bitand(3,6) returns 2. (0011 AND 0110 returns 0010)

Back to Top ^

int  bitnot(int x)
long bitnot(long x)

Returns the result of a bitwise NOT operation on value x. Compares each bit in x and sets its bitwise complement in the corresponding result bit, switching 0 for 1 and 1 for 0. Thus, bitnot(5) returns -6. (0...0101 returns 1...1010)

Back to Top ^

int  bitor(int x, int y)
long bitor(long x, long y)

Returns the result of a bitwise inclusive OR operation on values x and y. Compares each bit in x to the corresponding bit in y. If either bit is 1 or both bits are 1, sets the corresponding result bit to 1; otherwise, sets the corresponding result bit to 0. Thus, bitor(12,7) returns 15. (1100 OR 0111 returns 1111)

Back to Top ^

int  bitxor(int x, int y)
long bitxor(long x, long y)

Returns the result of a bitwise XOR (exclusive OR) operation on values x and y. Compares each bit in x to the corresponding bit in y. If either bit is 1 but not both bits, sets the corresponding result bit to 1; otherwise, sets the corresponding result bit to 0. Thus, bitxor(12,7) returns 11. (1100 OR 0111 returns 1011)

Back to Top ^

Function syntax:

double cbrt(int x)
double cbrt(double x)
double cbrt(long x)

Returns the (real) cube root of x.

Back to Top ^

Function syntax:

double ceil(int x)
double ceil(double x)
double ceil(long x)

Returns the smallest double value that is greater than or equal to the argument and is equal to a mathematical integer. The function name, ceil, is shorthand for ceiling. The argument can be an int, double or long. Examples:

See also the related function, floor().

Back to Top ^

Function syntax:

double choose(int n, int k)

Returns the n choose k binomial coefficient, which represents the number of ways to choose k unordered elements from a set of n elements. Specify n as a positive nonzero integer and k as a power of n, where k is greater than or equal to 1 and less than or equal to n–1. If n < 0 or k > n, 0.0 is returned.

Compare the permute() function.

Back to Top ^

Function syntax:

double cos(int x)
double cos(double x)
double cos(long x)

Returns the cosine of x, where x is given in radians.

Back to Top ^

Function syntax:

double cosh(int x)
double cosh(double x)
double cosh(long x)

Returns the hyperbolic cosine of its argument.

Back to Top ^

Function syntax:

double exp(int x)
double exp(double x)
double exp(long x)

Returns the value of e (the base of natural logarithms) raised to the power of x. The argument x is a small value of type int, double, or long.

Back to Top ^

Function syntax:

double expm1(int x)
double expm1(double x)
double expm1(long x)

Returns (e^x) -1. The argument x is a small value of type int, double, or long.

Back to Top ^

Function syntax:

double factorial(int n)

Returns the factorial of the provided integer between 0 and 170. Arguments below zero return NaN; arguments above 170 exceed the size of a double and return Infinity.

Back to Top ^

Function syntax:

double floor(int x)
double floor(double x)
double floor(long x)

Returns the largest double value that is less than or equal to the argument x, and equal to a mathematical integer. The argument can be an int, double, or long. Examples:

See also the related function, ceil().

Back to Top ^

Function syntax:

double gaussianrandom(double mean, double stdev)

Takes two arguments of type double, the mean and standard deviation of a Gaussian distribution, and returns a double randomly chosen from that distribution.

Gaussian distributions are also known as normal distributions (in statistics) or bell curves (in testing). The function is useful for simulating data from any population that tends to follow a normal distribution.

For example, to simulate the SAT score for a random student, we could call gaussianrandom(1500, 100), where 1500 and 100 might be the national mean and standard deviation respectively.

Back to Top ^

Function syntax:

double ln(int x)
double ln(double x)
double ln(long x)

Returns the natural logarithm of x.

Back to Top ^

Function syntax:

double log10(int x)
double log10(double x)
double log10(long x)

Returns the base-10 logarithm of x.

Back to Top ^

Function syntax:

double log1p(int x)
double log1p(double x)
double log1p(long x)

Returns the natural logarithm of the sum of the argument and 1.

Back to Top ^

int  lshift(int x, int y)
long lshift(long x, long y)

Returns the result of a bitwise left shift of the bits in x by the number of bit positions y. Thus, lshift(5,1) returns 10. (0101 returns 1010)

Back to Top ^

Function syntax:

T max(T e1, ..., T en)

This function returns the maximum non-null value using the greater-than relational operator across all its arguments e1 through en, which must all be expressions resolving to the same data type. The data type, T, of the returned value is the same as the arguments.

StreamBase data types are comparable with relational operators in different ways, as listed in the entry for each data type on StreamBase Data Types.

See also the aggregate version of max(), the maxelement() function for lists, and the aggregate maxn() function. Use this simple function max(list, , list) to determine the larger of two or more lists. In an aggregate context, max(list) returns the maximum list in the aggregate window. By contrast, use maxelement() to compare the element values of a single list.

Back to Top ^

Function syntax:

double maxdouble()

This function returns the maximum value for the double data type.

Back to Top ^

Function syntax:

int maxint()

This function returns the maximum value for the int data type.

Back to Top ^

Function syntax:

long maxlong()

This function returns the maximum value for the long data type.

Back to Top ^

Function syntax:

T min(T e1, ..., T en)

This function returns the minimum non-null value using the less-than relational operator across all its arguments e1 through en, which must all be expressions resolving to the same data type. The data type of the returned value is the same as the arguments.

StreamBase data types are comparable with relational operators in different ways, as listed in the entry for each data type on StreamBase Data Types.

See also the aggregate version of min(), the minelement() function for lists, and the aggregate minn() function. Use this simple function min(list, , list) to determine the smaller of two or more lists. In an aggregate context, min(list) returns the minimum list in the aggregate window. By contrast, use minelement() to compare the element values of a single list.

Back to Top ^

Function syntax:

double mindouble()

This function returns the minimum value for the double data type.

Back to Top ^

Function syntax:

int minint()

This function returns the minimum value for the int data type.

Back to Top ^

Function syntax:

long minlong()

This function returns the minimum value for the long data type.

Back to Top ^

Function syntax:

bool orall(bool b1, bool b2, ...)

Takes two or more values of type boolean, or expressions that resolve to type boolean, and returns the results of a logical OR operation on all arguments. For example, orall(true, true, false, true, false) returns true. Use orall() as a falsity detector function.

Null arguments have special handling. A null argument does not change the result of the evaluation if a true value is among the arguments: orall(null, false, true, null, false) still returns true. However, if one or more arguments is null while all other arguments are false, the function returns null: orall(null, false, false, null, false) returns null.

The orall() function follows the logic expressed in this statement:

See also the andall() simple function and the aggregate versions of andall() and orall().

Back to Top ^

Function syntax:

double permute(int n, int k)

Using permutation in the combinatorics sense, this function returns the number of ordered arrangements of k distinct elements that can be select from a set of n elements. Specify n as a positive nonzero integer and k as a number of elements of n, where k is between zero and n. If n < 0 or k > n, 0.0 is returned.

Compare the choose() function.

Back to Top ^

Function syntax:

double pow(int x, int y)
double pow(double x, double y)
double pow(long x, long y)

Returns the value of x raised to the power of y. Accepts an int, double, or long, and returns a double.

Back to Top ^

Function syntax:

double random()
int    random(int maxrange)

Without arguments, returns a pseudo-random double value with positive sign, greater than or equal to 0.0 and less than 1.0.

With an integer argument maxrange, returns a pseudo-random integer with positive sign, greater than or equal to 0 and less than maxrange. Use this form to pick a random number between 0 and maxrange—1, inclusive. For example, to simulate rolling a six-sided die, the expression maxrange(6) + 1 returns a random integer between 1 and 6 inclusive.

Back to Top ^

Function syntax:

long round(double e)
long round(int e, int n)
long round(double e, int n)
long round(long e, int n)

With one argument, a double, returns the closest long to the argument. Floating-point numbers are NOT supported.

With two arguments, round() is similar to the round() found in Microsoft Excel, but not identical to it. Specify a double, long, or int in the first argument. Specify an int in the second argument to designate the number of digits to round the first argument to. Use 0 to specify rounding to an integer, a positive integer to round the digits after the decimal point, or a negative number to specify rounding digits before the decimal point. If the first argument is an int or long, the second argument must be negative to actually perform rounding; otherwise the first argument is returned unchanged.

Back to Top ^

int  rshift(int x, int y)
long rshift(long x, long y)

Returns the result of a logical bitwise right shift of the bits in x by the number of bit positions y. This is the equivalent of the Java >> operator. Thus, rshift(5,1) returns 2. (0101 returns 0010)

Back to Top ^

Function syntax:

double securerandom()

A more secure form of random() that generates random bytes, converted to return a double.

Back to Top ^

Function syntax:

int sign(int x)
int sign(double x)
int sign(long x)

Returns the sign of its argument: –1 if less than zero, 0 if equal to zero, and 1 if greater than zero.

Back to Top ^

Function syntax:

double sin(int x)
double sin(double x)
double sin(long x)

Returns the sine of x, where x is given in radians.

Back to Top ^

Function syntax:

double sinh(int x)
double sinh(double x)
double sinh(long x)

Returns the hyperbolic sine of its argument.

Back to Top ^

Function syntax:

double sqrt(int x)
double sqrt(double x)
double sqrt(long x)

Returns the nonnegative square root of x.

Back to Top ^

Function syntax:

double tan(int x)
double tan(double x)
double tan(long x)

Returns the tangent of x, where x is given in radians.

Back to Top ^double

Function syntax:

double tanh(int x)
double tanh(double x)
double tanh(long x)

Returns the hyperbolic tangent of a double value.

Back to Top ^

Function syntax:

double to_degrees(double x)

Converts an angle measured in radians to an approximately equivalent angle measured in degrees.

Back to Top ^

Function syntax:

double to_radians(double x)

Converts an angle measured in degrees to an approximately equivalent angle measured in radians.

Back to Top ^

int  unsignedrshift(int x, int y)
long unsignedrshift(long x, long y)

Returns the result of a bitwise right shift of the bits in x by the number of bit positions y, filling the leftmost bit position with 0. This is the equivalent of the Java >>> operator. Thus, rshift(-1,1) returns -1 (1111 1111 1111 1111), but unsignedrshift(-1,1) returns 2147483647 (0111 1111 1111 1111).

Back to Top ^

bool  xorall(bool a, bool b, ...)

Takes two or more values of type boolean, or expressions that resolve to type boolean, and returns the results of a logical XOR (exclusive OR) operation on all arguments.

If any argument is null, the function returns null. Otherwise, it returns true iff an odd number of arguments are true and returns false iff an even number of arguments are true. Conceptually, xorall evaluates successive arguments pairwise to produce its result.

xorall(true, true) returns false.

xorall(true, false) returns true.

xorall(false, false) returns false.

xorall(true, null) returns null.

xorall(true, true, true) returns true, but

xorall(true, true, true, true) returns false.

The xorall function follows the logic expressed in this statement:

See also the andall() and orall() simple functions and the aggregate versions of andall() and orall().

Back to Top ^

Function syntax:

bool isnan(double value)
bool isnan(int value)
bool isnan(long value)
bool isnan(timestamp value)

Returns true if the argument is NaN (not a number), or returns null if the argument is null. Returns false otherwise.

Back to Top ^

Function syntax:

double nan()

This function returns a NaN literal as type double.

Back to Top ^

Function syntax:

bool notnan(double value)
bool notnan(int value)
bool notnan(long value)
bool notnan(timestamp value)

Returns false if the argument is NaN (not a number), or returns null if the argument is null. Returns true otherwise.

Notice that notnan() returns the opposite of isnan(), except if the argument is null, in which case they both return null.

Back to Top ^

Function syntax:

list(string) getAllHostIPs()

Returns as a list(string) all the non-loopback IP addresses assigned to the machine on which StreamBase Server is running.

Back to Top ^

Function syntax:

string getClientIP(string connectionID)

Returns as a string the IP address associated with the specified connectionID. Obtain the connectionID string from the first field returned by an sbadmin listConnections command, or from the connection stream in the system container.

Use this function to determine by IP address the actual computer connecting to, or recently disconnected from, a running instance of StreamBase Server.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getCompilerProperty(string sysprop)

Returns the value of the specified system property that StreamBase Server is actually using. By contrast, getSetCompilerProperty() answers the question of whether this value was explicitly set, and systemproperty() only returns values explicitly set with -Dsome.system.property=value.

Compare the following:

These results tell you that the streambase.querytable.default-memory-tables system property was not explicitly set at the command line with -D, was not explicitly set in a property table and is therefore using the compiled-in default value, and that this default value is MEMORY.

Back to Top ^

Function syntax:

string  get_conf_param(default-value, path1, path2, path3, ...)
boolean get_boolean_conf_param(default-value, path1, path2, path3, ...)
int     get_int_conf_param(default-value, path1, path2, path3, ...)
long    get_long_conf_param(default-value, path1, path2, path3, ...)
double  get_double_conf_param(default-value, path1, path2, path3, ...)

Returns the value portion of a name-value pair specified with a <param> element in the currently active server configuration file, usually named sbd.sbconf. Use the typed versions of the function to convert the returned value to the specified data type.

These functions only return values from <param> elements. Other configuration file elements cannot be accessed with these functions.

The first argument, default-value, specifies a value to return if parsing the configuration file returns nothing. The arguments path1, path2 ... pathn specify element and attribute names in the XML path to the value of interest (without counting the <streambase-configuration> top-level element).

For example, the value of the TCP port might be set in the configuration file with an entry like the following:

To extract the TCP port value from the configuration file, use the int version of the get_conf_param() function as follows:

get_int_conf_param(10000, "server", "tcp-port")

In another example, some of the values set in the configuration file's <security> element are nested deeper:

To extract the keystore-password value, use the following function:

get_conf_param("verysecret", "security", "ssl-authentication", "keystore-password")

These functions are not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getContainer()

Returns as a string the name of the container in which the current application is loaded. Can be used in expressions like this example:

if getContainer() == "default" ...

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getHostName()

Returns as a string the machine name of the host on which StreamBase Server is running. Can be used in expressions like this example:

if getHostName() == "fasthost" ...

Back to Top ^

Function syntax:

string getLeadershipStatus()

Returns the string LEADER or NON_LEADER, which represent the current StreamBase Server's leadership status as a member of a high availability cluster. Servers have LEADER status by default on startup, which can be changed with the sbadmin setLeadershipStatus command.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getNodeName()

Returns as a string the name of the node in which the current application is loaded. Can be used in expressions like this example:

if getNodeName() == "primaryserver" ...

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getParallelRoot()

Returns the qualified path name of the top-level container or Module Reference that is the root of the current parallel region. See Parallel Region Defined.

If this function is called in a simple module without concurrency settings, it returns the path name of the container that holds the operator that calls this function. If this function is called in a module whose Module Reference has a concurrency setting of Run in a parallel region, it returns the qualified path to that Module Reference. If the Module Reference also has a Multiplicity setting of multiple, and the number of instances is set to 2 or more, the returned path is appended with a colon and a zero-based integer representing the instance number of the calling module.

Thus:

See StreamBase Path Notation for details on the qualified path names that can be returned.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getPath(string componentname)

Returns the qualified path of the specified component of a StreamBase application. Can be used for verifying the container name for the specified component at run time, in expressions like this example:

if getPath("Symbol") == "default.Symbol" ...

See StreamBase Path Notation for details on the qualified path names that can be returned.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getServerURI()

Returns the StreamBase URI of the currently running StreamBase Server. The value returned is from the point of view of the server, and thus always returns the hostname localhost. Use this function to obtain the port number and any authentication parameters appended to the URI.

Use this function instead of systemproperty("streambase.uri") to obtain the same information.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

string getSetCompilerProperty(string sysprop)

Returns the value of the specified system property if you explicitly set it, or returns UNSET otherwise. The UNSET result means the Server is using the default value for the specified property.

By contrast, getCompilerProperty() returns the actual value of the specified property, and systemproperty() only returns values explicitly set with -Dsome.system.property=value.

Compare the following:

These results tell you that the streambase.querytable.default-memory-tables system property was not explicitly set at the command line with -D, was not explicitly set in a property table and is therefore using the compiled-in default value, and that this default value is MEMORY.

Back to Top ^

Function syntax:

int getTableSize(string QTname)

Returns the number of rows in the specified Query Table. When used in a Query operator that is in the process of adding or deleting table rows, the result is only approximate.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

list(double) correlation_coefficient(string name, int index, 
                                     list(double) var1, list(double) var2 ...)

Returns a list of correlation coefficients, containing as many members as there are list arguments (there must be at least two). The output list of doubles is in the same order as the list arguments. Given n variables, the index argument specifies which of those n lists holds the primary variable (for which the returned correlation coefficient is 1.0).

The name argument specifies the type of correlation coefficient to compute, taken from this list:

Click any name above to see the description of the statistic. You can abbreviate and approximate the spellings you supply for the name. You can call any of these functions directly by its full name, as well as using the above syntax. However, when you call these functions directly, only two variables can be correlated per call, and the output is a scalar double.

If any input list contains null values, the function returns null for its correlation coefficient(s).

Back to Top ^

Function syntax:

double goodman_kruskal_gamma(list(double) var1, list(double) var2)

Returns the Goodman-Kruskal Gamma correlation coefficient between values of variables in two lists as a double value. The Goodman-Kruskal Gamma statistic is a rank correlation of concordant pairs. If any field values are null, the returned value is null.

To perform multivariate Goodman-Kruskal Gamma correlations, use the simple correlation_coefficient function.

Back to Top ^

Function syntax:

double kendall_tau(list(double) var1, list(double) var2)

Returns the normalized Kendall Tau distance metric between values of variables in two lists as a double value. The lists must have the same number of elements. The Kendall Tau distance statistic counts the number of pairwise disagreements between the ranks of corresponding items in two fields. Larger values indicate greater disagreement in rank ordering, such that a return value of 0 means complete agreement and 1.0 means complete disagreement.

To perform multivariate Kendall Tau correlations, use the simple correlation_coefficient function.

Back to Top ^

Function syntax:

double pearson(list(double) var1, list(double) var2)

Returns the Pearson product-moment correlation coefficient between values of variables in two lists as a double value that indicates the degree of linear dependence between two variables. The Pearson statistic is defined as the covariance of the two variables divided by the product of their standard deviations. The term product-moment refers to the mean (the first moment about the origin) of the product of the mean-adjusted random variables. A return value of -1 indicates a perfect negative linear correlation. A value of 0 indicates no correlation (random variates). A value of 1 indicates perfect positive linear correlation. If any list elements are null, the returned value is null. If the variance of either input variable is zero, the function returns NaN.

To perform multivariate Pearson correlations, use the simple correlation_coefficient function.

Back to Top ^

Function syntax:

double spearmans_rank(list(double) var1, list(double) var2)

Returns the Spearman's Rank correlation coefficient between values of variables in two lists as a double value. Spearman's statistic is defined as the Pearson correlation coefficient between the ranked variables. A return value of -1 indicates a perfect negative correlation (reverse ordering). A value of 0 indicates no concordance of ranks. A value of 1 indicates identical rank orderings. If any list values are null, the returned value is null.

To perform multivariate Spearman's Rank correlations, use the simple correlation_coefficient function.

Back to Top ^

Function syntax:

bool contains(string haystack, string needle)

Takes two arguments: a string and a search string. Returns true if needle is a substring of haystack, or false if not.

If either argument is null, returns null.

The IN infix operator is an alternate syntax for contains().

Also see the list version of contains().

Back to Top ^

Function syntax:

bool endswith(String biggerString, String smallerString)

Takes two arguments: a string to search within and a (sub)string to search for. Returns true if biggerString ends with smallerString, or false if not.

If either argument is null, returns null.

Back to Top ^

Function syntax:

string format(string format-string, arg0, arg1, ..., argn)

Returns a formatted string for arguments arg0 through argn, each formatted according to a specification in format-string.

Format specifications are patterns specified in the manner of class java.text.MessageFormat.

For example, an incoming stream containing NYSE stock ticks might have a field named symbol containing four-character stock symbols. Let's say a downstream operator expects symbols to be prefixed with a string identifying their source stock exchange. In this case, use an expression like the following in a Map operator:

format("NYSE:{0}", symbol)

An incoming stream might have a price field specified to four decimal places. When the flow of tuples reaches an output stream that must be formatted for human readability, you can use an expression like the following to round the price field to two decimal places. This example assumes that the price field contains values of type double, which matches the format specifier ###.##.

format("{0,number,###.##}", price)

The format for argument arg0 is specified with the portion of the format-string that defines {0}. The format for arg1 is in the format-string portion that defines {1}, and so on. The data type of arg0 must match the type expected by the format-string specifier for {0}, and so on for each argument.

If you use format() to modify a tuple, use {0}, {1}, {2} and so on to specify the format for each field.

See the documentation for java.text.MessageFormat for further details and more examples.

Back to Top ^

Function syntax:random

int indexof(string haystack, string needle [, int start])

Returns the index of the first instance of the string needle within the string haystack, for which the index is greater than or equal to start. For all supported Unicode character sets, this function returns the index in number of graphemes, not bytes. For string arguments, if needle is not found, the function returns a value of -1.

If the search is successful, the value returned is always greater than or equal to start. If start is unspecified, it is taken to be 0, which designates the first character of the string or the first element of the list.

See also the indexof() function that operates on lists.

Back to Top ^

Function syntax:

bool isempty(String str)

Takes one string argument, str. Returns true if str is null or empty; false if not.

Back to Top ^

Function syntax:

int lastindexof(string haystack, string needle [, int lastStart])

Returns the index within string haystack of the rightmost instance of string needle, for which the index is less than or equal to lastStart. For all supported Unicode character sets, this function returns the index in number of graphemes, not bytes. For string arguments, if needle is not found, the function returns a value of -1.

If the search is successful, the value returned is always less than or equal to lastStart. If lastStart is unspecified, it is taken to be the index of the last grapheme of the string or the last element of the list.

See also the lastindexof() function that operates on lists.

Back to Top ^

Function syntax:

int length(string x)

Returns the number of graphemes in the string, for ASCII and all supported Unicode character sets. If the argument is a null string, the returned value is null.

See also the length() functions that operate on lists and blobs.

Back to Top ^

Function syntax:

string lower(string str)

Returns its argument in lowercase letters.

Back to Top ^

Function syntax:

string ltrim(string str)
string ltrim(string s1, string s2)

The same as trim(), except that the first argument is trimmed on the left side only.

Back to Top ^

Function syntax:

string randomstring(int len)

Returns a string of size len containing random ASCII characters A-Z.

Back to Top ^

Function syntax:

bool regexmatch(string regex, string str)

Attempts to match the specified regular expression in regex against the entire specified string in str. To match any substring of the specified string, use wildcards before and after your regular expression. For example, the regex IBM matches only when the entire string is "IBM", while the regex .*IBM.* matches if "IBM" is anywhere in the supplied string str.

Back to Top ^

Function syntax:

bool regexmatch_ignorecase(string regex, string str)

Same as regexmatch(), but the supplied regex matches str without regard to case.

Back to Top ^

Function syntax:

string regexreplace(string input_str, string regex_str, string replace_str [, int limit])

Accepts an input string, a regular expression pattern, a replacement string, and an optional integer, limit. Returns input_str modified by replacing occurrences of regex_str in input_str with replace_str up to limit times. If limit is negative or omitted, all occurrences in input_str are replaced.

See Oracle's Pattern class documentation for the supported regular expression syntax. The replace_str argument can contain references to fields in a regular expression capture group, in the same way as java.util.regex.Matcher.appendReplacement().

Usage note: the similar replace() command operates on string literals, and substitutes a string literal for a literal search string. The regexreplace() command operates on string literals, but substitutes its string literal for a regular expression search, and has support for capture groups. It would appear at first glance that regexreplace() without the optional limit argument is the same as replace(), but the difference in the second argument means the two commands have different semantics. For example, consider the following commands and their results:

replace("this.string", ".", ",") returns this,string

regexreplace("this.string", ".", ",") returns ,,,,,,,,,,,

regexreplace("this.string", "\\.", ",") returns this,string

To specify a capture group, surround an expression with parentheses (). This saves the section of the input string matching the capturing group for later recall via a backreference that you specify in replace_str.

A backreference is specified in the regular expression as a dollar sign ($) followed by a digit indicating the number of the group to be recalled, with a replacement string. For example:

regexreplace('a-b','([a-zA-Z])-([a-zA-Z])','$1_$2') returns a_b

Back to Top ^

Function syntax:

list(string) regexsplit(string input_str, string regex_delimiter [, int limit])

Use the regexsplit() function in the same ways as the split() function, except that you can specify a regular expression as the field delimiter. See Oracle's Pattern class documentation for the supported regular expression syntax.

The following example parses input_str into list elements using either colon, semicolon, or a space as the field delimiter:

regexsplit("aaa:bbb;ccc:ddd;eee fff", "[:; ]")

returns

list(string) [aaa, bbb, ccc, ddd, eee, fff]

See split() for further details and for instructions on using the optional limit argument.

Back to Top ^

Function syntax:

tuple regextuple(tuple tuplespec, string regex , sring input)

Use the regextuple() function to parse a string into a tuple.

For the first argument, provide a tuple specification in the form of an empty tuple. To do so, use type conversion functions in a tuple() function to define the data type of each field, and at the same time to create a null field of each type. The first argument of the example below creates a tuple with the required schema, and with each field filled with null: ((symbol string, price double)) null,null.

The second argument is a Java regular expression that uses named capturing groups, where the capture group names are the same as, and in the same order as, the tuple fields specified in the first argument.

The third argument is the string you want to parse into tuple format, possibly extracted from CSV or other plain text input upstream.

See Oracle's Pattern class documentation for the supported regular expression syntax.

In the following example, notice that you must escape the predefned character class strings with double backslashes:

regextuple(tuple(string() as symbol, double() as price), "(?<symbol>[A-Z]+)\\s+(?<price>\\d+(\\.\\d+)?)", "STP 42.00")

This returns:

((symbol string, price double)) STP,42.0

Back to Top ^

Function syntax:

string replace(string main_str, string search_str, string replace_str)

Returns main_str after locating all instances of search_str and replacing them with replace_str. The search_str and replace_str arguments are read as case-sensitive, literal strings. Any wildcard character is read as the literal character, not a wildcard.

Examples:

For a string field named UStext in the incoming stream:  replace(UStext, "honor", "honour")

replace('Open the pod bay doors, IBM.', 'IBM' , 'HAL')

replace('1,2,3,4,5', ',' , '-')

See also the regexreplace() command and the usage note there comparing with replace() syntax.

Back to Top ^

Function syntax:

string rtrim(string str)
string rtrim(string s1, string s2)

The same as trim(), except that the first argument is trimmed on the right side only.

Back to Top ^

Function syntax:

list(string) split(string input_str, string delimiter [, int limit])

Returns a list of strings parsed from input_str, splitting the input string into pieces delimited by the character or phrase specified as delimiter. The delimiter character or phrase itself is not preserved in the resulting list when a match is found. For example:

split("aaa:bbb:ccc:ddd:eee", ":")

returns

list(string) [aaa, bbb, ccc, ddd, eee]

If the delimiter character or phrase is not found in input_str, then input_str is returned verbatim as the only element of the resulting list. If the delimiter character or phrase occurs adjacent to another instance of the delimiter, the result is an empty list element. For example, split("aaa::bbb", ":") results in the following three-element list: [aaa,  ,bbb].

You can specify an optional third argument, limit, an integer specifying the number of list elements in the result list. Use the limit argument in the following ways:

See also the regexsplit() function, a variation of split() that allows you to use a regular expression to specify the delimiter.

Back to Top ^

Function syntax:

bool startswith(String biggerString, String smallerString)

Takes two arguments: a string to search within and a (sub)string to search for. Returns true if biggerString begins with smallerString, or false if not.

If either argument is null, returns null.

Back to Top ^

Converts its argument into a string. See string() in the Simple Functions: Type Conversions section.

Function syntax:

int strlen(string str)

Returns the length of the string str. This function returns the number of graphemes, not bytes, for all supported Unicode character sets.

Back to Top ^

Function syntax:

string strresize(string str, int length)

The strresize() function performs no action: it simply returns its str argument and ignores the length argument. The function is preserved for compatibility with previous StreamBase releases, in which the StreamBase string data type had a fixed maximum size. To perform string truncation, use substr() or strresizetrunc().

Back to Top ^

Function syntax:

string strresizetrunc(string str, int length)

Returns its argument str, truncated to the number of bytes specified in length.

Back to Top ^

Function syntax:

string substr(string str, int begin, int length)

Returns a substring of the string str, starting at the zero-indexed character begin with a size of length characters.

For all supported Unicode character sets, specify length in number of graphemes, not bytes.

Back to Top ^

Function syntax:

string trim(string str)
string trim(string s1, string s2)

With one argument, returns the specified string with leading and trailing spaces removed.

With two arguments, the second argument contains the characters to be removed from the string specified in the first argument.

Back to Top ^

Function syntax:

string upper(string str)

Returns its argument in uppercase letters.

Back to Top ^

Function syntax:

bool advanceTimeBy(long millis)

Use this function to increment the system time of an instance of sbd running in a controlled time environment by the specified number of milliseconds.

This function only works if you have configured the current project's sbd.sbconf file for testing purposes with elements like the following. See Using the StreamBase JUnit TimeService for further information.

Back to Top ^

Function syntax:

bool advanceTimeTo(timestamp timevalue)

Use this function to increment the system time of an instance of sbd running in a controlled time environment to the specified timestamp's date and time.

This function only works if you have configured the current project's sbd.sbconf file for testing purposes with elements like the following. See Using the StreamBase JUnit TimeService for further information.

Back to Top ^

Function syntax:

timestamp getTargetTime()

Use this function to retrieve a timestamp representing the time StreamBase Server thinks it is right now. This function is useful in a controlled time environment to retrieve a custom starting point time you have set with elements like the following in the project's sbd.sbconf file. Notice that the getTargetTime() timestamp is the same as that returned by now(), because in a controlled time environment, the server's sense of what current time means has been deliberately changed, and is temporarily not the same as wall clock time.

This function is not expected to work at the command prompt with sbd --eval.

Back to Top ^

Function syntax:

long nanotime()

Returns the current value of the system timer as a long value in nanoseconds. This function does not guarantee to return an accurate measurement of the system clock to the nanosecond level of precision, but does provide an accurate counter at nanosecond precision. Therefore, use this function only to measure elapsed time between two invocations, like the following example:

Differences in two calls to nanotime() are not accurate for a span greater than 2⁶³ (about 292 years). Do not compare nanotime() values between different machines or even across machine restart boundaries on the same machine, since the hardware time counters are reset on reboot.

Back to Top ^

Function syntax:

timestamp sleep(timestamp t)

Pauses execution of the current thread for the specified time period. The argument must be an interval timestamp, and the return value is the argument. This function can be useful in conjunction with operators that run in a separate thread, and is provided for debugging or for rare uses. The sleep() function blocks the concurrent portion of an application, if concurrency is enabled, or blocks the container holding the application, if concurrency is not enabled. Therefore, use sleep() with care in production applications. To learn about threading in StreamBase applications, refer to Execution Order and Concurrency.

Back to Top ^

Function syntax:

string systemenv(string key)

Calls the standard Java method java.lang.System.getenv(). Returns the string value of the environment variable specified by the key argument.

Back to Top ^

Function syntax:

string systemproperty(string key [, string defaultstring])

Calls the standard java.lang.System.getProperty() method. Returns the string value of the system property specified by the key argument. Use the standard set of system property keys described in Java documentation for java.lang.System.getProperties() (for example, os.name, java.home, and user.name), or specify a StreamBase-specific Java property.

If the optional defaultstring argument is used, and there is no system property for the specified key, the function returns the string specified in the defaultstring argument. If no default string is provided, null is returned.

Back to Top ^

Function syntax:

string version()

Returns as a string the three-position release number from the currently running release of TIBCO StreamBase, such as 7.5.4.

Back to Top ^