WRAPROWS

What it does

WRAPROWS(vector, wrap_count, [pad_with])

WRAPROWS turns a vector into a rectangle, filling it row by row.

Given a vector of N elements and a wrap count k, the result has k columns and ⌈N / k⌉ rows: the first k elements become row 1 (left to right), the next k become row 2, and so on. When N is not a multiple of k, the final row is short and its remaining cells take the pad_with value.

WRAPROWS({1,2,3,4,5}, 3) gives

1   2   3
4   5   #N/A

This is the arrangement people usually have in mind when they say "wrap": reading order, left to right then down, like text in a paragraph. WRAPCOLS does the same job in the other direction and is the one that surprises.

Two points about the argument's meaning:

• wrap_count is the row width — how many values fit on a row — and the number of rows is derived. It is not "make me k rows".
• The result's height grows with the input's length, so the output shape is not determined by the input's shape alone.

When wrap_count is greater than or equal to N, everything fits on one row and the result is a single-row array with no padding.

Arguments

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

vector — required, and genuinely one-dimensional: a single row or a single column. A rectangular input is documented as #VALUE! on the twin function's page, not silently flattened.

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

pad_with — optional, default #N/A. Placed in the trailing cells of the short final row.

As on WRAPCOLS and VSTACK, the error-valued default is deliberate: padding that announces itself cannot be mistaken for data. Supplying pad_with explicitly is preferable to wrapping the whole call in IFERROR, which would also erase genuine #N/A values coming from the source.

Try it

Quirks

Result and edge cases

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

• Exact multiples produce no padding.
• wrap_count ≥ N gives a single row.
• wrap_count = 1 gives a single column — one element per row.
• A one-element vector gives a 1×1 array, which must stay array-shaped.
• pad_with is placed verbatim, without coercion to the vector's type.
• Errors and blanks inside vector are ordinary elements; a genuine #N/A in the data is indistinguishable in the result from default padding.
• Dynamic-array publication and #SPILL! are host-side adaptation, described in the call pipeline.

Errors

The documented conditions for this pair, taken from the twin function's page:

The Handbook has not separately confirmed that the WRAPROWS page states these identically; they are recorded here as the documented conditions for the pair.

How to implement

Notes for implementers

• Output shape is ⌈N / wrap_count⌉ × wrap_count. The ceiling and the final-row remainder are the two off-by-one sites.
• Row-major fill is the defining behaviour and must not be reachable by flipping a flag on the column-major path without also flipping the shape derivation.
• pad_with defaults to an error value and is placed without coercion.
• One-dimensionality is validated, not repaired.

Rust code

14 wraprows_fn "WRAPROWS" (2, 3) [R "vector", V "wrap_count", V "pad_with"] |s, a, sv| {
    run(s, a, sv, k::eval_wraprows_prepared)
}

pub fn eval_wraprows_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);
    // A maximum width does not pad a vector that already fits in a single row.
    let cols = wrap_count.min(flat.len());
    let rows = flat.len().div_ceil(cols);
    let mut cells = Vec::with_capacity(rows * cols);
    let mut iter = flat.into_iter();
    for _row in 0..rows {
        for _col in 0..cols {
            cells.push(iter.next().unwrap_or_else(|| pad_cell.clone()));
        }
    }
    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

• WRAPCOLS is the twin, filling column by column with wrap_count as the column height. The pair are not transposes of one another in the simple sense: WRAPROWS(v, k) and TRANSPOSE(WRAPCOLS(v, k)) both have k columns and put the same elements in the same reading order, so for the same k they agree — but that identity is worth verifying rather than assuming, and it fails to hold in the obvious way once padding enters.
• TOROW / TOCOL are the inverse direction: rectangle to vector.
• EXPAND pads an array to a target size with a chosen filler, which is the explicit form of WRAPROWS's incidental padding.
• SEQUENCE(rows, cols) builds a numbered rectangle directly.
• MAKEARRAY builds a rectangle from a LAMBDA, which is the general form of everything in this corner of the family.
• Readers confuse WRAPROWS with TRANSPOSE (which does not change the element count per line) and with HSTACK (which concatenates rather than reshapes).

Named variants

No named variants are recorded yet.