@c DO NOT EDIT!  Generated automatically by munge-texi.

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

@c FIXME update for structure arrays
@c FIXME need discussion of comma-separated lists somewhere

@node Data Structures
@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 =
    @{
      d: 1x1 struct
    @}
  @}
@}
@end group
@end example

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

@anchor{doc-struct_levels_to_print}
@deftypefn {Built-in Function} {@var{val} =} struct_levels_to_print ()
@deftypefnx {Built-in Function} {@var{old_val} =} struct_levels_to_print (@var{new_val})
Query or set the internal variable that specifies the number of
structure levels to display.
@end deftypefn


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.

@anchor{doc-struct}
@deftypefn {Built-in Function} {} struct ("field", @var{value}, "field", @var{value}, @dots{})

Create a structure and initialize its value.

If the values are cell arrays, create a structure array and initialize
its values.  The dimensions of each cell array of values must match.
Singleton cells and non-cell values are repeated so that they fill
the entire array.  If the cells are empty, create an empty structure
array with the specified field names.
@end deftypefn


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


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


@anchor{doc-isfield}
@deftypefn {Built-in Function} {} isfield (@var{expr}, @var{name})
Return true 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


@anchor{doc-getfield}
@deftypefn {Function File} {[@var{v1}, @dots{}] =} getfield (@var{s}, @var{key}, @dots{}) 
Extract fields from a structure. For example

@example
@group
ss(1,2).fd(3).b=5;
getfield (ss, @{1,2@}, "fd", @{3@}, "b")
@result{} ans = 5
@end group
@end example

Note that the function call in the previous example is equivalent to
the expression

@example
         i1= @{1,2@}; i2= "fd"; i3= @{3@}; i4= "b";
         ss(i1@{:@}).(i2)(i3@{:@}).(i4)
@end example
@seealso{setfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn


@anchor{doc-orderfields}
@deftypefn {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1}, @var{s2})
Return a struct with fields arranged alphabetically or as specified
by @var{s2} and a corresponding permutation vector.

Given one struct, arrange field names in @var{s1} alphabetically.

Given two structs, arrange field names in @var{s1} as they appear
in @var{s2}.  The second argument may also specify the order in
a permutation vector or a cell array of strings.

@seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn


@anchor{doc-rmfield}
@deftypefn {Built-in Function} {} rmfield (@var{s}, @var{f})
Remove field @var{f} from the structure @var{s}.  If @var{f} is a
cell array of character strings or a character array, remove the
named fields.
@seealso{cellstr, iscellstr, setfield}
@end deftypefn


@anchor{doc-setfield}
@deftypefn {Function File} {[@var{k1}, @dots{}, @var{v1}] =} setfield (@var{s}, @var{k1}, @var{v1}, @dots{})
Set field members in a structure.

@example
@group
oo(1,1).f0= 1;
oo = setfield(oo,@{1,2@},'fd',@{3@},'b', 6);
oo(1,2).fd(3).b == 6
@result{} ans = 1
@end group
@end example

Note that this function could be written

@example
         i1= @{1,2@}; i2= 'fd'; i3= @{3@}; i4= 'b';
         oo( i1@{:@} ).( i2 )( i3@{:@} ).( i4 ) == 6;
@end example
@seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn


@anchor{doc-struct2cell}
@deftypefn {Built-in Function} {} struct2cell (@var{S})
Create a new cell array from the objects stored in the struct object.
If @var{f} is the number of fields in the structure, the resulting
cell array will have a dimension vector corresponding to
@code{[@var{F} size(@var{S})]}.
@seealso{cell2struct, fieldnames}
@end deftypefn


@anchor{doc-substruct}
@deftypefn {Function File} {} substruct (@var{type}, @var{subs}, @dots{})
Create a subscript structure for use with @code{subsref} or
@code{subsasgn}.
@seealso{subsref, subsasgn}
@end deftypefn

