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

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

     x.a = 1
     x.b = [1, 2; 3, 4]
     x.c = "string"

create a structure with three elements.  To print the value of the structure, you can type its name, just as for any other variable:

     octave:2> x
     x =
     {
       a = 1
       b =

         1  2
         3  4

       c = string
     }

Note that Octave may print the elements in any order.

Structures may be copied.

     octave:1> y = x
     y =
     {
       a = 1
       b =

         1  2
         3  4

       c = string
     }

Since structures are themselves values, structure elements may reference other structures.  The following statements change the value of the element b of the structure x to be a data structure containing the single element d, which has a value of 3.

     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
     }

Note that when Octave prints the value of a structure that contains other structures, only a few levels are displayed.  For example,

     octave:1> a.b.c.d.e = 1;
     octave:2> a
     a =
     {
       b =
       {
         c =
         {
           d: 1x1 struct
         }
       }
     }

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

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

     octave:1> function y = f (x)
     > y.re = real (x);
     > y.im = imag (x);
     > endfunction

When called with a complex-valued argument, f returns the data structure containing the real and imaginary parts of the original function argument.

     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
     }

Function return lists can include structure elements, and they may be indexed like any other variable.  For example,

     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

It is also possible to cycle through all the elements of a structure in a loop, using a special form of the for statement (see Looping Over Structure Elements)

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

     x(1).a = "string1"
     x(2).a = "string2"
     x(1).b = 1
     x(2).b = 2

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:

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

         a
         b
     }

Individual elements of the structure array can be returned by indexing the variable like X (1), which returns a structure with the two fields like

     octave:2> x(1)
     ans =
     {
       a = string1
       b =  1
     }

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

     octave:3> x.a
     ans = string1
     ans = string2

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

     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

Just as for numerical arrays, it is possible to use vectors as indices (see Index Expressions):

     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

The function size will return the size of the structure.  For the example above

     octave:10> size(x)
     ans =

        1   4

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

     in = struct ("call1", {x, Inf, "last"},
                  "call2", {x, Inf, "first"});
     in (1, :) = []
     => in =
           {
             call1 =

             (,
               [1] = Inf
               [2] = last
             ,)

             call2 =

             (,
               [1] = Inf
               [2] = first
             ,)

           }

Creating Structures
-------------------

As well as indexing a structure with ".", Octave can create a structure with the struct command.  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

     struct ("field1", 1, "field2", 2)
     => ans =
           {
             field1 =  1
             field2 =  2
           }

If the values passed to 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

     struct ("field1", {1, "one"}, "field2", {2, "two"},
             "field3", 3)
     => ans =
           {
             field1 =

             (,
               [1] =  1
               [2] = one
             ,)

             field2 =

             (,
               [1] =  2
               [2] = two
             ,)

             field3 =

             (,
               [1] =  3
               [2] =  3
             ,)

           }

(struct)

(isstruct)

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

(rmfield)

(setfield)

(orderfields)

Manipulating Structures
-----------------------

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

(fieldnames)

(isfield)

(getfield)

(substruct)

Processing Data in Structures
-----------------------------

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

(structfun)

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

(struct2cell)

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 N-dimensional arrays, with the exception of the use of { and } 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

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

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

     c{1}
          => ans = a string

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

     c{1:2}
          => ans =

               (,
                 [1] = a string
                 [2] =

                    0.593993   0.627732
                    0.377037   0.033643

               ,)

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

     c{3} = 3
          => c =

              {
                [1,1] = a string
                [1,2] =

                   0.593993   0.627732
                   0.377037   0.033643

                [1,3] =  3
              }

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 celldisp function.

(celldisp)

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 cell function returns a cell array of a given size, containing empty matrices.  This function is similar to the zeros function for creating new numerical arrays.  The following example creates a 2-by-2 cell array containing empty matrices

     c = cell(2,2)
          => c =

              {
                [1,1] = [](0x0)
                [2,1] = [](0x0)
                [1,2] = [](0x0)
                [2,2] = [](0x0)
              }

Just like numerical arrays, cell arrays can be multidimensional.  The 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

     c1 = cell(3, 4, 5);
     c2 = cell( [3, 4, 5] );
     size(c1)
          => ans =
              3   4   5

As can be seen, the size function also works for cell arrays.  As do the other functions describing the size of an object, such as length, numel, rows, and 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 num2cell and mat2cell functions.

(cell)

(iscell)

(num2cell)

(mat2cell)

Indexing Cell Arrays
--------------------

As shown in the introductory example elements can be inserted from cell arrays using the { and } 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 0 with the following code

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

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

     element = c{1, 2};

This will, however, 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 { and } operators will result in a comma-separated list (see Comma Separated Lists) of all the requested elements as discussed later.

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

     x = {"1", "2"; "3", "4"};
     x{1, :} = []
     => x =
           {
             [1,1] = [](0x0)
             [2,1] = 3
             [1,2] = [](0x0)
             [2,2] = 4
           }

     x(1, :) = []
     => x =
           {
             [1,1] = 3
             [1,2] = 4
           }

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 cellstr function

     a = ["hello"; "world"];
     c = cellstr (a)
          => c =
              {
                [1,1] = hello
                [2,1] = world
              }

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

     c = {"hello", "world"};
     strcmp ("hello", c)
          => ans =
             1   0

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

(cellstr)

(iscellstr)

(cellidx)

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 for loops.  The same idea can be implemented more easily through the use of the cellfun function that calls a user-specified function on all elements of a cell array.

(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 cell2mat and cell2struct functions.

(cell2mat)

(cell2struct)

Comma Separated Lists
=====================

Comma separated lists (Comma-separated lists are also sometimes informally referred to as cs-lists.) are the basic argument type to all Octave functions.  In the example

     max (A, B)

A, B is a comma separated list.  Comma separated lists can appear on both the right and left hand side of an equation.  For example

     [I, J] = ceil (find (X, [], "last"));

where I, 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 [ and ] as in the following example

     a = {1, [2, 3], 4};
     b = [a{:}]
          => b =
              1   2   3   4

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 printf in the following example are identical but the latter is simpler and handles more situations

     c = {"GNU", "Octave", "is", "Free", "Software"};
     printf ("%s ", c{1}, c{2}, c{3}, c{4}, c{5});
          -| GNU Octave is Free Software
     printf ("%s ", c{:});
          -| GNU Octave is Free Software

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 { and } a new cell array will be created, as the following example illustrates

     a = {1, rand(2, 2), "three"};
     b = { a{ [1, 3] } }
          => b =
              {
                [1,1] =  1
                [1,2] = three
              }

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

     a = {1, rand(2, 2), "three"};
     b = a( [1, 3] )
          => b =
              {
                [1,1] =  1
                [1,2] = three
              }

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

     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]});

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

     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);