@c Copyright (C) 1996, 1997, 2007, 2008, 2009 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Data Containers
@chapter Data Containers
@cindex containers

Octave includes support for two different mechanisms to contain
arbitrary data types in the same variable. Structures, which are C-like,
and are indexed with named fields, and cell arrays, where each element
of the array can have a different data type and or shape.

@menu
* Data Structures::
* Cell Arrays::
* Comma Separated Lists::
@end menu

@node Data Structures
@section 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.

@DOCSTRING(struct_levels_to_print)

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{Looping Over Structure Elements})

@menu
* Structure Arrays::
* Creating Structures::
* Manipulating Structures::
* Processing Data in Structures::
@end menu

@node Structure Arrays
@subsection Structure Arrays

A structure array is a particular instance of a structure, where each of
the fields of the structure is represented by a cell array. Each of
these cell arrays has the same dimensions. An example of the creation of
a structure array is

@example
@group
x(1).a = "string1"
x(2).a = "string2"
x(1).b = 1
x(2).b = 2
@end group
@end example

@noindent
which creates a 2-by-1 structure array with two fields. As previously,
to print the value of the structure array, you can type its name:

@example
@group
octave:1> x
x =
@{
  1x2 struct array containing the fields:

    a
    b
@}  
@end group
@end example

Individual elements of the structure array can be returned by indexing
the variable like @code{@var{x} (1)}, which returns a structure with the
two fields like

@example
@group
octave:2> x(1)
ans =
@{
  a = string1
  b =  1
@}
@end group
@end example

Furthermore, the structure array can return a comma separated list
(@pxref{Comma Separated Lists}), if indexed by one of its own field
names. For example

@example
@group
octave:3> x.a
ans = string1
ans = string2
@end group
@end example

Here is another example, using this comma separated list on the
left-hand side of an assignment:

@example
@group
octave:4> [x.a] = deal("new string1", "new string2");
octave:5> x(1).a
ans = new string1
octave:6> x(2).a
ans = new string2
@end group
@end example

Just as for numerical arrays, it is possible to use vectors as indices (@pxref{Index Expressions}):

@example
@group
octave:7> x(3:4) = x(1:2);
octave:8> [x([1,3]).a] = deal("other string1", "other string2");
octave:9> x.a
ans = other string1
ans = new string2
ans = other string2
ans = new string2
@end group
@end example

The function @code{size} will return the size of the structure. For
the example above

@example
@group
octave:10> size(x)
ans =

   1   4
@end group
@end example

Elements can be deleted from a structure array in a similar manner to a
numerical array, by assigning the elements to an empty matrix. For
example

@example
@group
in = struct ("call1", @{x, Inf, "last"@}, 
             "call2", @{x, Inf, "first"@});
in (1, :) = []
@result{} in =
      @{
        call1 =
      
        (,
          [1] = Inf
          [2] = last
        ,)
      
        call2 =
      
        (,
          [1] = Inf
          [2] = first
        ,)
      
      @}
@end group
@end example

@node Creating Structures
@subsection Creating Structures

As well as indexing a structure with ".", Octave can create a structure
with the @code{struct} command. @code{struct} takes pairs of arguments,
where the first argument in the pair is the fieldname to include in the
structure and the second is a scalar or cell array, representing the
values to include in the structure or structure array. For example

@example
@group
struct ("field1", 1, "field2", 2)
@result{} ans =
      @{
        field1 =  1
        field2 =  2
      @}
@end group
@end example

If the values passed to @code{struct} are a mix of scalar and cell
arrays, then the scalar arguments are expanded to create a 
structure array with a consistent dimension. For example

@example
@group
struct ("field1", @{1, "one"@}, "field2", @{2, "two"@},
        "field3", 3)
