6.1.4 Manipulating Structures

Other functions that can manipulate the fields of a structure are given below.

Built-in Function: nfields (s)

Return the number of fields of the structure s.

See also: fieldnames.

Function File: names = fieldnames (struct)

Function File: names = fieldnames (obj)

Function File: names = fieldnames (javaobj)

Function File: names = fieldnames ("jclassname")

Return a cell array of strings with the names of the fields in the specified input.

When the input is a structure struct, the names are the elements of the structure.

When the input is an Octave object obj, the names are the public properties of the object.

When the input is a Java object javaobj or Java classname jclassname the name are the public data elements of the object or class.

See also: nfields, isfield, orderfields, struct, methods.

Built-in Function: isfield (x, "name")

Built-in Function: isfield (x, name)

Return true if the x is a structure and it includes an element named name. If name is a cell array of strings then a logical array of equal dimension is returned.

See also: fieldnames.

Function File: s = setfield (s, field, val)

Function File: s = setfield (s, idx1, field1, idx2, field2, …, val)

Set a field member field in a structure s equal to val. For example:

s = struct ();
s = setfield (s, "foo bar", 42);

This is equivalent to

s.("foo bar") = 42;

Note that ordinary structure syntax s.foo bar = 42 cannot be used here, as the field name is not a valid Octave identifier. Using arbitrary strings for field name is incompatible with MATLAB, so this usage will warn if the Octave:matlab-incompatible warning is set. See XREFwarning_ids.

With the second calling form, set a field on a structure array, possibly nested, with successive nested indices idx1, idx2, … and fields field1, field2, … The indices must be cells containing the desired index at this nesting depth.

Thus consider instead,

s = struct ("baz", 42);
setfield (s, {1}, "foo", {1}, "bar", 5)
    ⇒ ans =
    scalar structure containing the fields:
      baz =  42
      foo =
        scalar structure containing the fields:
          bar =  54

Here we first have an ordinary structure array with one field baz set to 42. Then we set another field in a nested scalar structure indexing with two single cells containing the unique desired indices.

Finally an example with nested structure arrays,

sa.foo = 1;
sa = setfield (sa, {2}, "bar", {3}, "baz", 6);
sa(2).bar(3)
     ⇒ ans =
     scalar structure containing the fields:
       baz =  6

Here sa is a structure array whose field fd at elements 1 and 2 field is in turn another structure array whose third element is a structure

Note that the same result as in the above example could be achieved by:

SA.foo = 1;
SA(2).bar(3).baz = 6

See also: getfield, rmfield, isfield, fieldnames, isstruct, struct.

Function File: [val] = getfield (s, field)

Function File: [val] = getfield (s, idx1, field1, idx2, field2, …)

Extract a field from a structure (or a nested structure). The syntax is the same as setfield, except it omits the final val argument, returning this value instead of setting it.

See also: setfield, rmfield, isfield, fieldnames, isstruct, struct.

Built-in Function: s = rmfield (s, "f")

Built-in Function: s = rmfield (s, f)

Return a copy of the structure (array) s with the field f removed. If f is a cell array of strings or a character array, remove each of the named fields.

See also: orderfields, fieldnames.

Function File: [t, p] = orderfields (s1)

Function File: [t, p] = orderfields (s1, s2)

Return a copy of s1 with fields arranged alphabetically or as specified by s2.

Given one struct, arrange field names in s1 alphabetically.

If the second argument is a struct, arrange field names in s1 as they appear in s2. The second argument may also specify the order in a permutation vector or a cell array of strings containing the fieldnames of s1 in the desired order.

The optional second output argument p is assigned the permutation vector which converts the original name order into the new name order.

Examples:

s = struct ("d", 4, "b", 2, "a", 1, "c", 3);
t1 = orderfields (s)
     ⇒ t1 =
        {
          a =  1
          b =  2
          c =  3
          d =  4
        }

t = struct ("d", {}, "c", {}, "b", {}, "a", {});
t2 = orderfields (s, t)
     ⇒ t2 =
        {
          d =  4
          c =  3
          b =  2
          a =  1
        }

t3 = orderfields (s, [3, 2, 4, 1])
     ⇒ t3 =
        {
          a =  1
          b =  2
          c =  3
          d =  4
        }

[t4, p] = orderfields (s, {"d", "c", "b", "a"})
     ⇒ t4 =
        {
          d =  4
          c =  3
          b =  2
          a =  1
        }
        p =
           1
           4
           2
           3

See also: getfield, rmfield, isfield, isstruct, fieldnames, struct.

Function File: substruct (type, subs, …)

Create a subscript structure for use with subsref or subsasgn. For example:

idx = substruct ("()", {3, ":"})
     ⇒
       idx =
       {
         type = ()
         subs =
         {
           [1,1] =  3
           [1,2] = :
         }
       }
x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
subsref (x, idx)
   ⇒ 7  8  9

See also: subsref, subsasgn.