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