RunMat
GitHub

View all functions

CategoryStructs: Core

setfield — Assign into struct fields, struct arrays, or MATLAB-style object properties.

S = setfield(S, field, value) returns a copy of the struct (or object) with field assigned to value. Additional field names and index cells let you update nested structures, struct arrays, and array elements contained within fields.

How does the setfield function behave in MATLAB / RunMat?

  • Field names must be character vectors or string scalars. Provide as many field names as needed; each additional name drills deeper into nested structs, so setfield(S,"outer","inner",value) mirrors S.outer.inner = value.
  • Missing struct fields are created automatically. If intermediary structs do not exist, RunMat allocates them so that the assignment completes successfully.
  • Struct arrays require a leading cell array of one-based indices, e.g. setfield(S,{2},"field",value) or setfield(S,{1,3},"field",value), and accept the keyword end.
  • You can index into a field's contents before traversing deeper by placing a cell array of indices immediately after the field name: setfield(S,"values",{1,2},"leaf",x) matches S.values{1,2}.leaf = x.
  • MATLAB-style objects honour property metadata: private setters raise access errors, static properties cannot be written through instances, and dependent properties forward to set.<name> methods when available.
  • The function returns the updated struct or object. For value types the result is a new copy; handle objects still point at the same instance, and the handle is returned for chaining.

GPU behavior

setfield executes entirely on the host. When fields contain GPU-resident tensors, RunMat gathers those tensors to host memory before mutating them and stores the resulting host tensor back into the struct or object. No GPU kernels are launched for these assignments.

GPU residency

You do not have to move data explicitly when assigning into structs. If a field contains a GPU tensor, setfield gathers it to host memory so the mutation can be performed safely. Subsequent operations decide whether to migrate it back to the GPU.

Examples of using setfield in MATLAB / RunMat

Assigning a new field in a scalar struct

s = struct();
s = setfield(s, "answer", 42);
disp(s.answer)

Expected output:

42

Creating nested structs automatically

cfg = struct();
cfg = setfield(cfg, "solver", "name", "cg");
cfg = setfield(cfg, "solver", "tolerance", 1e-6);
disp(cfg.solver.tolerance)

Expected output:

1.0000e-06

Updating an element of a struct array

people = struct("name", {"Ada", "Grace"}, "id", {101, 102});
people = setfield(people, {2}, "id", 999);
disp(people(2).id)

Expected output:

999

Assigning through a field that contains a cell array

data = struct("samples", {{struct("value", 1), struct("value", 2)}} );
data = setfield(data, "samples", {2}, "value", 10);
disp(data.samples{2}.value)

Expected output:

10

Setting an object property that honours access attributes

classdef Point
    properties
        x double = 0;
    end
end

Expected output:

3

FAQ

Does setfield modify the input in-place?

No. Like MATLAB, it returns a new struct (or object) with the requested update. In Rust this entails cloning the source value and mutating the clone.

Can I create nested structs in a single call?

Yes. Missing intermediate structs are created automatically when you provide multiple field names, e.g. setfield(S,"outer","inner",value) builds outer when needed.

How do I update a specific element of a struct array?

Supply an index cell before the first field name: setfield(S,{row,col},"field",value) is the same as S(row,col).field = value.

Does setfield work with handle objects?

Yes. Valid handle objects forward the assignment to the underlying instance. Deleted or invalid handles raise the standard MATLAB-style error.

Can I index into field contents before continuing?

Yes. Place a cell array of indices immediately after the field name. Each set of indices uses MATLAB's one-based semantics and supports the keyword end.

Why are GPU tensors gathered to the host?

Assignments require host-side mutation. Providers can re-upload the updated tensor on subsequent GPU-aware operations; setfield itself never launches kernels.

See also

getfield, fieldnames, struct, gpuArray, gather

Source & Feedback