@result{} ans =
      @{
        field1 =
      
        (,
          [1] =  1
          [2] = one
        ,)
      
        field2 =
      
        (,
          [1] =  2
          [2] = two
        ,)
      
        field3 =
      
        (,
          [1] =  3
          [2] =  3
        ,)
      
      @}
@end group
@end example

@DOCSTRING(struct)

@DOCSTRING(isstruct)

Additional functions that can manipulate the fields of a structure are
listed below.

@DOCSTRING(rmfield)

@DOCSTRING(setfield)

@DOCSTRING(orderfields)

@node Manipulating Structures
@subsection Manipulating Structures

Other functions that can manipulate the fields of a structure are given below.

@DOCSTRING(fieldnames)

@DOCSTRING(isfield)

@DOCSTRING(getfield)

@DOCSTRING(substruct)

@node Processing Data in Structures
@subsection Processing Data in Structures

The simplest way to process data in a structure is within a @code{for}
loop (@pxref{Looping Over Structure Elements}). A similar effect can be
achieved with the @code{structfun} function, where a user defined
function is applied to each field of the structure.

@DOCSTRING(structfun)

Alternatively, to process the data in a structure, the structure might
be converted to another type of container before being treated.

@DOCSTRING(struct2cell)

@node Cell Arrays
@section Cell Arrays
@cindex cell arrays

It can be both necessary and convenient to store several variables of
different size or type in one variable. A cell array is a container
class able to do just that. In general cell arrays work just like
@math{N}-dimensional arrays, with the exception of the use of @samp{@{}
and @samp{@}} as allocation and indexing operators.

As an example, the following code creates a cell array containing a
string and a 2-by-2 random matrix

@example
c = @{"a string", rand(2, 2)@};
@end example

@noindent
And a cell array can be indexed with the @{ and @} operators, so the
variable created in the previous example can be indexed like this

@example
@group
c@{1@}
     @result{} ans = a string
@end group
@end example

@noindent
As with numerical arrays several elements of a cell array can be
extracted by indexing with a vector of indexes

@example
@group
c@{1:2@}
     @result{} ans =
          
          (,
            [1] = a string
            [2] =
          
               0.593993   0.627732
               0.377037   0.033643
          
          ,)
@end group
@end example

The indexing operators can also be used to insert or overwrite elements
of a cell array. The following code inserts the scalar 3 on the
third place of the previously created cell array

@example
@group
c@{3@} = 3
     @result{} c =
         
         @{
           [1,1] = a string
           [1,2] =
         
              0.593993   0.627732
              0.377037   0.033643
         
           [1,3] =  3
         @}
@end group
@end example

In general nested cell arrays are displayed hierarchically as above. In
some circumstances it makes sense to reference them by their index, and
this can be performed by the @code{celldisp} function.

@DOCSTRING(celldisp)

@menu
* Creating Cell Arrays::                 
* Indexing Cell Arrays::
* Cell Arrays of Strings::
* Processing Data in Cell Arrays::
@end menu

@node Creating Cell Arrays
@subsection Creating Cell Array

The introductory example showed how to create a cell array containing
currently available variables. In many situations, however, it is useful
to create a cell array and then fill it with data.

The @code{cell} function returns a cell array of a given size, containing
empty matrices. This function is similar to the @code{zeros}
function for creating new numerical arrays. The following example creates
a 2-by-2 cell array containing empty matrices

@example
@group
c = cell(2,2)
     @result{} c =
         
         @{
           [1,1] = [](0x0)
           [2,1] = [](0x0)
           [1,2] = [](0x0)
           [2,2] = [](0x0)
         @}
@end group
@end example

Just like numerical arrays, cell arrays can be multidimensional. The
@code{cell} function accepts any number of positive integers to describe
the size of the returned cell array. It is also possible to set the size
of the cell array through a vector of positive integers. In the
following example two cell arrays of equal size are created, and the size
of the first one is displayed

@example
c1 = cell(3, 4, 5);
c2 = cell( [3, 4, 5] );
size(c1)
     @result{} ans =
         3   4   5
