Fn

com.apama.functional
Event Fn

Provides static actions for functional operations such as map, reduce, filter and slice on EPL containers.

It also provides generators which can be used as input to the functional operations.

Examples:

// Calculate the average of the values in the sequence = 20
Fn.reduce([10, 20, 30], Fn.mean()); 

// Filter strings by regular expression using the string.matches action = ["Hello Alice", "Hello Al"] 
Fn.filter(["Hello Alice", "Hello Bob", "Hello Al"], Fn.callAction(string.matches, ["Hello Al.*"])); 

// Use Functional() to chain multiple operations: filter out odd numbers, then reduce the sequence to a single value containing the sum = 70
Functional([10, -5, 20, 40]).filter(Fn.even).reduce(Fn.sum);

Note: This library introduces some inevitable performance overhead compared to using the standard built-in EPL types and loops, so while it is very convenient, it may not be the best choice for any performance-critical sections of your application.

See below for links to some of the most important actions and related events.

Since:: 10.15.3.0

See Also:: com.apama.functional.Functional - This provides convenient fluent wrappers for the functionality in the Fn event.; com.apama.functional.Fn.filter() - A functional operator that filters the container to one only including items where the provided predicate is true.; com.apama.functional.Fn.map() - A functional operator that maps each item in the container to a new value, using the supplier functor.; com.apama.functional.Fn.reduce() - A functional operator that reduces all items in the container down to a single value.; com.apama.functional.Fn.allTrue() - A functional operator that returns true if all items in the container are true.; com.apama.functional.Fn.slice() - A functional operator that selects a subsequence from the beginning/end/middle of the items in the container.; com.apama.functional.Fn.partial() - A helper that partially specify the arguments for an action, leaving the remaining argument(s) to be supplied later (typically by values from the functional container).; com.apama.functional.Fn.generator() - A helper that uses an existing action to create a generator that can be used with this library.; com.apama.functional.Fn.isEqual() - A predicate that returns true if two values are the same.; com.apama.functional.Fn.gt() - A predicate that returns true if a number is greater than a specified threshold.; com.apama.functional.Fn.isNot() - A predicate that inverts the true/false value returned by another predicate.; com.apama.functional.Fn.sum() - A functor action that calculates the sum of the values in the container.; com.apama.functional.Fn.mean() - A functor action that calculates the average of the values in the container.; com.apama.functional.Fn.setEntry() - A functor action that sets the value of a named event/dictionary field.; com.apama.functional.Fn.waitForAllCompleted() - A functional operator that calls an action when a set of events have arrived.; com.apama.functional.Fn.getAllEvents() - A functional operator that calls an action with a set of events once a terminating event arrives.; com.apama.functional.Fn.sendToChannel() - A helper that makes it easier to implement request-response protocols by sending an event and keeping a fluent-style reference to it for use in subsequent listeners.

Sends:: any -

Listens:: any -

