/**
 * An object which can produce an iterator over its values.
 */
export interface IIterable<T> {
    /**
     * Create an iterator over the object's values.
     *
     * @returns A new iterator which traverses the object's values.
     */
    iter(): IIterator<T>;
}
/**
 * An object which traverses a collection of values.
 *
 * #### Notes
 * For the convenience of API implementors, an iterator itself is an
 * iterable. Most concrete iterators will simply return `this` from
 * their `iter()` method.
 */
export interface IIterator<T> extends IIterable<T> {
    /**
     * Create an independent clone of the iterator.
     *
     * @returns A new independent clone of the iterator.
     *
     * #### Notes
     * The cloned iterator can be consumed independently of the current
     * iterator. In essence, it is a copy of the iterator value stream
     * which starts at the current location. This can be useful for
     * lookahead and stream duplication.
     *
     * Most iterators can trivially support cloning. Those which cannot
     * should throw an exception and document the restriction.
     */
    clone(): IIterator<T>;
    /**
     * Get the next value in the collection.
     *
     * @returns The next value in the collection, or `undefined` if the
     *   iterator is exhausted.
     *
     * #### Notes
     * The `undefined` value is used to signal the end of iteration and
     * should therefore not be used as a value in a collection.
     *
     * The use of the `undefined` sentinel is an explicit design choice
     * which favors performance over purity. The ES6 iterator design of
     * returning a `{ value, done }` pair is suboptimal, as it requires
     * an object allocation on each iteration; and an `isDone()` method
     * increases implementation and runtime complexity.
     */
    next(): T;
}
/**
 * An object which behaves like an array for property access.
 *
 * #### Notes
 * This interface represents the builtin JS array-like objects.
 */
export interface IArrayLike<T> {
    /**
     * The length of the object.
     */
    length: number;
    /**
     * The index-based property accessor.
     */
    [index: number]: T;
}
/**
 * A type alias for an iterable or builtin array-like object.
 *
 * #### Notes
 * The [[iter]] function can be used to produce an [[IIterator]] for
 * objects of this type. This allows iteration algorithms to operate
 * on these objects in a uniform fashion.
 */
export declare type IterableOrArrayLike<T> = IIterable<T> | IArrayLike<T>;
/**
 * Create an iterator for an iterable or array-like object.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @returns A new iterator for the given object.
 *
 * #### Notes
 * This function allows iteration algorithms to operate on user-defined
 * iterable types and builtin array-like objects in a uniform fashion.
 */
export declare function iter<T>(object: IterableOrArrayLike<T>): IIterator<T>;
/**
 * Create an array from an iterable of values.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @returns A new array of values from the given object.
 */
export declare function toArray<T>(object: IterableOrArrayLike<T>): T[];
/**
 * Create an empty iterator.
 *
 * @returns A new iterator which yields nothing.
 */
export declare function empty<T>(): EmptyIterator<T>;
/**
 * An iterator which is always empty.
 */
export declare class EmptyIterator<T> implements IIterator<T> {
    /**
     * Construct a new empty iterator.
     */
    constructor();
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the current iterator.
     *
     * @returns A new independent clone of the current iterator.
     */
    clone(): EmptyIterator<T>;
    /**
     * Get the next value from the iterator.
     *
     * @returns Always `undefined`.
     */
    next(): T;
}
/**
 * An iterator for an array-like object.
 *
 * #### Notes
 * This iterator can be used for any builtin JS array-like object.
 */
export declare class ArrayIterator<T> implements IIterator<T> {
    /**
     * Construct a new array iterator.
     *
     * @param source - The array-like object of interest.
     *
     * @param start - The starting index for iteration.
     */
    constructor(source: IArrayLike<T>, start: number);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the current iterator.
     *
     * @returns A new independent clone of the current iterator.
     *
     * #### Notes
     * The source array is shared among clones.
     */
    clone(): ArrayIterator<T>;
    /**
     * Get the next value from the source array.
     *
     * @returns The next value from the source array, or `undefined`
     *   if the iterator is exhausted.
     */
    next(): T;
    private _source;
    private _index;
}
/**
 * Invoke a function for each value in an iterable.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param fn - The callback function to invoke for each value.
 *
 * #### Notes
 * Iteration cannot be terminated early.
 */
export declare function each<T>(object: IterableOrArrayLike<T>, fn: (value: T) => void): void;
/**
 * Test whether all values in an iterable satisfy a predicate.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param fn - The predicate function to invoke for each value.
 *
 * @returns `true` if all values pass the test, `false` otherwise.
 *
 * #### Notes
 * Iteration terminates on the first `false` predicate result.
 */
