@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Data Structures, Variables, Strings, Top
@chapter Data Structures
@cindex structures
@cindex 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

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

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

@example
@group
octave:2> x
x =
@{
  a = 1
  b =

    1  2
    3  4

  c = string
@}
@end group
@end example

@noindent
Note that Octave may print the elements in any order.

Structures may be copied.

@example
@group
octave:1> y = x
y =
@{
  a = 1
  b =

    1  2
    3  4

  c = string
@}
@end group
@end example

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

@example
@group
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
@}
@end group
@end example

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

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

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

@defvr {Built-in Variable} struct_levels_to_print
You can tell Octave how many structure levels to display by setting the
built-in variable @code{struct_levels_to_print}.  The default value is 2.
@end defvr

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.

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

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

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

    0.26475  0.14828
    0.18436  0.83669

  re =

    0.040239  0.242160
    0.238081  0.402523
@}
@end group
@end example

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

@example
@group
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
@end group
@end example

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

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

@deftypefn {Built-in Function} {} is_struct (@var{expr})
Return 1 if the value of the expression @var{expr} is a structure.
@end deftypefn

@deftypefn {Built-in Function} {} struct_contains (@var{expr}, @var{name})
Return 1 if the expression @var{expr} is a structure and it includes an
element named @var{name}.  The first argument must be a structure and
the second must be a string.
@end deftypefn

@deftypefn {Built-in Function} {} struct_elements (@var{struct})
Return a list of strings naming the elements of the structure
@var{struct}.  It is an error to call @code{struct_elements} with an
argument that is not a structure.
@end deftypefn