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