{
"title": "strings",
"category": "strings/core",
"keywords": [
"strings",
"preallocate",
"string array",
"empty strings",
"missing",
"like",
"gpu"
],
"summary": "Preallocate string arrays filled with empty text scalars using MATLAB-compatible size syntax.",
"references": [
"https://www.mathworks.com/help/matlab/ref/strings.html"
],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "none",
"notes": "Runs entirely on the host; GPU-resident size inputs are gathered before allocation and outputs always live in host memory."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 0,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::strings::core::strings::tests"
},
"description": "`strings` creates string arrays whose elements are empty string scalars (`\"\"`). It mirrors MATLAB's preallocation helper, accepting scalar, vector, or multiple dimension arguments to control the array shape.",
"behaviors": [
"`strings` with no inputs returns a 1×1 string array containing `\"\"`.",
"`strings(n)` produces an `n`-by-`n` array of empty strings. The single input must be a nonnegative integer scalar.",
"`strings(sz1,...,szN)` and `strings(sz)` accept nonnegative integer sizes. All specified dimensions—including trailing singletons—are preserved in the resulting array.",
"Setting any dimension to `0` yields an empty array whose remaining dimensions still shape the result (for example, `strings(0, 5, 3)` is a `0×5×3` string array).",
"`strings(___, \"missing\")` fills the allocation with the missing sentinel (`<missing>`) instead of empty strings, which is useful when you plan to replace placeholders later.",
"`strings(___, \"like\", prototype)` or `strings(\"like\", prototype)` reuses the size of `prototype` when you omit explicit dimensions. Any provided dimensions still take precedence, and GPU prototypes are gathered before their shape is inspected.",
"Size inputs must be finite integers. Negative, fractional, or NaN values trigger MATLAB-compatible \"Size inputs must be nonnegative integers\" errors.",
"Only numeric or logical size arguments are supported. Other types (strings, structs, objects) raise descriptive errors."
],
"examples": [
{
"description": "Creating a square array of empty strings",
"input": "S = strings(4)",
"output": "S = 4x4 string\n \"\" \"\" \"\" \"\"\n \"\" \"\" \"\" \"\"\n \"\" \"\" \"\" \"\"\n \"\" \"\" \"\" \"\""
},
{
"description": "Preallocating with separate dimension arguments",
"input": "grid = strings(2, 3, 4)",
"output": "grid = 2x3x4 string\ngrid(:,:,1) =\n \"\" \"\" \"\"\n \"\" \"\" \"\""
},
{
"description": "Cloning the size of another array",
"input": "A = magic(3);\nplaceholders = strings(size(A))",
"output": "placeholders = 3x3 string\n \"\" \"\" \"\"\n \"\" \"\" \"\"\n \"\" \"\" \"\""
},
{
"description": "Handling zero dimensions",
"input": "emptyRow = strings(0, 5)",
"output": "emptyRow = 0x5 string"
},
{
"description": "Preserving trailing singleton dimensions",
"input": "column = strings(3, 1, 1, 1);\nsz = size(column)",
"output": "sz =\n 3 1 1 1"
},
{
"description": "Filling arrays with missing string scalars",
"input": "placeholders = strings(2, 3, \"missing\")",
"output": "placeholders = 2x3 string\n <missing> <missing> <missing>\n <missing> <missing> <missing>"
},
{
"description": "Matching an existing array with `'like'`",
"input": "proto = zeros(3, 2);\nlabels = strings(\"like\", proto)",
"output": "labels = 3x2 string\n \"\" \"\"\n \"\" \"\"\n \"\" \"\""
},
{
"description": "Validating size inputs",
"input": "try\n strings(-3);\ncatch ME\n disp(ME.message)\nend",
"output": "Error using strings\nSize inputs must be nonnegative integers."
}
],
"faqs": [
{
"question": "How is `strings` different from `string`?",
"answer": "`strings` preallocates empty string scalars, while `string` converts existing data to string scalars. Use `strings` to reserve space, then assign values later."
},
{
"question": "Can I use non-integer sizes such as 2.5?",
"answer": "No. All size arguments must be finite integers. Fractional or NaN values raise descriptive errors."
},
{
"question": "How do I create missing string values (`<missing>`)?",
"answer": "Pass `\"missing\"` as an option— for example `strings(2, 3, \"missing\")` produces a `2×3` array filled with `<missing>` placeholders. You can still assign values later to replace the sentinel."
},
{
"question": "How can I reuse the size of an existing array?",
"answer": "Provide the `\"like\"` option: `strings(\"like\", prototype)` copies the size of `prototype` when you do not supply explicit dimensions. Any dimensions you specify override the inferred size."
},
{
"question": "Does the output ever live on the GPU?",
"answer": "No. `strings` always returns a host-resident string array. GPU inputs supplying sizes are gathered before validation."
},
{
"question": "How can I create a row versus column vector?",
"answer": "Use `strings(1, n)` for a row and `strings(n, 1)` for a column. Additional dimensions—including trailing singletons—remain part of the array shape."
},
{
"question": "Can I pass non-numeric types such as structs or string arrays as size inputs?",
"answer": "No. Only numeric or logical values are accepted. Other types produce MATLAB-compatible usage errors."
},
{
"question": "Is there an equivalent to `string.empty`?",
"answer": "Yes. `strings(0)` returns the same 0-by-0 empty string array as `string.empty`."
}
],
"links": [
{
"label": "string",
"url": "./string"
},
{
"label": "char",
"url": "./char"
},
{
"label": "zeros",
"url": "./zeros"
},
{
"label": "string.empty",
"url": "./string.empty"
},
{
"label": "compose",
"url": "./compose"
},
{
"label": "num2str",
"url": "./num2str"
},
{
"label": "sprintf",
"url": "./sprintf"
},
{
"label": "str2double",
"url": "./str2double"
},
{
"label": "strcmp",
"url": "./strcmp"
},
{
"label": "strcmpi",
"url": "./strcmpi"
},
{
"label": "strlength",
"url": "./strlength"
},
{
"label": "strncmp",
"url": "./strncmp"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/strings/core/strings.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/core/strings.rs"
},
"gpu_behavior": [
"`strings` never allocates data on the GPU. Size arguments that reside on a GPU are automatically gathered to the host before validation, and the resulting string array always lives in host memory. `\"like\"` prototypes follow the same rule—they are gathered before their shape is inspected. No provider hooks are required, so the GPU metadata marks the builtin as a gather-only operation."
]
}