@end example

@noindent
As can be seen, the @code{size} function also works for cell arrays. As
do the other functions describing the size of an object, such as
@code{length}, @code{numel}, @code{rows}, and @code{columns}.

As an alternative to creating empty cell arrays, and then filling them,  it
is possible to convert numerical arrays into cell arrays using the
@code{num2cell} and @code{mat2cell} functions.

@DOCSTRING(cell)

@DOCSTRING(iscell)

@DOCSTRING(num2cell)

@DOCSTRING(mat2cell)

@node Indexing Cell Arrays
@subsection Indexing Cell Arrays

As shown in the introductory example elements can be inserted from cell
arrays using the @samp{@{} and @samp{@}} operators. Besides the change
of operators, indexing works for cell arrays like for multidimensional
arrays.  As an example, all the rows of the first and third column of a
cell array can be set to @code{0} with the following code

@example
c@{:, [1, 3]@} = 0;
@end example

Accessing values in a cell array is, however, different from the same
operation for numerical arrays. Accessing a single element of a cell
array is very similar to numerical arrays, for example

@example
element = c@{1, 2@};
@end example

@noindent
This will, however, @emph{not} work when accessing multiple elements of
a cell array, because it might not be possible to represent all elements
with a single variable as is the case with numerical arrays.

Accessing multiple elements of a cell array with the @samp{@{} and
@samp{@}} operators will result in a comma-separated list (@pxref{Comma
Separated Lists}) of all the requested elements as discussed later. 

