RunMat
GitHub

View all functions

CategoryStructs: Core

What does the getfield function do in MATLAB / RunMat?

value = getfield(S, field) returns the contents of S.field. RunMat matches MATLAB by supporting nested field access, struct arrays (via index cells), and MATLAB-style objects created with new_object.

How does the getfield function behave in MATLAB / RunMat?

  • Field names must be character vectors or string scalars. Several field names in a row navigate nested structs: getfield(S, "outer", "inner") is equivalent to S.outer.inner.
  • When S is a struct array, getfield(S, "field") examines the first element by default. Provide indices in a cell array to target another element: getfield(S, {k}, "field") yields S(k).field.
  • After a field name you may supply an index cell to subscript the field value, e.g. getfield(S, "values", {row, col}). Each position accepts positive integers or the keyword end to reference the last element in that dimension.
  • MATLAB-style objects honour property attributes: static or private properties raise errors, while dependent properties invoke get.<name> when available.
  • Handle objects dereference to their underlying instance automatically. Deleted handles raise the standard MATLAB-style error.
  • MException values expose the message, identifier, and stack fields for compatibility with MATLAB error handling.

getfield Function GPU Execution Behaviour

getfield is metadata-only. When structs or objects contain GPU tensors, the tensors remain on the device. The builtin manipulates only the host-side metadata and does not dispatch GPU kernels or gather buffers back to the CPU. Results inherit residency from the values being returned.

Examples of using the getfield function in MATLAB / RunMat

Reading a scalar struct field

stats = struct("mean", 42, "stdev", 3.5);
mu = getfield(stats, "mean");

Expected output:

mu = 42

Navigating nested structs with multiple field names

cfg = struct("solver", struct("name", "cg", "tolerance", 1e-6));
tol = getfield(cfg, "solver", "tolerance");

Expected output:

tol = 1.0000e-06

Accessing an element of a struct array

people = struct("name", {"Ada", "Grace"}, "id", {101, 102});
lastId = getfield(people, {2}, "id");

Expected output:

lastId = 102

Reading the first element of a struct array automatically

people = struct("name", {"Ada", "Grace"}, "id", {101, 102});
firstName = getfield(people, "name");

Expected output:

firstName = "Ada"

Using end to reference the last item in a field

series = struct("values", {1:5});
lastValue = getfield(series, "values", {"end"});

Expected output:

lastValue = 5

Indexing into a numeric field value

measurements = struct("values", {[1 2 3; 4 5 6]});
entry = getfield(measurements, "values", {2, 3});

Expected output:

entry = 6

Gathering the exception message from a try/catch block

try
    error("MATLAB:domainError", "Bad input");
catch e
    msg = getfield(e, "message");
end

Expected output:

msg = 'Bad input'

GPU residency in RunMat (Do I need gpuArray?)

You do not have to move data between CPU and GPU explicitly when calling getfield. The builtin works entirely with metadata and returns handles or tensors in whatever memory space they already inhabit.

FAQ

Does getfield work on non-struct values?

No. The first argument must be a scalar struct, a struct array (possibly empty), an object instance created with new_object, a handle object, or an MException. Passing other types raises an error.

How do I access nested struct fields?

Provide every level explicitly: getfield(S, "parent", "child", "leaf") traverses the same path as S.parent.child.leaf.

How do I read from a struct array?

Supply a cell array of indices before the first field name. For example, getfield(S, {3}, "value") mirrors S(3).value. Indices are one-based like MATLAB.

Can I index the value stored in a field?

Yes. You may supply scalars or end inside the index cell to reference elements of the field value.

Do dependent properties run their getter methods?

Yes. If a property is marked Dependent and a get.propertyName builtin exists, getfield invokes it. Otherwise the backing field <property>_backing is inspected.

What happens when I query a deleted handle object?

RunMat mirrors MATLAB by raising Invalid or deleted handle object 'ClassName'.

See Also

fieldnames, isfield, setfield, struct, class