{
  "category": "Lookup and reference functions",
  "display_name": "WRAPCOLS",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.WRAPCOLS",
  "implementation_state": {
    "answer_bank": null,
    "detail": "Recorded: 15 workbook cells.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "matches",
    "state_label": "Matches every recorded Excel answer",
    "summary": "Matches all 15 recorded answers",
    "workbook_corpus": {
      "cells": 15,
      "matched": 15
    }
  },
  "implementations": [
    {
      "commit": "9e1884369a678158dd82d3d74188daf986995e87",
      "flavour": "excel-compatibility-candidate",
      "language": "Rust",
      "name": "CalcFunc",
      "own_code": [
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/arrays.rs#L700-L702",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/dynamic_array_reshape_family.rs#L602-L627"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/arrays::prepared",
        "catalogue/arrays::prepared_one",
        "catalogue/arrays::result",
        "catalogue/arrays::run",
        "ported/dynamic_array_reshape_family::coerce_prepared_to_number",
        "ported/dynamic_array_reshape_family::scalar_cell",
        "ported/dynamic_array_reshape_family::materialize_array_arg",
        "ported/dynamic_array_reshape_family::shape",
        "ported/dynamic_array_reshape_family::get",
        "ported/dynamic_array_reshape_family::parse_integer",
        "ported/dynamic_array_reshape_family::parse_positive_integer",
        "ported/dynamic_array_reshape_family::build_array",
        "ported/dynamic_array_reshape_family::flatten_cells",
        "ported/dynamic_array_reshape_family::wrap_count",
        "ported/dynamic_array_reshape_family::wrap_vector",
        "ported/dynamic_array_reshape_family::map_dynamic_array_reshape_error_to_ws"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/arrays.rs#L700-L702",
      "state": "matches",
      "suite": null,
      "summary": "Matches all 15 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.WRAPCOLS.json",
  "name": "WRAPCOLS",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n### Relationships\n\n\n- **`WRAPROWS`** is the twin, filling **row by row** instead of column by column, with\n  `wrap_count` as the row *width*. The two produce transposed-looking but genuinely different\n  arrangements of the same elements, and choosing the wrong one is the most common mistake in\n  this pair.\n- **`TOCOL` / `TOROW`** are the inverse operation — rectangle to vector — with the same\n  self-announcing relationship to structure.\n- **`EXPAND`** pads an existing array to a target size with a chosen filler; `WRAPCOLS` pads as\n  a side effect of reshaping.\n- **`SEQUENCE`** generates a rectangle of consecutive numbers directly, which is often what a\n  reader reaching for `WRAPCOLS(SEQUENCE(n), k)` actually wants.\n- **`INDEX` with computed row and column arithmetic** is the pre-dynamic-array way of doing\n  this, and is still what you will find in older workbooks.\n\n\n",
    "how-to-implement": "\n### Notes for implementers\n\n- The output shape is `wrap_count × ⌈N / wrap_count⌉`. Deriving the width by division needs the\n  ceiling, and the last column's fill boundary needs the remainder — two places to be off by\n  one.\n- Column-major fill is the defining behaviour; the twin function's row-major fill must not be\n  reachable by a shared code path with a flipped flag unless the shape derivation flips too.\n- `pad_with` defaults to `#N/A`, an error value, and must be placed verbatim without coercion.\n- One-dimensionality is validated, not repaired: a rectangular input is `#VALUE!`.\n\n\n",
    "quirks": "\n### Result and edge cases\n\n\nThe return kind is a two-dimensional array of `wrap_count` rows.\n\n- **Exact multiples** produce no padding at all.\n- **`wrap_count ≥ N`** produces a single column, unpadded.\n- **`wrap_count = 1`** produces a single row — every element in its own column. This is a\n  transposition of the input when the input is a column, and a no-op when it is a row.\n- **A one-element vector** produces a 1×1 array, which must stay array-shaped.\n- **`pad_with` is not coerced** to the vector's type; it is placed as given, and it may be text\n  in an otherwise numeric array.\n- **Blanks and errors inside `vector`** are ordinary elements and are placed unchanged, which\n  means a genuine `#N/A` in the data is indistinguishable from default padding in the result.\n- Dynamic-array publication and `#SPILL!` are host-side adaptation, described in\n  [the call pipeline](../model/03-call-pipeline.md).\n\n\n\n### Errors\n\n\nDocumented by Microsoft:\n\n| Error | Documented condition |\n|---|---|\n| `#VALUE!` | `vector` is not a one-dimensional array |\n| `#NUM!` | `wrap_count` is less than 1 |\n| `#N/A` | Placed in each cell of the return array that has no result — the default padding |\n\nThe third row is padding rather than failure, and a test oracle must not treat an `#N/A` in the\nresult as an error outcome.\n\n\n",
    "sources": "- Microsoft, *WRAPCOLS function* —\n  <https://support.microsoft.com/en-us/office/wrapcols-function-d038b05a-57b7-4ee0-be94-ded0792511e2>\n  (syntax, the column-by-column placement rule, `wrap_count` as the per-column element count,\n  the `#N/A` default for `pad_with`, the single-column case when `wrap_count ≥ N`, and the\n  `#VALUE!` and `#NUM!` conditions). Retrieved for this page.\n- Handbook `content/model/01-value-universe.md` and `content/model/03-call-pipeline.md`.\n- Handbook `data/functions/FUNC.WRAPCOLS.json` (signature, arity, classification axes).\n\n",
    "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.",
    "what-it-does": "\n`WRAPCOLS` turns a vector into a rectangle, filling it **column by column**.\n\nGiven a vector of `N` elements and a wrap count `k`, the result is an array of `k` rows and\n`⌈N / k⌉` columns: the first `k` elements become column 1 (top to bottom), the next `k` become\ncolumn 2, and so on. If `N` is not a multiple of `k`, the final column is short and its\nremaining cells are filled with `pad_with`.\n\nConcretely, `WRAPCOLS({1,2,3,4,5}, 3)` gives\n\n    1   4\n    2   5\n    3   #N/A\n\nTwo consequences of the definition are worth stating because the argument's name invites the\nopposite reading:\n\n- **`wrap_count` is the column *height*, not the number of columns.** It is \"how many values\n  per column\", and the number of columns is derived. Reading it as \"make me `k` columns\" gives\n  a transposed, wrongly sized answer.\n- **The result's width grows with the input.** Unlike every other function in this family, the\n  output shape depends on the input's *length* rather than on its shape.\n\nWhen `wrap_count` is greater than or equal to `N`, everything fits in one column and the result\nis a single column array — no padding, no second column.\n\n\n\n### Arguments\n\n\nMicrosoft documents `WRAPCOLS(vector, wrap_count, [pad_with])`.\n\n**`vector`** — required. Must be genuinely one-dimensional: a single row or a single column. A\nrectangular array is documented as `#VALUE!`, not as something to flatten first. (If you want\nflattening, that is `TOCOL`.)\n\n**`wrap_count`** — required. The maximum number of values in each column, so the result's row\ncount. Documented as `#NUM!` when less than 1.\n\n**`pad_with`** — optional, **default `#N/A`**. The value placed in the trailing cells of the\nfinal column.\n\nThe default deserves the same note as `VSTACK`'s: padding with an *error* is a deliberate\nchoice that makes the padding self-announcing. Passing `pad_with` explicitly — `\"\"`, `0`, or a\nplaceholder — is the usual remedy, and unlike the `IFERROR`-wrapping trick it does not also\nswallow genuine `#N/A` values from the data.\n\n\n"
  },
  "signature": {
    "display": "WRAPCOLS(vector, wrap_count, [pad_with])",
    "parameters": [
      {
        "description": null,
        "name": "vector",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "wrap_count",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "pad_with",
        "optional": true,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 3,
        "min": 2
      },
      "category": "Lookup and reference functions",
      "classification": {
        "arg_preparation_profile": "ValuesOnlyPreAdapter",
        "coercion_lift_profile": "Custom",
        "determinism_class": "Deterministic",
        "error_collapse_profile": "None",
        "fec_dependency_profile": "None",
        "host_interaction_class": "None",
        "kernel_signature_class": "Custom",
        "rich_value_usage": "RichBlind",
        "surface_fec_dependency_profile": "RefOnly",
        "thread_safety_class": "SafePure",
        "volatility_class": "NonVolatile"
      },
      "descriptions": {
        "long": null,
        "short": "A row or column of values folded into columns of a given length",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Wraps the provided row or column of values by columns after a specified number of elements",
        "microsoft_url": "https://support.microsoft.com/en-us/office/wrapcols-function-d038b05a-57b7-4ee0-be94-ded0792511e2"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "WRAPCOLS"
        },
        {
          "locale": "bg-BG",
          "name": "WRAPCOLS"
        },
        {
          "locale": "cs-CZ",
          "name": "ZABALSLOUPCE"
        },
        {
          "locale": "da-DK",
          "name": "FOLDKOLONNER"
        },
        {
          "locale": "de-DE",
          "name": "WRAPCOLS"
        },
        {
          "locale": "el-GR",
          "name": "WRAPCOLS"
        },
        {
          "locale": "en-AU",
          "name": "WRAPCOLS"
        },
        {
          "locale": "en-GB",
          "name": "WRAPCOLS"
        },
        {
          "locale": "en-US",
          "name": "WRAPCOLS"
        },
        {
          "locale": "es-ES",
          "name": "AJUSTARCOLS"
        },
        {
          "locale": "et-EE",
          "name": "WRAPCOLS"
        },
        {
          "locale": "fi-FI",
          "name": "RIVITÄSAR"
        },
        {
          "locale": "fr-FR",
          "name": "ORGA.COLS*"
        },
        {
          "locale": "he-IL",
          "name": "WRAPCOLS"
        },
        {
          "locale": "hr-HR",
          "name": "WRAPCOLS"
        },
        {
          "locale": "hu-HU",
          "name": "OSZLOPTÖRDELÉS"
        },
        {
          "locale": "id-ID",
          "name": "WRAPCOLS"
        },
        {
          "locale": "it-IT",
          "name": "WRAPCOLS"
        },
        {
          "locale": "ja-JP",
          "name": "WRAPCOLS"
        },
        {
          "locale": "ko-KR",
          "name": "WRAPCOLS"
        },
        {
          "locale": "lt-LT",
          "name": "WRAPCOLS"
        },
        {
          "locale": "lv-LV",
          "name": "WRAPCOLS"
        },
        {
          "locale": "nb-NO",
          "name": "WRAPCOLS"
        },
        {
          "locale": "nl-NL",
          "name": "OMLOOP.KOLOMMEN"
        },
        {
          "locale": "pl-PL",
          "name": "ZAWIŃ.KOLUMNY"
        },
        {
          "locale": "pt-BR",
          "name": "WRAPCOLS"
        },
        {
          "locale": "pt-PT",
          "name": "MOLDARCOLS"
        },
        {
          "locale": "ro-RO",
          "name": "WRAPCOLS"
        },
        {
          "locale": "ru-RU",
          "name": "СВЕРНСТОЛБЦ"
        },
        {
          "locale": "sk-SK",
          "name": "WRAPCOLS"
        },
        {
          "locale": "sl-SI",
          "name": "WRAPCOLS"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "WRAPCOLS"
        },
        {
          "locale": "sv-SE",
          "name": "BRYTKOLUMN"
        },
        {
          "locale": "th-TH",
          "name": "WRAPCOLS"
        },
        {
          "locale": "tr-TR",
          "name": "SÜTUNSAR"
        },
        {
          "locale": "uk-UA",
          "name": "WRAPCOLS"
        },
        {
          "locale": "vi-VN",
          "name": "WRAPCOLS"
        },
        {
          "locale": "zh-CN",
          "name": "WRAPCOLS"
        },
        {
          "locale": "zh-HK",
          "name": "WRAPCOLS"
        },
        {
          "locale": "zh-TW",
          "name": "WRAPCOLS"
        }
      ],
      "signature": {
        "display": "WRAPCOLS(vector, wrap_count, [pad_with])",
        "parameters": [
          {
            "description": null,
            "name": "vector",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "wrap_count",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "pad_with",
            "optional": true,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "WRAPCOLS",
      "version_marker": null,
      "xlcall": null
    },
    "microsoft": "https://support.microsoft.com/en-us/office/wrapcols-function-d038b05a-57b7-4ee0-be94-ded0792511e2"
  },
  "try_it": {
    "formula": "=WRAPCOLS({1;2;3;4},2)"
  },
  "url": "https://handbook.dnacalc.com/functions/WRAPCOLS.html",
  "variants": [],
  "versions": []
}