What does the fieldnames function do in MATLAB / RunMat?

fieldnames(S) returns a column cell array of character vectors containing the field names defined on S. RunMat mirrors MATLAB by supporting scalar structs, struct arrays, and MATLAB-style objects (including handle objects). The output is always deterministic and case-sensitive.

How does the fieldnames function behave in MATLAB / RunMat?

• Works with scalar structs as well as struct arrays created by struct, load, or other builtins.
• Returns a column cell array (n × 1) whose elements are character vectors (1 × N char arrays).
• Objects (value or handle) report the union of their public, non-static class properties together with any dynamic properties stored on the instance.
• For struct arrays, the union of field names across all elements is reported.
• Field names are sorted alphabetically and remain case-sensitive (name and Name are distinct).
• Empty structs yield an empty 0 × 1 cell array. GPU-resident field values stay on the device— fieldnames only inspects metadata.

fieldnames Function GPU Execution Behaviour

fieldnames is metadata-only. It does not launch kernels or gather data. GPU tensors or handles that live inside structs or objects remain device-resident, and the builtin simply walks the host-side descriptors that remember their names.

GPU residency in RunMat (Do I need gpuArray?)

You do not need to call gpuArray when using fieldnames. RunMat leaves each value—CPU or GPU—where it already resides. When structs or objects contain GPU handles, those handles remain valid and stay resident on the device throughout the introspection call.

Examples of using the fieldnames function in MATLAB / RunMat

Listing the fields of a scalar structure

s = struct("name", "Ada", "score", 42);
fields = fieldnames(s);

Expected output:

fields =
    {'name'}
    {'score'}

Inspecting field names before accessing values

stats = struct("min", 1.2, "max", 9.8);
if any(strcmp(fieldnames(stats), "median"))
    disp(stats.median);
else
    disp("median not available");
end

Expected output:

median not available

Gathering field names from a struct array

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

Expected output:

fields =
    {'id'}
    {'name'}

Listing the properties of an object

% Save this class in Counter.m before running the example:
% classdef Counter
%     properties
%         Value = 0
%         Step  = 1
%     end
% end
c = Counter;
props = fieldnames(c);

Expected output:

props =
    {'Step'}
    {'Value'}

Discovering fields inside nested structs

config.database = struct("host", "db.local", "port", 5432);
names = fieldnames(config.database);

Expected output:

names =
    {'host'}
    {'port'}

Handling empty structs safely

emptyScalar = struct();
emptyArray = struct("id", {});
fs = fieldnames(emptyScalar);
fa = fieldnames(emptyArray);

Expected output:

fs =
  0x1 empty cell array

fa =
  0x1 empty cell array

FAQ

What does fieldnames return?

It returns a column cell array of character vectors for every field or property defined on the input struct, struct array, or object instance.

Are the field names sorted?

Yes. RunMat stores fields and properties in hash maps, so fieldnames sorts them alphabetically to produce a stable, deterministic result.

Does fieldnames gather GPU data back to the CPU?

No. The builtin only inspects host-side metadata; GPU-resident tensors or handles remain untouched.

How do struct arrays affect the result?

All struct elements are examined and the union of their field names is returned. Duplicate names are collapsed automatically.

Does fieldnames work with objects and handle objects?

Yes. The builtin merges public, non-static class properties with any dynamic properties stored on the instance. Handle objects reuse the same logic even when their payloads are shared across references.

What happens with empty structs or empty struct arrays?

The result is an empty column cell array (0 × 1). This matches MATLAB behaviour for empty scalars and for struct arrays that contain no elements.

Can I use fieldnames on unsupported inputs?

No. Passing anything other than a struct, struct array, or object raises fieldnames: expected struct, struct array, or object.

See Also

struct, isfield, getfield, setfield, class

Source & Feedback

• Implementation: crates/runmat-runtime/src/builtins/structs/core/fieldnames.rs
• Found a bug or behaviour mismatch? Open an issue at https://github.com/runmat-org/runmat/issues/new/choose.