SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface ZipOptions

    Options for IRange.zip.

    interface ZipOptions {
        blankRegions?: "each" | "once";
        coerce?: CoerceParams;
        errorOnInvalidCoercion?: boolean;
        misalignValue?: Scalar;
        onError?: "value" | "throw" | "ignore" | ((error: Known) => void);
        tile?: boolean;
        type?: ScalarType | null;
    }

    Hierarchy (View Summary)

    Index
    blankRegions? coerce? errorOnInvalidCoercion? misalignValue? onError? tile? type?
    blankRegions?: "each" | "once"

    How the positions where EVERY shaped operand is blank are answered.

    'each'

    Such positions form regions of equal padding (see IRange.zip). 'each' visits every one with its coordinates; 'once' calls the callback a single time per region, with coords of { rowIndex: -1, colIndex: -1 }, and writes the region as runs. An explicit option rather than a callback-arity gate, so a callback that reads coords for the positions it IS given can still have the blanks answered in one call.

    coerce?: CoerceParams

    Overrides default coercion behavior per type. When a value cannot be coerced, onError determines the fallback.

    errorOnInvalidCoercion?: boolean

    If true, coercion failure produces #VALUE! rather than silently skipping the value.

    false

    misalignValue?: Scalar

    Controls how misaligned ranges are handled during broadcasting.

    • By default, broadcast() follows strict alignment rules like NumPy and will throw an error if the input ranges cannot be broadcasted together.
    • When misalignValue is provided, broadcast() will instead mimic Excel behavior:
      • It finds the largest valid intersection of the ranges.
      • It expands the result to the union of both range sizes.
      • Any cells that do not have valid corresponding values from the inputs will be filled with misalignValue instead of causing an error.
    • zip(), mask() and choose() always pad and default it to #N/A; in zip() the pad is delivered to the callback as that operand's value rather than written as the result.
    // Throws an error if A and B are not naturally broadcast-compatible
    const result = A.broadcast(B, (a, b) => a + b);

    // Expands to union size and fills gaps with "#N/A" instead of erroring
    const result = A.broadcast(B, (a, b) => a + b, { misalignValue: "#N/A" });
    onError?: "value" | "throw" | "ignore" | ((error: Known) => void)

    What to do when the visited value is a FormulaError.

    throw

    'throw' = throw error. 'ignore' = silently skip the value. 'value' = return a specific error value (default #VALUE!). 'function' = custom handler; use this to return a specific error value.

    tile?: boolean

    Whether a dimension of 1 tiles across the largest extent in that dimension.

    true

    Off, a dimension of 1 is a short dimension like any other and pads misalignValue past its one position: Excel's MAP rule, where a 1-row array is not stretched.

    type?: ScalarType | null

    Specifies the target type for coercion and filtering when getting or iterating values.

    The scalar type of the IRange itself (getType())

    • Values matching the type pass through unchanged.
    • Values coercible to the type are coerced.
    • If not set, the range's own scalar type (getType()) is used.
    • If the range has no scalar type, or set to null explicitly, no coercion or filtering is performed.

    Settings
    Member Visibility

    On This Page
    Properties