@c Copyright (C) 1996-2011 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.  Multiple
input arguments and return values of functions are organized as
another data container, the comma separated list.

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

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

@menu
* Basic Usage and Examples::
* Structure Arrays::
* Creating Structures::
* Manipulating Structures::
* Processing Data in Structures::
@end menu

@node Basic Usage and Examples
@subsection Basic Usage and Examples

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

@opindex .
@noindent
create a structure with three elements.  The @samp{.} character separates
the structure name from the field name and indicates to Octave that this
variable is a structure.  To print the value of the
structure you can type its name, just as for any other variable:

@example
@group
x
     @result{} 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 just like any other variable:

@example
@group
y = x
     @result{} 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
x.b.d = 3;
x.b
     @result{} ans =
        @{
          d = 3
        @}

x
     @result{} 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
a.b.c.d.e = 1;
a
     @result{} a =
        @{
          b =
          @{
            c =
            @{
              1x1 struct array containing the fields:

              d: 1x1 struct
            @}
          @}
        @}
@end group
@end example

@noindent
This prevents long and confusing output from large deeply nested
structures.  The number of levels to print for nested structures may be
set with the function @code{struct_levels_to_print}, and the function
@code{print_struct_array_contents} may be used to enable printing of the
contents of structure arrays.

@DOCSTRING(struct_levels_to_print)

@DOCSTRING(print_struct_array_contents)

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
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
f (rand (2) + rand (2) * I)
     @result{} 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
[ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]);
x
     @result{} x =
        @{
          u =

            -0.40455  -0.91451
            -0.91451   0.40455

          s =

             0.00000   0.00000   0.00000
             0.00000   5.46499   0.00000
             0.00000   0.00000   0.36597

          v =

            -0.57605   0.81742
            -0.81742  -0.57605

        @}
@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}).

@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.  Conceptually, a structure
array can also be seen as an array of structures with identical
fields.  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.  Another way
to create a structure array is with the @code{struct} function
(@pxref{Creating Structures}).  As previously, to print the value of
the structure array, you can type its name: 

@example
@group
x
     @result{} 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 
two fields:

@example
@group
x(1)
     @result{} ans =
        @{
          a = string1
          b =  1
        @}
@end group
@end example

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

@example
@group
x.a
     @result{}
        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
[x.a] = deal("new string1", "new string2");
 x(1).a
     @result{} ans = new string1
 x(2).a
     @result{} 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
x(3:4) = x(1:2);
[x([1,3]).a] = deal("other string1", "other string2");
x.a
     @result{}
        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
size(x)
     @result{} 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"@})
     @result{} in =
        @{
          1x3 struct array containing the fields:

            call1
            call2
        @}

in(1) = [];
in.call1
     @result{}
       ans = Inf
       ans = last
@end group
@end example

@node Creating Structures
@subsection Creating Structures
@cindex dynamic naming

Besides the index operator ".", Octave can use dynamic naming "(var)" or the
@code{struct} function to create structures.  Dynamic naming uses the string
value of a variable as the field name.  For example:

@example
@group
a = "field2";
x.a = 1;
x.(a) = 2;
x
     @result{} x =
        @{
          a =  1
          field2 =  2
        @}
@end group
@end example

More realistically, all of the functions that operate on strings can be used
to build the correct field name before it is entered into the data structure.

@example
@group
names = ["Bill"; "Mary"; "John"];
ages  = [37; 26; 31];
for i = 1:rows (names)
  database.(names(i,:)) = ages(i);
endfor
database
     @result{} database =
        @{
          Bill =  37
          Mary =  26
          John =  31
        @}
@end group
@end example

The third way to create structures is 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
s = struct ("field1", @{1, "one"@}, "field2", @{2, "two"@},
        "field3", 3);
s.field1
     @result{} 
        ans =  1
        ans = one

s.field2
     @result{}
        ans =  2
        ans = two

s.field3
     @result{}
        ans =  3
        ans =  3
@end group
@end example

If you want to create a struct which contains a cell array as an
individual field, you must wrap it in another cell array as shown in
the following example:

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

@DOCSTRING(struct)

The function @code{isstruct} can be used to test if an object is a
structure or a structure array.

@DOCSTRING(isstruct)

