WRAPCOLS

What it does

WRAPCOLS(vector, wrap_count, [pad_with])

WRAPCOLS turns a vector into a rectangle, filling it column by column.

Given a vector of N elements and a wrap count k, the result is an array of k rows and ⌈N / k⌉ columns: the first k elements become column 1 (top to bottom), the next k become column 2, and so on. If N is not a multiple of k, the final column is short and its remaining cells are filled with pad_with.

Concretely, WRAPCOLS({1,2,3,4,5}, 3) gives

1   4
2   5
3   #N/A

Two consequences of the definition are worth stating because the argument's name invites the opposite reading:

• wrap_count is the column height, not the number of columns. It is "how many values per column", and the number of columns is derived. Reading it as "make me k columns" gives a transposed, wrongly sized answer.
• The result's width grows with the input. Unlike every other function in this family, the output shape depends on the input's length rather than on its shape.

When wrap_count is greater than or equal to N, everything fits in one column and the result is a single column array — no padding, no second column.

Arguments

Microsoft documents WRAPCOLS(vector, wrap_count, [pad_with]).

vector — required. Must be genuinely one-dimensional: a single row or a single column. A rectangular array is documented as #VALUE!, not as something to flatten first. (If you want flattening, that is TOCOL.)

wrap_count — required. The maximum number of values in each column, so the result's row count. Documented as #NUM! when less than 1.

pad_with — optional, default #N/A. The value placed in the trailing cells of the final column.

The default deserves the same note as VSTACK's: padding with an error is a deliberate choice that makes the padding self-announcing. Passing pad_with explicitly — "", 0, or a placeholder — is the usual remedy, and unlike the IFERROR-wrapping trick it does not also swallow genuine #N/A values from the data.

Try it

Quirks

Result and edge cases

The return kind is a two-dimensional array of wrap_count rows.

• Exact multiples produce no padding at all.
• wrap_count ≥ N produces a single column, unpadded.
• wrap_count = 1 produces a single row — every element in its own column. This is a transposition of the input when the input is a column, and a no-op when it is a row.
• A one-element vector produces a 1×1 array, which must stay array-shaped.
• pad_with is not coerced to the vector's type; it is placed as given, and it may be text in an otherwise numeric array.
• Blanks and errors inside vector are ordinary elements and are placed unchanged, which means a genuine #N/A in the data is indistinguishable from default padding in the result.
• Dynamic-array publication and #SPILL! are host-side adaptation, described in the call pipeline.

Errors

Documented by Microsoft:

The third row is padding rather than failure, and a test oracle must not treat an #N/A in the result as an error outcome.

How to implement

Notes for implementers

• The output shape is wrap_count × ⌈N / wrap_count⌉. Deriving the width by division needs the ceiling, and the last column's fill boundary needs the remainder — two places to be off by one.
• Column-major fill is the defining behaviour; the twin function's row-major fill must not be reachable by a shared code path with a flipped flag unless the shape derivation flips too.
• pad_with defaults to #N/A, an error value, and must be placed verbatim without coercion.
• One-dimensionality is validated, not repaired: a rectangular input is #VALUE!.

Rust code

15 wrapcols_fn "WRAPCOLS" (2, 3) [R "vector", V "wrap_count", V "pad_with"] |s, a, sv| {
    run(s, a, sv, k::eval_wrapcols_prepared)
}

pub fn eval_wrapcols_prepared(
    args: &[CalcValue],
) -> Result<CalcValue, DynamicArrayReshapeEvalError> {
    let wrap_count = wrap_count(&args[1])?;
    match args[0].core_ref() {
        CoreRef::Number(_) | CoreRef::Text(_) | CoreRef::Logical(_) | CoreRef::Error(_) => {
            return Ok(args[0].clone());
        }
        CoreRef::Array(_) | CoreRef::Reference(_) | CoreRef::Missing | CoreRef::Empty => {}
    }
    let source = wrap_vector(&args[0])?;
    let pad_cell = args
        .get(2)
        .map(scalar_cell)
        .unwrap_or(CalcValue::error(WorksheetErrorCode::NA));
    let flat = flatten_cells(&source, false);
    let rows = wrap_count.min(flat.len());
    let cols = flat.len().div_ceil(rows);
    let mut grid = vec![pad_cell.clone(); rows * cols];
    for (index, cell) in flat.into_iter().enumerate() {
        let row = index % rows;
        let col = index / rows;
        grid[row * cols + col] = cell;
    }
    build_array(rows, cols, grid)
}

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

• WRAPROWS is the twin, filling row by row instead of column by column, with wrap_count as the row width. The two produce transposed-looking but genuinely different arrangements of the same elements, and choosing the wrong one is the most common mistake in this pair.
• TOCOL / TOROW are the inverse operation — rectangle to vector — with the same self-announcing relationship to structure.
• EXPAND pads an existing array to a target size with a chosen filler; WRAPCOLS pads as a side effect of reshaping.
• SEQUENCE generates a rectangle of consecutive numbers directly, which is often what a reader reaching for WRAPCOLS(SEQUENCE(n), k) actually wants.
• INDEX with computed row and column arithmetic is the pre-dynamic-array way of doing this, and is still what you will find in older workbooks.

Named variants

No named variants are recorded yet.