Mercurial > octave-libgccjit
annotate doc/interpreter/container.txi @ 8920:eb63fbe60fab
update copyright notices
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Sat, 07 Mar 2009 10:41:27 -0500 |
| parents | 8463d1a2e544 |
| children | 58604c45ca74 |
| rev | line source |
|---|---|
| 8920 | 1 @c Copyright (C) 1996, 1997, 2007, 2008, 2009 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 | |
|
8134
951917a0b9f8
container.txi: fix cross reference in struct docs
Francesco Potorti
parents:
8094
diff
changeset
|
211 (@pxref{Looping Over Structure Elements}) |
| 6837 | 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 | |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
243 octave:1> x |
| 6837 | 244 x = |
| 245 @{ | |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
246 1x2 struct array containing the fields: |
| 6837 | 247 |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
248 a |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
249 b |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
250 @} |
| 6837 | 251 @end group |
| 252 @end example | |
| 253 | |
| 254 Individual elements of the structure array can be returned by indexing | |
| 255 the variable like @code{@var{x} (1)}, which returns a structure with the | |
| 256 two fields like | |
| 257 | |
| 258 @example | |
| 259 @group | |
| 260 octave:2> x(1) | |
| 261 ans = | |
| 262 @{ | |
| 263 a = string1 | |
| 264 b = 1 | |
| 265 @} | |
| 266 @end group | |
| 267 @end example | |
| 268 | |
| 6939 | 269 Furthermore, the structure array can return a comma separated list |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8176
diff
changeset
|
270 (@pxref{Comma Separated Lists}), if indexed by one of its own field |
| 6837 | 271 names. For example |
| 272 | |
| 273 @example | |
| 274 @group | |
| 275 octave:3> x.a | |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
276 ans = string1 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
277 ans = string2 |
| 6837 | 278 @end group |
| 279 @end example | |
| 280 | |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
281 Here is another example, using this comma separated list on the |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
282 left-hand side of an assignment: |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
283 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
284 @example |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
285 @group |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
286 octave:4> [x.a] = deal("new string1", "new string2"); |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
287 octave:5> x(1).a |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
288 ans = new string1 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
289 octave:6> x(2).a |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
290 ans = new string2 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
291 @end group |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
292 @end example |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
293 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
294 Just as for numerical arrays, it is possible to use vectors as indices (@pxref{Index Expressions}): |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
295 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
296 @example |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
297 @group |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
298 octave:7> x(3:4) = x(1:2); |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
299 octave:8> [x([1,3]).a] = deal("other string1", "other string2"); |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
300 octave:9> x.a |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
301 ans = other string1 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
302 ans = new string2 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
303 ans = other string2 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
304 ans = new string2 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
305 @end group |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
306 @end example |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
307 |
|
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
308 The function @code{size} will return the size of the structure. For |
| 6837 | 309 the example above |
| 310 | |
| 311 @example | |
| 312 @group | |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
313 octave:10> size(x) |
| 6837 | 314 ans = |
| 315 | |
|
8584
848f7d3e589c
Update the examples for structure arrays in container.txi
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8541
diff
changeset
|
316 1 4 |
| 6837 | 317 @end group |
| 318 @end example | |
| 319 | |
| 320 Elements can be deleted from a structure array in a similar manner to a | |
| 7001 | 321 numerical array, by assigning the elements to an empty matrix. For |
| 6837 | 322 example |
| 323 | |
| 324 @example | |
| 325 @group | |
| 7031 | 326 in = struct ("call1", @{x, Inf, "last"@}, |
| 327 "call2", @{x, Inf, "first"@}); | |
| 328 in (1, :) = [] | |
| 6837 | 329 @result{} in = |
| 6839 | 330 @{ |
| 6837 | 331 call1 = |
| 332 | |
| 333 (, | |
| 334 [1] = Inf | |
| 335 [2] = last | |
| 336 ,) | |
| 337 | |
| 338 call2 = | |
| 339 | |
| 340 (, | |
| 341 [1] = Inf | |
| 342 [2] = first | |
| 343 ,) | |
| 344 | |
| 6839 | 345 @} |
| 6837 | 346 @end group |
| 347 @end example | |
| 348 | |
| 349 @node Creating Structures | |
| 350 @subsection Creating Structures | |
| 351 | |
| 352 As well as indexing a structure with ".", Octave can create a structure | |
| 353 with the @code{struct} command. @code{struct} takes pairs of arguments, | |
| 354 where the first argument in the pair is the fieldname to include in the | |
| 355 structure and the second is a scalar or cell array, representing the | |
| 356 values to include in the structure or structure array. For example | |
| 357 | |
| 358 @example | |
| 359 @group | |
| 7031 | 360 struct ("field1", 1, "field2", 2) |
| 6837 | 361 @result{} ans = |
| 362 @{ | |
| 363 field1 = 1 | |
| 364 field2 = 2 | |
| 365 @} | |
| 366 @end group | |
| 367 @end example | |
| 368 | |
| 369 If the values passed to @code{struct} are a mix of scalar and cell | |
| 370 arrays, then the scalar arguments are expanded to create a | |
| 371 structure array with a consistent dimension. For example | |
| 372 | |
| 373 @example | |
| 374 @group | |
| 7031 | 375 struct ("field1", @{1, "one"@}, "field2", @{2, "two"@}, |
| 376 "field3", 3) | |
| 6837 | 377 @result{} ans = |
| 378 @{ | |
| 379 field1 = | |
| 380 | |
| 381 (, | |
| 382 [1] = 1 | |
| 383 [2] = one | |
| 384 ,) | |
| 385 | |
| 386 field2 = | |
| 387 | |
| 388 (, | |
| 389 [1] = 2 | |
| 390 [2] = two | |
| 391 ,) | |
| 392 | |
| 393 field3 = | |
| 394 | |
| 395 (, | |
| 396 [1] = 3 | |
| 397 [2] = 3 | |
| 398 ,) | |
| 399 | |
| 400 @} | |
| 401 @end group | |
| 402 @end example | |
| 403 | |
| 404 @DOCSTRING(struct) | |
| 405 | |
| 406 @DOCSTRING(isstruct) | |
| 407 | |
| 408 Additional functions that can manipulate the fields of a structure are | |
| 409 listed below. | |
| 410 | |
| 411 @DOCSTRING(rmfield) | |
| 412 | |
| 413 @DOCSTRING(setfield) | |
| 414 | |
| 415 @DOCSTRING(orderfields) | |
| 416 | |
| 417 @node Manipulating Structures | |
| 418 @subsection Manipulating Structures | |
| 419 | |
| 420 Other functions that can manipulate the fields of a structure are given below. | |
| 421 | |
| 422 @DOCSTRING(fieldnames) | |
| 423 | |
| 424 @DOCSTRING(isfield) | |
| 425 | |
| 426 @DOCSTRING(getfield) | |
| 427 | |
| 6863 | 428 @DOCSTRING(substruct) |
| 429 | |
| 430 @node Processing Data in Structures | |
| 431 @subsection Processing Data in Structures | |
| 6837 | 432 |
| 6939 | 433 The simplest way to process data in a structure is within a @code{for} |
| 8135 | 434 loop (@pxref{Looping Over Structure Elements}). A similar effect can be |
| 6863 | 435 achieved with the @code{structfun} function, where a user defined |
| 6939 | 436 function is applied to each field of the structure. |
| 6863 | 437 |
| 438 @DOCSTRING(structfun) | |
| 439 | |
| 6939 | 440 Alternatively, to process the data in a structure, the structure might |
| 6863 | 441 be converted to another type of container before being treated. |
| 442 | |
| 443 @DOCSTRING(struct2cell) | |
| 6837 | 444 |
| 6517 | 445 @node Cell Arrays |
| 6837 | 446 @section Cell Arrays |
| 3439 | 447 @cindex cell arrays |
| 448 | |
| 6514 | 449 It can be both necessary and convenient to store several variables of |
| 450 different size or type in one variable. A cell array is a container | |
| 451 class able to do just that. In general cell arrays work just like | |
| 452 @math{N}-dimensional arrays, with the exception of the use of @samp{@{} | |
| 453 and @samp{@}} as allocation and indexing operators. | |
| 454 | |
| 455 As an example, the following code creates a cell array containing a | |
| 456 string and a 2-by-2 random matrix | |
| 457 | |
| 458 @example | |
| 459 c = @{"a string", rand(2, 2)@}; | |
| 460 @end example | |
| 461 | |
| 462 @noindent | |
| 463 And a cell array can be indexed with the @{ and @} operators, so the | |
| 464 variable created in the previous example can be indexed like this | |
| 465 | |
| 466 @example | |
| 467 @group | |
| 468 c@{1@} | |
| 469 @result{} ans = a string | |
| 470 @end group | |
| 471 @end example | |
| 472 | |
| 473 @noindent | |
| 474 As with numerical arrays several elements of a cell array can be | |
| 475 extracted by indexing with a vector of indexes | |
| 476 | |
| 477 @example | |
| 478 @group | |
| 479 c@{1:2@} | |
| 480 @result{} ans = | |
| 481 | |
| 482 (, | |
| 483 [1] = a string | |
| 484 [2] = | |
| 485 | |
| 486 0.593993 0.627732 | |
| 487 0.377037 0.033643 | |
| 488 | |
| 489 ,) | |
| 490 @end group | |
| 491 @end example | |
| 492 | |
| 493 The indexing operators can also be used to insert or overwrite elements | |
| 494 of a cell array. The following code inserts the scalar 3 on the | |
| 495 third place of the previously created cell array | |
| 496 | |
| 497 @example | |
| 498 @group | |
| 499 c@{3@} = 3 | |
| 500 @result{} c = | |
| 501 | |
| 502 @{ | |
| 503 [1,1] = a string | |
| 504 [1,2] = | |
| 505 | |
| 506 0.593993 0.627732 | |
| 507 0.377037 0.033643 | |
| 508 | |
| 509 [1,3] = 3 | |
| 510 @} | |
| 511 @end group | |
| 512 @end example | |
| 513 | |
| 6868 | 514 In general nested cell arrays are displayed hierarchically as above. In |
| 515 some circumstances it makes sense to reference them by their index, and | |
| 516 this can be performed by the @code{celldisp} function. | |
| 517 | |
| 518 @DOCSTRING(celldisp) | |
| 519 | |
| 6516 | 520 @menu |
| 521 * Creating Cell Arrays:: | |
| 522 * Indexing Cell Arrays:: | |
| 523 * Cell Arrays of Strings:: | |
| 524 * Processing Data in Cell Arrays:: | |
| 525 @end menu | |
| 526 | |
| 6514 | 527 @node Creating Cell Arrays |
| 6837 | 528 @subsection Creating Cell Array |
| 6514 | 529 |
| 530 The introductory example showed how to create a cell array containing | |
| 531 currently available variables. In many situations, however, it is useful | |
| 532 to create a cell array and then fill it with data. | |
| 533 | |
| 534 The @code{cell} function returns a cell array of a given size, containing | |
| 8828 | 535 empty matrices. This function is similar to the @code{zeros} |
| 6514 | 536 function for creating new numerical arrays. The following example creates |
| 537 a 2-by-2 cell array containing empty matrices | |
| 538 | |
| 539 @example | |
| 540 @group | |
| 541 c = cell(2,2) | |
| 542 @result{} c = | |
| 543 | |
| 544 @{ | |
| 545 [1,1] = [](0x0) | |
| 546 [2,1] = [](0x0) | |
| 547 [1,2] = [](0x0) | |
| 548 [2,2] = [](0x0) | |
| 549 @} | |
| 550 @end group | |
| 551 @end example | |
| 552 | |
| 553 Just like numerical arrays, cell arrays can be multidimensional. The | |
| 554 @code{cell} function accepts any number of positive integers to describe | |
| 555 the size of the returned cell array. It is also possible to set the size | |
| 556 of the cell array through a vector of positive integers. In the | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8176
diff
changeset
|
557 following example two cell arrays of equal size are created, and the size |
| 6514 | 558 of the first one is displayed |
| 559 | |
| 560 @example | |
| 561 c1 = cell(3, 4, 5); | |
| 562 c2 = cell( [3, 4, 5] ); | |
| 563 size(c1) | |
| 564 @result{} ans = | |
| 565 3 4 5 | |
| 566 @end example | |
| 567 | |
| 568 @noindent | |
| 6939 | 569 As can be seen, the @code{size} function also works for cell arrays. As |
| 6514 | 570 do the other functions describing the size of an object, such as |
| 571 @code{length}, @code{numel}, @code{rows}, and @code{columns}. | |
| 572 | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8176
diff
changeset
|
573 As an alternative to creating empty cell arrays, and then filling them, it |
| 6514 | 574 is possible to convert numerical arrays into cell arrays using the |
| 575 @code{num2cell} and @code{mat2cell} functions. | |
| 576 | |
| 3439 | 577 @DOCSTRING(cell) |
| 578 | |
| 6514 | 579 @DOCSTRING(iscell) |
| 580 | |
| 581 @DOCSTRING(num2cell) | |
| 582 | |
| 583 @DOCSTRING(mat2cell) | |
| 584 | |
| 585 @node Indexing Cell Arrays | |
| 6837 | 586 @subsection Indexing Cell Arrays |
| 6514 | 587 |
| 588 As shown in the introductory example elements can be inserted from cell | |
| 589 arrays using the @samp{@{} and @samp{@}} operators. Besides the change | |
| 590 of operators, indexing works for cell arrays like for multidimensional | |
| 591 arrays. As an example, all the rows of the first and third column of a | |
| 592 cell array can be set to @code{0} with the following code | |
| 593 | |
| 594 @example | |
| 595 c@{:, [1, 3]@} = 0; | |
| 596 @end example | |
| 597 | |
| 598 Accessing values in a cell array is, however, different from the same | |
| 599 operation for numerical arrays. Accessing a single element of a cell | |
| 600 array is very similar to numerical arrays, for example | |
| 601 | |
| 602 @example | |
| 603 element = c@{1, 2@}; | |
| 604 @end example | |
| 605 | |
| 606 @noindent | |
| 607 This will, however, @emph{not} work when accessing multiple elements of | |
| 608 a cell array, because it might not be possible to represent all elements | |
| 609 with a single variable as is the case with numerical arrays. | |
| 610 | |
| 6518 | 611 Accessing multiple elements of a cell array with the @samp{@{} and |
| 6837 | 612 @samp{@}} operators will result in a comma-separated list (@pxref{Comma |
| 613 Separated Lists}) of all the requested elements as discussed later. | |
| 614 | |
| 615 One distinction between @samp{@{} and @samp{(} to index cell arrays is | |
| 616 in the deletion of elements from the cell array. In a similar manner to | |
| 617 a numerical array the @samp{()} operator can be used to delete elements | |
| 618 from the cell array. The @samp{@{@}} operator however will remove the | |
| 619 elements of the cell array, but not delete the space for them. For example | |
| 620 | |
| 621 @example | |
| 622 @group | |
| 7031 | 623 x = @{"1", "2"; "3", "4"@}; |
| 6839 | 624 x@{1, :@} = [] |
| 625 @result{} x = | |
| 626 @{ | |
| 6837 | 627 [1,1] = [](0x0) |
| 628 [2,1] = 3 | |
| 629 [1,2] = [](0x0) | |
| 630 [2,2] = 4 | |
| 6839 | 631 @} |
| 6837 | 632 |
| 633 x(1, :) = [] | |
| 6839 | 634 @result{} x = |
| 635 @{ | |
| 6837 | 636 [1,1] = 3 |
| 637 [1,2] = 4 | |
| 6839 | 638 @} |
| 6837 | 639 @end group |
| 640 @end example | |
| 641 | |
| 642 @node Cell Arrays of Strings | |
| 643 @subsection Cell Arrays of Strings | |
| 644 | |
| 645 One common use of cell arrays is to store multiple strings in the same | |
| 646 variable. It is possible to store multiple strings in a character matrix | |
| 647 by letting each row be a string. This, however, introduces the problem | |
| 648 that all strings must be of equal length. Therefore it is recommended to | |
| 649 use cell arrays to store multiple strings. If, however, the character | |
| 650 matrix representation is required for an operation, it can be converted | |
| 651 to a cell array of strings using the @code{cellstr} function | |
| 652 | |
| 653 @example | |
| 654 a = ["hello"; "world"]; | |
| 655 c = cellstr (a) | |
| 656 @result{} c = | |
| 657 @{ | |
| 658 [1,1] = hello | |
| 659 [2,1] = world | |
| 660 @} | |
| 661 @end example | |
| 662 | |
| 8828 | 663 One further advantage of using cell arrays to store multiple strings is |
| 6837 | 664 that most functions for string manipulations included with Octave |
| 6939 | 665 support this representation. As an example, it is possible to compare |
| 6837 | 666 one string with many others using the @code{strcmp} function. If one of |
| 667 the arguments to this function is a string and the other is a cell array | |
| 668 of strings, each element of the cell array will be compared the string | |
| 669 argument, | |
| 670 | |
| 671 @example | |
| 672 c = @{"hello", "world"@}; | |
| 673 strcmp ("hello", c) | |
| 674 @result{} ans = | |
| 675 1 0 | |
| 676 @end example | |
| 677 | |
| 678 @noindent | |
| 679 The following functions for string manipulation support cell arrays of | |
| 680 strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, | |
|
8372
8dff9cba15fe
move str2mat to deprecated and make it a simple wrapper around char
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8347
diff
changeset
|
681 @code{str2double}, @code{char}, @code{strappend}, @code{strtrunc}, |
| 6837 | 682 @code{strvcat}, @code{strfind}, and @code{strmatch}. |
| 683 | |
| 684 @DOCSTRING(cellstr) | |
| 685 | |
| 686 @DOCSTRING(iscellstr) | |
| 687 | |
| 688 @DOCSTRING(cellidx) | |
| 689 | |
| 690 @node Processing Data in Cell Arrays | |
| 691 @subsection Processing Data in Cell Arrays | |
| 692 | |
| 693 Data that is stored in a cell array can be processed in several ways | |
| 8828 | 694 depending on the actual data. The simplest way to process that data |
| 6837 | 695 is to iterate through it using one or more @code{for} loops. The same |
| 8828 | 696 idea can be implemented more easily through the use of the @code{cellfun} |
|
8493
2f5a2c58c15e
[docs] user specified => user-specified
Brian Gough <bjg@gnu.org>
parents:
8372
diff
changeset
|
697 function that calls a user-specified function on all elements of a cell |
| 6837 | 698 array. |
| 699 | |
| 700 @DOCSTRING(cellfun) | |
| 701 | |
| 702 An alternative is to convert the data to a different container, such as | |
| 703 a matrix or a data structure. Depending on the data this is possible | |
| 704 using the @code{cell2mat} and @code{cell2struct} functions. | |
| 705 | |
| 706 @DOCSTRING(cell2mat) | |
| 707 | |
| 708 @DOCSTRING(cell2struct) | |
| 709 | |
| 710 @node Comma Separated Lists | |
| 711 @section Comma Separated Lists | |
| 712 @cindex comma separated lists | |
|
8541
d2cf983bdc9d
container.txi: define cs-list
John W. Eaton <jwe@octave.org>
parents:
8493
diff
changeset
|
713 @cindex cs-lists |
| 6837 | 714 |
|
8541
d2cf983bdc9d
container.txi: define cs-list
John W. Eaton <jwe@octave.org>
parents:
8493
diff
changeset
|
715 Comma separated lists@footnote{Comma-separated lists are also sometimes |
|
d2cf983bdc9d
container.txi: define cs-list
John W. Eaton <jwe@octave.org>
parents:
8493
diff
changeset
|
716 informally referred to as @dfn{cs-lists}.} are the basic argument type |
|
d2cf983bdc9d
container.txi: define cs-list
John W. Eaton <jwe@octave.org>
parents:
8493
diff
changeset
|
717 to all Octave functions. In the example |
| 6837 | 718 |
| 719 @example | |
| 720 max (@var{a}, @var{b}) | |
| 721 @end example | |
| 722 | |
| 723 @noindent | |
| 7001 | 724 @code{@var{a}, @var{b}} is a comma separated list. Comma separated lists |
| 6837 | 725 can appear on both the right and left hand side of an equation. For |
| 726 example | |
| 727 | |
| 728 @example | |
| 7031 | 729 [@var{i}, @var{j}] = ceil (find (@var{x}, [], "last")); |
| 6837 | 730 @end example |
| 731 | |
| 732 @noindent | |
| 733 where @code{@var{i}, @var{j}} is equally a comma separated list. Comma | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8176
diff
changeset
|
734 separated lists cannot be directly manipulated by the user. However, |
|
8094
5bc08f9758e6
typo in comma separated lists chapter
Thomas Weber <thomas.weber.mail@gmail.com>
parents:
7031
diff
changeset
|
735 both structures and cell arrays can be converted into comma |
| 6837 | 736 separated lists, which makes them useful to keep the input arguments and |
| 737 return values of functions organized. Another example of where a comma | |
| 738 separated list can be used is in the creation of a new array. If all the | |
| 739 accessed elements of a cell array are scalars or column vectors, they | |
| 740 can be concatenated into a new column vector containing the elements, by | |
| 741 surrounding the list with @code{[} and @code{]} as in the following | |
| 742 example | |
| 6514 | 743 |
| 744 @example | |
| 745 a = @{1, [2, 3], 4@}; | |
| 746 b = [a@{:@}] | |
| 747 @result{} b = | |
| 748 1 2 3 4 | |
| 749 @end example | |
| 750 | |
| 6518 | 751 It is also possible to pass the accessed elements directly to a |
| 752 function. The list of elements from the cell array will be passed as an | |
| 753 argument list to a given function as if it is called with the elements as | |
| 754 arguments. The two calls to @code{printf} in the following example are | |
| 7001 | 755 identical but the latter is simpler and handles more situations |
| 6518 | 756 |
| 757 @example | |
| 758 c = @{"GNU", "Octave", "is", "Free", "Software"@}; | |
| 759 printf ("%s ", c@{1@}, c@{2@}, c@{3@}, c@{4@}, c@{5@}); | |
| 760 @print{} GNU Octave is Free Software | |
| 761 printf ("%s ", c@{:@}); | |
| 762 @print{} GNU Octave is Free Software | |
| 763 @end example | |
| 764 | |
| 765 Just like it is possible to create a numerical array from selected | |
| 766 elements of a cell array, it is possible to create a new cell array | |
| 767 containing the selected elements. By surrounding the list with | |
| 8828 | 768 @samp{@{} and @samp{@}} a new cell array will be created, as the |
| 6518 | 769 following example illustrates |
| 6514 | 770 |
| 771 @example | |
| 772 a = @{1, rand(2, 2), "three"@}; | |
| 773 b = @{ a@{ [1, 3] @} @} | |
| 774 @result{} b = | |
| 775 @{ | |
| 776 [1,1] = 1 | |
| 777 [1,2] = three | |
| 778 @} | |
| 779 @end example | |
| 780 | |
| 6518 | 781 @noindent |
| 782 This syntax is however a bit cumbersome, and since this is a common | |
| 783 operation, it is possible to achieve the same using the @samp{(} | |
| 784 and @samp{)} operators for indexing. When a cell array is indexed | |
| 785 using the @samp{(} and @samp{)} operators a new cell array containing | |
|
8176
c9d6071b9696
uncomplete sentence in documentation text
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8135
diff
changeset
|
786 the selected elements will be created. Using this syntax, the previous |
|
c9d6071b9696
uncomplete sentence in documentation text
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8135
diff
changeset
|
787 example can be simplified into the following |
| 6514 | 788 |
| 789 @example | |
| 6518 | 790 a = @{1, rand(2, 2), "three"@}; |
| 791 b = a( [1, 3] ) | |
| 792 @result{} b = | |
| 793 @{ | |
| 794 [1,1] = 1 | |
| 795 [1,2] = three | |
| 796 @} | |
| 6514 | 797 @end example |
| 798 | |
| 6837 | 799 A comma separated list can equally appear on the left-hand side of an |
| 800 assignment. An example is | |
| 6514 | 801 |
| 802 @example | |
| 6837 | 803 @group |
| 804 in @{1@} = ceil (rand (10, 1)); | |
| 805 in @{2@} = []; | |
| 7031 | 806 in @{3@} = "last"; |
| 807 in @{4@} = "first"; | |
| 6837 | 808 out = cell (4, 1); |
| 809 [out@{1:2@}] = find (in@{1 : 3@}); | |
| 810 [out@{3:4@}] = find (in@{[1, 2, 4]@}); | |
| 811 @end group | |
| 6514 | 812 @end example |
| 813 | |
| 6939 | 814 Structure arrays can equally be used to create comma separated |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8176
diff
changeset
|
815 lists. This is done by addressing one of the fields of a structure |
| 6837 | 816 array. For example |
| 6514 | 817 |
| 6837 | 818 @example |
| 819 @group | |
| 820 x = ceil (randn (10, 1)); | |
| 7031 | 821 in = struct ("call1", @{x, Inf, "last"@}, |
| 822 "call2", @{x, Inf, "first"@}); | |
| 823 out = struct ("call1", cell (2, 1), "call2", cell (2, 1)); | |
| 6837 | 824 [out.call1] = find (in.call1); |
| 825 [out.call2] = find (in.call2); | |
| 826 @end group | |
| 827 @end example |