time-to-botec/squiggle/node_modules/@stdlib/utils/async/bifurcate-by/docs/repl.txt

{{alias}}( collection, [options,] predicate, done )
    Splits values into two groups according to a predicate function.

    When invoked, the predicate function is provided a maximum of four
    arguments:

    - `value`: collection value
    - `index`: collection index
    - `collection`: the input collection
    - `next`: a callback to be invoked after processing a collection `value`

    The actual number of provided arguments depends on function length. If the
    predicate function accepts two arguments, the predicate function is
    provided:

    - `value`
    - `next`

    If the predicate function accepts three arguments, the predicate function is
    provided:

    - `value`
    - `index`
    - `next`

    For every other predicate function signature, the predicate function is
    provided all four arguments.

    The `next` callback takes two arguments:

    - `error`: error argument
    - `group`: value group

    If an predicate function calls the `next` callback with a truthy `error`
    argument, the function suspends execution and immediately calls the `done`
    callback for subsequent `error` handling.

    If a predicate function calls the `next` callback with a truthy group value,
    a collection value is placed in the first group; otherwise, a collection
    value is placed in the second group.

    If provided an empty collection, the function calls the `done` callback with
    an empty array as the second argument.

    Execution is *not* guaranteed to be asynchronous. To guarantee asynchrony,
    wrap the `done` callback in a function which either executes at the end of
    the current stack (e.g., `nextTick`) or during a subsequent turn of the
    event loop (e.g., `setImmediate`, `setTimeout`).

    The function does not support dynamic collection resizing.

    The function does not skip `undefined` elements.

    Parameters
    ----------
    collection: Array|TypedArray|Object
        Input collection over which to iterate. If provided an object, the
        object must be array-like (excluding strings and functions).

    options: Object (optional)
        Function options.

    options.limit: integer (optional)
        Maximum number of pending invocations. Default: Infinity.

    options.series: boolean (optional)
        Boolean indicating whether to process each collection element
        sequentially. Default: false.

    options.returns: string (optional)
        If `values`, values are returned; if `indices`, indices are returned; if
        `*`, both indices and values are returned. Default: 'values'.

    options.thisArg: any (optional)
        Execution context.

    predicate: Function
        Predicate function indicating which group an element in the input
        collection belongs to.

    done: Function
        A callback invoked either upon processing all collection elements or
        upon encountering an error.

    Examples
    --------
    // Basic usage:
    > function predicate( value, index, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next( null, ( index%2 === 0 ) );
    ...     }
    ... };
    > function done( error, result ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( result );
    ... };
    > var arr = [ 3000, 2500, 1000 ];
    > {{alias}}( arr, predicate, done )
    1000
    2500
    3000
    [ [ 1000, 3000 ], [ 2500 ] ]

    // Output group results as indices:
    > var opts = { 'returns': 'indices' };
    > {{alias}}( arr, opts, predicate, done )
    1000
    2500
    3000
    [ [ 2, 0 ], [ 1 ] ]

    // Output group results as index-value pairs:
    > opts = { 'returns': '*' };
    > {{alias}}( arr, opts, predicate, done )
    1000
    2500
    3000
    [ [ [ 2, 1000 ], [ 0, 3000 ] ], [ [ 1, 2500 ] ] ]

    // Limit number of concurrent invocations:
    > function predicate( value, index, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next( null, ( index%2 === 0 ) );
    ...     }
    ... };
    > function done( error, result ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( result );
    ... };
    > var opts = { 'limit': 2 };
    > var arr = [ 3000, 2500, 1000 ];
    > {{alias}}( arr, opts, predicate, done )
    2500
    3000
    1000
    [ [ 3000, 1000 ], [ 2500 ] ]

    // Process sequentially:
    > function predicate( value, index, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next( null, ( index%2 === 0 ) );
    ...     }
    ... };
    > function done( error, result ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( result );
    ... };
    > var opts = { 'series': true };
    > var arr = [ 3000, 2500, 1000 ];
    > {{alias}}( arr, opts, predicate, done )
    3000
    2500
    1000
    [ [ 3000, 1000 ], [ 2500 ] ]


{{alias}}.factory( [options,] predicate )
    Returns a function which splits values into two groups according to an
    predicate function.

    Parameters
    ----------
    options: Object (optional)
        Function options.

    options.limit: integer (optional)
        Maximum number of pending invocations. Default: Infinity.

    options.series: boolean (optional)
        Boolean indicating whether to process each collection element
        sequentially. Default: false.

    options.returns: string (optional)
        If `values`, values are returned; if `indices`, indices are returned; if
        `*`, both indices and values are returned. Default: 'values'.

    options.thisArg: any (optional)
        Execution context.

    predicate: Function
        Predicate function indicating which group an element in the input
        collection belongs to.

    Returns
    -------
    out: Function
        A function which splits values into two groups.

    Examples
    --------
    > function predicate( value, index, next ) {
    ...     setTimeout( onTimeout, value );
    ...     function onTimeout() {
    ...         console.log( value );
    ...         next( null, ( index%2 === 0 ) );
    ...     }
    ... };
    > var opts = { 'series': true };
    > var f = {{alias}}.factory( opts, predicate );
    > function done( error, result ) {
    ...     if ( error ) {
    ...         throw error;
    ...     }
    ...     console.log( result );
    ... };
    > var arr = [ 3000, 2500, 1000 ];
    > f( arr, done )
    3000
    2500
    1000
    [ [ 3000, 1000 ], [ 2500 ] ]
    > arr = [ 2000, 1500, 1000 ];
    > f( arr, done )
    2000
    1500
    1000
    [ [ 2000, 1000 ], [ 1500 ] ]

    See Also
    --------