Action summary
`any`	`static` `$(integer n)` Return a placeholder variable for a partial function referring to the `n`th argument to the resulting partial function.
`com.apama.functional.Generator`	`static` `accumulate(any container, any func)` Returns a generator which accumulates over the underlying container, returning the result after accumulating each item.
`com.apama.functional.Generator`	`static` `accumulateFrom(any start, any container, any func)` Returns a generator which accumulates over the underlying container, returning the result after accumulating each item.
`boolean`	`static` `allTrue(any seq)` Checks whether all the items in the sequence are equal to true.
`boolean`	`static` `anyTrue(any seq)` Checks whether at least one item in the sequence is equal to true.
`com.apama.functional.Partial`	`static` `callAction(any actionToCall, any args)` Calls an instance/non-static action on an object (e.g. an event or built-in type) that is supplied later.
`string`	`static` `concat(string lhs, string rhs)` Action which concatenates two strings. Intended for use with accumulate, reduce or map.
`any`	`static` `consume(any generator, integer n)` Consumes a given number of items from a generator and discard them.
`com.apama.functional.Generator`	`static` `count()` Returns a generator producing a sequence of integers that counts upwards from 0.
`com.apama.functional.Generator`	`static` `cycle(any seq)` Iterates through a sequence of items and continues looping forever.
`boolean`	`static` `even(integer i)` A predicate which returns true if the argument is even.
`boolean`	`static` `fieldEqual(any fieldName, any fieldValue, any object)` A predicate that returns true if the item has a field/key/entry with the given value.
`any`	`static` `filter(any container, any func)` Filters the contents of a sequence, dictionary or generator using a boolean predicate function.
`com.apama.functional.Generator`	`static` `generator(any func)` Creates a generator that yields a series of values calculated by a function that returns the next value based on the previous value.
`com.apama.functional.Generator`	`static` `generatorFrom(any start, any func)` Creates a generator that yields a series of values calculated using a starting value and a function which returns the next value based on the previous value.
`sequence<listener>`	`static` `getAllEvents(string valueEventName, dictionary<string, any> valueEventFields, string endEventName, dictionary<string, any> endEventFields, any onComplete)` Listens for events matching the specified fields and then calls an action with the received events once a terminating event arrives.
`com.apama.functional.Partial`	`static` `getEntry(any entryName)` Gets a named entry/field/key from an object (such as event or dictionary) that is supplied later.
`boolean`	`static` `gt(any threshold, any number)` A predicate which returns true if the argument is greater than the given threshold number.
`integer`	`static` `increment(integer i)` Increments a given integer.
`boolean`	`static` `isEmpty(any value)` A predicate which returns true if the `any` is empty, or contains a listener, string, optional, sequence or dictionary that is empty.
`boolean`	`static` `isEqual(any value1, any value2)` A predicate which returns true if two values are equal according to the EPL `=` operator.
`action<any> returns boolean`	`static` `isNot(any pred)` A predicate which inverts the value of another predicate.
`boolean`	`static` `isTrue(boolean b)` A predicate which returns `true` if the argument is true and `false` if it is false.
`sequence<listener>`	`static` `listenForAnyOf(any seq, string typeName, string fieldName, dictionary<string, any> otherFields, any arrivedAction)` Listens for events with a field matching any value from a given sequence, and calls an action when each one arrives (similar to an EPL "or" event expression).
`boolean`	`static` `lt(any threshold, any number)` A predicate which returns true if the argument is less than the given threshold number.
`any`	`static` `map(any container, any func)` Applies a functor action that maps the current members of a sequence, values in a dictionary or output of a generator to new values.
`any`	`static` `mapKeys(any container, any func)` Applies a functor action that maps the current keys in a dictionary to new keys.
`action<any, any> returns any`	`static` `mean()` Returns an action that can be used with `accumulate` or `reduce` to calculate the mean of the integers, floats or decimals in a sequence or output by a generator.
`any`	`static` `mul(any number1, any number2)` Action that multiplies two values. It is intended for use with a sequence or generator of integers, floats or decimals using `accumulate` or `reduce`.
`boolean`	`static` `negative(any number)` A predicate which returns true if the argument is negative.
`boolean`	`static` `odd(integer i)` A predicate which returns true if the argument is odd.
`sequence<listener>`	`static` `onTimeout(sequence<listener> ls, float timeout, any onTimeout)` Takes a sequence of listeners, waits for a given timeout and then if any of the listeners are still valid quits them and calls an action.
`com.apama.functional.Partial`	`static` `partial(any func, any args)` Partially specifies the arguments for an action, leaving the remaining argument(s) to be supplied later.
`boolean`	`static` `positive(any number)` A predicate which returns true if the argument is positive (not including 0).
`integer`	`static` `quantify(any container, any pred)` Quantifies (counts) the number of times a predicate is true for the values of a sequence or dictionary.
`listener`	`static` `quit(listener l)` Terminates a listener by calling quit() on it.
`com.apama.functional.Generator`	`static` `random(any limit)` Returns a generator producing uniform random numbers between 0 (inclusive) and `limit` (exclusive).
`sequence<integer>`	`static` `range(integer start, integer end, integer stride)` Returns a sequence of integers from `start` (inclusive) to `end` (exclusive), incrementing by `stride` each time.
`any`	`static` `reduce(any container, any func)` Returns a single value resulting from applying an accumulator function to every item in the container.
`any`	`static` `reduceFrom(any accumulator, any container, any func)` Returns the accumulated value resulting from successive application of an accumulator function to each of the members of a sequence or dictionary.
`com.apama.functional.Generator`	`static` `repeat(any item)` Repeats the given element forever.
`any`	`static` `sendToChannel(string channel, any evt)` Helper that sends an event to a channel and returns it (for use when setting up response listeners).
`any`	`static` `sequenceOf(any item, integer n)` Returns a sequence containing the given item n times.
`com.apama.functional.Partial`	`static` `setEntry(any entryName, any entryValue)` Sets a named entry/field/key to an object (such as event or dictionary) that is supplied later.
`any`	`static` `setFields(any evt, any fields)` Helper that initializes one or more of the fields in an event, either by field name or by position.
`any`	`static` `slice(any container, integer start, integer end)` Returns a given section of a sequence. If a generator is supplied, it is immediately invoked the required number of times.
`any`	`static` `sliceFrom(any container, integer start)` Returns a given section of a sequence, from `start` to the last element.
`any`	`static` `sliceTo(any container, integer end)` Returns a section of a sequence, from the beginning to `end`.
`any`	`static` `stride(any container, integer gap)` Returns the result of iterating through the sequence, incrementing by gap each time.
`any`	`static` `sum(any number1, any number2)` Action that calculates the sum of two values. It is intended for use with a sequence or generator of integers, floats or decimals using `accumulate` or `reduce`.
`com.apama.functional.Partial`	`static` `toType(string typeName)` Converts items in a container to the specified type using a cast or toString conversion.
`sequence<listener>`	`static` `waitForAllCompleted(any seq, string typeName, string fieldName, any onCompleted)` Listens for events with a field matching every value from a given sequence, and calls a completion action when all have arrived (similar to an EPL "and" event expression).
`boolean`	`static` `whole(any number)` A predicate which returns true if the argument is a whole number.

Action detail

$

any static $(integer n)

Return a placeholder variable for a partial function referring to the nth argument to the resulting partial function.

Parameters:: n - The nth argument. Starts at 1.

Returns:: A placeholder which can be used with Fn.partial.

See Also:: com.apama.functional.Fn.partial() - This should be passed as one of the arguments to the partial function.

