#### 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")
    {
      octave_value retval;
      int nargin = args.length ();

      if (args.length () == 2)
        {
          octave_scalar_map arg0 = args(0).scalar_map_value ();
          //octave_map arg0 = args(0).map_value ();

          if (! error_state)
            {
              std::string arg1 = args(1).string_value ();

              if (! error_state)
                {
                  octave_value tmp = arg0.contents (arg1);
                  //octave_value tmp = arg0.contents (arg1)(0);

                  if (tmp.is_defined ())
                    {
                      octave_scalar_map st;

                      st.assign ("selected", tmp);

                      retval = octave_value (st);
                    }
                  else
                    error ("structdemo: struct does not have a field named '%s'\n",
                           arg1.c_str ());
                }
              else
                error ("structdemo: ARG2 must be a character string");
            }
          else
            error ("structdemo: ARG1 must be a struct");
        }
      else
        print_usage ();

      return retval;
    }

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 this single-struct example we 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`.