setfield — Assign a field, nested path, or indexed field value.
setfield provides functional field assignment for scalar structures, structure arrays, and supported RunMat object-family values.
Syntax
S = setfield(S, field, value)
S = setfield(S, field1, ..., fieldN, value)
S = setfield(S, idx, field1, ..., fieldN, value)
S = setfield(S, idx, field1, idx1, ..., fieldN, idxN, value)Inputs
S- Type
Any- Required
- Yes
- Description
- Structure or supported RunMat object-family target.
field- Type
PropertyName- Required
- Yes
- Description
- Field name.
value- Type
Any- Required
- Yes
- Description
- Assigned value.
path- Type
Any- Required
- Variadic
- Description
- Field names with optional cell-array index selectors.
Returns
S- Type
Any- Description
- Updated structure or supported RunMat object-family value.
Errors
RunMat:setfield:TooManyOutputs- When
- More than one output is requested.
- Message
setfield: too many output arguments
RunMat:setfield:NotEnoughInputs- When
- A field path and value are not supplied.
- Message
setfield: expected at least one field name and a value
RunMat:setfield:FieldExpected- When
- A selector is not followed by a field name.
- Message
setfield: expected field name arguments
Field assignment
S2 = setfield(S,field,value) returns the updated value. Additional field names traverse nested structures; absent fields and absent intermediate structures are created where the path permits them.
The input follows ordinary value semantics. Scalar structures and value objects produce updated values; a valid handle object updates its referenced instance and returns the same handle identity.
Structure arrays and indexed fields
Place an index cell before the first field to select one structure-array element. Place one after a field name to apply ordinary parenthesis assignment to that field's contents. Intermediate selections must identify one value; the final selector may update several elements. Every index is one-based.
Indexed assignment observes the selected container's class and shape rules. A numeric or logical final selector supports multi-element assignment when the right-hand side is scalar or has a compatible shape. Parenthesis assignment into a cell field requires a cell-array right-hand side and preserves the cell container.
Objects and resident values
RunMat mode extends setfield to supported object and handle values. Property assignment observes declared access, static, dynamic, and dependent-property behavior.
Replacing a field with a resident value preserves that handle without provider work. Indexing into a resident field is a separately gated RunMat extension: the owning provider gathers the target for host mutation, and the updated field becomes host-resident.
Examples
Assign a new field
s = struct();
s = setfield(s, 'answer', 42)Expected output:
s.answer = 42Create a nested field path
cfg = struct();
cfg = setfield(cfg, 'solver', 'name', 'cg');
cfg = setfield(cfg, 'solver', 'tolerance', 1e-6)Expected output:
cfg.solver contains name and toleranceUpdate one structure-array element
records = struct('label', {'first', 'second'}, 'id', {101, 102});
records = setfield(records, {2}, 'id', 999)Expected output:
records(2).id = 999Assign selected field elements
s = struct('values', {[10 20 30 40]});
s = setfield(s, 'values', {[2 4]}, [200 400])Expected output:
s.values = [10 200 30 400]Replace one cell with parenthesis indexing
s = struct('samples', {{10, 20, 30}});
s = setfield(s, 'samples', {2}, {200})Expected output:
s.samples = {10, 200, 30}Using setfield with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how setfield changes the result.
Run a small setfield example, explain the result, then change one input and compare the output.
FAQ
Does setfield modify its input?⌄
Structures and value objects return updated values under ordinary value semantics. Handle objects update their referenced instance.
Can setfield create nested fields?⌄
Yes. Missing intermediate structures are created along an otherwise valid nested field path.
How do I update a structure-array element?⌄
Put a cell array of one-based indices before the first field name.
Does every GPU field get gathered?⌄
No. Direct replacement preserves untouched and newly assigned resident handles. Only indexed mutation of the resident field gathers that target.
Can I continue a path through a selected cell?⌄
No. Selector cells express parenthesis indexing, so a selected cell remains a cell array. Use ordinary brace indexing outside setfield when you need its contents.
How are object properties assigned?⌄
RunMat mode supports value and handle object properties as an explicit extension and observes static, private, dynamic, and dependent-property rules.
Related Structs functions
fieldnames · getfield · isfield · orderfields · rmfield · struct · structfun
Source you can read
Every RunMat function's source is public. Read exactly how setfield is executed, line by line, in Rust.
- View the source for setfield in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.