TOROW

What it does

TOROW(array, [ignore], [scan_by_column])

TOROW flattens an m × n array into a single row.

The elements are visited in one of two traversal orders and, optionally, filtered by kind before being laid out left to right:

• scan_by_column omitted or FALSE — scan by row: row 1 left to right, then row 2, and so on (row-major).
• scan_by_column TRUE — scan by column: column 1 top to bottom, then column 2 (column-major).

For {1,2;3,4} those give {1,2,3,4} and {1,3,2,4}.

The ignore argument drops element kinds before assembly, with the same code vocabulary the whole flattening pair shares: 0 keep everything (default), 1 ignore blanks, 2 ignore errors, 3 ignore both.

TOROW and TOCOL are the same operation with the output axis exchanged; TOROW(x, i, s) equals TRANSPOSE(TOCOL(x, i, s)). Which one you want is decided by what consumes the result, not by anything about the input.

Arguments

Microsoft documents TOROW(array, [ignore], [scan_by_column]).

array — required. The array or reference to flatten.

ignore — optional, default 0. Values 0–3 as above. It is an integer code, not a logical, even though 1 and TRUE coerce alike.

scan_by_column — optional, default FALSE. A logical selecting the traversal order.

The common confusion is between the two optional positions: TOROW(A, 1) filters blanks; TOROW(A, , 1) changes the traversal. Both are legal and neither errors, so the mistake shows up as a silently reordered or silently shortened row.

A second confusion is specific to this function's name. TOROW does not mean "read the array by rows" — that is scan_by_column FALSE. It means "produce a row". The name describes the output shape; the traversal is the third argument's business.

Try it

Quirks

Result and edge cases

The return kind is a single-row array.

• The result can be empty when ignore removes everything; Excel's convention for an empty array result is #CALC! (the value universe), and TOROW uses it with ignore 2 when nothing is left (FN-HSTACK-001).
• "Blank" is ambiguous between an empty cell and text of zero length. Which one ignore 1 drops is the question that decides how the function behaves on formula-generated data, and the documentation does not disambiguate it.
• Ignoring errors shortens the result; positions no longer correspond to source cells. A direct error is not an element and is not ignored (FN-HSTACK-001).
• A one-element result stays an array.
• Dynamic-array publication and #SPILL! are host-side adaptation.

Errors

Microsoft's TOCOL page documents #VALUE! for an array constant containing numbers that are not whole numbers, and #NUM! for an array that is too large. TOROW is documented as the twin function and the same conditions are the expected ones; the Handbook has not confirmed that the TOROW page states them identically, and does not assert the first condition's meaning, which does not obviously describe a flattening operation.

How to implement

Notes for implementers

• The output axis and the traversal axis are independent. Writing TOROW as "transpose, then TOCOL" is correct but changes which traversal flag means what — the composition has to be worked out rather than assumed.
• ignore is a code with four admitted values; anything else needs a decided outcome.
• The blank definition must be stated explicitly and shared with TOCOL.
• Filtering must preserve traversal order.

Rust code

13 torow_fn "TOROW" (1, 3) [R "array", V "ignore", V "scan_by_column"] |s, a, sv| {
    source_error(a)?;
    match by_area(s, a, sv, k::eval_torow_prepared, false)? {
        Some(value) => Ok(value),
        None => run(s, a, sv, k::eval_torow_prepared),
    }
}

pub fn eval_torow_prepared(args: &[CalcValue]) -> Result<CalcValue, DynamicArrayReshapeEvalError> {
    let array = materialize_array_arg(&args[0]);
    let ignore_mode = parse_ignore_mode(args.get(1))?;
    let by_col = args
        .get(2)
        .map(parse_bool_like)
        .transpose()?
        .unwrap_or(false);
    let cells: Vec<CalcValue> = flatten_cells(&array, by_col)
        .into_iter()
        .filter(|cell| !should_ignore_cell(cell, ignore_mode))
        .collect();
    if cells.is_empty() {
        return Err(DynamicArrayReshapeEvalError::EmptyArrayResult);
    }
    build_array(1, cells.len(), 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

• TOCOL is the transpose twin, with the identical argument vocabulary.
• WRAPROWS / WRAPCOLS invert the flattening: a vector back to a rectangle. WRAPROWS is the natural partner of TOROW when reshaping m × n to p × q.
• TRANSPOSE exchanges axes without flattening.
• HSTACK builds a row by concatenation rather than by flattening; for single-row inputs the two coincide, and for rectangular inputs they do not.
• TEXTJOIN(delim, TRUE, TOROW(range, 1)) is the idiomatic "list these values in a sentence" composition.

Named variants

No named variants are recorded yet.