One distinction between @samp{@{} and @samp{(} to index cell arrays is
in the deletion of elements from the cell array. In a similar manner to
a numerical array the @samp{()} operator can be used to delete elements
from the cell array. The @samp{@{@}} operator however will remove the
elements of the cell array, but not delete the space for them. For example

@example
@group
x = @{"1", "2"; "3", "4"@};
x@{1, :@} = []
@result{} x =
      @{
        [1,1] = [](0x0)
        [2,1] = 3
        [1,2] = [](0x0)
        [2,2] = 4
      @}

x(1, :) = []
@result{} x =
      @{
        [1,1] = 3
        [1,2] = 4
      @}
@end group
@end example

@node Cell Arrays of Strings
@subsection Cell Arrays of Strings

One common use of cell arrays is to store multiple strings in the same
variable. It is possible to store multiple strings in a character matrix
by letting each row be a string. This, however, introduces the problem
that all strings must be of equal length. Therefore it is recommended to
use cell arrays to store multiple strings. If, however, the character
matrix representation is required for an operation, it can be converted
to a cell array of strings using the @code{cellstr} function

@example
a = ["hello"; "world"];
c = cellstr (a)
     @result{} c =
         @{
           [1,1] = hello
           [2,1] = world
         @}
@end example

One further advantage of using cell arrays to store multiple strings is
that most functions for string manipulations included with Octave
support this representation. As an example, it is possible to compare
one string with many others using the @code{strcmp} function. If one of
the arguments to this function is a string and the other is a cell array
of strings, each element of the cell array will be compared the string
argument,

@example
c = @{"hello", "world"@};
strcmp ("hello", c)
     @result{} ans =
        1   0
@end example

@noindent
The following functions for string manipulation support cell arrays of
strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, 
@code{str2double}, @code{char}, @code{strappend}, @code{strtrunc},
@code{strvcat}, @code{strfind}, and @code{strmatch}.

@DOCSTRING(cellstr)

@DOCSTRING(iscellstr)

@DOCSTRING(cellidx)

@node Processing Data in Cell Arrays
@subsection Processing Data in Cell Arrays

Data that is stored in a cell array can be processed in several ways
depending on the actual data. The simplest way to process that data
is to iterate through it using one or more @code{for} loops. The same
idea can be implemented more easily through the use of the @code{cellfun}
function that calls a user-specified function on all elements of a cell
array.

@DOCSTRING(cellfun)

An alternative is to convert the data to a different container, such as
a matrix or a data structure.  Depending on the data this is possible
using the @code{cell2mat} and @code{cell2struct} functions.

@DOCSTRING(cell2mat)

@DOCSTRING(cell2struct)

@node Comma Separated Lists
@section Comma Separated Lists
@cindex comma separated lists
@cindex cs-lists

Comma separated lists@footnote{Comma-separated lists are also sometimes
informally referred to as @dfn{cs-lists}.} are the basic argument type
to all Octave functions. In the example

@example
max (@var{a}, @var{b})
@end example

@noindent
@code{@var{a}, @var{b}} is a comma separated list. Comma separated lists
can appear on both the right and left hand side of an equation. For
example

@example
[@var{i}, @var{j}] = ceil (find (@var{x}, [], "last"));
@end example

@noindent
where @code{@var{i}, @var{j}} is equally a comma separated list. Comma
separated lists cannot be directly manipulated by the user. However,
both structures and cell arrays can be converted into comma
separated lists, which makes them useful to keep the input arguments and
return values of functions organized. Another example of where a comma
separated list can be used is in the creation of a new array. If all the
accessed elements of a cell array are scalars or column vectors, they
can be concatenated into a new column vector containing the elements, by
surrounding the list with @code{[} and @code{]} as in the following
example

@example
a = @{1, [2, 3], 4@};
b = [a@{:@}]
     @result{} b =
         1   2   3   4
@end example

It is also possible to pass the accessed elements directly to a
function.  The list of elements from the cell array will be passed as an
argument list to a given function as if it is called with the elements as
arguments.  The two calls to @code{printf} in the following example are
identical but the latter is simpler and handles more situations

@example
c = @{"GNU", "Octave", "is", "Free", "Software"@};
printf ("%s ", c@{1@}, c@{2@}, c@{3@}, c@{4@}, c@{5@});
     @print{} GNU Octave is Free Software 
printf ("%s ", c@{:@});
     @print{} GNU Octave is Free Software 
@end example

Just like it is possible to create a numerical array from selected
elements of a cell array, it is possible to create a new cell array
containing the selected elements. By surrounding the list with 
@samp{@{} and @samp{@}} a new cell array will be created, as the
following example illustrates

@example
a = @{1, rand(2, 2), "three"@};
b = @{ a@{ [1, 3] @} @}
     @result{} b =
         @{
           [1,1] =  1
           [1,2] = three
         @}
@end example

@noindent
This syntax is however a bit cumbersome, and since this is a common
operation, it is possible to achieve the same using the @samp{(}
and @samp{)} operators for indexing. When a cell array is indexed
using the @samp{(} and @samp{)} operators a new cell array containing
the selected elements will be created. Using this syntax, the previous 
example can be simplified into the following

@example
a = @{1, rand(2, 2), "three"@};
b = a( [1, 3] )
     @result{} b =
         @{
           [1,1] =  1
           [1,2] = three
         @}
@end example

A comma separated list can equally appear on the left-hand side of an
assignment. An example is 

@example
@group
in @{1@} = ceil (rand (10, 1));
in @{2@} = [];
in @{3@} = "last";
in @{4@} = "first";
out = cell (4, 1);
[out@{1:2@}] = find (in@{1 : 3@});
[out@{3:4@}] = find (in@{[1, 2, 4]@});
@end group
@end example

Structure arrays can equally be used to create comma separated
lists. This is done by addressing one of the fields of a structure
array. For example

@example
@group
x = ceil (randn (10, 1)); 
in = struct ("call1", @{x, Inf, "last"@}, 
             "call2", @{x, Inf, "first"@});
out = struct ("call1", cell (2, 1), "call2", cell (2, 1));
[out.call1] = find (in.call1);
[out.call2] = find (in.call2);
@end group
@end example