FRAMES    NO FRAMES    
Overview  PackageDeprecated  Help  API Reference for EPL (ApamaDoc) 10.15.5.3
SUMMARY: IMPORT | CONSTANT | FIELD | ACTIONDETAIL: IMPORT | CONSTANT | FIELD | ACTION

com.apama.functional
Event Functional

Holds a sequence, dictionary or generator and provides fluent-style actions to perform functional operations on the contents.

Contains instance methods for operators and static methods for creation, all of which return values wrapped in a Functional for further calls. The underlying value can be retrieved at the end of the chain with the get action.

The functor and predicate actions provided by Fn can be used. You can create a Functional either using one of the static methods, or by wrapping a sequence, dictionary or generator directly.

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 on this event and on the Fn event.
Since:
10.15.3.0
See Also:
com.apama.functional.Functional.get() - Call this to get the final calculated value/container from a Functional.

com.apama.functional.Functional.filter() - A functional operator that filters the container to one only including items where the provided predicate is true.
com.apama.functional.Functional.map() - A functional operator that maps each item in the container to a new value, using the supplier functor.
com.apama.functional.Functional.reduce() - A functional operator that reduces all items in the container down to a single value.
com.apama.functional.Functional.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.Functional.waitForAllCompleted() - A functional operator that calls an action when a set of events have arrived.
com.apama.functional.Functional.getAllEvents() - A functional operator that calls an action with a set of events once a terminating event arrives.
Action summary
 com.apama.functional.Functionalstatic count()

Returns a generator producing a sequence of integers that counts upwards from 0.
 com.apama.functional.Functionalstatic cycle(any seq)

Loops perpetually over a sequence of items, returning the next element of the sequence.
 com.apama.functional.Functionalstatic generator(any func)

Creates a generator from a function which takes as an input the current value and returns the next value.
 com.apama.functional.Functionalstatic generatorFrom(any start, any func)

Creates a generator from a function which takes as an input the current value and returns the next value.
 com.apama.functional.Functionalstatic 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.Functionalstatic random(any limit)

Returns a Functional generator producing uniform random numbers between 0 (inclusive) and limit (exclusive).
 com.apama.functional.Functionalstatic range(integer start, integer end, integer stride)

Returns a Functional yielding the sequence of integers from start (inclusive) to end (exclusive), incrementing by stride each time.
 com.apama.functional.Functionalstatic repeat(any item)

Returns a generator that perpetually repeats the given value.
 com.apama.functional.Functionalstatic sequenceOf(any item, integer n)

Returns a sequence comprising the given value repeated a given number of times.
 com.apama.functional.Functionalaccumulate(any func)

Returns a generator which accumulates over the underlying container, returning the result after accumulating each item.
 com.apama.functional.FunctionalaccumulateFrom(any start, any func)

Returns a generator which accumulates over the underlying container, returning the result after accumulating each item.
 com.apama.functional.Functionalconsume(integer n)

Consumes a given number of items from the contained generator and discard them.
 com.apama.functional.Functionalfilter(any func)

Filters the contents using a boolean predicate func.
 anygenerate()

If this Functional is wrapping a generator, generate one item with the underlying generator and return it.
 anyget()

Returns the wrapped container.
 com.apama.functional.FunctionallistenForAnyOf(string typeName, string fieldName, dictionary<string, any> otherFields, any arrivedAction)

