getfield — Access struct or object fields in MATLAB and RunMat.
value = getfield(S, field) returns the contents of S.field. Nested field access and structure-array indexing follow MATLAB semantics; RunMat object-family access is a separately gated extension.
Syntax
value = getfield(S, field)
value = getfield(S, field_or_index, ...)
value = getfield(S, {idx0}, field_or_index, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
S | Any | Yes | — | Struct, struct array, object, or supported metadata container. |
field | PropertyName | Yes | — | Field/property name. |
path | Any | Variadic | — | Alternating field names and optional index-selector cells `{...}` for nested access. |
S | Any | Yes | — | Struct array or supported indexable container. |
index_selector | Any | Yes | — | Leading index selector in a cell array, e.g. `{2}` or `{end}`. |
Returns
| Name | Type | Description |
|---|---|---|
value | Any | Selected field/property value. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:getfield:NotEnoughInputs | No field-name/path arguments are supplied. | getfield: expected at least one field name |
RunMat:getfield:FieldExpected | Field name is missing after indices or argument parsing. | getfield: expected field name arguments |
RunMat:getfield:IndexSelectorType | Index selector is not provided as a cell array. | getfield: indices must be provided in a cell array |
RunMat:getfield:InvalidIndex | Index components are malformed, empty, unsupported, or not positive integers. | getfield: invalid index element |
RunMat:getfield:FieldNameType | Field name is not a string scalar or 1-by-N char vector. | getfield: expected field name |
RunMat:getfield:IndexShape | Indexing rank/shape is unsupported for the targeted value. | getfield: unsupported index shape for target value |
RunMat:getfield:NonStructReference | Field lookup is attempted on a non-struct/non-object container. | Struct contents reference from a non-struct array object. |
RunMat:getfield:IndexOutOfBounds | Resolved index is outside the bounds of the targeted value. | Index exceeds the number of array elements. |
RunMat:getfield:MissingField | Requested field does not exist on struct/exception/listener. | Reference to non-existent field |
RunMat:PropertyPrivateAccess | Property exists but is private/inaccessible from this context. | You cannot get this property from the current context. |
RunMat:getfield:ObjectProperty | Object property access is invalid (static-through-instance, unknown, or non-public). | getfield: invalid object property access |
RunMat:getfield:InvalidHandle | Handle object is invalid/deleted. | Invalid or deleted handle object |
RunMat:getfield:InternalError | Internal value conversion or output assembly failed. | getfield: internal error |
How getfield works
- Field names must be character vectors or string scalars. Several field names in a row navigate nested structs:
getfield(S, "outer", "inner")is equivalent toS.outer.inner. - When
Sis 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")yieldsS(k).field. - After a field name you may supply an index cell to subscript the field value, e.g.
getfield(S, "values", {row, col}). Numeric indices accept exact positive scalar or vector values from every integer class, and logical vectors select matching elements. - Direct integer field access and host subarray selection preserve the field's exact class, shape, storage, and magnitude; an index class never determines the output class.
- RunMat mode additionally accepts textual
endor numeric selectors, object/handle/listener/exception property access, and indexed resident-field gather. Each family is independently disabled in MATLAB-compatible modes. - Directly retrieved resident fields retain their original handle without provider access. Indexed resident fields use the explicit RunMat-only typed host-gather form and return host data.
Does RunMat run getfield on the GPU?
Direct resident field retrieval performs no provider operation. Indexed resident-field access is not presented as metadata-only: in RunMat mode it routes through the owning provider, downloads authoritative storage, and returns a host result; MATLAB-compatible modes reject it before provider access.
GPU memory and residency
Direct field access is metadata-only and preserves an existing resident handle. Indexing into a resident field is a separately gated RunMat form that gathers exact typed storage to the host.
Examples
Reading a scalar struct field
stats = struct("mean", 42, "stdev", 3.5);
mu = getfield(stats, "mean")Expected output:
mu = 42Navigating 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-06Accessing an element of a struct array
people = struct("name", {"Ada", "Grace"}, "id", {101, 102});
lastId = getfield(people, {2}, "id")Expected output:
lastId = 102Reading the first element of a struct array automatically
people = struct("name", {"Ada", "Grace"}, "id", {101, 102});
firstName = getfield(people, "name")Expected output:
firstName = "Ada"Selecting the last item in a field
series = struct("values", {1:5});
lastValue = getfield(series, "values", {5})Expected output:
lastValue = 5Indexing into a numeric field value
measurements = struct("values", {[1 2 3; 4 5 6]});
entry = getfield(measurements, "values", {2, 3})Expected output:
entry = 6Gathering the exception message from a try/catch block
try
error("RunMat:domainError", "Bad input");
catch e
msg = getfield(e, "message");
endExpected output:
msg = 'Bad input'Using getfield with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how getfield changes the result.
Run a small getfield example, explain the result, then change one input and compare the output.
FAQ
Does getfield work on non-struct values?⌄
The MATLAB-compatible surface requires a scalar or nonscalar structure. RunMat mode additionally supports selected object, handle, listener, and exception values through an explicit extension gate.
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. Supply numeric or logical values inside an index cell. RunMat mode also provides a separately gated textual end convenience.
Do dependent properties run their getter methods?⌄
In RunMat mode, yes. Object-family access is a RunMat extension; dependent properties invoke get.<name> when available, otherwise the backing field <property>_backing is inspected.
What happens when I query a deleted handle object?⌄
The RunMat object-family extension raises Invalid or deleted handle object 'ClassName'.
Related Structs functions
fieldnames · isfield · orderfields · rmfield · setfield · struct · structfun
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how getfield is executed, line by line, in Rust.
- View the source for getfield in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.