|
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:: |
|
|
203 @end menu |
|
|
204 |
|
|
205 @node Structure Arrays |
|
|
206 @subsection Structure Arrays |
|
|
207 |
|
|
208 A structure array is a particular instance of a structure, where each of |
|
|
209 the fields of the structure is represented by a cell array. Each of |
|
|
210 these cell arrays has the same dimensions. An example of the creation of |
|
|
211 a structure array is |
|
|
212 |
|
|
213 @example |
|
|
214 @group |
|
|
215 x(1).a = "string1" |
|
|
216 x(2).a = "string2" |
|
|
217 x(1).b = 1 |
|
|
218 x(2).b = 2 |
|
|
219 @end group |
|
|
220 @end example |
|
|
221 |
|
|
222 @noindent |
|
|
223 which creates a 2-by-1 structure array with two fields. As previously, |
|
|
224 to print the value of the structure array, you can type its name: |
|
|
225 |
|
|
226 @example |
|
|
227 @group |
|
|
228 octave:2> x |
|
|
229 x = |
|
|
230 @{ |
|
|
231 a = |
|
|
232 |
|
|
233 (, |
|
|
234 [1] = string1 |
|
|
235 [2] = string2 |
|
|
236 ,) |
|
|
237 |
|
|
238 b = |
|
|
239 |
|
|
240 (, |
|
|
241 [1] = 1 |
|
|
242 [2] = 2 |
|
|
243 ,) |
|
|
244 |
|
|
245 @} |
|
|
246 @end group |
|
|
247 @end example |
|
|
248 |
|
|
249 Individual elements of the structure array can be returned by indexing |
|
|
250 the variable like @code{@var{x} (1)}, which returns a structure with the |
|
|
251 two fields like |
|
|
252 |
|
|
253 @example |
|
|
254 @group |
|
|
255 octave:2> x(1) |
|
|
256 ans = |
|
|
257 @{ |
|
|
258 a = string1 |
|
|
259 b = 1 |
|
|
260 @} |
|
|
261 @end group |
|
|
262 @end example |
|
|
263 |
|
|
264 Furthermore, the structure array can return a comma seperated list |
|
|
265 (@pxref{Comma Separated Lists}), if indexed by one of itself field |
|
|
266 names. For example |
|
|
267 |
|
|
268 @example |
|
|
269 @group |
|
|
270 octave:3> x.a |
|
|
271 ans = |
|
|
272 |
|
|
273 (, |
|
|
274 [1] = string1 |
|
|
275 [2] = string2 |
|
|
276 ,) |
|
|
277 @end group |
|
|
278 @end example |
|
|
279 |
|
|
280 The function @code{size} with return the size of the structure. For |
|
|
281 the example above |
|
|
282 |
|
|
283 @example |
|
|
284 @group |
|
|
285 octave:4> size(x) |
|
|
286 ans = |
|
|
287 |
|
|
288 1 2 |
|
|
289 @end group |
|
|
290 @end example |
|
|
291 |
|
|
292 Elements can be deleted from a structure array in a similar manner to a |
|
|
293 numerial array, by assignment the elements to an empty matrix. For |
|
|
294 example |
|
|
295 |
|
|
296 @example |
|
|
297 @group |
|
|
298 in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@}); |
|
|
299 in (1, :) = [] |
|
|
300 @result{} in = |
|
|
301 { |
|
|
302 call1 = |
|
|
303 |
|
|
304 (, |
|
|
305 [1] = Inf |
|
|
306 [2] = last |
|
|
307 ,) |
|
|
308 |
|
|
309 call2 = |
|
|
310 |
|
|
311 (, |
|
|
312 [1] = Inf |
|
|
313 [2] = first |
|
|
314 ,) |
|
|
315 |
|
|
316 } |
|
|
317 @end group |
|
|
318 @end example |
|
|
319 |
|
|
320 @node Creating Structures |
|
|
321 @subsection Creating Structures |
|
|
322 |
|
|
323 As well as indexing a structure with ".", Octave can create a structure |
|
|
324 with the @code{struct} command. @code{struct} takes pairs of arguments, |
|
|
325 where the first argument in the pair is the fieldname to include in the |
|
|
326 structure and the second is a scalar or cell array, representing the |
|
|
327 values to include in the structure or structure array. For example |
|
|
328 |
|
|
329 @example |
|
|
330 @group |
|
|
331 struct ('field1', 1, 'field2', 2) |
|
|
332 @result{} ans = |
|
|
333 @{ |
|
|
334 field1 = 1 |
|
|
335 field2 = 2 |
|
|
336 @} |
|
|
337 @end group |
|
|
338 @end example |
|
|
339 |
|
|
340 If the values passed to @code{struct} are a mix of scalar and cell |
|
|
341 arrays, then the scalar arguments are expanded to create a |
|
|
342 structure array with a consistent dimension. For example |
|
|
343 |
|
|
344 @example |
|
|
345 @group |
|
|
346 struct ('field1', @{1, 'one'@}, 'field2', @{2, 'two'@}, 'field3', 3); |
|
|
347 @result{} ans = |
|
|
348 @{ |
|
|
349 field1 = |
|
|
350 |
|
|
351 (, |
|
|
352 [1] = 1 |
|
|
353 [2] = one |
|
|
354 ,) |
|
|
355 |
|
|
356 field2 = |
|
|
357 |
|
|
358 (, |
|
|
359 [1] = 2 |
|
|
360 [2] = two |
|
|
361 ,) |
|
|
362 |
|
|
363 field3 = |
|
|
364 |
|
|
365 (, |
|
|
366 [1] = 3 |
|
|
367 [2] = 3 |
|
|
368 ,) |
|
|
369 |
|
|
370 @} |
|
|
371 @end group |
|
|
372 @end example |
|
|
373 |
|
|
374 @DOCSTRING(struct) |
|
|
375 |
|
|
376 @DOCSTRING(isstruct) |
|
|
377 |
|
|
378 Additional functions that can manipulate the fields of a structure are |
|
|
379 listed below. |
|
|
380 |
|
|
381 @DOCSTRING(rmfield) |
|
|
382 |
|
|
383 @DOCSTRING(setfield) |
|
|
384 |
|
|
385 @DOCSTRING(orderfields) |
|
|
386 |
|
|
387 @node Manipulating Structures |
|
|
388 @subsection Manipulating Structures |
|
|
389 |
|
|
390 Other functions that can manipulate the fields of a structure are given below. |
|
|
391 |
|
|
392 @DOCSTRING(fieldnames) |
|
|
393 |
|
|
394 @DOCSTRING(isfield) |
|
|
395 |
|
|
396 @DOCSTRING(getfield) |
|
|
397 |
|
|
398 @DOCSTRING(struct2cell) |
|
|
399 |
|
|
400 @DOCSTRING(substruct) |
|
|
401 |
|
6517
|
402 @node Cell Arrays |
|
6837
|
403 @section Cell Arrays |
|
3439
|
404 @cindex cell arrays |
|
|
405 |
|
6514
|
406 It can be both necessary and convenient to store several variables of |
|
|
407 different size or type in one variable. A cell array is a container |
|
|
408 class able to do just that. In general cell arrays work just like |
|
|
409 @math{N}-dimensional arrays, with the exception of the use of @samp{@{} |
|
|
410 and @samp{@}} as allocation and indexing operators. |
|
|
411 |
|
|
412 As an example, the following code creates a cell array containing a |
|
|
413 string and a 2-by-2 random matrix |
|
|
414 |
|
|
415 @example |
|
|
416 c = @{"a string", rand(2, 2)@}; |
|
|
417 @end example |
|
|
418 |
|
|
419 @noindent |
|
|
420 And a cell array can be indexed with the @{ and @} operators, so the |
|
|
421 variable created in the previous example can be indexed like this |
|
|
422 |
|
|
423 @example |
|
|
424 @group |
|
|
425 c@{1@} |
|
|
426 @result{} ans = a string |
|
|
427 @end group |
|
|
428 @end example |
|
|
429 |
|
|
430 @noindent |
|
|
431 As with numerical arrays several elements of a cell array can be |
|
|
432 extracted by indexing with a vector of indexes |
|
|
433 |
|
|
434 @example |
|
|
435 @group |
|
|
436 c@{1:2@} |
|
|
437 @result{} ans = |
|
|
438 |
|
|
439 (, |
|
|
440 [1] = a string |
|
|
441 [2] = |
|
|
442 |
|
|
443 0.593993 0.627732 |
|
|
444 0.377037 0.033643 |
|
|
445 |
|
|
446 ,) |
|
|
447 @end group |
|
|
448 @end example |
|
|
449 |
|
|
450 The indexing operators can also be used to insert or overwrite elements |
|
|
451 of a cell array. The following code inserts the scalar 3 on the |
|
|
452 third place of the previously created cell array |
|
|
453 |
|
|
454 @example |
|
|
455 @group |
|
|
456 c@{3@} = 3 |
|
|
457 @result{} c = |
|
|
458 |
|
|
459 @{ |
|
|
460 [1,1] = a string |
|
|
461 [1,2] = |
|
|
462 |
|
|
463 0.593993 0.627732 |
|
|
464 0.377037 0.033643 |
|
|
465 |
|
|
466 [1,3] = 3 |
|
|
467 @} |
|
|
468 @end group |
|
|
469 @end example |
|
|
470 |
|
6516
|
471 @menu |
|
|
472 * Creating Cell Arrays:: |
|
|
473 * Indexing Cell Arrays:: |
|
|
474 * Cell Arrays of Strings:: |
|
|
475 * Processing Data in Cell Arrays:: |
|
|
476 @end menu |
|
|
477 |
|
6514
|
478 @node Creating Cell Arrays |
|
6837
|
479 @subsection Creating Cell Array |
|
6514
|
480 |
|
|
481 The introductory example showed how to create a cell array containing |
|
|
482 currently available variables. In many situations, however, it is useful |
|
|
483 to create a cell array and then fill it with data. |
|
|
484 |
|
|
485 The @code{cell} function returns a cell array of a given size, containing |
|
|
486 empty matrices. This function works very similar to the @code{zeros} |
|
|
487 function for creating new numerical arrays. The following example creates |
|
|
488 a 2-by-2 cell array containing empty matrices |
|
|
489 |
|
|
490 @example |
|
|
491 @group |
|
|
492 c = cell(2,2) |
|
|
493 @result{} c = |
|
|
494 |
|
|
495 @{ |
|
|
496 [1,1] = [](0x0) |
|
|
497 [2,1] = [](0x0) |
|
|
498 [1,2] = [](0x0) |
|
|
499 [2,2] = [](0x0) |
|
|
500 @} |
|
|
501 @end group |
|
|
502 @end example |
|
|
503 |
|
|
504 Just like numerical arrays, cell arrays can be multidimensional. The |
|
|
505 @code{cell} function accepts any number of positive integers to describe |
|
|
506 the size of the returned cell array. It is also possible to set the size |
|
|
507 of the cell array through a vector of positive integers. In the |
|
|
508 following example two cell arrays of equal size is created, and the size |
|
|
509 of the first one is displayed |
|
|
510 |
|
|
511 @example |
|
|
512 c1 = cell(3, 4, 5); |
|
|
513 c2 = cell( [3, 4, 5] ); |
|
|
514 size(c1) |
|
|
515 @result{} ans = |
|
|
516 3 4 5 |
|
|
517 @end example |
|
|
518 |
|
|
519 @noindent |
|
|
520 As can be seen, the @code{size} function also work for cell arrays. As |
|
|
521 do the other functions describing the size of an object, such as |
|
|
522 @code{length}, @code{numel}, @code{rows}, and @code{columns}. |
|
|
523 |
|
|
524 An alternative to creating empty cell arrays, and then filling them, it |
|
|
525 is possible to convert numerical arrays into cell arrays using the |
|
|
526 @code{num2cell} and @code{mat2cell} functions. |
|
|
527 |
|
3439
|
528 @DOCSTRING(cell) |
|
|
529 |
|
6514
|
530 @DOCSTRING(iscell) |
|
|
531 |
|
|
532 @DOCSTRING(num2cell) |
|
|
533 |
|
|
534 @DOCSTRING(mat2cell) |
|
|
535 |
|
|
536 @node Indexing Cell Arrays |
|
6837
|
537 @subsection Indexing Cell Arrays |
|
6514
|
538 |
|
|
539 As shown in the introductory example elements can be inserted from cell |
|
|
540 arrays using the @samp{@{} and @samp{@}} operators. Besides the change |
|
|
541 of operators, indexing works for cell arrays like for multidimensional |
|
|
542 arrays. As an example, all the rows of the first and third column of a |
|
|
543 cell array can be set to @code{0} with the following code |
|
|
544 |
|
|
545 @example |
|
|
546 c@{:, [1, 3]@} = 0; |
|
|
547 @end example |
|
|
548 |
|
|
549 Accessing values in a cell array is, however, different from the same |
|
|
550 operation for numerical arrays. Accessing a single element of a cell |
|
|
551 array is very similar to numerical arrays, for example |
|
|
552 |
|
|
553 @example |
|
|
554 element = c@{1, 2@}; |
|
|
555 @end example |
|
|
556 |
|
|
557 @noindent |
|
|
558 This will, however, @emph{not} work when accessing multiple elements of |
|
|
559 a cell array, because it might not be possible to represent all elements |
|
|
560 with a single variable as is the case with numerical arrays. |
|
|
561 |
|
6518
|
562 Accessing multiple elements of a cell array with the @samp{@{} and |
|
6837
|
563 @samp{@}} operators will result in a comma-separated list (@pxref{Comma |
|
|
564 Separated Lists}) of all the requested elements as discussed later. |
|
|
565 |
|
|
566 One distinction between @samp{@{} and @samp{(} to index cell arrays is |
|
|
567 in the deletion of elements from the cell array. In a similar manner to |
|
|
568 a numerical array the @samp{()} operator can be used to delete elements |
|
|
569 from the cell array. The @samp{@{@}} operator however will remove the |
|
|
570 elements of the cell array, but not delete the space for them. For example |
|
|
571 |
|
|
572 @example |
|
|
573 @group |
|
|
574 x = {'1', '2'; '3', '4'}; |
|
|
575 x{1, :} = [] |
|
|
576 @result x = |
|
|
577 { |
|
|
578 [1,1] = [](0x0) |
|
|
579 [2,1] = 3 |
|
|
580 [1,2] = [](0x0) |
|
|
581 [2,2] = 4 |
|
|
582 } |
|
|
583 |
|
|
584 x(1, :) = [] |
|
|
585 @result {} x = |
|
|
586 { |
|
|
587 [1,1] = 3 |
|
|
588 [1,2] = 4 |
|
|
589 } |
|
|
590 @end group |
|
|
591 @end example |
|
|
592 |
|
|
593 @node Cell Arrays of Strings |
|
|
594 @subsection Cell Arrays of Strings |
|
|
595 |
|
|
596 One common use of cell arrays is to store multiple strings in the same |
|
|
597 variable. It is possible to store multiple strings in a character matrix |
|
|
598 by letting each row be a string. This, however, introduces the problem |
|
|
599 that all strings must be of equal length. Therefore it is recommended to |
|
|
600 use cell arrays to store multiple strings. If, however, the character |
|
|
601 matrix representation is required for an operation, it can be converted |
|
|
602 to a cell array of strings using the @code{cellstr} function |
|
|
603 |
|
|
604 @example |
|
|
605 a = ["hello"; "world"]; |
|
|
606 c = cellstr (a) |
|
|
607 @result{} c = |
|
|
608 @{ |
|
|
609 [1,1] = hello |
|
|
610 [2,1] = world |
|
|
611 @} |
|
|
612 @end example |
|
|
613 |
|
|
614 One further advantage of using cell arrays to store multiple strings, is |
|
|
615 that most functions for string manipulations included with Octave |
|
|
616 supports this representation. As an example, it is possible to compare |
|
|
617 one string with many others using the @code{strcmp} function. If one of |
|
|
618 the arguments to this function is a string and the other is a cell array |
|
|
619 of strings, each element of the cell array will be compared the string |
|
|
620 argument, |
|
|
621 |
|
|
622 @example |
|
|
623 c = @{"hello", "world"@}; |
|
|
624 strcmp ("hello", c) |
|
|
625 @result{} ans = |
|
|
626 1 0 |
|
|
627 @end example |
|
|
628 |
|
|
629 @noindent |
|
|
630 The following functions for string manipulation support cell arrays of |
|
|
631 strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, |
|
|
632 @code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc}, |
|
|
633 @code{strvcat}, @code{strfind}, and @code{strmatch}. |
|
|
634 |
|
|
635 @DOCSTRING(cellstr) |
|
|
636 |
|
|
637 @DOCSTRING(iscellstr) |
|
|
638 |
|
|
639 @DOCSTRING(cellidx) |
|
|
640 |
|
|
641 @node Processing Data in Cell Arrays |
|
|
642 @subsection Processing Data in Cell Arrays |
|
|
643 |
|
|
644 Data that is stored in a cell array can be processed in several ways |
|
|
645 depending on the actual data. The most simple way to process that data |
|
|
646 is to iterate through it using one or more @code{for} loops. The same |
|
|
647 idea can be implemented easier through the use of the @code{cellfun} |
|
|
648 function that calls a user specified function on all elements of a cell |
|
|
649 array. |
|
|
650 |
|
|
651 @DOCSTRING(cellfun) |
|
|
652 |
|
|
653 An alternative is to convert the data to a different container, such as |
|
|
654 a matrix or a data structure. Depending on the data this is possible |
|
|
655 using the @code{cell2mat} and @code{cell2struct} functions. |
|
|
656 |
|
|
657 @DOCSTRING(cell2mat) |
|
|
658 |
|
|
659 @DOCSTRING(cell2struct) |
|
|
660 |
|
|
661 @node Comma Separated Lists |
|
|
662 @section Comma Separated Lists |
|
|
663 @cindex comma separated lists |
|
|
664 |
|
|
665 Comma separated lists are the basic argument type to all Octave |
|
|
666 functions. In the example |
|
|
667 |
|
|
668 @example |
|
|
669 max (@var{a}, @var{b}) |
|
|
670 @end example |
|
|
671 |
|
|
672 @noindent |
|
|
673 @code{@var{a}, @var{b}} is a somma separated list. Comma separated lists |
|
|
674 can appear on both the right and left hand side of an equation. For |
|
|
675 example |
|
|
676 |
|
|
677 @example |
|
|
678 [@var{i}, @var{j}] = ceil (find (@var{x}, [], 'last')); |
|
|
679 @end example |
|
|
680 |
|
|
681 @noindent |
|
|
682 where @code{@var{i}, @var{j}} is equally a comma separated list. Comma |
|
|
683 separated lists can not be directly manipulated by the user. However, |
|
|
684 both structures are cell arrays can be converted into into comma |
|
|
685 separated lists, which makes them useful to keep the input arguments and |
|
|
686 return values of functions organized. Another example of where a comma |
|
|
687 separated list can be used is in the creation of a new array. If all the |
|
|
688 accessed elements of a cell array are scalars or column vectors, they |
|
|
689 can be concatenated into a new column vector containing the elements, by |
|
|
690 surrounding the list with @code{[} and @code{]} as in the following |
|
|
691 example |
|
6514
|
692 |
|
|
693 @example |
|
|
694 a = @{1, [2, 3], 4@}; |
|
|
695 b = [a@{:@}] |
|
|
696 @result{} b = |
|
|
697 1 2 3 4 |
|
|
698 @end example |
|
|
699 |
|
6518
|
700 It is also possible to pass the accessed elements directly to a |
|
|
701 function. The list of elements from the cell array will be passed as an |
|
|
702 argument list to a given function as if it is called with the elements as |
|
|
703 arguments. The two calls to @code{printf} in the following example are |
|
|
704 identical but the latter is more simple and handles more situations |
|
|
705 |
|
|
706 @example |
|
|
707 c = @{"GNU", "Octave", "is", "Free", "Software"@}; |
|
|
708 printf ("%s ", c@{1@}, c@{2@}, c@{3@}, c@{4@}, c@{5@}); |
|
|
709 @print{} GNU Octave is Free Software |
|
|
710 printf ("%s ", c@{:@}); |
|
|
711 @print{} GNU Octave is Free Software |
|
|
712 @end example |
|
|
713 |
|
|
714 Just like it is possible to create a numerical array from selected |
|
|
715 elements of a cell array, it is possible to create a new cell array |
|
|
716 containing the selected elements. By surrounding the list with |
|
|
717 @samp{@{} and @samp{@}} a new cell array will be created, like the |
|
|
718 following example illustrates |
|
6514
|
719 |
|
|
720 @example |
|
|
721 a = @{1, rand(2, 2), "three"@}; |
|
|
722 b = @{ a@{ [1, 3] @} @} |
|
|
723 @result{} b = |
|
|
724 @{ |
|
|
725 [1,1] = 1 |
|
|
726 [1,2] = three |
|
|
727 @} |
|
|
728 @end example |
|
|
729 |
|
6518
|
730 @noindent |
|
|
731 This syntax is however a bit cumbersome, and since this is a common |
|
|
732 operation, it is possible to achieve the same using the @samp{(} |
|
|
733 and @samp{)} operators for indexing. When a cell array is indexed |
|
|
734 using the @samp{(} and @samp{)} operators a new cell array containing |
|
|
735 the selected elements. Using this syntax, the previous example can |
|
|
736 be simplified into the following |
|
6514
|
737 |
|
|
738 @example |
|
6518
|
739 a = @{1, rand(2, 2), "three"@}; |
|
|
740 b = a( [1, 3] ) |
|
|
741 @result{} b = |
|
|
742 @{ |
|
|
743 [1,1] = 1 |
|
|
744 [1,2] = three |
|
|
745 @} |
|
6514
|
746 @end example |
|
|
747 |
|
6837
|
748 A comma separated list can equally appear on the left-hand side of an |
|
|
749 assignment. An example is |
|
6514
|
750 |
|
|
751 @example |
|
6837
|
752 @group |
|
|
753 in @{1@} = ceil (rand (10, 1)); |
|
|
754 in @{2@} = []; |
|
|
755 in @{3@} = 'last'; |
|
|
756 in @{4@} = 'first'; |
|
|
757 out = cell (4, 1); |
|
|
758 [out@{1:2@}] = find (in@{1 : 3@}); |
|
|
759 [out@{3:4@}] = find (in@{[1, 2, 4]@}); |
|
|
760 @end group |
|
6514
|
761 @end example |
|
|
762 |
|
6837
|
763 Structures arrays can equally be used to create comma separated |
|
|
764 lists. This is done by addresses one of the fields of a structure |
|
|
765 array. For example |
|
6514
|
766 |
|
6837
|
767 @example |
|
|
768 @group |
|
|
769 x = ceil (randn (10, 1)); |
|
|
770 in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@}); |
|
|
771 out = struct ('call1', cell (2, 1), 'call2', cell (2, 1)); |
|
|
772 [out.call1] = find (in.call1); |
|
|
773 [out.call2] = find (in.call2); |
|
|
774 @end group |
|
|
775 @end example |
