Go to the first, previous, next, last section, table of contents.

# 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 section 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.

Go to the first, previous, next, last section, table of contents.