6.1.4 Manipulating Structures

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

: numfields (s)

Return the number of fields of the structure s.

See also: fieldnames.

: names = fieldnames (struct)

: names = fieldnames (obj)

: names = fieldnames (javaobj)

: names = fieldnames ("javaclassname")

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 a string containing the name of a Java class javaclassname, the names are the public fields (data members) of the object or class.

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

: isfield (x, "name")

: 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.

: sout = setfield (s, field, val)

: sout = setfield (s, sidx1, field1, fidx1, sidx2, field2, fidx2, …, val)

Return a copy of the structure s with the field member field set to the value 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 because of the space character. Using arbitrary strings for field names is incompatible with MATLAB, and this usage will emit a warning if the warning ID Octave:language-extension is enabled. See warning_ids.

With the second calling form, set a field of a structure array. The input sidx selects an element of the structure array, field specifies the field name of the selected element, and fidx selects which element of the field (in the case of an array or cell array). The sidx, field, and fidx inputs can be repeated to address nested structure array elements. The structure array index and field element index must be cell arrays while the field name must be a string.

For example:

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

The example begins with an ordinary scalar structure to which a nested scalar structure is added. In all cases, if the structure index sidx is not specified it defaults to 1 (scalar structure). Thus, the example above could be written more concisely as setfield (s, "foo", "bar", 54)

Finally, an example with nested structure arrays:

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

Here sa is a structure array whose field at elements 1 and 2 is in turn another structure array whose third element is a simple scalar structure. The terminal scalar structure has a field which contains a matrix value.

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

sa.foo = 1;
sa(2).bar(3).baz(1,4) = 5

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

: val = getfield (s, field)

: val = getfield (s, sidx1, field1, fidx1, …)

Get the value of the field named field from a structure or nested structure s.

If s is a structure array then sidx selects an element of the structure array, field specifies the field name of the selected element, and fidx selects which element of the field (in the case of an array or cell array). See setfield for a more complete description of the syntax.

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

: sout = rmfield (s, "f")

: sout = 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, isfield.

: sout = orderfields (s1)

: sout = orderfields (s1, s2)

: sout = orderfields (s1, {cellstr})

: sout = orderfields (s1, p)

: [sout, p] = orderfields (…)

Return a copy of s1 with fields arranged alphabetically, or as specified by the second input.

Given one input struct s1, arrange field names alphabetically.

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

The optional second output argument p is the permutation vector which converts the original name order to 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: fieldnames, getfield, setfield, rmfield, isfield, isstruct, struct.

: 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.