HSTACK

What it does

HSTACK(array1, [array2], ...)

HSTACK(array1, [array2], …) places its arguments side by side, left to right in the order given, and returns the combined array.

The result's width is the sum of the arguments' widths. Its height is the height of the tallest argument — and every argument shorter than that is padded at the bottom. Microsoft documents the pad value as #N/A, which is the same convention VSTACK uses and the same default EXPAND uses: synthesized cells announce themselves rather than passing as zeros.

That padding rule is what makes HSTACK a stacking operation rather than a join. It does not align rows by any key; it aligns them by position, starting at row 1. Two lists of different lengths stacked horizontally give you a two-column array whose shorter column trails off into #N/A, which is correct and is very often not what the author meant.

Arguments

Scalars are admissible: a scalar is a 1×1 array, so HSTACK(A1:A10, "total") produces a two-column result whose second column is one value and nine #N/As.

The misunderstanding to head off: HSTACK takes several arguments, not a multi-area reference. HSTACK((A1:A5,C1:C5)) passes one union-shaped argument, which is a different thing from HSTACK(A1:A5, C1:C5). What the union form does is not established here.

Try it

Quirks

Result and edge cases

Return kind: Array, spilled. Spilling is host-side adaptation (the call pipeline).

• References are resolved first (ValuesOnlyPreAdapter), so the result carries values, not reference structure. HSTACK cannot be used where a reference is required.
• A single argument returns that argument as an array — the identity case, and a useful way to force a reference into array form.
• Element kinds are preserved: no coercion is applied to the stacked elements, and errors inside the inputs pass through as values (error_collapse_profile: None).
• Ragged inputs are the normal case, not an error. Padding is the documented behaviour; there is no strict mode.
• Whether a whole-column reference is admissible as an argument, and what height it contributes, is not established here — it is the input most likely to interact badly with the "height of the tallest argument" rule.

Errors

Microsoft's page for HSTACK documents #N/A as the pad value, which is a value in the result rather than a failure of the call. The page does not publish a general error table. #VALUE! for an inadmissible argument is the family's conventional code and is recorded here as expected, not verified.

An error value supplied as an argument propagates under the universal rule in coercion and lifting — as distinct from an error sitting inside an argument array, which is stacked like any other value.

A result exceeding the grid's dimensions is a host limit rather than a function semantic; what Excel returns at that limit is not established here.

How to implement

Notes for implementers

• The pad is per-argument, not per-result. Each argument is padded to the common height independently; there is no single rectangle being filled. Implementations that build the output row-major must know each source's height to decide where padding begins in that row.
• Width is a sum and can overflow the grid. Validate against the host's column limit before allocating, and decide what the failure looks like — the Handbook has not established Excel's behaviour at the boundary.
• Preserve element kinds exactly. Stacking is a copy, not a conversion; text, logicals and errors must arrive unchanged. This is the property that lets HSTACK build heterogeneous tables, and the easiest one to lose in an implementation that types its buffers numerically.
• The identity case matters. HSTACK(x) with a single argument is a legitimate call — the arity minimum is 1 — and it is used deliberately to materialize a reference as an array. It must not be optimized into a pass-through that preserves reference-ness.
• This function has its own module in the reference implementation rather than sharing the reshape family's, which is a code-organization fact, not a behavioural one.

Rust code

11 hstack_fn "HSTACK" (1, 254) [R "array1", R "array2"] |s, a, sv| {
    // Fn2: a direct error in any source precedes stacking; reference/array cells remain cells.
    for source in a { scalar_error(source)?; }
    // dc-h9u: a row of functions, as GROUPBY and PIVOTBY take them
    // (`GROUPBY(A2:A9,B2:B9,HSTACK(SUM,MAX))`, Excel 16.0.20527).
    if a.iter().all(|v| v.callable_value().is_some()) {
        return CalcArray::from_rows(vec![a.to_vec()])
            .map(CalcValue::array)
            .ok_or_else(|| s.not_modelled(None));
    }
    run(s, a, sv, k::eval_hstack_prepared)
}

/// HSTACK (hstack.rs): the arguments side by side, each padded with #N/A below to the tallest.
pub fn eval_hstack_prepared(args: &[CalcValue]) -> Result<CalcValue, DynamicArrayReshapeEvalError> {
    let sources: Vec<StackArgSource<'_>> = args.iter().map(StackArgSource::new).collect();
    let rows = sources.iter().map(|source| source.shape().rows).max().unwrap_or(1);
    let cols: usize = sources.iter().map(|source| source.shape().cols).sum();
    let mut cells = Vec::with_capacity(rows * cols);
    for row in 0..rows {
        for source in &sources {
            for col in 0..source.shape().cols {
                cells.push(
                    source
                        .get(row, col)
                        .cloned()
                        .unwrap_or(CalcValue::error(WorksheetErrorCode::NA)),
                );
            }
        }
    }
    build_array(rows, cols, cells)
}

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• VSTACK stacks vertically: widths are padded instead of heights, and the result's height is the sum. The pair is symmetric, and HSTACK(VSTACK(…), …) compositions are how dynamic-array formulas assemble tables.
• EXPAND is how you control the padding rather than accept #N/A: expand each piece to the common height with your own pad value first, then stack.
• CHOOSECOLS is the inverse in spirit — it takes columns out of one array where HSTACK puts columns from several together.
• TOROW / TOCOL flatten rather than stack, and WRAPROWS / WRAPCOLS reshape a vector into a rectangle; all four answer the neighbouring question of "how do I get this data into that shape".
• The & operator and TEXTJOIN concatenate values; HSTACK concatenates arrays. The word "concatenate" pulls readers toward the wrong one.
• INDEX / OFFSET gymnastics were how workbooks assembled multi-source arrays before the stacking functions existed; HSTACK replaces most of that with a call whose intent is legible.

Named variants

No named variants are recorded yet.