|
3439
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
4167
|
5 @node Containers |
|
3439
|
6 @chapter Containers |
|
|
7 @cindex containers |
|
|
8 |
|
|
9 @menu |
|
|
10 * Cell Arrays:: |
|
|
11 @end menu |
|
|
12 |
|
4167
|
13 @node Cell Arrays |
|
3439
|
14 @section Cell Arrays |
|
|
15 @cindex cell arrays |
|
|
16 |
|
6514
|
17 It can be both necessary and convenient to store several variables of |
|
|
18 different size or type in one variable. A cell array is a container |
|
|
19 class able to do just that. In general cell arrays work just like |
|
|
20 @math{N}-dimensional arrays, with the exception of the use of @samp{@{} |
|
|
21 and @samp{@}} as allocation and indexing operators. |
|
|
22 |
|
|
23 As an example, the following code creates a cell array containing a |
|
|
24 string and a 2-by-2 random matrix |
|
|
25 |
|
|
26 @example |
|
|
27 c = @{"a string", rand(2, 2)@}; |
|
|
28 @end example |
|
|
29 |
|
|
30 @noindent |
|
|
31 And a cell array can be indexed with the @{ and @} operators, so the |
|
|
32 variable created in the previous example can be indexed like this |
|
|
33 |
|
|
34 @example |
|
|
35 @group |
|
|
36 c@{1@} |
|
|
37 @result{} ans = a string |
|
|
38 @end group |
|
|
39 @end example |
|
|
40 |
|
|
41 @noindent |
|
|
42 As with numerical arrays several elements of a cell array can be |
|
|
43 extracted by indexing with a vector of indexes |
|
|
44 |
|
|
45 @example |
|
|
46 @group |
|
|
47 c@{1:2@} |
|
|
48 @result{} ans = |
|
|
49 |
|
|
50 (, |
|
|
51 [1] = a string |
|
|
52 [2] = |
|
|
53 |
|
|
54 0.593993 0.627732 |
|
|
55 0.377037 0.033643 |
|
|
56 |
|
|
57 ,) |
|
|
58 @end group |
|
|
59 @end example |
|
|
60 |
|
|
61 The indexing operators can also be used to insert or overwrite elements |
|
|
62 of a cell array. The following code inserts the scalar 3 on the |
|
|
63 third place of the previously created cell array |
|
|
64 |
|
|
65 @example |
|
|
66 @group |
|
|
67 c@{3@} = 3 |
|
|
68 @result{} c = |
|
|
69 |
|
|
70 @{ |
|
|
71 [1,1] = a string |
|
|
72 [1,2] = |
|
|
73 |
|
|
74 0.593993 0.627732 |
|
|
75 0.377037 0.033643 |
|
|
76 |
|
|
77 [1,3] = 3 |
|
|
78 @} |
|
|
79 @end group |
|
|
80 @end example |
|
|
81 |
|
6516
|
82 @menu |
|
|
83 * Creating Cell Arrays:: |
|
|
84 * Indexing Cell Arrays:: |
|
|
85 * Cell Arrays of Strings:: |
|
|
86 * Processing Data in Cell Arrays:: |
|
|
87 @end menu |
|
|
88 |
|
6514
|
89 @node Creating Cell Arrays |
|
|
90 @subsection Creating Cell Array |
|
|
91 |
|
|
92 The introductory example showed how to create a cell array containing |
|
|
93 currently available variables. In many situations, however, it is useful |
|
|
94 to create a cell array and then fill it with data. |
|
|
95 |
|
|
96 The @code{cell} function returns a cell array of a given size, containing |
|
|
97 empty matrices. This function works very similar to the @code{zeros} |
|
|
98 function for creating new numerical arrays. The following example creates |
|
|
99 a 2-by-2 cell array containing empty matrices |
|
|
100 |
|
|
101 @example |
|
|
102 @group |
|
|
103 c = cell(2,2) |
|
|
104 @result{} c = |
|
|
105 |
|
|
106 @{ |
|
|
107 [1,1] = [](0x0) |
|
|
108 [2,1] = [](0x0) |
|
|
109 [1,2] = [](0x0) |
|
|
110 [2,2] = [](0x0) |
|
|
111 @} |
|
|
112 @end group |
|
|
113 @end example |
|
|
114 |
|
|
115 Just like numerical arrays, cell arrays can be multidimensional. The |
|
|
116 @code{cell} function accepts any number of positive integers to describe |
|
|
117 the size of the returned cell array. It is also possible to set the size |
|
|
118 of the cell array through a vector of positive integers. In the |
|
|
119 following example two cell arrays of equal size is created, and the size |
|
|
120 of the first one is displayed |
|
|
121 |
|
|
122 @example |
|
|
123 c1 = cell(3, 4, 5); |
|
|
124 c2 = cell( [3, 4, 5] ); |
|
|
125 size(c1) |
|
|
126 @result{} ans = |
|
|
127 3 4 5 |
|
|
128 @end example |
|
|
129 |
|
|
130 @noindent |
|
|
131 As can be seen, the @code{size} function also work for cell arrays. As |
|
|
132 do the other functions describing the size of an object, such as |
|
|
133 @code{length}, @code{numel}, @code{rows}, and @code{columns}. |
|
|
134 |
|
|
135 An alternative to creating empty cell arrays, and then filling them, it |
|
|
136 is possible to convert numerical arrays into cell arrays using the |
|
|
137 @code{num2cell} and @code{mat2cell} functions. |
|
|
138 |
|
3439
|
139 @DOCSTRING(cell) |
|
|
140 |
|
6514
|
141 @DOCSTRING(iscell) |
|
|
142 |
|
|
143 @DOCSTRING(num2cell) |
|
|
144 |
|
|
145 @DOCSTRING(mat2cell) |
|
|
146 |
|
|
147 @node Indexing Cell Arrays |
|
|
148 @subsection Indexing Cell Arrays |
|
|
149 |
|
|
150 As shown in the introductory example elements can be inserted from cell |
|
|
151 arrays using the @samp{@{} and @samp{@}} operators. Besides the change |
|
|
152 of operators, indexing works for cell arrays like for multidimensional |
|
|
153 arrays. As an example, all the rows of the first and third column of a |
|
|
154 cell array can be set to @code{0} with the following code |
|
|
155 |
|
|
156 @example |
|
|
157 c@{:, [1, 3]@} = 0; |
|
|
158 @end example |
|
|
159 |
|
|
160 Accessing values in a cell array is, however, different from the same |
|
|
161 operation for numerical arrays. Accessing a single element of a cell |
|
|
162 array is very similar to numerical arrays, for example |
|
|
163 |
|
|
164 @example |
|
|
165 element = c@{1, 2@}; |
|
|
166 @end example |
|
|
167 |
|
|
168 @noindent |
|
|
169 This will, however, @emph{not} work when accessing multiple elements of |
|
|
170 a cell array, because it might not be possible to represent all elements |
|
|
171 with a single variable as is the case with numerical arrays. |
|
|
172 |
|
|
173 Accessing multiple elements of a cell array will result in a list of all |
|
|
174 the requested elements. This list can then form the basis of a new |
|
|
175 numerical array or cell array, or be passed as arguments to a |
|
|
176 function. If all the accessed elements of a cell array are scalars or |
|
|
177 column vectors, they can be concatenated into a new column vector |
|
|
178 containing the elements, by surrounding the list with @code{[} and |
|
|
179 @code{]} as in the following example |
|
|
180 |
|
|
181 @example |
|
|
182 a = @{1, [2, 3], 4@}; |
|
|
183 b = [a@{:@}] |
|
|
184 @result{} b = |
|
|
185 1 2 3 4 |
|
|
186 @end example |
|
|
187 |
|
|
188 In much the same way, a new cell array containing the accessed elements |
|
|
189 can be created. By surrounding the list with @samp{@{} and @samp{@}} a |
|
|
190 new cell array will be created, like the following example illustrates |
|
|
191 |
|
|
192 @example |
|
|
193 a = @{1, rand(2, 2), "three"@}; |
|
|
194 b = @{ a@{ [1, 3] @} @} |
|
|
195 @result{} b = |
|
|
196 @{ |
|
|
197 [1,1] = 1 |
|
|
198 [1,2] = three |
|
|
199 @} |
|
|
200 @end example |
|
|
201 |
|
|
202 It is also possible to pass the accessed elements directly to a |
|
|
203 function. The list of elements from the cell array will be passed as an |
|
|
204 argument list to a given function if it is called with the elements as |
|
|
205 arguments. The two calls to @code{printf} in the following example are |
|
|
206 identical but the latter is more simple and handles more situations |
|
|
207 |
|
|
208 @example |
|
|
209 c = @{"GNU", "Octave", "is", "Free", "Software"@}; |
|
|
210 printf ("%s ", c@{1@}, c@{2@}, c@{3@}, c@{4@}, c@{5@}); |
|
|
211 @print{} GNU Octave is Free Software |
|
|
212 printf ("%s ", c@{:@}); |
|
|
213 @print{} GNU Octave is Free Software |
|
|
214 @end example |
|
|
215 |
|
|
216 @node Cell Arrays of Strings |
|
|
217 @subsection Cell Arrays of Strings |
|
|
218 |
|
|
219 One common use of cell arrays is to store multiple strings in the same |
|
|
220 variable. It is possible to store multiple strings in a character matrix |
|
|
221 by letting each row be a string. This, however, introduces the problem |
|
|
222 that all strings must be of equal length. Therefore it is recommended to |
|
|
223 use cell arrays to store multiple strings. If, however, the character |
|
|
224 matrix representation is required for an operation, it can be converted |
|
|
225 to a cell array of strings using the @code{cellstr} function |
|
|
226 |
|
|
227 @example |
|
|
228 a = ["hello"; "world"]; |
|
|
229 c = cellstr (a) |
|
|
230 @result{} c = |
|
|
231 @{ |
|
|
232 [1,1] = hello |
|
|
233 [2,1] = world |
|
|
234 @} |
|
|
235 @end example |
|
|
236 |
|
|
237 One further advantage of using cell arrays to store multiple strings, is |
|
|
238 that most functions for string manipulations included with Octave |
|
|
239 supports this representation. As an example, it is possible to compare |
|
|
240 one string with many others using the @code{strcmp} function. If one of |
|
|
241 the arguments to this function is a string and the other is a cell array |
|
|
242 of strings, each element of the cell array will be compared the string |
|
|
243 argument, |
|
|
244 |
|
|
245 @example |
|
|
246 c = @{"hello", "world"@}; |
|
|
247 strcmp ("hello", c) |
|
|
248 @result{} ans = |
|
|
249 1 0 |
|
|
250 @end example |
|
|
251 |
|
|
252 @noindent |
|
|
253 The following functions for string manipulation support cell arrays of |
|
|
254 strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, |
|
|
255 @code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc}, |
|
|
256 @code{strvcat}, @code{strfind}, and @code{strmatch}. |
|
|
257 |
|
4358
|
258 @DOCSTRING(cellstr) |
|
|
259 |
|
6514
|
260 @DOCSTRING(iscellstr) |
|
|
261 |
|
|
262 @DOCSTRING(cellidx) |
|
|
263 |
|
|
264 @node Processing Data in Cell Arrays |
|
|
265 @subsection Processing Data in Cell Arrays |
|
|
266 |
|
|
267 Data that is stored in a cell array can be processed in several ways |
|
|
268 depending on the actual data. The most simple way to process that data |
|
|
269 is to iterate through it using one or more @code{for} loops. The same |
|
|
270 idea can be implemented easier through the use of the @code{cellfun} |
|
|
271 function that calls a user specified function on all elements of a cell |
|
|
272 array. |
|
|
273 |
|
|
274 @DOCSTRING(cellfun) |
|
|
275 |
|
|
276 An alternative is to convert the data to a different container, such as |
|
|
277 a matrix or a data structure. Depending on the data this is possible |
|
|
278 using the @code{cell2mat} and @code{cell2struct} functions. |
|
6502
|
279 |
|
|
280 @DOCSTRING(cell2mat) |
|
|
281 |
|
|
282 @DOCSTRING(cell2struct) |
