|
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 |
|
7031
|
313 in = struct ("call1", @{x, Inf, "last"@}, |
|
|
314 "call2", @{x, Inf, "first"@}); |
|
|
315 in (1, :) = [] |
|
6837
|
316 @result{} in = |
|
6839
|
317 @{ |
|
6837
|
318 call1 = |
|
|
319 |
|
|
320 (, |
|
|
321 [1] = Inf |
|
|
322 [2] = last |
|
|
323 ,) |
|
|
324 |
|
|
325 call2 = |
|
|
326 |
|
|
327 (, |
|
|
328 [1] = Inf |
|
|
329 [2] = first |
|
|
330 ,) |
|
|
331 |
|
6839
|
332 @} |
|
6837
|
333 @end group |
|
|
334 @end example |
|
|
335 |
|
|
336 @node Creating Structures |
|
|
337 @subsection Creating Structures |
|
|
338 |
|
|
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 |
|
|
344 |
|
|
345 @example |
|
|
346 @group |
|
7031
|
347 struct ("field1", 1, "field2", 2) |
|
6837
|
348 @result{} ans = |
|
|
349 @{ |
|
|
350 field1 = 1 |
|
|
351 field2 = 2 |
|
|
352 @} |
|
|
353 @end group |
|
|
354 @end example |
|
|
355 |
|
|
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 |
|
|
359 |
|
|
360 @example |
|
|
361 @group |
|
7031
|
362 struct ("field1", @{1, "one"@}, "field2", @{2, "two"@}, |
|
|
363 "field3", 3) |
|
6837
|
364 @result{} ans = |
|
|
365 @{ |
|
|
366 field1 = |
|
|
367 |
|
|
368 (, |
|
|
369 [1] = 1 |
|
|
370 [2] = one |
|
|
371 ,) |
|
|
372 |
|
|
373 field2 = |
|
|
374 |
|
|
375 (, |
|
|
376 [1] = 2 |
|
|
377 [2] = two |
|
|
378 ,) |
|
|
379 |
|
|
380 field3 = |
|
|
381 |
|
|
382 (, |
|
|
383 [1] = 3 |
|
|
384 [2] = 3 |
|
|
385 ,) |
|
|
386 |
|
|
387 @} |
|
|
388 @end group |
|
|
389 @end example |
|
|
390 |
|
|
391 @DOCSTRING(struct) |
|
|
392 |
|
|
393 @DOCSTRING(isstruct) |
|
|
394 |
|
|
395 Additional functions that can manipulate the fields of a structure are |
|
|
396 listed below. |
|
|
397 |
|
|
398 @DOCSTRING(rmfield) |
|
|
399 |
|
|
400 @DOCSTRING(setfield) |
|
|
401 |
|
|
402 @DOCSTRING(orderfields) |
|
|
403 |
|
|
404 @node Manipulating Structures |
|
|
405 @subsection Manipulating Structures |
|
|
406 |
|
|
407 Other functions that can manipulate the fields of a structure are given below. |
|
|
408 |
|
|
409 @DOCSTRING(fieldnames) |
|
|
410 |
|
|
411 @DOCSTRING(isfield) |
|
|
412 |
|
|
413 @DOCSTRING(getfield) |
|
|
414 |
|
6863
|
415 @DOCSTRING(substruct) |
|
|
416 |
|
|
417 @node Processing Data in Structures |
|
|
418 @subsection Processing Data in Structures |
|
6837
|
419 |
|
6939
|
420 The simplest way to process data in a structure is within a @code{for} |
|
6863
|
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 |
|
6939
|
423 function is applied to each field of the structure. |
|
6863
|
424 |
|
|
425 @DOCSTRING(structfun) |
|
|
426 |
|
6939
|
427 Alternatively, to process the data in a structure, the structure might |
|
6863
|
428 be converted to another type of container before being treated. |
|
|
429 |
|
|
430 @DOCSTRING(struct2cell) |
|
6837
|
431 |
|
6517
|
432 @node Cell Arrays |
|
6837
|
433 @section Cell Arrays |
|
3439
|
434 @cindex cell arrays |
|
|
435 |
|
6514
|
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. |
|
|
441 |
|
|
442 As an example, the following code creates a cell array containing a |
|
|
443 string and a 2-by-2 random matrix |
|
|
444 |
|
|
445 @example |
|
|
446 c = @{"a string", rand(2, 2)@}; |
|
|
447 @end example |
|
|
448 |
|
|
449 @noindent |
|
|
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 |
|
|
452 |
|
|
453 @example |
|
|
454 @group |
|
|
455 c@{1@} |
|
|
456 @result{} ans = a string |
|
|
457 @end group |
|
|
458 @end example |
|
|
459 |
|
|
460 @noindent |
|
|
461 As with numerical arrays several elements of a cell array can be |
|
|
462 extracted by indexing with a vector of indexes |
|
|
463 |
|
|
464 @example |
|
|
465 @group |
|
|
466 c@{1:2@} |
|
|
467 @result{} ans = |
|
|
468 |
|
|
469 (, |
|
|
470 [1] = a string |
|
|
471 [2] = |
|
|
472 |
|
|
473 0.593993 0.627732 |
|
|
474 0.377037 0.033643 |
|
|
475 |
|
|
476 ,) |
|
|
477 @end group |
|
|
478 @end example |
|
|
479 |
|
|
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 |
|
|
483 |
|
|
484 @example |
|
|
485 @group |
|
|
486 c@{3@} = 3 |
|
|
487 @result{} c = |
|
|
488 |
|
|
489 @{ |
|
|
490 [1,1] = a string |
|
|
491 [1,2] = |
|
|
492 |
|
|
493 0.593993 0.627732 |
|
|
494 0.377037 0.033643 |
|
|
495 |
|
|
496 [1,3] = 3 |
|
|
497 @} |
|
|
498 @end group |
|
|
499 @end example |
|
|
500 |
|
6868
|
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. |
|
|
504 |
|
|
505 @DOCSTRING(celldisp) |
|
|
506 |
|
6516
|
507 @menu |
|
|
508 * Creating Cell Arrays:: |
|
|
509 * Indexing Cell Arrays:: |
|
|
510 * Cell Arrays of Strings:: |
|
|
511 * Processing Data in Cell Arrays:: |
|
|
512 @end menu |
|
|
513 |
|
6514
|
514 @node Creating Cell Arrays |
|
6837
|
515 @subsection Creating Cell Array |
|
6514
|
516 |
|
|
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. |
|
|
520 |
|
|
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 |
|
|
525 |
|
|
526 @example |
|
|
527 @group |
|
|
528 c = cell(2,2) |
|
|
529 @result{} c = |
|
|
530 |
|
|
531 @{ |
|
|
532 [1,1] = [](0x0) |
|
|
533 [2,1] = [](0x0) |
|
|
534 [1,2] = [](0x0) |
|
|
535 [2,2] = [](0x0) |
|
|
536 @} |
|
|
537 @end group |
|
|
538 @end example |
|
|
539 |
|
|
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 |
|
|
546 |
|
|
547 @example |
|
|
548 c1 = cell(3, 4, 5); |
|
|
549 c2 = cell( [3, 4, 5] ); |
|
|
550 size(c1) |
|
|
551 @result{} ans = |
|
|
552 3 4 5 |
|
|
553 @end example |
|
|
554 |
|
|
555 @noindent |
|
6939
|
556 As can be seen, the @code{size} function also works for cell arrays. As |
|
6514
|
557 do the other functions describing the size of an object, such as |
|
|
558 @code{length}, @code{numel}, @code{rows}, and @code{columns}. |
|
|
559 |
|
|
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. |
|
|
563 |
|
3439
|
564 @DOCSTRING(cell) |
|
|
565 |
|
6514
|
566 @DOCSTRING(iscell) |
|
|
567 |
|
|
568 @DOCSTRING(num2cell) |
|
|
569 |
|
|
570 @DOCSTRING(mat2cell) |
|
|
571 |
|
|
572 @node Indexing Cell Arrays |
|
6837
|
573 @subsection Indexing Cell Arrays |
|
6514
|
574 |
|
|
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 |
|
|
580 |
|
|
581 @example |
|
|
582 c@{:, [1, 3]@} = 0; |
|
|
583 @end example |
|
|
584 |
|
|
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 |
|
|
588 |
|
|
589 @example |
|
|
590 element = c@{1, 2@}; |
|
|
591 @end example |
|
|
592 |
|
|
593 @noindent |
|
|
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. |
|
|
597 |
|
6518
|
598 Accessing multiple elements of a cell array with the @samp{@{} and |
|
6837
|
599 @samp{@}} operators will result in a comma-separated list (@pxref{Comma |
|
|
600 Separated Lists}) of all the requested elements as discussed later. |
|
|
601 |
|
|
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 |
|
|
607 |
|
|
608 @example |
|
|
609 @group |
|
7031
|
610 x = @{"1", "2"; "3", "4"@}; |
|
6839
|
611 x@{1, :@} = [] |
|
|
612 @result{} x = |
|
|
613 @{ |
|
6837
|
614 [1,1] = [](0x0) |
|
|
615 [2,1] = 3 |
|
|
616 [1,2] = [](0x0) |
|
|
617 [2,2] = 4 |
|
6839
|
618 @} |
|
6837
|
619 |
|
|
620 x(1, :) = [] |
|
6839
|
621 @result{} x = |
|
|
622 @{ |
|
6837
|
623 [1,1] = 3 |
|
|
624 [1,2] = 4 |
|
6839
|
625 @} |
|
6837
|
626 @end group |
|
|
627 @end example |
|
|
628 |
|
|
629 @node Cell Arrays of Strings |
|
|
630 @subsection Cell Arrays of Strings |
|
|
631 |
|
|
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 |
|
|
639 |
|
|
640 @example |
|
|
641 a = ["hello"; "world"]; |
|
|
642 c = cellstr (a) |
|
|
643 @result{} c = |
|
|
644 @{ |
|
|
645 [1,1] = hello |
|
|
646 [2,1] = world |
|
|
647 @} |
|
|
648 @end example |
|
|
649 |
|
|
650 One further advantage of using cell arrays to store multiple strings, is |
|
|
651 that most functions for string manipulations included with Octave |
|
6939
|
652 support this representation. As an example, it is possible to compare |
|
6837
|
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 |
|
|
656 argument, |
|
|
657 |
|
|
658 @example |
|
|
659 c = @{"hello", "world"@}; |
|
|
660 strcmp ("hello", c) |
|
|
661 @result{} ans = |
|
|
662 1 0 |
|
|
663 @end example |
|
|
664 |
|
|
665 @noindent |
|
|
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}. |
|
|
670 |
|
|
671 @DOCSTRING(cellstr) |
|
|
672 |
|
|
673 @DOCSTRING(iscellstr) |
|
|
674 |
|
|
675 @DOCSTRING(cellidx) |
|
|
676 |
|
|
677 @node Processing Data in Cell Arrays |
|
|
678 @subsection Processing Data in Cell Arrays |
|
|
679 |
|
|
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 |
|
|
685 array. |
|
|
686 |
|
|
687 @DOCSTRING(cellfun) |
|
|
688 |
|
|
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. |
|
|
692 |
|
|
693 @DOCSTRING(cell2mat) |
|
|
694 |
|
|
695 @DOCSTRING(cell2struct) |
|
|
696 |
|
|
697 @node Comma Separated Lists |
|
|
698 @section Comma Separated Lists |
|
|
699 @cindex comma separated lists |
|
|
700 |
|
|
701 Comma separated lists are the basic argument type to all Octave |
|
|
702 functions. In the example |
|
|
703 |
|
|
704 @example |
|
|
705 max (@var{a}, @var{b}) |
|
|
706 @end example |
|
|
707 |
|
|
708 @noindent |
|
7001
|
709 @code{@var{a}, @var{b}} is a comma separated list. Comma separated lists |
|
6837
|
710 can appear on both the right and left hand side of an equation. For |
|
|
711 example |
|
|
712 |
|
|
713 @example |
|
7031
|
714 [@var{i}, @var{j}] = ceil (find (@var{x}, [], "last")); |
|
6837
|
715 @end example |
|
|
716 |
|
|
717 @noindent |
|
|
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, |
|
7001
|
720 both structures are cell arrays can be converted into comma |
|
6837
|
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 |
|
|
727 example |
|
6514
|
728 |
|
|
729 @example |
|
|
730 a = @{1, [2, 3], 4@}; |
|
|
731 b = [a@{:@}] |
|
|
732 @result{} b = |
|
|
733 1 2 3 4 |
|
|
734 @end example |
|
|
735 |
|
6518
|
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 |
|
7001
|
740 identical but the latter is simpler and handles more situations |
|
6518
|
741 |
|
|
742 @example |
|
|
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 |
|
|
748 @end example |
|
|
749 |
|
|
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 |
|
6514
|
755 |
|
|
756 @example |
|
|
757 a = @{1, rand(2, 2), "three"@}; |
|
|
758 b = @{ a@{ [1, 3] @} @} |
|
|
759 @result{} b = |
|
|
760 @{ |
|
|
761 [1,1] = 1 |
|
|
762 [1,2] = three |
|
|
763 @} |
|
|
764 @end example |
|
|
765 |
|
6518
|
766 @noindent |
|
|
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 |
|
6514
|
773 |
|
|
774 @example |
|
6518
|
775 a = @{1, rand(2, 2), "three"@}; |
|
|
776 b = a( [1, 3] ) |
|
|
777 @result{} b = |
|
|
778 @{ |
|
|
779 [1,1] = 1 |
|
|
780 [1,2] = three |
|
|
781 @} |
|
6514
|
782 @end example |
|
|
783 |
|
6837
|
784 A comma separated list can equally appear on the left-hand side of an |
|
|
785 assignment. An example is |
|
6514
|
786 |
|
|
787 @example |
|
6837
|
788 @group |
|
|
789 in @{1@} = ceil (rand (10, 1)); |
|
|
790 in @{2@} = []; |
|
7031
|
791 in @{3@} = "last"; |
|
|
792 in @{4@} = "first"; |
|
6837
|
793 out = cell (4, 1); |
|
|
794 [out@{1:2@}] = find (in@{1 : 3@}); |
|
|
795 [out@{3:4@}] = find (in@{[1, 2, 4]@}); |
|
|
796 @end group |
|
6514
|
797 @end example |
|
|
798 |
|
6939
|
799 Structure arrays can equally be used to create comma separated |
|
6837
|
800 lists. This is done by addresses one of the fields of a structure |
|
|
801 array. For example |
|
6514
|
802 |
|
6837
|
803 @example |
|
|
804 @group |
|
|
805 x = ceil (randn (10, 1)); |
|
7031
|
806 in = struct ("call1", @{x, Inf, "last"@}, |
|
|
807 "call2", @{x, Inf, "first"@}); |
|
|
808 out = struct ("call1", cell (2, 1), "call2", cell (2, 1)); |
|
6837
|
809 [out.call1] = find (in.call1); |
|
|
810 [out.call2] = find (in.call2); |
|
|
811 @end group |
|
|
812 @end example |