export declare function every<T>(object: IterableOrArrayLike<T>, fn: (value: T) => boolean): boolean;
/**
 * Test whether any value in an iterable satisfies a predicate.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param fn - The predicate function to invoke for each value.
 *
 * @returns `true` if any value passes the test, `false` otherwise.
 *
 * #### Notes
 * Iteration terminates on the first `true` predicate result.
 */
export declare function some<T>(object: IterableOrArrayLike<T>, fn: (value: T) => boolean): boolean;
/**
 * Summarize all values in an iterable using a reducer function.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param fn - The reducer function to invoke for each value.
 *
 * @param initial - The initial value for the accumulator.
 *
 * @returns The final accumulated value.
 *
 * #### Notes
 * The `reduce` function follows the conventions of `Array#reduce`.
 *
 * If the iterator is empty, an initial value is required. That value
 * will be used as the return value. If no initial value is provided,
 * an error will be thrown.
 *
 * If the iterator contains a single item and no initial value is
 * provided, the single item is used as the return value.
 *
 * Otherwise, the reducer is invoked for each element in the iterable.
 * If an initial value is not provided, the first element will be used
 * as the initial accumulator value.
 */
export declare function reduce<T>(object: IterableOrArrayLike<T>, fn: (accumulator: T, value: T) => T): T;
export declare function reduce<T, U>(object: IterableOrArrayLike<T>, fn: (accumulator: U, value: T) => U, initial: U): U;
/**
 * Filter an iterable for values which pass a test.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param fn - The predicate function to invoke for each value.
 *
 * @returns An iterator which yields the values which pass the test.
 */
export declare function filter<T>(object: IterableOrArrayLike<T>, fn: (value: T) => boolean): FilterIterator<T>;
/**
 * An iterator which yields values which pass a test.
 */
export declare class FilterIterator<T> implements IIterator<T> {
    /**
     * Construct a new filter iterator.
     *
     * @param source - The iterator of values of interest.
     *
     * @param fn - The predicate function to invoke for each value in
     *   the iterator. It returns whether the value passes the test.
     */
    constructor(source: IIterator<T>, fn: (value: T) => boolean);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the current iterator.
     *
     * @returns A new independent clone of the current iterator.
     *
     * #### Notes
     * The source iterator must be cloneable.
     *
     * The predicate function is shared among clones.
     */
    clone(): FilterIterator<T>;
    /**
     * Get the next value which passes the test.
     *
     * @returns The next value from the source iterator which passes
     *   the predicate, or `undefined` if the iterator is exhausted.
     */
    next(): T;
    private _source;
    private _fn;
}
/**
 * Transform the values of an iterable with a mapping function.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param fn - The mapping function to invoke for each value.
 *
 * @returns An iterator which yields the transformed values.
 */
export declare function map<T, U>(object: IterableOrArrayLike<T>, fn: (value: T) => U): MapIterator<T, U>;
/**
 * An iterator which transforms values using a mapping function.
 */
export declare class MapIterator<T, U> implements IIterator<U> {
    /**
     * Construct a new map iterator.
     *
     * @param source - The iterator of values of interest.
     *
     * @param fn - The mapping function to invoke for each value in the
     *   iterator. It returns the transformed value.
     */
    constructor(source: IIterator<T>, fn: (value: T) => U);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the current iterator.
     *
     * @returns A new independent clone of the current iterator.
     *
     * #### Notes
     * The source iterator must be cloneable.
     *
     * The mapping function is shared among clones.
     */
    clone(): MapIterator<T, U>;
    /**
     * Get the next mapped value from the source iterator.
     *
     * @returns The next value from the source iterator transformed
     *   by the mapper, or `undefined` if the iterator is exhausted.
     */
    next(): U;
    private _source;
    private _fn;
}
/**
 * Attach an incremental index to an iterable.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param start - The initial value of the index. The default is zero.
 *
 * @returns An iterator which yields `[index, value]` tuples.
 */
export declare function enumerate<T>(object: IterableOrArrayLike<T>, start?: number): EnumerateIterator<T>;
/**
 * An iterator which attaches an incremental index to a source.
 */
export declare class EnumerateIterator<T> implements IIterator<[number, T]> {
    /**
     * Construct a new enumerate iterator.
     *
     * @param source - The iterator of values of interest.
     *
     * @param start - The initial value of the index.
     */
    constructor(source: IIterator<T>, start: number);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the enumerate iterator.
     *
     * @returns A new iterator starting with the current value.
     *
     * #### Notes
     * The source iterator must be cloneable.
     */
    clone(): EnumerateIterator<T>;
    /**
     * Get the next value from the enumeration.
     *
     * @returns The next value from the enumeration, or `undefined` if
     *   the iterator is exhausted.
     */
    next(): [number, T];
    private _source;
    private _index;
}
/**
 * Create an iterator which yields a value a single time.
 *
 * @param value - The value to wrap in an iterator.
 *
 * @returns A new iterator which yields the value a single time.
 */