@node Manipulating Structures
@subsection Manipulating Structures

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

@DOCSTRING(nfields)

@DOCSTRING(fieldnames)

@DOCSTRING(isfield)

@DOCSTRING(getfield)

@DOCSTRING(setfield)

@DOCSTRING(rmfield)

@DOCSTRING(orderfields)

@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.  @xref{doc-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.

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

@node Basic Usage of Cell Arrays
@subsection Basic Usage of Cell Arrays
@opindex @{
@opindex @}
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
To access the elements of a cell array, it can be indexed with the @{
and @} operators.  Thus, 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 = a string
     @result{} ans =
          
               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

Details on indexing cell arrays are explained in @ref{Indexing Cell Arrays}.

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

@DOCSTRING(celldisp)

To test if an object is a cell array, use the @code{iscell}
function.  For example:

@example
@group
iscell(c)
     @result{} ans = 1

iscell(3)
     @result{} ans = 0

@end group
@end example

@DOCSTRING(iscell)

@node Creating Cell Arrays
@subsection Creating Cell Array

The introductory example (@pxref{Basic Usage of Cell Arrays}) 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 multi-dimensional.  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
@group
c1 = cell(3, 4, 5);
c2 = cell( [3, 4, 5] );
size(c1)
     @result{} ans =
         3   4   5
@end group
@end example

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

@DOCSTRING(cell)

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}, @code{mat2cell} and @code{cellslices} functions.

@DOCSTRING(num2cell)

@DOCSTRING(mat2cell)

@DOCSTRING(cellslices)

@node Indexing Cell Arrays
@subsection Indexing Cell Arrays

As shown in @pxref{Basic Usage of Cell Arrays} elements can be
extracted from cell arrays using the @samp{@{} and @samp{@}}
operators.  If you want to extract or access subarrays which are still 
cell arrays, you need to use the @samp{(} and @samp{)} operators.  The
following example illustrates the difference:

@example
@group
c = @{"1", "2", "3"; "a", "b", "c"; "4", "5", "6"@};
c@{2,3@}
     @result{} ans = c

c(2,3)
     @result{} ans = 
        @{
          [1,1] = c
        @}
@end group
@end example

@noindent So with @samp{@{@}} you access elements of a cell
array, while with @samp{()} you access a sub array of a cell
array.

Using the @samp{(} and @samp{)} operators, indexing works for cell
arrays like for multi-dimensional 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 command:

@example
@group
c(:, [1, 3]) = @{0@}
     @result{}  =
        @{
          [1,1] = 0
          [2,1] = 0
          [3,1] = 0
          [1,2] = 2
          [2,2] =  10
          [3,2] =  20
          [1,3] = 0
          [2,3] = 0
          [3,3] = 0
        @}
@end group
@end example

Note, that the above can also be achieved like this:

@example
c(:, [1, 3]) = 0;
@end example

@noindent Here, the scalar @samp{0} is automatically promoted to 
cell array @samp{@{0@}} and then assigned to the subarray of @code{c}.

To give another example for indexing cell arrays with @samp{()}, you
can exchange the first and the second row of a cell array as in the
following command: 

@example
@group
c = @{1, 2, 3; 4, 5, 6@};
c([1, 2], :) = c([2, 1], :)
     @result{} = 
        @{
          [1,1] =  4
          [2,1] =  1
          [1,2] =  5
          [2,2] =  2
          [1,3] =  6
          [2,3] =  3
        @}
@end group
@end example

Accessing multiple elements of a cell array with the @samp{@{} and
@samp{@}} operators will result in a comma-separated list of all the
requested elements (@pxref{Comma Separated Lists}).  Using the
@samp{@{} and @samp{@}} operators the first two rows in the above
example can be swapped back like this:

@example
@group
[c@{[1,2], :@}] = deal(c@{[2, 1], :@})
     @result{} = 
        @{
          [1,1] =  1
          [2,1] =  4
          [1,2] =  2
          [2,2] =  5
          [1,3] =  3
          [2,3] =  6
        @}
@end group
@end example

As for struct arrays and numerical arrays, the empty matrix @samp{[]}
can be used to delete elements from a cell array:

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

The following example shows how to just remove the contents of cell
array elements but not delete the space for them:

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

The indexing operations operate on the cell array and not on the objects
within the cell array.  By contrast, @code{cellindexmat} applies matrix indexing
to the objects within each cell array entry and returns the requested values.

@DOCSTRING(cellindexmat)

@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 also 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.  For cases, where the character matrix representation is required
for an operation, there are several functions that convert a cell
array of strings to a character array and back.  @code{char} and
@code{strvcat} convert cell arrays to a character array
(@pxref{Concatenating Strings}), while the function @code{cellstr}
converts a character array to a cell array of strings: 

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

@DOCSTRING(cellstr)

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 to the string
argument:

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

@noindent
The following string functions support cell arrays of strings:
@code{char}, @code{strvcat}, @code{strcat} (@pxref{Concatenating
Strings}), @code{strcmp}, @code{strncmp}, @code{strcmpi},
@code{strncmpi} (@pxref{Comparing Strings}), @code{str2double},
@code{deblank}, @code{strtrim}, @code{strtrunc}, @code{strfind},
@code{strmatch}, , @code{regexp}, @code{regexpi} (@pxref{Manipulating 
Strings}) and @code{str2double} (@pxref{String Conversions}).

The function @code{iscellstr} can be used to test if an object is a
cell array of strings.

@DOCSTRING(iscellstr)

@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.  @xref{doc-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 - both for input and return arguments.  In the
example

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

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

@example
@group
x = [1 0 1 0 0 1 1; 0 0 0 0 0 0 7];
[@var{i}, @var{j}] = find (@var{x}, 2, "last");
@end group
@end example

@noindent
Here, @samp{@var{x}, 2, "last"} is a comma separated list constituting
the input arguments of @code{find}.  @code{find} returns a comma
separated list of output arguments which is assigned element by
element to the comma separated list @samp{@var{i}, @var{j}}.

Another example of where comma separated lists are used is in the
creation of a new array with @code{[]} (@pxref{Matrices}) or the
creation of a cell array with @code{@{@}} (@pxref{Basic Usage of Cell
Arrays}).  In the expressions 

@example
@group
a = [1, 2, 3, 4];
c = @{4, 5, 6, 7@};
@end group
@end example

@noindent
both @samp{1, 2, 3, 4} and @samp{4, 5, 6, 7} are comma separated lists.

Comma separated lists cannot be directly manipulated by the
user.  However, both structure arrays and cell arrays can be converted
into comma separated lists, and thus used in place of explicitly
written comma separated lists.  This feature is useful in many ways,
as will be shown in the following subsections.

@menu
* Comma Separated Lists Generated from Cell Arrays::
* Comma Separated Lists Generated from Structure Arrays::
@end menu

@node Comma Separated Lists Generated from Cell Arrays
@subsection Comma Separated Lists Generated from Cell Arrays

As has been mentioned above (@pxref{Indexing Cell Arrays}), elements
of a cell array can be extracted into a comma separated list with the
@code{@{} and @code{@}} operators.  By surrounding this list with
@code{[} and @code{]}, it can be concatenated into an array.  For example:

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

Similarly, it is possible to create a new cell array containing cell
elements selected with @code{@{@}}.  By surrounding the list with  
@samp{@{} and @samp{@}} a new cell array will be created, as the
following example illustrates:

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

Furthermore, cell elements (accessed by @code{@{@}}) can be passed
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 individual arguments.  The two calls to
@code{printf} in the following example are identical but the latter is
simpler and can handle cell arrays of an arbitrary size:

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

If used on the left-hand side of an assignment, a comma separated list
generated with @code{@{@}} can be assigned to.  An example is 

@example
@group
in@{1@} = [10, 20, 30, 40, 50, 60, 70, 80, 90];
in@{2@} = inf;
in@{3@} = "last";
in@{4@} = "first";
out = cell (4, 1);
[out@{1:3@}] = find (in@{1 : 3@});
[out@{4:6@}] = find (in@{[1, 2, 4]@})
     @result{} out =
        @{
          [1,1] = 1
          [2,1] = 9
          [3,1] = 90
          [4,1] = 1
          [3,1] = 1
          [4,1] = 10
        @}
@end group
@end example


@node Comma Separated Lists Generated from Structure Arrays
@subsection Comma Separated Lists Generated from Structure Arrays
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, 3, "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