{
"title": "struct",
"category": "structs/core",
"keywords": [
"struct",
"structure",
"name-value",
"record",
"struct array"
],
"summary": "Create scalar structs or struct arrays from name/value pairs.",
"references": [],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "none",
"notes": "Struct construction runs on the host. GPU tensors stay as handles inside the resulting struct or struct array."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 0,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::structs::core::r#struct::tests",
"integration": "builtins::structs::core::r#struct::tests::struct_preserves_gpu_handles_with_registered_provider"
},
"description": "`S = struct(...)` creates scalar structs or struct arrays by pairing field names with values. The inputs can be simple name/value pairs, existing structs, or cell arrays whose elements are expanded into struct array entries.",
"behaviors": [
"Field names must satisfy the MATLAB `isvarname` rules: they start with a letter or underscore and contain only letters, digits, or underscores.",
"The last occurrence of a repeated field name wins and overwrites earlier values.",
"String scalars, character vectors, and single-element string arrays are accepted as field names.",
"`struct()` returns a scalar struct with no fields, while `struct([])` yields a `0×0` struct array.",
"When any value input is a cell array, every cell array input must share the same size. Non-cell inputs are replicated across every element of the resulting struct array.",
"Passing an existing struct or struct array (`struct(S)`) creates a deep copy; the original data is untouched."
],
"examples": [
{
"description": "Creating a simple structure for named fields",
"input": "s = struct(\"name\", \"Ada\", \"score\", 42);\ndisp(s.name);\ndisp(s.score)",
"output": "Ada\n42"
},
{
"description": "Building a struct array from paired cell inputs",
"input": "names = {\"Ada\", \"Grace\"};\nages = {36, 45};\npeople = struct(\"name\", names, \"age\", ages);\n{people.name}",
"output": " {'Ada'} {'Grace'}"
},
{
"description": "Broadcasting scalars across a struct array",
"input": "ids = struct(\"id\", {101, 102, 103}, \"department\", \"Research\");\n{ids.department}",
"output": " {'Research'} {'Research'} {'Research'}"
},
{
"description": "Copying an existing structure",
"input": "a = struct(\"id\", 7, \"label\", \"demo\");\nb = struct(a);\nb.id = 8;\ndisp([a.id b.id])",
"output": " 7 8"
},
{
"description": "Building an empty struct array",
"input": "s = struct([]);\ndisp(size(s))",
"output": " 0 0"
}
],
"faqs": [
{
"question": "Do field names have to be valid identifiers?",
"answer": "Yes. RunMat mirrors MATLAB and requires names to satisfy `isvarname`. Names must begin with a letter or underscore and may contain letters, digits, and underscores."
},
{
"question": "How do I create a struct array?",
"answer": "Provide one or more value arguments as cell arrays with identical sizes. Each cell contributes the value for the corresponding struct element. Non-cell values are replicated across all elements."
},
{
"question": "What happens when the same field name appears more than once?",
"answer": "The last value wins; earlier values for the same field are overwritten."
},
{
"question": "Does `struct` gather GPU data back to the CPU?",
"answer": "No. GPU tensors remain device-resident handles inside the resulting struct or struct array."
},
{
"question": "Can I pass non-string objects as field names?",
"answer": "No. Field names must be provided as string scalars, character vectors, or single-element string arrays. Passing other types raises an error."
}
],
"links": [
{
"label": "load",
"url": "./load"
},
{
"label": "whos",
"url": "./whos"
},
{
"label": "gpuArray",
"url": "./gpuarray"
},
{
"label": "gather",
"url": "./gather"
},
{
"label": "fieldnames",
"url": "./fieldnames"
},
{
"label": "getfield",
"url": "./getfield"
},
{
"label": "isfield",
"url": "./isfield"
},
{
"label": "orderfields",
"url": "./orderfields"
},
{
"label": "rmfield",
"url": "./rmfield"
},
{
"label": "setfield",
"url": "./setfield"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/structs/core/struct.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/structs/core/struct.rs"
},
"gpu_residency": "Usually not. RunMat's planner keeps GPU values resident as long as downstream operations can profit from them. You can still seed GPU residency explicitly with `gpuArray` for MATLAB compatibility; the handles remain untouched inside the struct until another builtin decides to gather or operate on them.",
"gpu_behavior": [
"`struct` performs all bookkeeping on the host. GPU-resident values—such as tensors created with `gpuArray`—are stored as-is inside the resulting struct or struct array. No kernels are launched and no data is implicitly gathered back to the CPU."
]
}