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

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

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

@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

@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
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 can be
set with the function @code{struct_levels_to_print}:

@c pr-output.cc
@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
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
@group
[ 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 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}).

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

If you want to create a struct which contains a cell array as an
individual field, you have to put it into another cell array like in
the following example:

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

@c ov-struct.cc
@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.

If the argument is an object, return the underlying struct.
@end deftypefn


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

@c ov-struct.cc
@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


@node Manipulating Structures
@subsection Manipulating Structures

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

@c ov-struct.cc
@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{@ref{doc-cellstr,,cellstr}, @ref{doc-iscellstr,,iscellstr}, @ref{doc-setfield,,setfield}}
@end deftypefn


@c ./miscellaneous/setfield.m
@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
@group
i1 = @{1,2@}; i2 = "fd"; i3 = @{3@}; i4 = "b";
oo(i1@{:@}).(i2)(i3@{:@}).(i4) == 6;
@end group
@end example
@seealso{@ref{doc-getfield,,getfield}, @ref{doc-rmfield,,rmfield}, @ref{doc-isfield,,isfield}, @ref{doc-isstruct,,isstruct}, @ref{doc-fieldnames,,fieldnames}, @ref{doc-struct,,struct}}
@end deftypefn


@c ./miscellaneous/orderfields.m
@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{@ref{doc-getfield,,getfield}, @ref{doc-rmfield,,rmfield}, @ref{doc-isfield,,isfield}, @ref{doc-isstruct,,isstruct}, @ref{doc-fieldnames,,fieldnames}, @ref{doc-struct,,struct}}
@end deftypefn


@c ov-struct.cc
@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


@c ov-struct.cc
@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


@c ./miscellaneous/getfield.m
@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
@group
i1 = @{1,2@}; i2 = "fd"; i3 = @{3@}; i4= "b";
ss(i1@{:@}).(i2)(i3@{:@}).(i4)
@end group
@end example
@seealso{@ref{doc-setfield,,setfield}, @ref{doc-rmfield,,rmfield}, @ref{doc-isfield,,isfield}, @ref{doc-isstruct,,isstruct}, @ref{doc-fieldnames,,fieldnames}, @ref{doc-struct,,struct}}
@end deftypefn


@c ./miscellaneous/substruct.m
@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{@ref{doc-subsref,,subsref}, @ref{doc-subsasgn,,subsasgn}}
@end deftypefn


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

@c ./general/structfun.m
@anchor{doc-structfun}
@deftypefn {Function File} {} structfun (@var{func}, @var{s})
@deftypefnx {Function File} {[@var{a}, @var{b}] =} structfun (@dots{})
@deftypefnx {Function File} {} structfun (@dots{}, "ErrorHandler", @var{errfunc})
@deftypefnx {Function File} {} structfun (@dots{}, "UniformOutput", @var{val})

Evaluate the function named @var{name} on the fields of the structure
@var{s}.  The fields of @var{s} are passed to the function @var{func}
individually.

@code{structfun} 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.  If the function returns more than one argument, they are
returned as separate output variables.

If the parameter "UniformOutput" is set to true (the default), then the function
must return a single element which will be concatenated into the
return value.  If "UniformOutput" is false, the outputs placed in a structure
with the same fieldnames as the input structure.

@example
@group
s.name1 = "John Smith"; 
s.name2 = "Jill Jones"; 
structfun (@@(x) regexp (x, '(\w+)$', "matches")@{1@}, s, 
           "UniformOutput", false)
@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{se}, @dots{})
@end example

where there is an additional input argument to @var{errfunc} relative to
@var{func}, given by @var{se}.  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.
@seealso{@ref{doc-cellfun,,cellfun}, @ref{doc-arrayfun,,arrayfun}}
@end deftypefn


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

@c ov-cell.cc
@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{@ref{doc-cell2struct,,cell2struct}, @ref{doc-fieldnames,,fieldnames}}
@end deftypefn


@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

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 =
          
          (,
            [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

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.

@c ./general/celldisp.m
@anchor{doc-celldisp}
@deftypefn {Function File} {} celldisp (@var{c}, @var{name})
Recursively display the contents of a cell array.  By default the values
are displayed with the name of the variable @var{c}.  However, this name
can be replaced with the variable @var{name}.
@seealso{@ref{doc-disp,,disp}}
@end deftypefn


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

@c ov-cell.cc
@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


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

@c ov-cell.cc
@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


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.

@c ./DLD-FUNCTIONS/cellfun.cc
@anchor{doc-num2cell}
@deftypefn  {Loadable Function} {@var{c} =} num2cell (@var{m})
@deftypefnx {Loadable Function} {@var{c} =} num2cell (@var{m}, @var{dim})
Convert the matrix @var{m} to a cell array.  If @var{dim} 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{@ref{doc-mat2cell,,mat2cell}}
@end deftypefn


@c ./DLD-FUNCTIONS/cellfun.cc
@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})
Convert 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
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 example
@seealso{@ref{doc-num2cell,,num2cell}, @ref{doc-cell2mat,,cell2mat}}
@end deftypefn


@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 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 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

@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

@c ov-cell.cc
@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


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.

@c ov-cell.cc
@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


@c ./general/cellidx.m
@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
@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.

@c ./DLD-FUNCTIONS/cellfun.cc
@anchor{doc-cellfun}
@deftypefn {Loadable Function} {} cellfun (@var{name}, @var{c})
@deftypefnx {Loadable Function} {} cellfun ("size", @var{c}, @var{k})
@deftypefnx {Loadable Function} {} cellfun ("isclass", @var{c}, @var{class})
@deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{c})
@deftypefnx {Loadable Function} {} cellfun (@var{func}, @var{c}, @var{d})
@deftypefnx {Loadable Function} {[@var{a}, @var{b}] =} cellfun (@dots{})
@deftypefnx {Loadable Function} {} cellfun (@dots{}, 'ErrorHandler', @var{errfunc})
@deftypefnx {Loadable 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 parameter 'UniformOutput' is set to true (the default), then the function
must return 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{@ref{doc-isempty,,isempty}, @ref{doc-islogical,,islogical}, @ref{doc-isreal,,isreal}, @ref{doc-length,,length}, @ref{doc-ndims,,ndims}, @ref{doc-numel,,numel}, @ref{doc-size,,size}}
@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.

@c ./general/cell2mat.m
@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{@ref{doc-mat2cell,,mat2cell}, @ref{doc-num2cell,,num2cell}}
@end deftypefn


@c ov-struct.cc
@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


@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
a = [1, 2, 3, 4];
c = @{4, 5, 6, 7@};
@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
@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