A.1.5 Structures in Oct-Files

A structure in Octave is 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.")
     {
       int nargin = args.length ();
       octave_value retval;
     
       if (args.length () == 2)
         {
           octave_scalar_map arg0 = args(0).scalar_map_value ();
     
           if (! error_state)
             {
               std::string arg1 = args(1).string_value ();
     
               if (! error_state)
                 {
                   octave_value tmp = arg0.contents (arg1);
     
                   if (tmp.is_defined ())
                     {
                       octave_scalar_map st;
     
                       st.assign ("selected", tmp);
     
                       retval = octave_value (st);
                     }
                   else
                     error ("sruct does not contain field named '%s'\n",
                            arg1.c_str ());
                 }
               else
                 error ("expecting character string as second argument");
             }
           else
             error ("expecting struct as first argument");
         }
       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 commented code above demonstrates how to iterate over all of the fields of the structure, where as the following code demonstrates finding a particular field in a more concise manner.

As can be seen the contents method of the Octave_map class returns a Cell which allows structure arrays to be represented. Therefore, to obtain the underlying octave_value we write

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

where the trailing (0) is the () operator on the Cell object. We can equally iterate of the elements of the Cell array to address the elements of the structure array.