export declare function once<T>(value: T): RepeatIterator<T>;
/**
 * Create an iterator which repeats a value a number of times.
 *
 * @param value - The value to repeat.
 *
 * @param count - The number of times to repeat the value.
 *
 * @returns A new iterator which repeats the specified value.
 */
export declare function repeat<T>(value: T, count: number): RepeatIterator<T>;
/**
 * An iterator which repeats a value a specified number of times.
 */
export declare class RepeatIterator<T> implements IIterator<T> {
    /**
     * Construct a new repeat iterator.
     *
     * @param value - The value to repeat.
     *
     * @param count - The number of times to repeat the value.
     */
    constructor(value: T, count: number);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the repeat iterator.
     *
     * @returns A new iterator starting with the current value.
     */
    clone(): RepeatIterator<T>;
    /**
     * Get the next value from the iterator.
     *
     * @returns The next value from the iterator, or `undefined` if
     *   the iterator is exhausted.
     */
    next(): T;
    private _value;
    private _count;
}
/**
 * Chain together several iterables.
 *
 * @param objects - The iterables or array-like objects of interest.
 *
 * @returns An iterator which yields the values of the given iterables
 *   in the order in which they are supplied.
 */
export declare function chain<T>(...objects: IterableOrArrayLike<T>[]): ChainIterator<T>;
/**
 * An iterator which chains together several iterators.
 */
export declare class ChainIterator<T> implements IIterator<T> {
    /**
     * Construct a new chain iterator.
     *
     * @param source - The iterator of iterators of interest.
     */
    constructor(source: IIterator<IIterator<T>>);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the chain iterator.
     *
     * @returns A new iterator starting with the current value.
     *
     * #### Notes
     * The source iterators must be cloneable.
     */
    clone(): ChainIterator<T>;
    /**
     * Get the next value from the iterator.
     *
     * @returns The next value from the iterator, or `undefined` when
     *   all source iterators are exhausted.
     */
    next(): T;
    private _source;
    private _active;
    private _cloned;
}
/**
 * Iterate several iterables in lockstep.
 *
 * @param objects - The iterables or array-like objects of interest.
 *
 * @returns An iterator which yields successive tuples of values where
 *   each value is taken in turn from the provided iterables. It will
 *   be as long as the shortest provided iterable.
 */
export declare function zip<T>(...objects: IterableOrArrayLike<T>[]): ZipIterator<T>;
/**
 * An iterator which iterates several sources in lockstep.
 */
export declare class ZipIterator<T> implements IIterator<T[]> {
    /**
     * Construct a new zip iterator.
     *
     * @param source - The iterators of interest.
     */
    constructor(source: IIterator<T>[]);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the zip iterator.
     *
     * @returns A new iterator starting with the current value.
     *
     * #### Notes
     * The source iterators must be cloneable.
     */
    clone(): ZipIterator<T>;
    /**
     * Get the next zipped value from the iterator.
     *
     * @returns The next zipped value from the iterator, or `undefined`
     *   when the first source iterator is exhausted.
     */
    next(): T[];
    private _source;
}
/**
 * Iterate over an iterable using a stepped increment.
 *
 * @param object - The iterable or array-like object of interest.
 *
 * @param step - The distance to step on each iteration. A value
 *   of less than `1` will behave the same as a value of `1`.
 *
 * @returns An iterator which traverses the iterable step-wise.
 */
export declare function stride<T>(object: IterableOrArrayLike<T>, step: number): StrideIterator<T>;
/**
 * An iterator which traverses a source iterator step-wise.
 */
export declare class StrideIterator<T> implements IIterator<T> {
    /**
     * Construct a new stride iterator.
     *
     * @param source - The iterator of values of interest.
     *
     * @param step - The distance to step on each iteration. A value
     *   of less than `1` will behave the same as a value of `1`.
     */
    constructor(source: IIterator<T>, step: number);
    /**
     * Create an iterator over the object's values.
     *
     * @returns A reference to `this` iterator.
     */
    iter(): this;
    /**
     * Create an independent clone of the stride iterator.
     *
     * @returns A new iterator starting with the current value.
     *
     * #### Notes
     * The source iterator must be cloneable.
     */
    clone(): StrideIterator<T>;
    /**
     * Get the next stepped value from the iterator.
     *
     * @returns The next stepped value from the iterator, or `undefined`
     *   when the source iterator is exhausted.
     */
    next(): T;
    private _source;
    private _step;
}