rmfield — Remove one or more named fields from structs or struct arrays with MATLAB-compatible validation.
S2 = rmfield(S, name) returns a copy of S with the named field removed. It accepts multiple field names, string arrays, or cell arrays of names and follows MATLAB-compatible errors for missing fields and invalid field-name inputs.
Syntax
S = rmfield(S, field)
S = rmfield(S, fields)
S = rmfield(S, field, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
S | Any | Yes | — | Input struct or struct array. |
field | StringScalar | Yes | — | Field name to remove. |
fields | Any | Yes | — | String array or cell array of field names. |
field | StringScalar | Yes | — | First field name to remove. |
more_fields | Any | Variadic | — | Additional field names. |
Returns
| Name | Type | Description |
|---|---|---|
S | Any | Updated struct or struct array. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:rmfield:NotEnoughInputs | No field-name arguments are supplied. | rmfield: not enough input arguments |
RunMat:rmfield:InvalidTarget | First input is not a struct or struct array. | rmfield: expected struct or struct array |
RunMat:rmfield:FieldNameType | Field-name argument has unsupported type or non-scalar shape. | rmfield: field names must be string scalars, character vectors, or single-element string arrays |
RunMat:rmfield:FieldNameEmpty | A field name is empty. | rmfield: field names must be nonempty character vectors or strings |
RunMat:rmfield:MissingField | At least one requested field does not exist on the input struct. | Reference to non-existent field |
RunMat:rmfield:StructArrayContents | Struct-array input contains non-struct elements. | rmfield: expected struct array contents to be structs |
RunMat:rmfield:RebuildFailed | Rebuilding the updated struct array failed. | rmfield: failed to rebuild struct array |
How rmfield works
- Works with scalar structs and struct arrays created by
struct,load, or other builtins. - Accepts character vectors, string scalars, string arrays, and cell arrays containing those types to identify the fields that should be removed.
- Every listed field must already exist. Attempting to remove a missing field raises the standard MATLAB-style error
Reference to non-existent field '<name>'. - Removing multiple fields applies to every element in a struct array; the operation fails if any element is missing one of the requested fields.
- The input
Sis not mutated in place.rmfieldreturns a new struct (or struct array) while the original remains unchanged. - Retained fields preserve every nested integer class and exact payload structurally, including wide values, without conversion or provider access.
Does RunMat run rmfield on the GPU?
rmfield performs metadata updates on the host. Values that already reside on the GPU—such as gpuArray tensors stored in other fields—stay on the device. Because this builtin only rewrites struct metadata it does not require or invoke acceleration provider hooks.
GPU memory and residency
No additional residency management is required. rmfield leaves existing GPU tensors untouched and never gathers or uploads buffers. Subsequent GPU-aware builtins decide whether to keep values on the device.
Examples
Removing a single field from a scalar struct
s = struct("name", "Ada", "score", 42);
t = rmfield(s, "score");
isfield(t, "score")Expected output:
ans =
logical
0Removing several fields with a cell array of names
cfg = struct("mode", "fast", "rate", 60, "debug", true);
cfg = rmfield(cfg, {"rate", "debug"});
fieldnames(cfg)Expected output:
ans =
1×1 cell array
{'mode'}Removing a field from every element of a struct array
people = struct("name", {"Ada", "Grace"}, "id", {101, 102}, "email", {"ada@example.com", "grace@example.com"});
trimmed = rmfield(people, "email");
fieldnames(trimmed)Expected output:
ans =
2×1 cell array
{'id'}
{'name'}Supplying a string array of field names to delete
stats = struct("mean", 10, "median", 9, "stdev", 2);
names = ["mean", "median"];
reduced = rmfield(stats, names);
fieldnames(reduced)Expected output:
ans =
1×1 cell array
{'stdev'}Conditionally removing optional fields
record = struct("id", 7, "notes", "draft");
if isfield(record, "notes")
record = rmfield(record, "notes");
end
fieldnames(record)Expected output:
ans =
1×1 cell array
{'id'}Using rmfield with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how rmfield changes the result.
Run a small rmfield example, explain the result, then change one input and compare the output.
FAQ
Does rmfield modify the input in place?⌄
No. The function returns a new struct (or struct array) with the specified fields removed. The input value remains unchanged, mirroring MATLAB's copy-on-write semantics.
What argument types can I use for the field names?⌄
You can pass character vectors, string scalars, string arrays, or cell arrays whose elements are strings or character vectors. Mixing these forms in a single call is supported—rmfield concatenates all supplied names into one list.
What happens if a field is missing?⌄
RunMat raises the MATLAB-compatible error Reference to non-existent field '<name>'. and leaves the struct unchanged.
Can I remove nested fields with rmfield?⌄
No. rmfield only removes top-level fields. Use setfield with nested assignments or restructure your data if you need to manipulate nested content.
Does rmfield work with MATLAB-style objects or handle classes?⌄
No. The builtin is restricted to structs and struct arrays. Use class-specific helpers (such as rmprop) for objects.
Does removing a field move GPU tensors back to the CPU?⌄
No. The builtin merely rewrites metadata. Any GPU-resident values stored in remaining fields stay on the device until another operation decides otherwise.
Related Structs functions
fieldnames · getfield · isfield · orderfields · setfield · struct · structfun
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how rmfield is executed, line by line, in Rust.
- View the source for rmfield 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.