accumulate

com.apama.functional.Generator static accumulate(any container, any func)

Returns a generator which accumulates over the underlying container, returning the result after accumulating each item.

Similar to reduce, but returns a generator yielding each item in turn, rather than just the final value. The initial value of the accumulator is the default value of func's return type (RETURNTYPE).

Parameters:: container - The sequence, dictionary or generator to accumulate.; func - An action which accumulates each item in turn and returns the new value. The signature should be either action<RETURNTYPE accumulatedValue, ITEMTYPE item> returns RETURNTYPE, or (for dictionaries) action<RETURNTYPE accumulatedValue, KEYTYPE itemKey, VALUETYPE itemValue> returns RETURNTYPE.

Returns:: A generator which returns each accumulated item in turn.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.reduce()

accumulateFrom

com.apama.functional.Generator static accumulateFrom(any start, any container, any func)

Parameters:: start - The initial value of the accumulator; must have the same type as func's return type (RETURNTYPE).; container - The sequence, dictionary or generator to accumulate.; func - An action which accumulates each item in turn and returns the new value. The signature should be either action<RETURNTYPE accumulatedValue, ITEMTYPE item> returns RETURNTYPE, or (for dictionaries) action<RETURNTYPE accumulatedValue, KEYTYPE itemKey, VALUETYPE itemValue> returns RETURNTYPE.

Returns:: A generator which returns each accumulated item in turn.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.reduceFrom()

allTrue

boolean static allTrue(any seq)

Checks whether all the items in the sequence are equal to true.

Logical 'AND' over a sequence of booleans.

Parameters:: seq - sequence<any> of booleans.

Returns:: A boolean which is true if there are no items in the seq that evaluate to false. True is returned for an empty sequence.

Since:: 10.15.3.0

anyTrue

boolean static anyTrue(any seq)

Checks whether at least one item in the sequence is equal to true.

Logical 'OR' over a sequence of booleans.

Parameters:: seq - sequence<any> of booleans.

Returns:: A boolean which is false if there are no items in the seq that evaluate to true. False is returned for an empty sequence.

Since:: 10.15.3.0

callAction

com.apama.functional.Partial static callAction(any actionToCall, any args)

Calls an instance/non-static action on an object (e.g. an event or built-in type) that is supplied later.

This is useful for using built-in EPL actions, for example:

Fn.filter(["Hello Alice", "Hello Bob"], Fn.callAction(string.matches, ["Hello Al.*"])) // ["Hello Alice"] 
Fn.map(["Hello Alice", "Hello Bob"], Fn.callAction(string.replaceAll, ["Hello", "Yo!"])) // ["Yo! Alice", "Yo! Bob"]

Parameters:: actionToCall - The (non-static/instance) action to call, as an action value (e.g. MyEvent.foo, string.replaceAll) or as a string (e.g. "replaceAll"). If a string is used (rather than an action value) the return type cannot be determined so is treated as if it returned any.; args - The sequence of arguments to that will be used to call the action on each object.

May be an empty any() (if no arguments), a single argument (not a sequence or dictionary), or a sequence of several arguments provided in the same order as the action signature.

If you wish to provide a single argument that is itself a sequence or an empty any, you must wrap it inside a [...] sequence.

Returns:: A partially bound function that can be executed later when objects containing an action of this name are supplied.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.map()

concat

string static concat(string lhs, string rhs)

Action which concatenates two strings. Intended for use with accumulate, reduce or map.

For non-functional concatenation, don't use this function - use the "+" operator, for example, string1+string2.

Parameters:: lhs - The left side of the concatenation.; rhs - The right side of the concatenation.

Returns:: The result of concatenating lhs and rhs.

Since:: 10.15.3.0

consume

any static consume(any generator, integer n)

Consumes a given number of items from a generator and discard them.

Parameters:: generator - The generator to step.; n - The number of times to step the generator.

Returns:: A reference to the original generator, stepped n times.

Since:: 10.15.3.0

count

com.apama.functional.Generator static count()

Returns a generator producing a sequence of integers that counts upwards from 0.

Returns:: A generator yielding integers of increasing size, beginning with 0.

Since:: 10.15.3.0

cycle

com.apama.functional.Generator static cycle(any seq)

Iterates through a sequence of items and continues looping forever.

Parameters:: seq - The sequence of values to iterate over.

Returns:: A generator which iterates over seq.

Since:: 10.15.3.0

even

boolean static even(integer i)

A predicate which returns true if the argument is even.

Parameters:: i - An integer to be evaluated.

Returns:: A boolean which is true if i is an even number and false if i is an odd number.

Since:: 10.15.3.0

fieldEqual

boolean static fieldEqual(any fieldName, any fieldValue, any object)

A predicate that returns true if the item has a field/key/entry with the given value.

Use with Fn.partial to provide the field name and field value.

This is equivalent to object.getEntry(fieldName) = fieldValue.

Parameters:: fieldName - The name of the field whose value should be compared to fieldValue.; fieldValue - The value with which the value of the field named fieldName should be compared.; object - The object with the field named fieldValue, for example an event or dictionary.

Returns:: A boolean which is true if the fieldName field of object equals fieldValue, and false if it is not.

