transpose

function transpose(arr: unknown): Array<Array<unknown>>;

The value at row i, column j of the input is at row j, column i of the result. A new matrix is built; the input is not modified.

The input must be a matrix with uniform row lengths — the rule isConsistent2DArray states — since a ragged input has no transpose. Anything else throws a plain Error.

In a spreadsheet this is the conversion between the two shapes a range comes in: a column read as one row per cell, and a single row holding the same values.

Parameters

Parameter	Type	Description
`arr`	`unknown`	The matrix to transpose. Left untouched.

Returns

Array<Array<unknown>> — a new matrix with the rows and columns swapped. Element types are preserved.

Throws

Exception	Condition
`Error`	The input is not a matrix, or its rows differ in length.

Examples

Rows become columns

transpose([
  [1, 2, 3],
  [4, 5, 6]
]);
// => [
//   [1, 4],
//   [2, 5],
//   [3, 6]
// ]

Writing a list down a column

setValues wants one row per cell to fill a column, and a flat list is not that shape.

/**
 * Writes a flat list down a column. `setValues` wants one row per cell, which
 * is the transpose of a single row.
 */
export function writeColumn(sheet: GoogleAppsScript.Spreadsheet.Sheet, values: string[]): void {
  const column = transpose([values]);

  sheet.getRange(1, 1, column.length, 1).setValues(column);
}

function writeColumn(sheet, values) {
  const column = transpose([values]);
  sheet.getRange(1, 1, column.length, 1).setValues(column);
}

Invalid input

transpose([1, 2, 3]); // throws Error: Input must be a 2D array.
transpose([[1, 2], [3]]); // throws Error: Input must be a 2D array.

Source

src/lang/array/transpose.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help