testbox.system.modules.cbstreams.models

Class Stream

lucee.Component
    extended by testbox.system.modules.cbstreams.models.Stream

This is a transient class that models a Java Stream: https://docs.oracle.com/javase/8/docs/api/?java/util/stream/Stream.html

Class Attributes:
  • synchronized : false
  •  
  • accessors : true
  •  
  • persistent : false
  •  
    Property Summary
    type property default serializable required
    any jStream
          The Java Stream we represent.

    • access = public
    • returntype = any
    true false
    any jType
          If this stream has a specific Java Type, defaults to "" or any.

    • access = public
    • returntype = any
    any true false
    Constructor Summary
    init([any collection=''], [any isNumeric='false'], [any primitive=''])
          Construct a stream from an incoming collection.
    Method Summary
    boolean allMatch(any predicate)
         Returns whether all elements of this stream match the provided predicate.
    boolean anyMatch(any predicate)
         Returns whether any elements of this stream match the provided predicate.
    Optional average()
         Returns an Optional describing the average of the elements of this stream, or a null if this stream is empty.
    Builder builder()
         Returns a builder for a Stream.
    void close()
         Only use this method for closing streams that require IO resources.
    any collect()
         A mutable reduction operation that accumulates input elements into a mutable result container, optionally transforming the accumulated result into a final representation after all input elements have been processed.
    any collectAsList([any delimiter=','], [any prefix=''], [any suffix=''])
         Collect the items to a string list using delimiters and/or a prefix and suffix.
    any collectAsStruct(any keyID, any valueID, [boolean overwrite='true'])
         Collect the items to a struct.
    any collectAverage(any mapper, [any primitive='long'])
         Returns a Collector that produces the arithmetic mean of an integer-valued function applied to the input elements.
    any collectGroupingBy(any classifier)
         Returns a Collector implementing a "group by" operation on input elements, grouping elements according to a.
    any collectPartitioningBy(any predicate)
         Returns a Collector which partitions the input elements according to a Predicate, and organizes them into a Map>.
    any collectSum(any mapper, [any primitive='long'])
         Returns a Collector that produces the sum of a valued function applied to the input elements.
    any collectSummary(any mapper, [any primitive='long'], [boolean returnNative='false'])
         Returns a Collector which applies an producing mapping function to each input element, and.
    Stream concat(any a, any b)
         Creates a lazily concatenated stream whose elements are all the elements of the first stream followed by all the elements of.
    numeric count()
         Returns the count of elements in this stream.
    private any createPrimitiveProxyFunction(any f, any primitive)
         Create a primitive typed proxy function.
    Stream distinct()
         Returns a stream consisting of the distinct elements (according to Object.
    Stream empty()
         Returns an empty sequential Stream.
    Stream filter(any predicate)
         Returns a stream consisting of the elements of this stream that match the given predicate.
    Optional findAny()
         Returns an Optional describing some element of the stream, or an empty Optional if the stream is empty.
    Optional findFirst()
         Returns an Optional describing the first element of this stream, or an empty Optional if the stream is empty.
    void forEach(any action)
         Performs an action for each element of this stream.
    void forEachOrdered(any action)
         Performs an action for each element of this stream, in the encounter order of the stream if the stream has a defined encounter order.
    Stream generate(any supplier)
         Returns an infinite sequential unordered stream where each element is generated by the provided Supplier.
    string getJStream()
    string getJType()
    private any getNativeStatsStruct(any stats)
         Build a stats structure from a Java SummaryStatistics Object.
    private any getStrongTypePrefix()
         Return the strong type prefix for classes according to types.
    boolean isParallel()
         Returns whether this stream, if a terminal operation were to be executed, would execute in parallel.
    private boolean isStrongTyped()
         Check if this stream is strong typed.
    any iterator()
         Returns an iterator for the elements of this stream.
    Stream limit(numeric maxSize)
         Returns a stream consisting of the elements of this stream, truncated to be no longer than maxSize in length.
    Stream map(any mapper)
         Returns a stream consisting of the results of applying the given function to the elements of this stream.
    Optional max([any comparator])
         Returns an numeric describing the maximum element of this stream, or a null if this stream is empty.
    Optional min([any comparator])
         Returns an numeric describing the minimum element of this stream, or a null if this stream is empty.
    boolean noneMatch(any predicate)
         Returns whether no elements of this stream match the provided predicate.
    Stream of()
         Returns a sequential ordered stream whose elements are the specified values.
    Stream ofChars(string target)
         Create a character stream from a string.
    Stream ofFile(string path, [any encoding='UTF-8'])
         Create a stream from a file.
    Stream onClose(any closeHandler)
         Returns an equivalent stream with an additional close handler.
    Stream parallel()
         Returns an equivalent stream that is parallel.
    Stream peek(any action)
         Returns a stream consisting of the elements of this stream, additionally performing the provided action on each element as elements are consumed from the resulting stream.
    Stream range(numeric start, numeric end)
         Returns a sequential ordered LongStream from start (inclusive) to end (exclusive) by an incremental step of 1.
    Stream rangeClosed(numeric start, numeric end)
         Returns a sequential ordered LongStream from start (inclusive) to end (inclusive) by an incremental step of 1.
    any reduce(any accumulator, [any identity])
         Performs a reduction on the elements of this stream.
    Stream sequential()
         Returns an equivalent stream that is sequential.
    any setJStream(any jStream)
    any setJType(any jType)
    Stream skip(numeric n)
         Returns a stream consisting of the remaining elements of this stream after discarding the first n elements of the stream.
    Stream sorted([any comparator])
         Returns a stream consisting of the elements of this stream, sorted according to natural order.
    any spliterator()
         Returns a spliterator for the elements of this stream.
    struct summaryStatistics([boolean returnNative='false'])
         Returns a Summary describing various summary data about the elements in this stream.
    any toArray()
         Returns an array containing the elements of this stream.
    Stream unordered()
         Returns an equivalent stream that is unordered.
     
    Methods inherited from class lucee.Component
    None

    Constructor Detail

    init

    public init([any collection=''], [any isNumeric='false'], [any primitive=''])

    Construct a stream from an incoming collection. The supported types are: structs, arrays, lists, and strings. You can also strong type the stream according to the predicate argument. This is useful when doing mathematical operations on the stream.

    Parameters:
    collection - This is an optional collection to build a stream on: List, Array, Struct, Query
    isNumeric - This is a shorthand for doing a numeric typed array of values. This will choose a long stream for you by default.
    primitive - If you will be doing operations on the stream, you can mark it with a primitive type of: int, long or double. Else we will use generic object streams

    Property Detail

    jStream

    property any jStream

    The Java Stream we represent

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    jType

    property any jType = [any]

    If this stream has a specific Java Type, defaults to "" or any

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    Method Detail

    allMatch

    public boolean allMatch(any predicate)

    Returns whether all elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then true is returned and the predicate is not evaluated. This is a terminal operation.

    Parameters:
    predicate - a non-interfering, stateless predicate to apply to elements of this stream

    anyMatch

    public boolean anyMatch(any predicate)

    Returns whether any elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then false is returned and the predicate is not evaluated. This is a terminal operation.

    Parameters:
    predicate - a non-interfering, stateless predicate to apply to elements of this stream

    average

    public Optional average()

    Returns an Optional describing the average of the elements of this stream, or a null if this stream is empty. This can only be done with int, long, or double typed streams This is a terminal operation.


    builder

    public Builder builder()

    Returns a builder for a Stream. So you can build a stream manually by calling on the builder's add() method.


    close

    public void close()

    Only use this method for closing streams that require IO resources


    collect

    public any collect()

    A mutable reduction operation that accumulates input elements into a mutable result container, optionally transforming the accumulated result into a final representation after all input elements have been processed. By default we will collect to an array. This is a terminal operation.


    collectAsList

    public any collectAsList([any delimiter=','], [any prefix=''], [any suffix=''])

    Collect the items to a string list using delimiters and/or a prefix and suffix. The cool things is that you don't even need to know the start or end of the stream for applying the prefix and suffix This is a terminal operation.

    Parameters:
    delimiter - The delimiter to use in the list. The default is a comma (,)
    prefix - A prefix to add to the stream result
    suffix - A suffix to add to the stream result

    collectAsStruct

    public any collectAsStruct(any keyID, any valueID, [boolean overwrite='true'])

    Collect the items to a struct. Please be sure to map the appropriate key and value identifiers NOTE: the struct type will only work if the collection we are collecting is a struct or an object This is a terminal operation.

    Parameters:
    keyID - If using struct, then we need to know what will be the key value in the collection struct
    valueID - If using struct, then we need to know what will be the value key in the collection struct
    overwrite - If using struct, then do you overwrite elements if the same key id is found. Defaults is true.

    collectAverage

    public any collectAverage(any mapper, [any primitive='long'])

    Returns a Collector that produces the arithmetic mean of an integer-valued function applied to the input elements. If no elements are present, the result is 0.

    Parameters:
    mapper - The mapper lambda or closure to determine averages on
    primitive - The primitive type to cast with, we default to 'long'. Accepted values are int, long, double

    collectGroupingBy

    public any collectGroupingBy(any classifier)

    Returns a Collector implementing a "group by" operation on input elements, grouping elements according to a classification function, and returning the results in a struct according to the classifier function

    Parameters:
    classifier - the classifier function mapping input elements to keys

    collectPartitioningBy

    public any collectPartitioningBy(any predicate)

    Returns a Collector which partitions the input elements according to a Predicate, and organizes them into a Map>.

    Parameters:
    predicate - a non-interfering, stateless predicate to apply to each element to determine if it should be included

    collectSum

    public any collectSum(any mapper, [any primitive='long'])

    Returns a Collector that produces the sum of a valued function applied to the input elements.

    Parameters:
    mapper - The mapper lambda or closure to determine the sum on
    primitive - The primitive type to cast with, we default to 'long'. Accepted values are int, long, double

    collectSummary

    public any collectSummary(any mapper, [any primitive='long'], [boolean returnNative='false'])

    Returns a Collector which applies an producing mapping function to each input element, and returns summary statistics for the resulting values as a struct with the following keys: average, count, max, min, sum. You can also get the raw stats report by using the returnNative argument.

    Parameters:
    mapper - The mapper lambda or closure to determine the statistics on
    primitive - The primitive type to cast with, we default to 'long'. Accepted values are int, long, double
    returnNative - If true, this will return the SummaryStatistics object instead of the struct report.
    Returns:
    By default a struct with {average,count,max,min,sum}.

    concat

    public Stream concat(any a, any b)

    Creates a lazily concatenated stream whose elements are all the elements of the first stream followed by all the elements of the second stream. The resulting stream is ordered if both of the input streams are ordered, and parallel if either of the input streams is parallel. When the resulting stream is closed, the close handlers for both input streams are invoked. Use caution when constructing streams from repeated concatenation. Accessing an element of a deeply concatenated stream can result in deep call chains, or even StackOverflowException.

    Parameters:
    a - the first stream
    b - the second stream
    Returns:
    the concatenation of the two input streams

    count

    public numeric count()

    Returns the count of elements in this stream.


    createPrimitiveProxyFunction

    private any createPrimitiveProxyFunction(any f, any primitive)

    Create a primitive typed proxy function

    Parameters:
    f - The target closure or lambda
    primitive - The target primitive

    distinct

    public Stream distinct()

    Returns a stream consisting of the distinct elements (according to Object.equals(Object)) of this stream.


    empty

    public Stream empty()

    Returns an empty sequential Stream.


    filter

    public Stream filter(any predicate)

    Returns a stream consisting of the elements of this stream that match the given predicate. This is an intermediate operation.

    Parameters:
    predicate - a non-interfering, stateless predicate to apply to each element to determine if it should be included

    findAny

    public Optional findAny()

    Returns an Optional describing some element of the stream, or an empty Optional if the stream is empty. This is a short-circuiting terminal operation. The behavior of this operation is explicitly nondeterministic; it is free to select any element in the stream. This is to allow for maximal performance in parallel operations; the cost is that multiple invocations on the same source may not return the same result. (If a stable result is desired, use findFirst() instead.)

    Returns:
    an Optional describing some element of this stream, or an empty Optional if the stream is empty

    findFirst

    public Optional findFirst()

    Returns an Optional describing the first element of this stream, or an empty Optional if the stream is empty. If the stream has no encounter order, then any element may be returned. This is a short-circuiting terminal operation.

    Returns:
    an Optional describing the first element of this stream, or an empty Optional if the stream is empty. If the stream has no encounter order, then any element may be returned.

    forEach

    public void forEach(any action)

    Performs an action for each element of this stream. This is a terminal operation. The behavior of this operation is explicitly nondeterministic. For parallel stream pipelines, this operation does not guarantee to respect the encounter order of the stream, as doing so would sacrifice the benefit of parallelism. For any given element, the action may be performed at whatever time and in whatever thread the library chooses. If the action accesses shared state, it is responsible for providing the required synchronization.

    Parameters:
    action - a non-interfering action to perform on the elements

    forEachOrdered

    public void forEachOrdered(any action)

    Performs an action for each element of this stream, in the encounter order of the stream if the stream has a defined encounter order. This is a terminal operation. This operation processes the elements one at a time, in encounter order if one exists. Performing the action for one element happens-before performing the action for subsequent elements, but for any given element, the action may be performed in whatever thread the library chooses.

    Parameters:
    action - a non-interfering action to perform on the elements

    generate

    public Stream generate(any supplier)

    Returns an infinite sequential unordered stream where each element is generated by the provided Supplier. This is suitable for generating constant streams, streams of random elements, etc. Please make sure you limit your stream or this method will work until it reaches the memory limit. Use the limit()

    Parameters:
    supplier - A closure or lambda that will supply the generated elements

    getJStream

    public string getJStream()


    getJType

    public string getJType()


    getNativeStatsStruct

    private any getNativeStatsStruct(any stats)

    Build a stats structure from a Java SummaryStatistics Object

    Parameters:
    stats

    getStrongTypePrefix

    private any getStrongTypePrefix()

    Return the strong type prefix for classes according to types


    isParallel

    public boolean isParallel()

    Returns whether this stream, if a terminal operation were to be executed, would execute in parallel. Calling this method after invoking an terminal stream operation method may yield unpredictable results.


    isStrongTyped

    private boolean isStrongTyped()

    Check if this stream is strong typed


    iterator

    public any iterator()

    Returns an iterator for the elements of this stream. This is an terminal operation.

    Returns:
    https://docs.oracle.com/javase/8/docs/api/java/util/Iterator.html

    limit

    public Stream limit(numeric maxSize)

    Returns a stream consisting of the elements of this stream, truncated to be no longer than maxSize in length. Please see warnings for parallel streams: https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#limit-long-

    Parameters:
    maxSize

    map

    public Stream map(any mapper)

    Returns a stream consisting of the results of applying the given function to the elements of this stream.

    Parameters:
    mapper - The closure or lambda to map apply to each element

    max

    public Optional max([any comparator])

    Returns an numeric describing the maximum element of this stream, or a null if this stream is empty. This can only be done with int, long, or double typed streams unless you pass in a Comparator function or lambda: (a,b) => return 0, +- value This is a terminal operation. obj1 and obj2 are the objects to be compared. This method returns zero if the objects are equal. It returns a positive value if obj1 is greater than obj2. Otherwise, a negative value is returned.

    Parameters:
    comparator - A comparator function or lambda

    min

    public Optional min([any comparator])

    Returns an numeric describing the minimum element of this stream, or a null if this stream is empty. This can only be done with int, long, or double typed streams unless you pass in a Comparator function or lambda: (a,b) => return 0, +- value This is a terminal operation. obj1 and obj2 are the objects to be compared. This method returns zero if the objects are equal. It returns a positive value if obj1 is greater than obj2. Otherwise, a negative value is returned.

    Parameters:
    comparator - A comparator function or lambda

    noneMatch

    public boolean noneMatch(any predicate)

    Returns whether no elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then true is returned and the predicate is not evaluated. This is a short-cicuiting terminal operation.

    Parameters:
    predicate - a non-interfering, stateless predicate to apply to elements of this stream

    of

    public Stream of()

    Returns a sequential ordered stream whose elements are the specified values. Each argument passed to this function will generate the stream from.


    ofChars

    public Stream ofChars(string target)

    Create a character stream from a string This won't work on ACF11 due to stupidity

    Parameters:
    target - The string to convert to a stream using its characters

    ofFile

    public Stream ofFile(string path, [any encoding='UTF-8'])

    Create a stream from a file. Every line of the text becomes an element of the stream:

    Parameters:
    path - The absolute path of the file to generate a stream from
    encoding - The encoding of the file, the default is `UTF-8`

    onClose

    public Stream onClose(any closeHandler)

    Returns an equivalent stream with an additional close handler. Close handlers are run when the close() method is called on the stream, and are executed in the order they were added. All close handlers are run, even if earlier close handlers throw exceptions. If any close handler throws an exception, the first exception thrown will be relayed to the caller of close(), with any remaining exceptions added to that exception as suppressed exceptions (unless one of the remaining exceptions is the same exception as the first exception, since an exception cannot suppress itself.) May return itself.

    Parameters:
    closeHandler - A lambda,closure or a CFC that implements a run() method. to be executed when the stream is closed.

    parallel

    public Stream parallel()

    Returns an equivalent stream that is parallel. May return itself, either because the stream was already parallel, or because the underlying stream state was modified to be parallel. This is an intermediate operation.


    peek

    public Stream peek(any action)

    Returns a stream consisting of the elements of this stream, additionally performing the provided action on each element as elements are consumed from the resulting stream. This is an intermediate operation. For parallel stream pipelines, the action may be called at whatever time and in whatever thread the element is made available by the upstream operation. If the action modifies shared state, it is responsible for providing the required synchronization. This method exists mainly to support debugging, where you want to see the elements as they flow past a certain point in a pipeline:

    Stream.of("one", "two", "three", "four")
    .filter( (e) +> e.len() > 3 )
    .peek( (e) => SystemOutput( "Filtered value: " & e, true ) )
    .map( (item) => item.toUpperCase() )
    .peek( (e) => SystemOutput( "Mapped value: " & e, true ) )
    .collect();
    

    Parameters:
    action - a non-interfering action to perform on the elements as they are consumed from the stream lambda or closure

    range

    public Stream range(numeric start, numeric end)

    Returns a sequential ordered LongStream from start (inclusive) to end (exclusive) by an incremental step of 1. See https://docs.oracle.com/javase/8/docs/api/java/util/stream/LongStream.html

    Parameters:
    start
    end

    rangeClosed

    public Stream rangeClosed(numeric start, numeric end)

    Returns a sequential ordered LongStream from start (inclusive) to end (inclusive) by an incremental step of 1. See https://docs.oracle.com/javase/8/docs/api/java/util/stream/LongStream.html

    Parameters:
    start
    end

    reduce

    public any reduce(any accumulator, [any identity])

    Performs a reduction on the elements of this stream. This function can run the reduction in 2 modes: 1 - Accumulation only: Using the accumulation function, and returns the reduced value, if any inside an Optional 2 - Accumulation with identity value: Performs a reduction on the elements of this stream, using the provided identity or starting value and an associative accumulation function, and returns the reduced value. NOT AN OPTIONAL This is a terminal operation.

    Parameters:
    accumulator - an associative, non-interfering, stateless function for combining two values
    identity - the identity value for the accumulating function. If not used, then the accumulator is used in isolation

    sequential

    public Stream sequential()

    Returns an equivalent stream that is sequential. May return itself, either because the stream was already sequential, or because the underlying stream state was modified to be sequential. This is an intermediate operation.


    setJStream

    public any setJStream(any jStream)

    Parameters:
    jStream

    setJType

    public any setJType(any jType)

    Parameters:
    jType

    skip

    public Stream skip(numeric n)

    Returns a stream consisting of the remaining elements of this stream after discarding the first n elements of the stream. If this stream contains fewer than n elements then an empty stream will be returned.

    Parameters:
    n - the number of leading elements to skip

    sorted

    public Stream sorted([any comparator])

    Returns a stream consisting of the elements of this stream, sorted according to natural order. You can pass in a lambda or closure to create your own Comparator.

    Parameters:
    comparator - A lambda or closure to apply as a comparator when sorting.

    spliterator

    public any spliterator()

    Returns a spliterator for the elements of this stream. This is a terminal operation.

    Returns:
    https://docs.oracle.com/javase/8/docs/api/java/util/Spliterator.html

    summaryStatistics

    public struct summaryStatistics([boolean returnNative='false'])

    Returns a Summary describing various summary data about the elements in this stream. By default we return a struct with the following stats: average, count, max, min, and sum. This is a terminal operation.

    Parameters:
    returnNative - If true, then we will return the native Java object, else a struct of stats

    toArray

    public any toArray()

    Returns an array containing the elements of this stream.


    unordered

    public Stream unordered()

    Returns an equivalent stream that is unordered. May return itself, either because the stream was already unordered, or because the underlying stream state was modified to be unordered. This is an intermediate operation.