Next: , Previous: Cell Arrays in Oct-Files, Up: Oct-Files


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.