Data Structures
***************

Octave includes support for organizing data in structures.  The current implementation uses an associative array with indices limited to strings, but the syntax is more like C-style structures.  Here are some examples of using data structures in Octave.

Elements of structures can be of any value type.  For example, the three expressions

     x.a = 1
     x.b = [1, 2; 3, 4]
     x.c = "string"

create a structure with three elements.  To print the value of the structure, you can type its name, just as for any other variable:

     octave:2> x
     x =
     {
       a = 1
       b =

         1  2
         3  4

       c = string
     }

Note that Octave may print the elements in any order.

Structures may be copied.

     octave:1> y = x
     y =
     {
       a = 1
       b =

         1  2
         3  4

       c = string
     }

Since structures are themselves values, structure elements may reference other structures.  The following statements change the value of the element b of the structure x to be a data structure containing the single element d, which has a value of 3.

     octave:1> x.b.d = 3
     x.b.d = 3
     octave:2> x.b
     ans =
     {
       d = 3
     }
     octave:3> x
     x =
     {
       a = 1
       b =
       {
         d = 3
       }

       c = string
     }

Note that when Octave prints the value of a structure that contains other structures, only a few levels are displayed.  For example,

     octave:1> a.b.c.d.e = 1;
     octave:2> a
     a =
     {
       b =
       {
         c = <structure>
       }
     }

This prevents long and confusing output from large deeply nested structures.

 -- Built-in Variable: struct_levels_to_print
     You can tell Octave how many structure levels to display by setting the built-in variable struct_levels_to_print.  The default value is 2.

Functions can return structures.  For example, the following function separates the real and complex parts of a matrix and stores them in two elements of the same structure variable.

     octave:1> function y = f (x)
     > y.re = real (x);
     > y.im = imag (x);
     > endfunction

When called with a complex-valued argument, f returns the data structure containing the real and imaginary parts of the original function argument.

     octave:2> f (rand (3) + rand (3) * I);
     ans =
     {
       im =

         0.26475  0.14828
         0.18436  0.83669

       re =

         0.040239  0.242160
         0.238081  0.402523
     }

Function return lists can include structure elements, and they may be indexed like any other variable.  For example,

     octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4])
     x.u =

       -0.40455  -0.91451
       -0.91451   0.40455

     x.s =

       0.00000  0.00000  0.00000
       0.00000  5.46499  0.00000
       0.00000  0.00000  0.36597

     x.v =

       -0.57605   0.81742
       -0.81742  -0.57605

It is also possible to cycle through all the elements of a structure in a loop, using a special form of the for statement (see The for Statement)

The following functions are available to give you information about structures.

 -- Built-in Function: is_struct (EXPR)
     Return 1 if the value of the expression EXPR is a structure.

 -- Built-in Function: struct_contains (EXPR, NAME)
     Return 1 if the expression EXPR is a structure and it includes an element named NAME.  The first argument must be a structure and the second must be a string.

 -- Built-in Function: struct_elements (STRUCT)
     Return a list of strings naming the elements of the structure STRUCT.  It is an error to call struct_elements with an argument that is not a structure.