|
6778
|
1 @c Copyright (C) 1996, 1997, 2007 John W. Eaton |
|
7018
|
2 @c |
|
|
3 @c This file is part of Octave. |
|
|
4 @c |
|
|
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. |
|
|
9 @c |
|
|
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 |
|
|
13 @c for more details. |
|
|
14 @c |
|
|
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/>. |
|
3439
|
18 |
|
6837
|
19 @node Data Containers |
|
|
20 @chapter Data Containers |
|
|
21 @cindex containers |
|
|
22 |
|
6939
|
23 Octave includes support for two different mechanisms to contain |
|
6837
|
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. |
|
|
27 |
|
|
28 @menu |
|
|
29 * Data Structures:: |
|
|
30 * Cell Arrays:: |
|
|
31 * Comma Separated Lists:: |
|
|
32 @end menu |
|
|
33 |
|
|
34 @node Data Structures |
|
|
35 @section Data Structures |
|
|
36 @cindex structures |
|
|
37 @cindex data structures |
|
|
38 |
|
|
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. |
|
|
43 |
|
|
44 Elements of structures can be of any value type. For example, the three |
|
|
45 expressions |
|
|
46 |
|
|
47 @example |
|
|
48 @group |
|
|
49 x.a = 1 |
|
|
50 x.b = [1, 2; 3, 4] |
|
|
51 x.c = "string" |
|
|
52 @end group |
|
|
53 @end example |
|
|
54 |
|
|
55 @noindent |
|
|
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: |
|
|
58 |
|
|
59 @example |
|
|
60 @group |
|
|
61 octave:2> x |
|
|
62 x = |
|
|
63 @{ |
|
|
64 a = 1 |
|
|
65 b = |
|
|
66 |
|
|
67 1 2 |
|
|
68 3 4 |
|
|
69 |
|
|
70 c = string |
|
|
71 @} |
|
|
72 @end group |
|
|
73 @end example |
|
|
74 |
|
|
75 @noindent |
|
|
76 Note that Octave may print the elements in any order. |
|
|
77 |
|
|
78 Structures may be copied. |
|
|
79 |
|
|
80 @example |
|
|
81 @group |
|
|
82 octave:1> y = x |
|
|
83 y = |
|
|
84 @{ |
|
|
85 a = 1 |
|
|
86 b = |
|
|
87 |
|
|
88 1 2 |
|
|
89 3 4 |
|
|
90 |
|
|
91 c = string |
|
|
92 @} |
|
|
93 @end group |
|
|
94 @end example |
|
|
95 |
|
|
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. |
|
|
100 |
|
|
101 @example |
|
|
102 @group |
|
|
103 octave:1> x.b.d = 3 |
|
|
104 x.b.d = 3 |
|
|
105 octave:2> x.b |
|
|
106 ans = |
|
|
107 @{ |
|
|
108 d = 3 |
|
|
109 @} |
|
|
110 octave:3> x |
|
|
111 x = |
|
|
112 @{ |
|
|
113 a = 1 |
|
|
114 b = |
|
|
115 @{ |
|
|
116 d = 3 |
|
|
117 @} |
|
|
118 |
|
|
119 c = string |
|
|
120 @} |
|
|
121 @end group |
|
|
122 @end example |
|
|
123 |
|
|
124 Note that when Octave prints the value of a structure that contains |
|
|
125 other structures, only a few levels are displayed. For example, |
|
|
126 |
|
|
127 @example |
|
|
128 @group |
|
|
129 octave:1> a.b.c.d.e = 1; |
|
|
130 octave:2> a |
|
|
131 a = |
|
|
132 @{ |
|
|
133 b = |
|
|
134 @{ |
|
|
135 c = |
|
|
136 @{ |
|
|
137 d: 1x1 struct |
|
|
138 @} |
|
|
139 @} |
|
|
140 @} |
|
|
141 @end group |
|
|
142 @end example |
|
|
143 |
|
|
144 @noindent |
|
|
145 This prevents long and confusing output from large deeply nested |
|
|
146 structures. |
|
|
147 |
|
|
148 @DOCSTRING(struct_levels_to_print) |
|
|
149 |
|
|
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. |
|
|
153 |
|
|
154 @example |
|
|
155 @group |
|
|
156 octave:1> function y = f (x) |
|
|
157 > y.re = real (x); |
|
|
158 > y.im = imag (x); |
|
|
159 > endfunction |
|
|
160 @end group |
|
|
161 @end example |
|
|
162 |
|
|
163 When called with a complex-valued argument, @code{f} returns the data |
|
|
164 structure containing the real and imaginary parts of the original |
|
|
165 function argument. |
|
|
166 |
|
|
167 @example |
|
|
168 @group |
|
|
169 octave:2> f (rand (2) + rand (2) * I) |
|
|
170 ans = |
|
|
171 @{ |
|
|
172 im = |
|
|
173 |
|
|
174 0.26475 0.14828 |
|
|
175 0.18436 0.83669 |
|
|
176 |
|
|
177 re = |
|
|
178 |
|
|
179 0.040239 0.242160 |
|
|
180 0.238081 0.402523 |
|
|
181 @} |
|
|
182 @end group |
|
|
183 @end example |
|
|
184 |
|
|
185 Function return lists can include structure elements, and they may be |
|
|
186 indexed like any other variable. For example, |
|
|
187 |
|
|
188 @example |
|
|
189 @group |
|
|
190 octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) |
|
|
191 x.u = |
|
|
192 |
|
|
193 -0.40455 -0.91451 |
|
|
194 -0.91451 0.40455 |
|
|
195 |
|
|
196 x.s = |
|
|
197 |
|
|
198 0.00000 0.00000 0.00000 |
|
|
199 0.00000 5.46499 0.00000 |
|
|
200 0.00000 0.00000 0.36597 |
|
|
201 |
|
|
202 x.v = |
|
|
203 |
|
|
204 -0.57605 0.81742 |
|
|
205 -0.81742 -0.57605 |
|
|
206 @end group |
|
|
207 @end example |
|
|
208 |
|
|
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}) |
|
|
212 |
|
|
213 @menu |
|
|
214 * Structure Arrays:: |
|
|
215 * Creating Structures:: |
|
|
216 * Manipulating Structures:: |
|
6863
|
217 * Processing Data in Structures:: |
|
6837
|
218 @end menu |
|
|
219 |
|
|
220 @node Structure Arrays |
|
|
221 @subsection Structure Arrays |
|
|
222 |
|
|
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 |
|
|
226 a structure array is |
|
|
227 |
|
|
228 @example |
|
|
229 @group |
|
|
230 x(1).a = "string1" |
|
|
231 x(2).a = "string2" |
|
|
232 x(1).b = 1 |
|
|
233 x(2).b = 2 |
|
|
234 @end group |
|
|
235 @end example |
|
|
236 |
|
|
237 @noindent |
|
|
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: |
|
|
240 |
|
|
241 @example |
|
|
242 @group |
|
|
243 octave:2> x |
|
|
244 x = |
|
|
245 @{ |
|
|
246 a = |
|
|
247 |
|
|
248 (, |
|
|
249 [1] = string1 |
|
|
250 [2] = string2 |
|
|
251 ,) |
|
|
252 |
|
|
253 b = |
|
|
254 |
|
|
255 (, |
|
|
256 [1] = 1 |
|
|
257 [2] = 2 |
|
|
258 ,) |
|
|
259 |
|
|
260 @} |
|
|
261 @end group |
|
|
262 @end example |
|
|
263 |
|
|
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 |
|
|
266 two fields like |
|
|
267 |
|
|
268 @example |
|
|
269 @group |
|
|
270 octave:2> x(1) |
|
|
271 ans = |
|
|
272 @{ |
|
|
273 a = string1 |
|
|
274 b = 1 |
|
|
275 @} |
|
|
276 @end group |
|
|
277 @end example |
|
|
278 |
|
6939
|
279 Furthermore, the structure array can return a comma separated list |
|
6837
|
280 (@pxref{Comma Separated Lists}), if indexed by one of itself field |
|
|
281 names. For example |
|
|
282 |
|
|
283 @example |
|
|
284 @group |
|
|
285 octave:3> x.a |
|
|
286 ans = |
|
|
287 |
|
|
288 (, |
|
|
289 [1] = string1 |
|
|
290 [2] = string2 |
|
|
291 ,) |
|
|
292 @end group |
|
|
293 @end example |
|
|
294 |
|
|
295 The function @code{size} with return the size of the structure. For |
|
|
296 the example above |
|
|
297 |
|
|
298 @example |
|
|
299 @group |
|
|
300 octave:4> size(x) |
|
|
301 ans = |
|
|
302 |
|
|
303 1 2 |
|
|
304 @end group |
|
|
305 @end example |
|
|
306 |
|
|
307 Elements can be deleted from a structure array in a similar manner to a |
|
7001
|
308 numerical array, by assigning the elements to an empty matrix. For |
|
6837
|
309 example |
|
|
310 |
|
|
311 @example |
|
|
312 @group |
|
|
313 in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@}); |
|
7025
|
314 in (:, 1) = [] |
|
6837
|
315 @result{} in = |
|
6839
|
316 @{ |
|
6837
|
317 call1 = |
|
|
318 |
|
|
319 (, |
|
|
320 [1] = Inf |
|
|
321 [2] = last |
|
|
322 ,) |
|
|
323 |
|
|
324 call2 = |
|
|
325 |
|
|
326 (, |
|
|
327 [1] = Inf |
|
|
328 [2] = first |
|
|
329 ,) |
|
|
330 |
|
6839
|
331 @} |
|
6837
|
332 @end group |
|
|
333 @end example |
|
|
334 |
|
|
335 @node Creating Structures |
|
|
336 @subsection Creating Structures |
|
|
337 |
|
|
338 As well as indexing a structure with ".", Octave can create a structure |
|
|
339 with the @code{struct} command. @code{struct} takes pairs of arguments, |
|
|
340 where the first argument in the pair is the fieldname to include in the |
|
|
341 structure and the second is a scalar or cell array, representing the |
|
|
342 values to include in the structure or structure array. For example |
|
|
343 |
|
|
344 @example |
|
|
345 @group |
|
|
346 struct ('field1', 1, 'field2', 2) |
|
|
347 @result{} ans = |
|
|
348 @{ |
|
|
349 field1 = 1 |
|
|
350 field2 = 2 |
|
|
351 @} |
|
|
352 @end group |
|
|
353 @end example |
|
|
354 |
|
|
355 If the values passed to @code{struct} are a mix of scalar and cell |
|
|
356 arrays, then the scalar arguments are expanded to create a |
|
|
357 structure array with a consistent dimension. For example |
|
|
358 |
|
|
359 @example |
|
|
360 @group |
|
|
361 struct ('field1', @{1, 'one'@}, 'field2', @{2, 'two'@}, 'field3', 3); |
|
|
362 @result{} ans = |
|
|
363 @{ |
|
|
364 field1 = |
|
|
365 |
|
|
366 (, |
|
|
367 [1] = 1 |
|
|
368 [2] = one |
|
|
369 ,) |
|
|
370 |
|
|
371 field2 = |
|
|
372 |
|
|
373 (, |
|
|
374 [1] = 2 |
|
|
375 [2] = two |
|
|
376 ,) |
|
|
377 |
|
|
378 field3 = |
|
|
379 |
|
|
380 (, |
|
|
381 [1] = 3 |
|
|
382 [2] = 3 |
|
|
383 ,) |
|
|
384 |
|
|
385 @} |
|
|
386 @end group |
|
|
387 @end example |
|
|
388 |
|
|
389 @DOCSTRING(struct) |
|
|
390 |
|
|
391 @DOCSTRING(isstruct) |
|
|
392 |
|
|
393 Additional functions that can manipulate the fields of a structure are |
|
|
394 listed below. |
|
|
395 |
|
|
396 @DOCSTRING(rmfield) |
|
|
397 |
|
|
398 @DOCSTRING(setfield) |
|
|
399 |
|
|
400 @DOCSTRING(orderfields) |
|
|
401 |
|
|
402 @node Manipulating Structures |
|
|
403 @subsection Manipulating Structures |
|
|
404 |
|
|
405 Other functions that can manipulate the fields of a structure are given below. |
|
|
406 |
|
|
407 @DOCSTRING(fieldnames) |
|
|
408 |
|
|
409 @DOCSTRING(isfield) |
|
|
410 |
|
|
411 @DOCSTRING(getfield) |
|
|
412 |
|
6863
|
413 @DOCSTRING(substruct) |
|
|
414 |
|
|
415 @node Processing Data in Structures |
|
|
416 @subsection Processing Data in Structures |
|
6837
|
417 |
|
6939
|
418 The simplest way to process data in a structure is within a @code{for} |
|
6863
|
419 loop or othe means of iterating over the fields. A similar effect can be |
|
|
420 achieved with the @code{structfun} function, where a user defined |
|
6939
|
421 function is applied to each field of the structure. |
|
6863
|
422 |
|
|
423 @DOCSTRING(structfun) |
|
|
424 |
|
6939
|
425 Alternatively, to process the data in a structure, the structure might |
|
6863
|
426 be converted to another type of container before being treated. |
|
|
427 |
|
|
428 @DOCSTRING(struct2cell) |
|
6837
|
429 |
|
6517
|
430 @node Cell Arrays |
|
6837
|
431 @section Cell Arrays |
|
3439
|
432 @cindex cell arrays |
|
|
433 |
|
6514
|
434 It can be both necessary and convenient to store several variables of |
|
|
435 different size or type in one variable. A cell array is a container |
|
|
436 class able to do just that. In general cell arrays work just like |
|
|
437 @math{N}-dimensional arrays, with the exception of the use of @samp{@{} |
|
|
438 and @samp{@}} as allocation and indexing operators. |
|
|
439 |
|
|
440 As an example, the following code creates a cell array containing a |
|
|
441 string and a 2-by-2 random matrix |
|
|
442 |
|
|
443 @example |
|
|
444 c = @{"a string", rand(2, 2)@}; |
|
|
445 @end example |
|
|
446 |
|
|
447 @noindent |
|
|
448 And a cell array can be indexed with the @{ and @} operators, so the |
|
|
449 variable created in the previous example can be indexed like this |
|
|
450 |
|
|
451 @example |
|
|
452 @group |
|
|
453 c@{1@} |
|
|
454 @result{} ans = a string |
|
|
455 @end group |
|
|
456 @end example |
|
|
457 |
|
|
458 @noindent |
|
|
459 As with numerical arrays several elements of a cell array can be |
|
|
460 extracted by indexing with a vector of indexes |
|
|
461 |
|
|
462 @example |
|
|
463 @group |
|
|
464 c@{1:2@} |
|
|
465 @result{} ans = |
|
|
466 |
|
|
467 (, |
|
|
468 [1] = a string |
|
|
469 [2] = |
|
|
470 |
|
|
471 0.593993 0.627732 |
|
|
472 0.377037 0.033643 |
|
|
473 |
|
|
474 ,) |
|
|
475 @end group |
|
|
476 @end example |
|
|
477 |
|
|
478 The indexing operators can also be used to insert or overwrite elements |
|
|
479 of a cell array. The following code inserts the scalar 3 on the |
|
|
480 third place of the previously created cell array |
|
|
481 |
|
|
482 @example |
|
|
483 @group |
|
|
484 c@{3@} = 3 |
|
|
485 @result{} c = |
|
|
486 |
|
|
487 @{ |
|
|
488 [1,1] = a string |
|
|
489 [1,2] = |
|
|
490 |
|
|
491 0.593993 0.627732 |
|
|
492 0.377037 0.033643 |
|
|
493 |
|
|
494 [1,3] = 3 |
|
|
495 @} |
|
|
496 @end group |
|
|
497 @end example |
|
|
498 |
|
6868
|
499 In general nested cell arrays are displayed hierarchically as above. In |
|
|
500 some circumstances it makes sense to reference them by their index, and |
|
|
501 this can be performed by the @code{celldisp} function. |
|
|
502 |
|
|
503 @DOCSTRING(celldisp) |
|
|
504 |
|
6516
|
505 @menu |
|
|
506 * Creating Cell Arrays:: |
|
|
507 * Indexing Cell Arrays:: |
|
|
508 * Cell Arrays of Strings:: |
|
|
509 * Processing Data in Cell Arrays:: |
|
|
510 @end menu |
|
|
511 |
|
6514
|
512 @node Creating Cell Arrays |
|
6837
|
513 @subsection Creating Cell Array |
|
6514
|
514 |
|
|
515 The introductory example showed how to create a cell array containing |
|
|
516 currently available variables. In many situations, however, it is useful |
|
|
517 to create a cell array and then fill it with data. |
|
|
518 |
|
|
519 The @code{cell} function returns a cell array of a given size, containing |
|
|
520 empty matrices. This function works very similar to the @code{zeros} |
|
|
521 function for creating new numerical arrays. The following example creates |
|
|
522 a 2-by-2 cell array containing empty matrices |
|
|
523 |
|
|
524 @example |
|
|
525 @group |
|
|
526 c = cell(2,2) |
|
|
527 @result{} c = |
|
|
528 |
|
|
529 @{ |
|
|
530 [1,1] = [](0x0) |
|
|
531 [2,1] = [](0x0) |
|
|
532 [1,2] = [](0x0) |
|
|
533 [2,2] = [](0x0) |
|
|
534 @} |
|
|
535 @end group |
|
|
536 @end example |
|
|
537 |
|
|
538 Just like numerical arrays, cell arrays can be multidimensional. The |
|
|
539 @code{cell} function accepts any number of positive integers to describe |
|
|
540 the size of the returned cell array. It is also possible to set the size |
|
|
541 of the cell array through a vector of positive integers. In the |
|
|
542 following example two cell arrays of equal size is created, and the size |
|
|
543 of the first one is displayed |
|
|
544 |
|
|
545 @example |
|
|
546 c1 = cell(3, 4, 5); |
|
|
547 c2 = cell( [3, 4, 5] ); |
|
|
548 size(c1) |
|
|
549 @result{} ans = |
|
|
550 3 4 5 |
|
|
551 @end example |
|
|
552 |
|
|
553 @noindent |
|
6939
|
554 As can be seen, the @code{size} function also works for cell arrays. As |
|
6514
|
555 do the other functions describing the size of an object, such as |
|
|
556 @code{length}, @code{numel}, @code{rows}, and @code{columns}. |
|
|
557 |
|
|
558 An alternative to creating empty cell arrays, and then filling them, it |
|
|
559 is possible to convert numerical arrays into cell arrays using the |
|
|
560 @code{num2cell} and @code{mat2cell} functions. |
|
|
561 |
|
3439
|
562 @DOCSTRING(cell) |
|
|
563 |
|
6514
|
564 @DOCSTRING(iscell) |
|
|
565 |
|
|
566 @DOCSTRING(num2cell) |
|
|
567 |
|
|
568 @DOCSTRING(mat2cell) |
|
|
569 |
|
|
570 @node Indexing Cell Arrays |
|
6837
|
571 @subsection Indexing Cell Arrays |
|
6514
|
572 |
|
|
573 As shown in the introductory example elements can be inserted from cell |
|
|
574 arrays using the @samp{@{} and @samp{@}} operators. Besides the change |
|
|
575 of operators, indexing works for cell arrays like for multidimensional |
|
|
576 arrays. As an example, all the rows of the first and third column of a |
|
|
577 cell array can be set to @code{0} with the following code |
|
|
578 |
|
|
579 @example |
|
|
580 c@{:, [1, 3]@} = 0; |
|
|
581 @end example |
|
|
582 |
|
|
583 Accessing values in a cell array is, however, different from the same |
|
|
584 operation for numerical arrays. Accessing a single element of a cell |
|
|
585 array is very similar to numerical arrays, for example |
|
|
586 |
|
|
587 @example |
|
|
588 element = c@{1, 2@}; |
|
|
589 @end example |
|
|
590 |
|
|
591 @noindent |
|
|
592 This will, however, @emph{not} work when accessing multiple elements of |
|
|
593 a cell array, because it might not be possible to represent all elements |
|
|
594 with a single variable as is the case with numerical arrays. |
|
|
595 |
|
6518
|
596 Accessing multiple elements of a cell array with the @samp{@{} and |
|
6837
|
597 @samp{@}} operators will result in a comma-separated list (@pxref{Comma |
|
|
598 Separated Lists}) of all the requested elements as discussed later. |
|
|
599 |
|
|
600 One distinction between @samp{@{} and @samp{(} to index cell arrays is |
|
|
601 in the deletion of elements from the cell array. In a similar manner to |
|
|
602 a numerical array the @samp{()} operator can be used to delete elements |
|
|
603 from the cell array. The @samp{@{@}} operator however will remove the |
|
|
604 elements of the cell array, but not delete the space for them. For example |
|
|
605 |
|
|
606 @example |
|
|
607 @group |
|
6839
|
608 x = @{'1', '2'; '3', '4'@}; |
|
|
609 x@{1, :@} = [] |
|
|
610 @result{} x = |
|
|
611 @{ |
|
6837
|
612 [1,1] = [](0x0) |
|
|
613 [2,1] = 3 |
|
|
614 [1,2] = [](0x0) |
|
|
615 [2,2] = 4 |
|
6839
|
616 @} |
|
6837
|
617 |
|
|
618 x(1, :) = [] |
|
6839
|
619 @result{} x = |
|
|
620 @{ |
|
6837
|
621 [1,1] = 3 |
|
|
622 [1,2] = 4 |
|
6839
|
623 @} |
|
6837
|
624 @end group |
|
|
625 @end example |
|
|
626 |
|
|
627 @node Cell Arrays of Strings |
|
|
628 @subsection Cell Arrays of Strings |
|
|
629 |
|
|
630 One common use of cell arrays is to store multiple strings in the same |
|
|
631 variable. It is possible to store multiple strings in a character matrix |
|
|
632 by letting each row be a string. This, however, introduces the problem |
|
|
633 that all strings must be of equal length. Therefore it is recommended to |
|
|
634 use cell arrays to store multiple strings. If, however, the character |
|
|
635 matrix representation is required for an operation, it can be converted |
|
|
636 to a cell array of strings using the @code{cellstr} function |
|
|
637 |
|
|
638 @example |
|
|
639 a = ["hello"; "world"]; |
|
|
640 c = cellstr (a) |
|
|
641 @result{} c = |
|
|
642 @{ |
|
|
643 [1,1] = hello |
|
|
644 [2,1] = world |
|
|
645 @} |
|
|
646 @end example |
|
|
647 |
|
|
648 One further advantage of using cell arrays to store multiple strings, is |
|
|
649 that most functions for string manipulations included with Octave |
|
6939
|
650 support this representation. As an example, it is possible to compare |
|
6837
|
651 one string with many others using the @code{strcmp} function. If one of |
|
|
652 the arguments to this function is a string and the other is a cell array |
|
|
653 of strings, each element of the cell array will be compared the string |
|
|
654 argument, |
|
|
655 |
|
|
656 @example |
|
|
657 c = @{"hello", "world"@}; |
|
|
658 strcmp ("hello", c) |
|
|
659 @result{} ans = |
|
|
660 1 0 |
|
|
661 @end example |
|
|
662 |
|
|
663 @noindent |
|
|
664 The following functions for string manipulation support cell arrays of |
|
|
665 strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, |
|
|
666 @code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc}, |
|
|
667 @code{strvcat}, @code{strfind}, and @code{strmatch}. |
|
|
668 |
|
|
669 @DOCSTRING(cellstr) |
|
|
670 |
|
|
671 @DOCSTRING(iscellstr) |
|
|
672 |
|
|
673 @DOCSTRING(cellidx) |
|
|
674 |
|
|
675 @node Processing Data in Cell Arrays |
|
|
676 @subsection Processing Data in Cell Arrays |
|
|
677 |
|
|
678 Data that is stored in a cell array can be processed in several ways |
|
|
679 depending on the actual data. The most simple way to process that data |
|
|
680 is to iterate through it using one or more @code{for} loops. The same |
|
|
681 idea can be implemented easier through the use of the @code{cellfun} |
|
|
682 function that calls a user specified function on all elements of a cell |
|
|
683 array. |
|
|
684 |
|
|
685 @DOCSTRING(cellfun) |
|
|
686 |
|
|
687 An alternative is to convert the data to a different container, such as |
|
|
688 a matrix or a data structure. Depending on the data this is possible |
|
|
689 using the @code{cell2mat} and @code{cell2struct} functions. |
|
|
690 |
|
|
691 @DOCSTRING(cell2mat) |
|
|
692 |
|
|
693 @DOCSTRING(cell2struct) |
|
|
694 |
|
|
695 @node Comma Separated Lists |
|
|
696 @section Comma Separated Lists |
|
|
697 @cindex comma separated lists |
|
|
698 |
|
|
699 Comma separated lists are the basic argument type to all Octave |
|
|
700 functions. In the example |
|
|
701 |
|
|
702 @example |
|
|
703 max (@var{a}, @var{b}) |
|
|
704 @end example |
|
|
705 |
|
|
706 @noindent |
|
7001
|
707 @code{@var{a}, @var{b}} is a comma separated list. Comma separated lists |
|
6837
|
708 can appear on both the right and left hand side of an equation. For |
|
|
709 example |
|
|
710 |
|
|
711 @example |
|
|
712 [@var{i}, @var{j}] = ceil (find (@var{x}, [], 'last')); |
|
|
713 @end example |
|
|
714 |
|
|
715 @noindent |
|
|
716 where @code{@var{i}, @var{j}} is equally a comma separated list. Comma |
|
|
717 separated lists can not be directly manipulated by the user. However, |
|
7001
|
718 both structures are cell arrays can be converted into comma |
|
6837
|
719 separated lists, which makes them useful to keep the input arguments and |
|
|
720 return values of functions organized. Another example of where a comma |
|
|
721 separated list can be used is in the creation of a new array. If all the |
|
|
722 accessed elements of a cell array are scalars or column vectors, they |
|
|
723 can be concatenated into a new column vector containing the elements, by |
|
|
724 surrounding the list with @code{[} and @code{]} as in the following |
|
|
725 example |
|
6514
|
726 |
|
|
727 @example |
|
|
728 a = @{1, [2, 3], 4@}; |
|
|
729 b = [a@{:@}] |
|
|
730 @result{} b = |
|
|
731 1 2 3 4 |
|
|
732 @end example |
|
|
733 |
|
6518
|
734 It is also possible to pass the accessed elements directly to a |
|
|
735 function. The list of elements from the cell array will be passed as an |
|
|
736 argument list to a given function as if it is called with the elements as |
|
|
737 arguments. The two calls to @code{printf} in the following example are |
|
7001
|
738 identical but the latter is simpler and handles more situations |
|
6518
|
739 |
|
|
740 @example |
|
|
741 c = @{"GNU", "Octave", "is", "Free", "Software"@}; |
|
|
742 printf ("%s ", c@{1@}, c@{2@}, c@{3@}, c@{4@}, c@{5@}); |
|
|
743 @print{} GNU Octave is Free Software |
|
|
744 printf ("%s ", c@{:@}); |
|
|
745 @print{} GNU Octave is Free Software |
|
|
746 @end example |
|
|
747 |
|
|
748 Just like it is possible to create a numerical array from selected |
|
|
749 elements of a cell array, it is possible to create a new cell array |
|
|
750 containing the selected elements. By surrounding the list with |
|
|
751 @samp{@{} and @samp{@}} a new cell array will be created, like the |
|
|
752 following example illustrates |
|
6514
|
753 |
|
|
754 @example |
|
|
755 a = @{1, rand(2, 2), "three"@}; |
|
|
756 b = @{ a@{ [1, 3] @} @} |
|
|
757 @result{} b = |
|
|
758 @{ |
|
|
759 [1,1] = 1 |
|
|
760 [1,2] = three |
|
|
761 @} |
|
|
762 @end example |
|
|
763 |
|
6518
|
764 @noindent |
|
|
765 This syntax is however a bit cumbersome, and since this is a common |
|
|
766 operation, it is possible to achieve the same using the @samp{(} |
|
|
767 and @samp{)} operators for indexing. When a cell array is indexed |
|
|
768 using the @samp{(} and @samp{)} operators a new cell array containing |
|
|
769 the selected elements. Using this syntax, the previous example can |
|
|
770 be simplified into the following |
|
6514
|
771 |
|
|
772 @example |
|
6518
|
773 a = @{1, rand(2, 2), "three"@}; |
|
|
774 b = a( [1, 3] ) |
|
|
775 @result{} b = |
|
|
776 @{ |
|
|
777 [1,1] = 1 |
|
|
778 [1,2] = three |
|
|
779 @} |
|
6514
|
780 @end example |
|
|
781 |
|
6837
|
782 A comma separated list can equally appear on the left-hand side of an |
|
|
783 assignment. An example is |
|
6514
|
784 |
|
|
785 @example |
|
6837
|
786 @group |
|
|
787 in @{1@} = ceil (rand (10, 1)); |
|
|
788 in @{2@} = []; |
|
|
789 in @{3@} = 'last'; |
|
|
790 in @{4@} = 'first'; |
|
|
791 out = cell (4, 1); |
|
|
792 [out@{1:2@}] = find (in@{1 : 3@}); |
|
|
793 [out@{3:4@}] = find (in@{[1, 2, 4]@}); |
|
|
794 @end group |
|
6514
|
795 @end example |
|
|
796 |
|
6939
|
797 Structure arrays can equally be used to create comma separated |
|
6837
|
798 lists. This is done by addresses one of the fields of a structure |
|
|
799 array. For example |
|
6514
|
800 |
|
6837
|
801 @example |
|
|
802 @group |
|
|
803 x = ceil (randn (10, 1)); |
|
|
804 in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@}); |
|
|
805 out = struct ('call1', cell (2, 1), 'call2', cell (2, 1)); |
|
|
806 [out.call1] = find (in.call1); |
|
|
807 [out.call2] = find (in.call2); |
|
|
808 @end group |
|
|
809 @end example |
