SheetXL - v1.0.2
    Preparing search index...

    Interface IFunctionCollection

    Collections of IFunction.

    Keyed by name, not ordered: iteration order is unspecified.

    interface IFunctionCollection {
        isICollection: true;
        isIFunctionCollection: true;
        length: number;
        "[iterator]"(): IterableIterator<IFunction>;
        add(
            option: string | IFunction | IFunctionCollection.AddOptions,
        ): Promise<IFunction>;
        addListeners(
            listeners: ICollection.IListeners,
            options?: IListener.Options,
        ): Remove;
        at(index: number): IFunction | undefined;
        every(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => boolean,
        ): boolean;
        filter<S extends IFunction>(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => value is S,
        ): S[];
        filter(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => boolean,
        ): IFunction[];
        find<S extends IFunction>(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => value is S,
        ): S | undefined;
        find(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => boolean,
        ): IFunction | undefined;
        findIndex(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => boolean,
        ): number;
        forEach(
            fn: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => void,
        ): void;
        getByName(
            name: string,
            options?: IFunctionCollection.GetByNameOptions,
        ): IFunction | null;
        getCategories(
            options?: GetCategoryOptions,
        ): Promise<IFunctionCollection.Category[]>;
        getCount(options?: IFunctionCollection.GetItemsOptions): number;
        getItems(options?: IFunctionCollection.GetItemsOptions): IFunction[];
        indexOf(item: IFunction): number;
        isClosed(): boolean;
        map<U>(
            fn: (value: IFunction, index: number, items: readonly IFunction[]) => U,
        ): U[];
        search(options?: IFunctionCollection.SearchOptions): Promise<IFunction[]>;
        some(
            predicate: (
                value: IFunction,
                index: number,
                items: readonly IFunction[],
            ) => boolean,
        ): boolean;
        toArray(): IFunction[];
        readonly [index: number]: IFunction;
    }

    Hierarchy (View Summary)

    Indexable

    • readonly [index: number]: IFunction

      The item at the given index, or undefined if there is none — wb.getWorksheets()[0].

      Read-only and live: each read is against the collection as it is now. Assigning through an index throws.

    Index
    isICollection isIFunctionCollection length
    [iterator] add addListeners at every filter find findIndex forEach getByName getCategories getCount getItems indexOf isClosed map search some toArray
    isICollection: true

    For runtime type checking.

    isIFunctionCollection: true

    For runtime type checking.

    length: number

    The number of items — the same as getCount.

    • Iterates the collection's items.

      Returns IterableIterator<IFunction>

      The unfiltered walk — for (const sheet of wb.getWorksheets()). Every other iterable surface in the SDK (ICellRange, ICellRegions, ICellRanges) reads this way, so a collection that did not was a trap: for…of over one is the obvious line to write and it threw at runtime with nothing in the types to warn first.

      getItems remains the call that takes options — filtering, ordering, anything parameterized. This is sugar over the unfiltered case, not a replacement for it.

    • Add a custom function to the collection.

      Parameters

      Returns Promise<IFunction>

      The registered function. When source is supplied and defines multiple functions, all are registered and the first (primary) one is returned.

    • Returns the item at the given index, or undefined if there is none.

      Parameters

      • index: number

        The position in iteration order. A negative index counts back from the end, as Array.prototype.at does.

      Returns IFunction | undefined

    • Returns true if the predicate accepts every item, including when there are none.

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => boolean

        Called once per item in iteration order until it returns false.

      Returns boolean

    • Returns the items the predicate accepts, in iteration order.

      Type Parameters

      • S extends IFunction

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => value is S

        Called once per item.

      Returns S[]

    • Returns the items the predicate accepts, in iteration order.

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => boolean

        Called once per item.

      Returns IFunction[]

    • Returns the first item the predicate accepts, or undefined if it accepts none.

      Type Parameters

      • S extends IFunction

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => value is S

        Called once per item in iteration order until it returns true.

      Returns S | undefined

    • Returns the first item the predicate accepts, or undefined if it accepts none.

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns IFunction | undefined

    • Returns the index of the first item the predicate accepts, or -1 if it accepts none.

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns number

    • Calls the function once per item, in iteration order.

      Parameters

      • fn: (value: IFunction, index: number, items: readonly IFunction[]) => void

        Called once per item.

      Returns void

    • The function with this name, hidden or not.

      Parameters

      Returns IFunction | null

      With options.sheet, returns a NEW instance bound to that sheet, for calling the function as a regular API outside the calculation graph — reference arguments and address strings resolve against the bound sheet with no evaluation current, and the instance is safe to hold across awaits. Without options, the shared registry instance is returned (the one the engine evaluates with); its reference resolution requires an active evaluation.

      A defined name whose body is LAMBDA(…) answers too, when no function has the name: a function whose isLambda() is true, with the lambda's parameters and, as its summary, the name's comment (or its formula, without one). getItems and search list these under the category Lambda. options.sheet only chooses which sheet's names are visible — a named lambda cannot be bound or called outside its name.

    • The categories the collection's functions declare, each with how many functions carry it.

      Parameters

      Returns Promise<IFunctionCollection.Category[]>

      The categories, ordered by name. Never contains an empty category — a category exists because a function is in it.

      The category is a display string owned by the descriptor (Math & Trig, Date & Time, …), so this is a descriptor-reading call with the same lazy cost as a text search — and, being per-language, it re-derives when the language changes. It exists so a function picker can build its category list from what is actually registered (custom functions included) rather than from a hard-coded table that silently drifts.

    • Returns the index of the item in iteration order, or -1 if it is not in the collection.

      Parameters

      • item: IFunction

        The item to find.

      Returns number

    • Returns true once the collection has been closed.

      Returns boolean

      A closed collection is empty and announces nothing further. Collections that are closed by their owner (the workbook's names, functions and modules, when the workbook closes) announce it once with ICollection.Events.onClose; the others are never closed and always return false.

    • Returns the result of calling the function on every item, in iteration order.

      Type Parameters

      • U

      Parameters

      • fn: (value: IFunction, index: number, items: readonly IFunction[]) => U

        Called once per item.

      Returns U[]

    • getItems, with the filters that read a function's IFunction.IDescriptor.

      Parameters

      Returns Promise<IFunction[]>

      Without SearchOptions.text or SearchOptions.category, returns exactly what getItems returns for the same options.

      By relevance when there is text, by canonical name otherwise.

      With text, relevance is: an exact name, then a name prefix, then a name substring, then the same three for the LOCALIZED name (each one tier behind its canonical counterpart), and finally a summary substring. Matching is case-insensitive "contains" — never fuzzy.

      text and category read each function's descriptor, which loads (once, lazily, per language) the descriptor chunk of every module — pennies for a search box, but not something to put on a hot path.

    • Returns true if the predicate accepts at least one item.

      Parameters

      • predicate: (value: IFunction, index: number, items: readonly IFunction[]) => boolean

        Called once per item in iteration order until it returns true.

      Returns boolean

    • Returns the items as a fresh array, in iteration order.

      Returns IFunction[]

      The call to make when an array is really wanted. The array is the caller's: changing it does not change the collection, and it does not follow later changes to the collection.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods