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

@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 Cell Arrays
@chapter Cell Arrays
@cindex containers
@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

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

@node Creating Cell Arrays
@section 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 works very 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 is 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 work 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}.

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.

@anchor{doc-cell}
@deftypefn {Built-in Function} {} cell (@var{x})
@deftypefnx {Built-in Function} {} cell (@var{n}, @var{m})
Create a new cell array object.  If invoked with a single scalar
argument, @code{cell} returns a square cell array with the dimension
specified.  If you supply two scalar arguments, @code{cell} takes
them to be the number of rows and columns.  If given a vector with two
elements, @code{cell} uses the values of the elements as the number of
rows and columns, respectively.
@end deftypefn


@anchor{doc-iscell}
@deftypefn {Built-in Function} {} iscell (@var{x})
Return true if @var{x} is a cell array object.  Otherwise, return
false.
@end deftypefn


@anchor{doc-num2cell}
@deftypefn {Loadable Function} {@var{c} =} num2cell (@var{m})
@deftypefnx {Loadable Function} {@var{c} =} num2cell (@var{m}, @var{d})
Convert to matrix @var{m} into a cell array. If @var{d} is defined the
value @var{c} is of dimension 1 in this dimension and the elements of
@var{m} are placed in slices in @var{c}.
@seealso{mat2cell}
@end deftypefn


@anchor{doc-mat2cell}
@deftypefn {Loadable Function} {@var{b} =} mat2cell (@var{a}, @var{m}, @var{n})
@deftypefnx {Loadable Function} {@var{b} =} mat2cell (@var{a}, @var{d1}, @var{d2}, @dots{})
@deftypefnx {Loadable Function} {@var{b} =} mat2cell (@var{a}, @var{r})
Converts the matrix @var{a} to a cell array If @var{a} is 2-D, then
it is required that @code{sum (@var{m}) == size (@var{a}, 1)} and
@code{sum (@var{n}) == size (@var{a}, 2)}. Similarly, if @var{a} is
a multi-dimensional and the number of dimensional arguments is equal
to the dimensions of @var{a}, then it is required that @code{sum (@var{di})
== size (@var{a}, i)}.

Given a single dimensional argument @var{r}, the other dimensional
arguments are assumed to equal @code{size (@var{a},@var{i})}.

An example of the use of mat2cell is

@example
@group
mat2cell (reshape(1:16,4,4),[3,1],[3,1])
@result{} @{
  [1,1] =

     1   5   9
     2   6  10
     3   7  11

  [2,1] =

     4   8  12

  [1,2] =

    13
    14
    15

  [2,2] = 16
@}
@end group
@end example
@seealso{num2cell, cell2mat}
@end deftypefn


@node Indexing Cell Arrays
@section 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 of all
the requested elements. This list can then be used anywhere where a
comma-separated list is used, such as in the creation of a new
numerical array or cell array, or be passed as arguments to a
function. 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 more simple 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, like 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. 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

@node Cell Arrays of Strings
@section 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
supports 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{str2mat}, @code{strappend}, @code{strtrunc},
@code{strvcat}, @code{strfind}, and @code{strmatch}.

@anchor{doc-cellstr}
@deftypefn {Built-in Function} {} cellstr (@var{string})
Create a new cell array object from the elements of the string
array @var{string}.
@end deftypefn


@anchor{doc-iscellstr}
@deftypefn {Built-in Function} {} iscellstr (@var{cell})
Return true if every element of the cell array @var{cell} is a
character string
@end deftypefn


@anchor{doc-cellidx}
@deftypefn {Function File} {[@var{idxvec}, @var{errmsg}] =} cellidx (@var{listvar}, @var{strlist})
Return indices of string entries in @var{listvar} that match strings
in @var{strlist}.

Both @var{listvar} and @var{strlist} may be passed as strings or
string matrices.  If they are passed as string matrices, each entry
is processed by @code{deblank} prior to searching for the entries.

The first output is the vector of indices in @var{listvar}.

If @var{strlist} contains a string not in @var{listvar}, then
an error message is returned in @var{errmsg}.  If only one output
argument is requested, then @var{cellidx} prints @var{errmsg} to the
screen and exits with an error.
@end deftypefn


@node Processing Data in Cell Arrays
@section 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 most simple way to process that data
is to iterate through it using one or more @code{for} loops. The same
idea can be implemented easier through the use of the @code{cellfun}
function that calls a user specified function on all elements of a cell
array.

@anchor{doc-cellfun}
@deftypefn {Lodable Function} {} cellfun (@var{name}, @var{c})
@deftypefnx {Lodable Function} {} cellfun ("size", @var{c}, @var{k})
@deftypefnx {Lodable Function} {} cellfun ("isclass", @var{c}, @var{class})
@deftypefnx {Lodable Function} {} cellfun (@var{func}, @var{c})
@deftypefnx {Lodable Function} {} cellfun (@var{func}, @var{c}, @var{d})
@deftypefnx {Lodable Function} {[@var{a}, @var{b}] =} cellfun (@dots{})
@deftypefnx {Lodable Function} {} cellfun (@dots{}, 'ErrorHandler', @var{errfunc})
@deftypefnx {Lodable Function} {} cellfun (@dots{}, 'UniformOutput', @var{val})

Evaluate the function named @var{name} on the elements of the cell array
@var{c}.  Elements in @var{c} are passed on to the named function
individually.  The function @var{name} can be one of the functions

@table @code
@item isempty
Return 1 for empty elements.
@item islogical
Return 1 for logical elements.
@item isreal
Return 1 for real elements.
@item length
Return a vector of the lengths of cell elements.
@item ndims
Return the number of dimensions of each element.
@item prodofsize
Return the product of dimensions of each element.
@item size
Return the size along the @var{k}-th dimension.
@item isclass
Return 1 for elements of @var{class}.
@end table

Additionally, @code{cellfun} accepts an arbitrary function @var{func}
in the form of an inline function, function handle, or the name of a
function (in a character string). In the case of a character string
argument, the function must accept a single argument named @var{x}, and
it must return a string value. The function can take one or more arguments,
with the inputs args given by @var{c}, @var{d}, etc. Equally the function
can return one or more output arguments. For example

@example
@group
cellfun (@@atan2, @{1, 0@}, @{0, 1@})
@result{}ans = [1.57080   0.00000]
@end group
@end example

Note that the default output argument is an array of the same size as the
input arguments.

If the param 'UniformOutput' is set to true (the default), then the function
must return either a single element which will be concatenated into the
return value. If 'UniformOutput is false, the outputs are concatenated in
a cell array. For example

@example
@group
cellfun ("tolower(x)", @{"Foo", "Bar", "FooBar"@},
         "UniformOutput",false)
@result{} ans = @{"foo", "bar", "foobar"@}
@end group
@end example

Given the parameter 'ErrorHandler', then @var{errfunc} defines a function to
call in case @var{func} generates an error. The form of the function is

@example
function [@dots{}] = errfunc (@var{s}, @dots{})
@end example

where there is an additional input argument to @var{errfunc} relative to
@var{func}, given by @var{s}. This is a structure with the elements
'identifier', 'message' and 'index', giving respectively the error
identifier, the error message, and the index into the input arguments
of the element that caused the error. For example

@example
@group
function y = foo (s, x), y = NaN; endfunction
cellfun (@@factorial, @{-1,2@},'ErrorHandler',@@foo)
@result{} ans = [NaN 2]
@end group
@end example

@seealso{isempty, islogical, isreal, length, ndims, numel, size, isclass}
@end deftypefn


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.

@anchor{doc-cell2mat}
@deftypefn {Function File} {@var{m} =} cell2mat (@var{c})
Convert the cell array @var{c} into a matrix by concatenating all
elements of @var{c} into a hyperrectangle.  Elements of @var{c} must
be numeric, logical or char, and @code{cat} must be able to
concatenate them together.
@seealso{mat2cell, num2cell}
@end deftypefn


@anchor{doc-cell2struct}
@deftypefn {Built-in Function} {} cell2struct (@var{cell}, @var{fields}, @var{dim})
Convert @var{cell} to a structure. The number of fields in @var{fields}
must match the number of elements in @var{cell} along dimension @var{dim},
that is @code{numel (@var{fields}) == size (@var{cell}, @var{dim})}.

@example
@group
A = cell2struct (@{'Peter', 'Hannah', 'Robert'; 185, 170, 168@},
                 @{'Name','Height'@}, 1);
A(1)
@result{} ans =
      @{
        Height = 185
        Name   = Peter
      @}

@end group
@end example
@end deftypefn