Listens for events with a field matching any value from this Functional sequence, and calls an action when each one arrives (similar to an EPL "or" event expression).
 com.apama.functional.Functionalmap(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.
 com.apama.functional.FunctionalmapKeys(any func)

Applies a functor action that maps the current keys in a dictionary to new keys.
 voidonTimeout(float timeout, any onTimeout)

Waits for a given timeout and then if any of the listeners from this Functional are still valid, quits them and calls an action.
 integerquantify(any pred)

Counts how many times a predicate is true for the values of a sequence or dictionary. Works on a sequence or a dictionary. The result is an actual value, not a Functional, since it's no longer a container.
 anyreduce(any func)

Returns a single value resulting from applying an accumulator function to every item in the container.
 com.apama.functional.Functionalslice(integer start, integer end)

Returns a given sub-range as a finite sequence.
 com.apama.functional.FunctionalsliceFrom(integer start)

Returns a given sub-range as a finite sequence.
 com.apama.functional.FunctionalsliceTo(integer end)

Returns a given sub-range as a finite sequence, from the beginning of the sequence/generator to the specified end value.
 com.apama.functional.Functionalstride(integer gap)

Returns the result of iterating through the sequence, incrementing by gap each time.
 com.apama.functional.FunctionalwaitForAllCompleted(string typeName, string fieldName, any onCompleted)

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

count

com.apama.functional.Functional static count()
Returns a generator producing a sequence of integers that counts upwards from 0.
Returns:
A Functional generator.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.count()

cycle

com.apama.functional.Functional static cycle(any seq)
Loops perpetually over a sequence of items, returning the next element of the sequence.
Parameters:
seq - The sequence of values over which to iterate.
Returns:
A generator which iterates over seq, wrapped in a Functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.cycle()

generator

com.apama.functional.Functional static generator(any func)
Creates a generator from a function which takes as an input the current value and returns the next value.

The initial value will be a default-initialized TYPE and 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: Functional.generator(Fn.increment) creates a generator 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 action which takes the previous value and returns the next value.
Returns:
A generator for TYPE, wrapped in a Functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.generator()

generatorFrom

com.apama.functional.Functional static generatorFrom(any start, any func)
Creates a generator from a function which takes as an input the current value and returns the next value.

Example: Functional.generatorFrom(100, Fn.increment)
Parameters:
start - The value to pass to func to generate the first generation.
func - An action<TYPE> returns TYPE action which takes the existing value and returns the next value.
Returns:
A generator for TYPE, wrapped in a functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.generator()

getAllEvents

com.apama.functional.Functional 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 type of the event containing the value.
valueEventFields - The fields in valueEventName to filter on.
endEventName - The event whose arrival signals that all of the valueEventName events have been received.
endEventFields - The fields in endEventName to filter on.
onComplete - An action<sequence<any>> to be called with each of the valueEventName events once endEventName has been received.
Returns:
A Functional containing a sequence of listeners whose onTimeout action can be called.
Since:
10.15.3.0
See Also:
com.apama.functional.Functional.onTimeout()
com.apama.functional.Fn.getAllEvents()

random

com.apama.functional.Functional static random(any limit)
Returns a Functional 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 random number generator.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.random()

range

com.apama.functional.Functional static range(integer start, integer end, integer stride)
Returns a Functional yielding the 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 generator for the sequence.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.range()

repeat

com.apama.functional.Functional static repeat(any item)
Returns a generator that perpetually repeats the given value.
Parameters:
item - The item to return.
Returns:
A generator which perpetually returns item, wrapped in a Functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.repeat()

sequenceOf

com.apama.functional.Functional static sequenceOf(any item, integer n)
Returns a sequence comprising the given value repeated a given number of 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, wrapped in a Functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.sequenceOf()

accumulate

com.apama.functional.Functional accumulate(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:
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, wrapped in a Functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.accumulate()

accumulateFrom

com.apama.functional.Functional accumulateFrom(any start, 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.
Parameters:
start - The initial value of the accumulator; must have the same type as func's return type (RETURNTYPE).
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, wrapped in a Functional.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.accumulateFrom()

consume

com.apama.functional.Functional consume(integer n)
Consumes a given number of items from the contained generator and discard them.

Only works on generators.
Parameters:
n - The number of times to step the generator.
Returns:
This Functional operator with the generator stepped n times.
Since:
10.15.3.0

filter

com.apama.functional.Functional filter(any func)
Filters the contents using a boolean predicate func.

Works on a dictionary, sequence or generator.

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

The semantics are the same as Fn.filter.
Parameters:
func - A boolean predicate function.
Returns:
A Functional container filtered using the predicate function.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.filter() - This also lists some common predicates that can be used with this function.

generate

any generate()
If this Functional is wrapping a generator, generate one item with the underlying generator and return it.

Only works on generators.
Returns:
The next item from the wrapped generator.
Since:
10.15.3.0
See Also:
com.apama.functional.Generator.generate()

get

any get()
Returns the wrapped container.

You may need to cast the resulting any to another type. If the result is a sequence/dictionary container that itself holds any and you need a sequence of a different type, you can use the toType helper to map each contained item to the desired type: For example: 
sequence<any> values := <sequence<any>> Functional(...).get();
sequence<string> strings := <sequence<string>> Functional(...).map(toType("string")).get();
Returns:
The underlying container held by this Functional, typically a sequence, dictionary or Generator.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.toType()

listenForAnyOf

com.apama.functional.Functional listenForAnyOf(string typeName, string fieldName, dictionary<string, any> otherFields, any arrivedAction)
Listens for events with a field matching any value from this Functional 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:
typeName - The event type to listen for.
fieldName - The name of the field which each listener will attempt to match with their respective anticipated value from this Functional sequence, for example a request or object identifier.
otherFields - Names and values of other fields which will be the same for each listener and should also be used for filtering events.
arrivedAction - The action to call for each matching event that arrives. The action must take a single argument to receive the matched event.
Returns:
A generator for the sequence of listeners.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.listenForAnyOf()

map

com.apama.functional.Functional map(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: numbers.map(Fn.partial(Fn.map, 2)) doubles all numbers in the sequence.

Specifically, given:

The semantics are the same as Fn.map.
Parameters:
func - A functor action to be applied to this container, which takes as its argument an input value and returns the mapped value. 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.
Returns:
A Functional holding a container of the same type with all the values run through func.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.map()
com.apama.util.AnyExtractor.create() - For an example of extracting deeply nested values from any items in a functional container.

mapKeys

com.apama.functional.Functional mapKeys(any func)
Applies a functor action that maps the current keys in a dictionary to new keys.

Example: Functional({0:"v0", 1:"v1"}).mapKeys(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.

The semantics are the same as Fn.map.
Parameters:
func - A functor action to be applied to this container, which takes as its argument an input key or key and value and returns the mapped key.
Returns:
A Functional holding 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.Fn.mapKeys()
com.apama.util.AnyExtractor.create() - For an example of extracting deeply nested values from any items in a functional container.

onTimeout

void onTimeout(float timeout, any onTimeout)
Waits for a given timeout and then if any of the listeners from this Functional are still valid, quits them and calls an action.

Equivalent to writing (with handling for listeners having previously been quit):

on wait (timeout) { for l in listeners { l.quit(); } onTimeout(); }
Parameters:
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.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.onTimeout()

quantify

integer quantify(any pred)
Counts how many times a predicate is true for the values of a sequence or dictionary. Works on a sequence or a dictionary. The result is an actual value, not a Functional, since it's no longer a container.

Example: numbers.quantify(Fn.even) will return the amount of even numbers in the sequence.
Parameters:
pred - An action that returns boolean.
Returns:
The number of values in the container for which the predicate returns true.

reduce

any reduce(any func)
Returns a single value resulting from applying an accumulator function to every item in the container.

Works on a sequence or a dictionary. The result is the actual value, not a Functional, since it's no longer a container.

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

The semantics are the same as Fn.reduce.
Parameters:
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 of the accumulator function.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.reduce()

slice

com.apama.functional.Functional slice(integer start, integer end)
Returns a given sub-range as a finite sequence.

Works on a sequence or generator. If it is a generator, it is immediately called enough times to satisfy the slice.

Example: Functional([1,2,3,4,5]).slice(2, 4); // returns [3,4]
Parameters:
start - The first item to return.
end - The last item to return (negative values permitted only for sequences).
Returns:
A Functional containing the selected range of values.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.slice()

sliceFrom

com.apama.functional.Functional sliceFrom(integer start)
Returns a given sub-range as a finite sequence.

Works on a sequence or generator. If it is a generator, it will invoke the generator sufficient times immediately to satisfy the slice.

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

Warning: This is a wrapper around Fn.slice, where the end value is integer.MAX. If you pass a generator to this function, it will generate integer.MAX (263-1) values.
Parameters:
start - The first item to return.
Returns:
A Functional containing the selected range of values.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.sliceFrom()

sliceTo

com.apama.functional.Functional sliceTo(integer end)
Returns a given sub-range as a finite sequence, from the beginning of the sequence/generator to the specified end value.

Works on a sequence or generator. If it is a generator, it is immediately called enough times to satisfy the slice.

Example: Functional([1,2,3,4,5]).sliceTo(4); // returns [1,2,3,4]
Parameters:
end - The last item to return (negative values permitted only for sequences).
Returns:
A Functional containing the selected range of values.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.sliceTo()

stride

com.apama.functional.Functional stride(integer gap)
Returns the result of iterating through the sequence, incrementing by gap each time.

Example: Functional([0,1,2,3,4]).stride(2); // returns [0,2,4]
Parameters:
gap - The amount to increment through.
Returns:
A Functional containing the sequence generated by iterating through the sequence, incrementing by gap.
Since:
10.15.3.0
See Also:
com.apama.functional.Fn.stride()

waitForAllCompleted

com.apama.functional.Functional waitForAllCompleted(string typeName, string fieldName, any onCompleted)
Listens for events with a field matching each value from this Functional 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 ... and not wait(timeout) { onCompleted(); }

Call the onTimeout() action when timeout behaviour such as the above is desired.
Parameters:
typeName - The type of event to wait for.
fieldName - The name of the field which each listener will attempt to match with their respective anticipated value from this Functional sequence, for example a request or object identifier.
onCompleted - A zero argument action<> to be called if all of the events arrive within the timeout.
Returns:
A Functional containing a sequence of listeners on which onTimeout can be called.
Since:
10.15.3.0
See Also:
com.apama.functional.Functional.onTimeout()
com.apama.functional.Fn.waitForAllCompleted()
FRAMES    NO FRAMES    
Overview  PackageDeprecated  Help  API Reference for EPL (ApamaDoc) 10.15.5.3
SUMMARY: IMPORT | CONSTANT | FIELD | ACTIONDETAIL: IMPORT | CONSTANT | FIELD | ACTION