1
@c Copyright (C) 1996, 1997, 2007 John W. Eaton
3
@c This file is part of Octave.
5
@c Octave is free software; you can redistribute it and/or modify it
6
@c under the terms of the GNU General Public License as published by the
7
@c Free Software Foundation; either version 3 of the License, or (at
8
@c your option) any later version.
10
@c Octave is distributed in the hope that it will be useful, but WITHOUT
11
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12
@c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15
@c You should have received a copy of the GNU General Public License
16
@c along with Octave; see the file COPYING. If not, see
17
@c <http://www.gnu.org/licenses/>.
20
@chapter Data Containers
23
Octave includes support for two different mechanisms to contain
24
arbitrary data types in the same variable. Structures, which are C-like,
25
and are indexed with named fields, and cell arrays, where each element
26
of the array can have a different data type and or shape.
31
* Comma Separated Lists::
35
@section Data Structures
37
@cindex data structures
39
Octave includes support for organizing data in structures. The current
40
implementation uses an associative array with indices limited to
41
strings, but the syntax is more like C-style structures. Here are some
42
examples of using data structures in Octave.
44
Elements of structures can be of any value type. For example, the three
56
create a structure with three elements. To print the value of the
57
structure, you can type its name, just as for any other variable:
76
Note that Octave may print the elements in any order.
78
Structures may be copied.
96
Since structures are themselves values, structure elements may reference
97
other structures. The following statements change the value of the
98
element @code{b} of the structure @code{x} to be a data structure
99
containing the single element @code{d}, which has a value of 3.
124
Note that when Octave prints the value of a structure that contains
125
other structures, only a few levels are displayed. For example,
129
octave:1> a.b.c.d.e = 1;
145
This prevents long and confusing output from large deeply nested
148
@DOCSTRING(struct_levels_to_print)
150
Functions can return structures. For example, the following function
151
separates the real and complex parts of a matrix and stores them in two
152
elements of the same structure variable.
156
octave:1> function y = f (x)
163
When called with a complex-valued argument, @code{f} returns the data
164
structure containing the real and imaginary parts of the original
169
octave:2> f (rand (2) + rand (2) * I)
185
Function return lists can include structure elements, and they may be
186
indexed like any other variable. For example,
190
octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4])
198
0.00000 0.00000 0.00000
199
0.00000 5.46499 0.00000
200
0.00000 0.00000 0.36597
209
It is also possible to cycle through all the elements of a structure in
210
a loop, using a special form of the @code{for} statement
211
(@pxref{The for Statement})
215
* Creating Structures::
216
* Manipulating Structures::
217
* Processing Data in Structures::
220
@node Structure Arrays
221
@subsection Structure Arrays
223
A structure array is a particular instance of a structure, where each of
224
the fields of the structure is represented by a cell array. Each of
225
these cell arrays has the same dimensions. An example of the creation of
238
which creates a 2-by-1 structure array with two fields. As previously,
239
to print the value of the structure array, you can type its name:
264
Individual elements of the structure array can be returned by indexing
265
the variable like @code{@var{x} (1)}, which returns a structure with the
279
Furthermore, the structure array can return a comma separated list
280
(@pxref{Comma Separated Lists}), if indexed by one of itself field
295
The function @code{size} with return the size of the structure. For
307
Elements can be deleted from a structure array in a similar manner to a
308
numerical array, by assigning the elements to an empty matrix. For
313
in = struct ("call1", @{x, Inf, "last"@},
314
"call2", @{x, Inf, "first"@});
336
@node Creating Structures
337
@subsection Creating Structures
339
As well as indexing a structure with ".", Octave can create a structure
340
with the @code{struct} command. @code{struct} takes pairs of arguments,
341
where the first argument in the pair is the fieldname to include in the
342
structure and the second is a scalar or cell array, representing the
343
values to include in the structure or structure array. For example
347
struct ("field1", 1, "field2", 2)
356
If the values passed to @code{struct} are a mix of scalar and cell
357
arrays, then the scalar arguments are expanded to create a
358
structure array with a consistent dimension. For example
362
struct ("field1", @{1, "one"@}, "field2", @{2, "two"@},
395
Additional functions that can manipulate the fields of a structure are
402
@DOCSTRING(orderfields)
404
@node Manipulating Structures
405
@subsection Manipulating Structures
407
Other functions that can manipulate the fields of a structure are given below.
409
@DOCSTRING(fieldnames)
415
@DOCSTRING(substruct)
417
@node Processing Data in Structures
418
@subsection Processing Data in Structures
420
The simplest way to process data in a structure is within a @code{for}
421
loop or othe means of iterating over the fields. A similar effect can be
422
achieved with the @code{structfun} function, where a user defined
423
function is applied to each field of the structure.
425
@DOCSTRING(structfun)
427
Alternatively, to process the data in a structure, the structure might
428
be converted to another type of container before being treated.
430
@DOCSTRING(struct2cell)
436
It can be both necessary and convenient to store several variables of
437
different size or type in one variable. A cell array is a container
438
class able to do just that. In general cell arrays work just like
439
@math{N}-dimensional arrays, with the exception of the use of @samp{@{}
440
and @samp{@}} as allocation and indexing operators.
442
As an example, the following code creates a cell array containing a
443
string and a 2-by-2 random matrix
446
c = @{"a string", rand(2, 2)@};
450
And a cell array can be indexed with the @{ and @} operators, so the
451
variable created in the previous example can be indexed like this
456
@result{} ans = a string
461
As with numerical arrays several elements of a cell array can be
462
extracted by indexing with a vector of indexes
480
The indexing operators can also be used to insert or overwrite elements
481
of a cell array. The following code inserts the scalar 3 on the
482
third place of the previously created cell array
501
In general nested cell arrays are displayed hierarchically as above. In
502
some circumstances it makes sense to reference them by their index, and
503
this can be performed by the @code{celldisp} function.
508
* Creating Cell Arrays::
509
* Indexing Cell Arrays::
510
* Cell Arrays of Strings::
511
* Processing Data in Cell Arrays::
514
@node Creating Cell Arrays
515
@subsection Creating Cell Array
517
The introductory example showed how to create a cell array containing
518
currently available variables. In many situations, however, it is useful
519
to create a cell array and then fill it with data.
521
The @code{cell} function returns a cell array of a given size, containing
522
empty matrices. This function works very similar to the @code{zeros}
523
function for creating new numerical arrays. The following example creates
524
a 2-by-2 cell array containing empty matrices
540
Just like numerical arrays, cell arrays can be multidimensional. The
541
@code{cell} function accepts any number of positive integers to describe
542
the size of the returned cell array. It is also possible to set the size
543
of the cell array through a vector of positive integers. In the
544
following example two cell arrays of equal size is created, and the size
545
of the first one is displayed
549
c2 = cell( [3, 4, 5] );
556
As can be seen, the @code{size} function also works for cell arrays. As
557
do the other functions describing the size of an object, such as
558
@code{length}, @code{numel}, @code{rows}, and @code{columns}.
560
An alternative to creating empty cell arrays, and then filling them, it
561
is possible to convert numerical arrays into cell arrays using the
562
@code{num2cell} and @code{mat2cell} functions.
572
@node Indexing Cell Arrays
573
@subsection Indexing Cell Arrays
575
As shown in the introductory example elements can be inserted from cell
576
arrays using the @samp{@{} and @samp{@}} operators. Besides the change
577
of operators, indexing works for cell arrays like for multidimensional
578
arrays. As an example, all the rows of the first and third column of a
579
cell array can be set to @code{0} with the following code
585
Accessing values in a cell array is, however, different from the same
586
operation for numerical arrays. Accessing a single element of a cell
587
array is very similar to numerical arrays, for example
594
This will, however, @emph{not} work when accessing multiple elements of
595
a cell array, because it might not be possible to represent all elements
596
with a single variable as is the case with numerical arrays.
598
Accessing multiple elements of a cell array with the @samp{@{} and
599
@samp{@}} operators will result in a comma-separated list (@pxref{Comma
600
Separated Lists}) of all the requested elements as discussed later.
602
One distinction between @samp{@{} and @samp{(} to index cell arrays is
603
in the deletion of elements from the cell array. In a similar manner to
604
a numerical array the @samp{()} operator can be used to delete elements
605
from the cell array. The @samp{@{@}} operator however will remove the
606
elements of the cell array, but not delete the space for them. For example
610
x = @{"1", "2"; "3", "4"@};
629
@node Cell Arrays of Strings
630
@subsection Cell Arrays of Strings
632
One common use of cell arrays is to store multiple strings in the same
633
variable. It is possible to store multiple strings in a character matrix
634
by letting each row be a string. This, however, introduces the problem
635
that all strings must be of equal length. Therefore it is recommended to
636
use cell arrays to store multiple strings. If, however, the character
637
matrix representation is required for an operation, it can be converted
638
to a cell array of strings using the @code{cellstr} function
641
a = ["hello"; "world"];
650
One further advantage of using cell arrays to store multiple strings, is
651
that most functions for string manipulations included with Octave
652
support this representation. As an example, it is possible to compare
653
one string with many others using the @code{strcmp} function. If one of
654
the arguments to this function is a string and the other is a cell array
655
of strings, each element of the cell array will be compared the string
659
c = @{"hello", "world"@};
666
The following functions for string manipulation support cell arrays of
667
strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi},
668
@code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc},
669
@code{strvcat}, @code{strfind}, and @code{strmatch}.
673
@DOCSTRING(iscellstr)
677
@node Processing Data in Cell Arrays
678
@subsection Processing Data in Cell Arrays
680
Data that is stored in a cell array can be processed in several ways
681
depending on the actual data. The most simple way to process that data
682
is to iterate through it using one or more @code{for} loops. The same
683
idea can be implemented easier through the use of the @code{cellfun}
684
function that calls a user specified function on all elements of a cell
689
An alternative is to convert the data to a different container, such as
690
a matrix or a data structure. Depending on the data this is possible
691
using the @code{cell2mat} and @code{cell2struct} functions.
695
@DOCSTRING(cell2struct)
697
@node Comma Separated Lists
698
@section Comma Separated Lists
699
@cindex comma separated lists
701
Comma separated lists are the basic argument type to all Octave
702
functions. In the example
705
max (@var{a}, @var{b})
709
@code{@var{a}, @var{b}} is a comma separated list. Comma separated lists
710
can appear on both the right and left hand side of an equation. For
714
[@var{i}, @var{j}] = ceil (find (@var{x}, [], "last"));
718
where @code{@var{i}, @var{j}} is equally a comma separated list. Comma
719
separated lists can not be directly manipulated by the user. However,
720
both structures are cell arrays can be converted into comma
721
separated lists, which makes them useful to keep the input arguments and
722
return values of functions organized. Another example of where a comma
723
separated list can be used is in the creation of a new array. If all the
724
accessed elements of a cell array are scalars or column vectors, they
725
can be concatenated into a new column vector containing the elements, by
726
surrounding the list with @code{[} and @code{]} as in the following
730
a = @{1, [2, 3], 4@};
736
It is also possible to pass the accessed elements directly to a
737
function. The list of elements from the cell array will be passed as an
738
argument list to a given function as if it is called with the elements as
739
arguments. The two calls to @code{printf} in the following example are
740
identical but the latter is simpler and handles more situations
743
c = @{"GNU", "Octave", "is", "Free", "Software"@};
744
printf ("%s ", c@{1@}, c@{2@}, c@{3@}, c@{4@}, c@{5@});
745
@print{} GNU Octave is Free Software
746
printf ("%s ", c@{:@});
747
@print{} GNU Octave is Free Software
750
Just like it is possible to create a numerical array from selected
751
elements of a cell array, it is possible to create a new cell array
752
containing the selected elements. By surrounding the list with
753
@samp{@{} and @samp{@}} a new cell array will be created, like the
754
following example illustrates
757
a = @{1, rand(2, 2), "three"@};
758
b = @{ a@{ [1, 3] @} @}
767
This syntax is however a bit cumbersome, and since this is a common
768
operation, it is possible to achieve the same using the @samp{(}
769
and @samp{)} operators for indexing. When a cell array is indexed
770
using the @samp{(} and @samp{)} operators a new cell array containing
771
the selected elements. Using this syntax, the previous example can
772
be simplified into the following
775
a = @{1, rand(2, 2), "three"@};
784
A comma separated list can equally appear on the left-hand side of an
785
assignment. An example is
789
in @{1@} = ceil (rand (10, 1));
794
[out@{1:2@}] = find (in@{1 : 3@});
795
[out@{3:4@}] = find (in@{[1, 2, 4]@});
799
Structure arrays can equally be used to create comma separated
800
lists. This is done by addresses one of the fields of a structure
805
x = ceil (randn (10, 1));
806
in = struct ("call1", @{x, Inf, "last"@},
807
"call2", @{x, Inf, "first"@});
808
out = struct ("call1", cell (2, 1), "call2", cell (2, 1));
809
[out.call1] = find (in.call1);
810
[out.call2] = find (in.call2);
added
removed
doc/interpreter/container.txi