Throws:: IllegalArgumentException if object does not have a field named fieldValue.

Since:: 10.15.3.0

filter

any static filter(any container, any func)

Filters the contents of a sequence, dictionary or generator using a boolean predicate function.

Example: Fn.filter(numbers, Fn.even) removes all odd numbers, leaving only even numbers.

Specifically, given:

sequence<TYPE> container and action<TYPE> returns boolean func will return sequence<TYPE> containing all the elements for which func returned true.
dictionary<KEYTYPE,VALUETYPE> container and action<KEYTYPE,VALUETYPE> returns boolean func will return dictionary<KEYTYPE,VALUETYPE> containing all the elements for which func returned true.
- If the func takes one parameter, the value is used to filter - otherwise, the key and value are passed as separate parameters to func, with the key coming first.
A generator returning TYPE and action<TYPE> returns boolean func will return a generator returning TYPE which only generates items from the original generator for which func returned true.

Parameters:: container - A sequence, dictionary, or generator.; func - A boolean predicate function.

Returns:: The container to be filtered using the predicate function.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.partial() - Use this for building your own predicate functions from existing actions.; com.apama.functional.Fn.isNot(); com.apama.functional.Fn.isTrue(); com.apama.functional.Fn.allTrue(); com.apama.functional.Fn.anyTrue(); com.apama.functional.Fn.even(); com.apama.functional.Fn.odd(); com.apama.functional.Fn.negative(); com.apama.functional.Fn.positive(); com.apama.functional.Fn.whole(); com.apama.functional.Fn.isEqual(); com.apama.functional.Fn.fieldEqual(); com.apama.functional.Fn.gt(); com.apama.functional.Fn.lt(); com.apama.functional.Fn.isEmpty()

generator

com.apama.functional.Generator static generator(any func)

Creates a generator that yields a series of values calculated by a function that returns the next value based on the previous value.

The start value will be the default value of the type the action returns. The result of the first generation will be the result of invoking func on that default-initialized value. To specify the initial value, use generateFrom.

Example: Fn.generator(Fn.increment) creates a generator of integer values with the default value for an integer, which is 0. Every call to generate() will increment the value by 1.

Parameters:: func - An action<TYPE> returns TYPE which takes the existing value and returns the next value.

Returns:: A generator for TYPE.

Since:: 10.15.3.0

generatorFrom

com.apama.functional.Generator static generatorFrom(any start, any func)

Creates a generator that yields a series of values calculated using a starting value and a function which returns the next value based on the previous value.

Example: Fn.generatorFrom(100, Fn.increment) creates a generator of integer values, starting at 100. Every call to generate() will increment the value by 1.

Parameters:: start - The value to pass to func to calculate the first generated value.; func - An action<TYPE> returns TYPE action which takes the existing value and returns the next value.

Returns:: A generator for TYPE.

Since:: 10.15.3.0

getAllEvents

sequence<listener> static getAllEvents(string valueEventName, dictionary<string, any> valueEventFields, string endEventName, dictionary<string, any> endEventFields, any onComplete)

Listens for events matching the specified fields and then calls an action with the received events once a terminating event arrives.

The behavior is the same as writing:

sequence<ValueEventName> seq; 
on all ValueEventName(fields=valueEventFields) as t1 and not (EndEventName(fields=endEventFields) { 
    seq.append(t1); 
} 
on EndEventName(fields=endEventFields) { 
    onComplete(seq); 
}

Parameters:: valueEventName - The name of the value event type.; valueEventFields - The fields in valueEventName to filter on.; endEventName - The event which signals all the valueEventNames have been received.; endEventFields - The fields in endEventName to filter on.; onComplete - An action<sequence<valueEventName>> to be called with all of the valueEventNames once endEventName has been received.

Returns:: A sequence of listeners suitable for passing to onTimeout.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.onTimeout()

Listens:: any -

getEntry

com.apama.functional.Partial static getEntry(any entryName)

Gets a named entry/field/key from an object (such as event or dictionary) that is supplied later.

Example:

Fn.map([
    Fn.setFields(new MyEvent, {"path": "/foo"}), 
    Fn.setFields(new MyEvent, {"path": "/bar"})
], Fn.getEntry("path"))
// = [any("/foo"), any("/bar")]

This is equivalent to calling object.getEntry(entryName).

Parameters:: entryName - The name of the entry to return.

Returns:: A partially bound function that can be executed later when the objects containing the field are supplied.

Throws:: IllegalArgumentException If the entryName is not found.

Since:: 10.15.3.0

See Also:: com.apama.util.AnyExtractor.create() - For an example of extracting deeply nested values from any items in a functional container.

gt

boolean static gt(any threshold, any number)

A predicate which returns true if the argument is greater than the given threshold number.

Parameters:: threshold - A numeric threshold against which to evaluate number.; number - An integer, float, or decimal to be evaluated against threshold.

Returns:: A boolean which is true if number is greater than threshold and false if number is less than or equal to threshold.

Since:: 10.15.3.0

increment

integer static increment(integer i)

Increments a given integer.

Parameters:: i - An integer.

Returns:: i plus one.

Since:: 10.15.3.0

isEmpty

boolean static isEmpty(any value)

A predicate which returns true if the any is empty, or contains a listener, string, optional, sequence or dictionary that is empty.

Parameters:: value - A value to check.

Returns:: A boolean which is true if value is empty and false if it is not.

Since:: 10.15.3.0

isEqual

boolean static isEqual(any value1, any value2)

A predicate which returns true if two values are equal according to the EPL = operator.

For example:

Fn.filter(["foo", "bar", "baz"], Fn.isNot(Fn.partial(Fn.isEqual, "bar"))); // = ["foo", "baz"]

Parameters:: value1 - A value to check. An exception nwill br thrown if this is not one of EPL's comparable types (for example comparing action or listener values is not permitted).; value2 - Another value to check. An exception nwill br thrown if this is not one of EPL's comparable types.

Returns:: A boolean which is true if both values are of the same type and

Since:: 10.15.3.0

isNot

action<any> returns boolean static isNot(any pred)

A predicate which inverts the value of another predicate.

Parameters:: pred - The input predicate.

Returns:: A predicate which, when called, calls the input predicate, and returns the inverse of the result.

Since:: 10.15.3.0

isTrue

boolean static isTrue(boolean b)

A predicate which returns true if the argument is true and false if it is false.

Parameters:: b - A boolean.

Returns:: A boolean that is true if the argument is true and false if it is false.

Since:: 10.15.3.0

listenForAnyOf

sequence<listener> static listenForAnyOf(any seq, string typeName, string fieldName, dictionary<string, any> otherFields, any arrivedAction)

Listens for events with a field matching any value from a given sequence, and calls an action when each one arrives (similar to an EPL "or" event expression).

The behavior is the same as writing:

on all ( TypeName(fieldName=seq[0], otherfields=...) or TypeName(fieldName=seq[1], otherfields=...) or ...) { arrivedAction(t); }

Parameters:: seq - sequence<any> of different values of fieldName to listen for, typically request or object identifiers.; typeName - The event type to listen for.; fieldName - The event field used to match the values, typically request or object identifiers.; otherFields - Names and values of any other event field values to match (the same in all listeners).; arrivedAction - The action to call for each matching event that arrives. The action must take a single argument to receive the matched event.

Returns:: The sequence of listeners created.

Since:: 10.15.3.0

lt

boolean static lt(any threshold, any number)

A predicate which returns true if the argument is less than the given threshold number.

Parameters:: threshold - A threshold against which to evaluate number.; number - An integer, float, or decimal to be evaluated against threshold.

Returns:: A boolean which is true if number is less than threshold and false if number is greater than or equal to threshold.

Since:: 10.15.3.0

map

any static map(any container, any func)

Applies a functor action that maps the current members of a sequence, values in a dictionary or output of a generator to new values.

Example: Fn.map(numbers, Fn.increment) increments all the elements in numbers by 1.

Specifically, given:

sequence<TYPEA> container and action<TYPEA> returns TYPEB func will return sequence<TYPEB> containing the result of running func on all the elements in container.
dictionary<KEYTYPE,VALUETYPEA> container and action<KEYTYPE,VALUETYPEA> returns VALUETYPEB func will return dictionary<KEYTYPE,VALUETYPEB> containing the keys from container with the values being the result of running func.

If the func takes one parameter, the value is used for mapping - otherwise, the key and value are passed as separate parameters to func, with the key coming first.

A generator returning TYPEA and action<TYPEA> returns TYPEB func will return a generator returning TYPEB where each item is the corresponding item from the original generator after running func.

Parameters:: container - A sequence, dictionary, or generator.; func - A functor action to be applied to the container, which takes as its argument an input value and returns the mapped value.

Returns:: A new container of the same type with elements generated by applying func to each member of container. If func performs some action but does not return anything (and is not a generator), it will still be called on all of the elements, but an empty any will be returned instead.

Since:: 10.15.3.0

See Also:: com.apama.functional.Functional.map() - Use the Functional version if you want to chain several different mapping operations on the same sequence.

mapKeys

any static mapKeys(any container, any func)

Applies a functor action that maps the current keys in a dictionary to new keys.

Example: Fn.mapKeys({0:"v0", 1:"v1"}, Fn.increment) increments the keys by 1 resulting in {1:"v0", 2:"v1"}

Specifically, given: dictionary<KEYTYPEA,VALUETYPE> container and action<KEYTYPEA,VALUETYPE> returns KEYTYPE func will return dictionary<KEYTYPEB,VALUETYPE> containing the keys being the result of running func and the values from container. If the func takes one parameter, the key is used for mapping - otherwise, the key and value are passed as separate parameters to func, with the key coming first.

Parameters:: container - A dictionary; func - A functor action to be applied to the container, which takes as its argument an input key or key and value and returns the mapped key.

Returns:: A new dictionary with keys generated by applying func to each member of container. If func performs some action but does not return anything, it will still be called on all of the elements, but an empty any will be returned instead.

Since:: 10.15.4.0

See Also:: com.apama.functional.Functional.mapKeys() - Use the Functional version if you want to chain several different mapping operations on the same container.

mean

action<any, any> returns any static mean()

Returns an action that can be used with accumulate or reduce to calculate the mean of the integers, floats or decimals in a sequence or output by a generator.

For example:

Fn.reduce([10, 20, 30], Fn.mean()); // Calculates the average of the values in the sequence = 20

There is no way to reset the underlying state so the action can only be used with a single sequence.

Example: integer mean := Fn.reduce(numbers, Fn.mean());

Returns:: An action that can be used with accumulate or reduce to calculate a mean.

Since:: 10.15.3.0

mul

any static mul(any number1, any number2)

Action that multiplies two values. It is intended for use with a sequence or generator of integers, floats or decimals using accumulate or reduce.

For non-functional multiplication, don't use this function - use the "*" operator, for example, number1*number2.

Example: integer product := Fn.reduce(numbers, Fn.mul); multiplies all the numbers in the sequence together.

Parameters:: number1 - An integer, float, or decimal.; number2 - A second value of the same type as number1.

Returns:: The product of number1 and number2.

Since:: 10.15.3.0

negative

boolean static negative(any number)

A predicate which returns true if the argument is negative.

Parameters:: number - An integer, float, or decimal to be evaluated.

Returns:: A boolean which is true if number is less than zero and false if number is greater than or equal to zero.

Since:: 10.15.3.0

odd

boolean static odd(integer i)

A predicate which returns true if the argument is odd.

Parameters:: i - An integer to be evaluated.

Returns:: A boolean which is true if i is an odd number and false if i is an even number.

Since:: 10.15.3.0

onTimeout

sequence<listener> static onTimeout(sequence<listener> ls, float timeout, any onTimeout)

Takes a sequence of listeners, waits for a given timeout and then if any of the listeners are still valid quits them and calls an action.

Equivalent to writing the following (plus handling for listeners having been quit first):

on wait (timeout) { for l in listeners { l.quit(); } onTimeout(); }

Note: the resulting wait listener will not be quit if the original listeners complete. It will quit once the timeout has expired. This function returns a list of all the listeners which it creates which can be quit by the user earlier if needed.

Parameters:: ls - The listeners to quit upon the timeout.; timeout - The number of seconds to wait before quitting the listeners.; onTimeout - The function to call if the listeners didn't all terminate before the timeout.

Returns:: A sequence of the wait listeners created by this function.

Since:: 10.15.3.0

partial

com.apama.functional.Partial static partial(any func, any args)

Partially specifies the arguments for an action, leaving the remaining argument(s) to be supplied later.

Binding the first one or more arguments results in a Partial holding an action with fewer (or zero) arguments than the original action. This partial action can later be executed with just the remaining arguments.

Partial objects can be passed to any of the other actions on Fn where an action would be expected.

Often it is useful to bind all arguments except the final one, which is then supplied by the values from a sequence (or other functional container). For example:

Fn.map(["Bob", "Alice"], Fn.partial(Fn.concat, "Hello ")) // produces a sequence of ["Hello Bob", "Hello Alice"]

If the bound arguments aren't the first arguments to the underlying function, then you can provide placeholders. These refer to the arguments of the resulting partial action and where they should be inserted into the bound arguments.

Example:

Fn.map(["Hi Bob", "Hi Alice"], Fn.partial(replaceString, [Fn.$(1), "Hi", "Hello"]))

Here, instead of the argument from map being passed as the final argument to replaceString it is inserted as the first argument, before the two literals provided to partial.

Parameters:: func - An action, or a previously-created Partial, to execute once all arguments are provided.; args - The arguments to store for later execution. May be an empty any() (if no arguments), a single argument (not a sequence or dictionary), or a sequence of several arguments provided in the same order as the action signature.

If you wish to provide a single argument that is itself a sequence or an empty any, you must wrap it inside a [...] sequence.

Returns:: A Partial that wraps func with the provided args.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.callAction() - For calling named actions on EPL built-in methods or event instance methods.; com.apama.functional.Fn.$() - A function to provide placeholders which can appear in args.

positive

boolean static positive(any number)

A predicate which returns true if the argument is positive (not including 0).

Parameters:: number - An integer, float, or decimal to be evaluated.

Returns:: A boolean which is true if number is greater than zero and false if number is less than or equal to zero.

Since:: 10.15.3.0

quantify

integer static quantify(any container, any pred)

Quantifies (counts) the number of times a predicate is true for the values of a sequence or dictionary.

Example: Fn.quantify(numbers, Fn.even) will return the amount of even numbers in the sequence.

Parameters:: container - A sequence or dictionary.; pred - A predicate action<TYPE> that returns boolean.

Returns:: The number of values in the container for which the predicate returns true.

Since:: 10.15.3.0

quit

listener static quit(listener l)

Terminates a listener by calling quit() on it.

Parameters:: l - The listener on which to call the quit() action.

Returns:: The listener after quit() has been called on it.

Since:: 10.15.3.0

random

com.apama.functional.Generator static random(any limit)

Returns a generator producing uniform random numbers between 0 (inclusive) and limit (exclusive).

Caution: This random number generator is not cryptographically strong. Therefore, it should not be used for purposes where a strong random number is required.

Parameters:: limit - The generated numbers will be less than this number.

Returns:: A generator producing random numbers between 0 (inclusive) and limit (exclusive).

Since:: 10.15.3.0

range

sequence<integer> static range(integer start, integer end, integer stride)

Returns a sequence of integers from start (inclusive) to end (exclusive), incrementing by stride each time.

Parameters:: start - The first number to return.; end - The number after the last one to return, equal to the last number plus the stride.; stride - How much greater each subsequent element of the sequence should be from the last.

Returns:: A sequence<integer> containing an arithmetic sequence from start to end minus one, incrementing by stride.

Since:: 10.15.3.0

reduce

any static reduce(any container, any func)

Returns a single value resulting from applying an accumulator function to every item in the container.

Example: Fn.reduce(numbers, Fn.sum) returns the result of adding all the numbers in the sequence together.

Specifically, given:

sequence<ITEMTYPE> container and action<RETURNTYPE,ITEMTYPE> returns RETURNTYPE func will return the final RETURNTYPE after calling func on each value, retaining RETURNTYPE each time.
dictionary<KEYTYPE,VALUETYPE> container and action<RETURNTYPE,KEYTYPE,VALUETYPE> returns RETURNTYPE func will return the final RETURNTYPE after calling func on each key and value, retaining RETURNTYPE each time.

func will always take the accumulated value as the first parameter, with a minimum of two parameters required. If there are only two parameters, the second parameter will be the value. If there are three, the second parameter will be the key, and the third parameter the value.

Parameters:: container - A sequence or dictionary.; func - An action which accumulates each item in turn and returns the new value. The signature should be either action<RETURNTYPE accumulatedValue, ITEMTYPE item> returns RETURNTYPE, or (for dictionaries) action<RETURNTYPE accumulatedValue, KEYTYPE itemKey, VALUETYPE itemValue> returns RETURNTYPE.

Returns:: The final result generated by the accumulator function.

Since:: 10.15.3.0

reduceFrom

any static reduceFrom(any accumulator, any container, any func)

Returns the accumulated value resulting from successive application of an accumulator function to each of the members of a sequence or dictionary.

Example: Fn.reduceFrom(42, numbers, Fn.sum)

Specifically, given:

sequence<ITEMTYPE> container and action<RETURNTYPE,ITEMTYPE> returns RETURNTYPE func will return the final RETURNTYPE after calling func on each value, retaining RETURNTYPE each time.
dictionary<KEYTYPE,VALUETYPE> container and action<RETURNTYPE,KEYTYPE,VALUETYPE> returns RETURNTYPE func will return the final RETURNTYPE after calling func on each key and value, retaining RETURNTYPE each time.

func will always take the accumulated value as the first parameter, with a minimum of two parameters required. If there are only two parameters, the second parameter will be the value. If there are three, the second parameter will be the key, and the third parameter the value.

Parameters:: accumulator - The initial value of the running accumulation, which can be used to continue a previous calculation.; container - A sequence or dictionary.; func - An action which accumulates each item in turn and returns the new value. The signature should be either action<RETURNTYPE accumulatedValue, ITEMTYPE item> returns RETURNTYPE, or (for dictionaries) action<RETURNTYPE accumulatedValue, KEYTYPE itemKey, VALUETYPE itemValue> returns RETURNTYPE.

Returns:: The final result generated by the accumulator function.

Since:: 10.15.3.0

repeat

com.apama.functional.Generator static repeat(any item)

Repeats the given element forever.

Parameters:: item - The item to return.

Returns:: A generator which returns item repeatedly.

sendToChannel

any static sendToChannel(string channel, any evt)

Helper that sends an event to a channel and returns it (for use when setting up response listeners).

This is useful for implementing request/response protocols where you need to provide a unique identifier in both the request event and the response listener. Using this helper avoids the need to store the event or request identifier in an intermediate variable.

For example:

on MyResponse(reqId=<integer> Fn.sendToChannel(MyEvent.SEND_CHANNEL, 
    Fn.setFields(new MyEvent, [createRequestId(), "/myrequest"])
).getEntry("reqId")) as response { ... }

// or to specify argument by name rather than by position:
on MyResponse(reqId=<integer> Fn.sendToChannel(MyEvent.SEND_CHANNEL, Fn.setFields(new MyEvent, {
    "reqId": createRequestId(), 
    "path": "/myrequest", 
    "method": "GET"
})).getEntry("reqId") ) as response {... }

Parameters:: channel - The channel to send the event to.; evt - An event instance, typically initialized using setFields.

Returns:: A reference to the original event, modified with the specified fields.

See Also:: com.apama.functional.Fn.setFields()

Sends:: any -

sequenceOf

any static sequenceOf(any item, integer n)

Returns a sequence containing the given item n times.

Parameters:: item - The element to put in the sequence.; n - The number of times to repeat the element.

Returns:: A sequence<ITEMTYPE> with n items in it.

Since:: 10.15.3.0

setEntry

com.apama.functional.Partial static setEntry(any entryName, any entryValue)

Sets a named entry/field/key to an object (such as event or dictionary) that is supplied later.

Example:

Fn.map(sequenceOfEvents, Fn.setEntry("method", "POST")) // Returns sequenceOfEvents, having modified the "method" field of each event in-place

This is equivalent to calling object.setEntry(entryName, entryValue). The objects are modified in-place, not copied.

Parameters:: entryName - The name of the entry/field/key to set.; entryValue - The value to set it to.

Returns:: A partially bound function that can be executed later when the objects containing the field are supplied.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.setFields() - For setting multiple fields/entries in an event at the same time.

setFields

any static setFields(any evt, any fields)

Helper that initializes one or more of the fields in an event, either by field name or by position.

This is especially useful for initializing large events where you may only care about setting the first few fields, or where specifying the fields by name is more readable than a long comma-separated list.

For example:

myevt := <MyEvent>Fn.setFields(new MyEvent, [createRequestId(), "/myrequest"]);
myevt := <MyEvent>Fn.setFields(new MyEvent, {
    "reqId": createRequestId(), 
    "path": "/myrequest", 
    "method": "GET"
});

Parameters:: evt - An event instance.; fields - An ordered sequence of field values, a dictionary where each key is a field name. It is also possible to set just the first field by providing a non-sequence/dictionary value.

Returns:: A reference to the original event, modified with the specified fields.

See Also:: com.apama.functional.Fn.sendToChannel()

slice

any static slice(any container, integer start, integer end)

Returns a given section of a sequence. If a generator is supplied, it is immediately invoked the required number of times.

Example: Fn.slice([1,2,3,4,5], 2, 4); // returns [3,4]

Parameters:: container - A sequence<TYPE> or a generator which can be used to produce a sequence of values of type TYPE.; start - The index of the first element to return.; end - The index of the last element to return (negative values permitted only for sequences).

Returns:: A sequence<TYPE> containing the selected values from container.

Since:: 10.15.3.0

sliceFrom

any static sliceFrom(any container, integer start)

Returns a given section of a sequence, from start to the last element.

Example: Fn.sliceFrom([1,2,3,4, 5], 1); // returns [2,3,4,5]

Warning: This is a wrapper around slice, where the end value is integer.MAX. If you pass a generator to this function, it will generate integer.MAX (2⁶³-1) values.

Parameters:: container - A sequence<TYPE> or a generator which can be used to produce a sequence of values of type TYPE.; start - The index of the first element to return.

Since:: 10.15.3.0

sliceTo

any static sliceTo(any container, integer end)

Returns a section of a sequence, from the beginning to end.

Example: Fn.sliceTo([1,2,3,4,5], 4); // returns [1,2,3,4]

Parameters:: container - A sequence<TYPE> or a generator which can be used to produce a sequence of values of type TYPE.; end - The index of the last element to return.

Since:: 10.15.3.0

stride

any static stride(any container, integer gap)

Returns the result of iterating through the sequence, incrementing by gap each time.

Example:

sequence<integer> num := [0,1,2,3,4];
Fn.stride(num, 2); // returns [0,2,4]

Parameters:: container - A sequence<TYPE>.; gap - The amount to increment through.

Returns:: A sequence generated by iterating through the sequence, incrementing by gap.

Since:: 10.15.3.0

sum

any static sum(any number1, any number2)

Action that calculates the sum of two values. It is intended for use with a sequence or generator of integers, floats or decimals using accumulate or reduce.

For basic addition, don't use this function - use the "+" operator, for example, number1+number2.

Example: integer sum := Fn.reduce(numbers, Fn.sum);

Parameters:: number1 - An integer, float, or decimal.; number2 - A second value of the same type as number1.

Returns:: The sum of number1 and number2.

Since:: 10.15.3.0

toType

com.apama.functional.Partial static toType(string typeName)

Converts items in a container to the specified type using a cast or toString conversion.

This is useful when you have a sequence<any> containing values of the same type and need a sequence<TYPE>:

Fn.map([123, 456], Fn.toType("integer")) // returns [123, 456]

This is also useful when you want to convert all the values in a sequence to strings from whatever type(s) they currently are:

" and ".join(<sequence<string>> Fn.map([123, 45.6, "hello"], Fn.toType("string"))) // returns "123 and 45.6 and hello"

Parameters:: typeName - The name of the type to convert to. If this is "string" then the any.valueToString method will be used to convert each item. For all other types (e.g. "integer") a simple type cast is performed so an exception will be raised for any item that is not of the specified type.

Returns:: A Partial object that can be passed to map() to apply the conversion to all items in a container.

See Also:: com.apama.functional.Fn.map(); com.apama.functional.Functional.map()

waitForAllCompleted

sequence<listener> static waitForAllCompleted(any seq, string typeName, string fieldName, any onCompleted)

Listens for events with a field matching every value from a given sequence, and calls a completion action when all have arrived (similar to an EPL "and" event expression).

The behavior is the same as writing:

on TypeName(fieldName=seq[0]) and TypeName(fieldName=seq[1]) and ... { onCompleted(); }

Parameters:: seq - sequence<any> of values (typically request or object identifiers) to wait for.; typeName - The type of event to wait for.; fieldName - The event field used to match the values.; onCompleted - A zero argument action<> to be called if all the events arrive.

Returns:: A sequence of listeners suitable for passing to onTimeout.

Since:: 10.15.3.0

See Also:: com.apama.functional.Fn.onTimeout()

Listens:: any -

whole

boolean static whole(any number)

A predicate which returns true if the argument is a whole number.

Parameters:: number - An integer, float, or decimal to be evaluated.

Returns:: A boolean which is true if number has no fractional part. If number is an integer, this function will always return true.

Since:: 10.15.3.0

com.apama.functionalEvent Fn

$