A.1.5 Structures in Oct-Files

A structure in Octave is a map between a number of fields represented and their values. The Standard Template Library map class is used, with the pair consisting of a std::string and an Octave Cell variable.

A simple example demonstrating the use of structures within oct-files is

#include <octave/oct.h>
#include <octave/ov-struct.h>

DEFUN_DLD (structdemo, args, , "Struct Demo")
{
  if (args.length () != 2)
    print_usage ();

  if (! args(0).isstruct ())
    error ("structdemo: ARG1 must be a struct");

  octave_scalar_map arg0 = args(0).scalar_map_value ();
  //octave_map arg0 = args(0).map_value ();

  if (! args(1).is_string ())
    error ("structdemo: ARG2 must be a character string");

  std::string arg1 = args(1).string_value ();

  octave_value tmp = arg0.contents (arg1);
  //octave_value tmp = arg0.contents (arg1)(0);

  if (! tmp.is_defined ())
    error ("structdemo: struct does not have a field named '%s'\n",
           arg1.c_str ());

  octave_scalar_map st;

  st.assign ("selected", tmp);

  return octave_value (st);
}

An example of its use is

x.a = 1; x.b = "test"; x.c = [1, 2];
structdemo (x, "b")
⇒ selected = test

The example above specifically uses the octave_scalar_map class which is for representing a single struct. For structure arrays, the octave_map class is used instead. The commented code shows how the demo could be modified to handle a structure array. In that case, the contents method returns a Cell which may have more than one element. Therefore, to obtain the underlying octave_value in the single struct example we would write

octave_value tmp = arg0.contents (arg1)(0);

where the trailing (0) is the () operator on the Cell object. If this were a true structure array with multiple elements we could iterate over the elements using the () operator.

Structures are a relatively complex data container and there are more functions available in oct-map.h which make coding with them easier than relying on just contents.

© 1996–2020 John W. Eaton
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.
https://octave.org/doc/v5.2.0/Structures-in-Oct_002dFiles.html