Mercurial > hg > octave-avbm
changeset 6837:7eefeed173ea
[project @ 2007-08-27 20:20:55 by dbateman]
author | dbateman |
---|---|
date | Mon, 27 Aug 2007 20:20:55 +0000 |
parents | ea6ae3af82d1 |
children | 5e3350bdd91d |
files | doc/ChangeLog doc/interpreter/container.txi doc/interpreter/octave.texi doc/interpreter/struct.txi |
diffstat | 4 files changed, 567 insertions(+), 290 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,13 @@ +2007-08-27 David Bateman <dbateman@free.fr> + + * interpreter/struct.txi: Remove. + * interpreter/containers.txi: Combine with this chapter. Add + examples, and section on comma separated lists. Document the + difference between "c(1,:) = []" and c{1,:} = []" for a cell + arrays. + * interpreter/octave.texi: Document new indexing of containers + section. + 2007-08-25 David Bateman <dbateman@free.fr> * interpreter/geometry.txi: Add examples and explanatory text.
--- a/doc/interpreter/container.txi +++ b/doc/interpreter/container.txi @@ -2,9 +2,405 @@ @c This is part of the Octave manual. @c For copying conditions, see the file gpl.texi. +@node Data Containers +@chapter Data Containers +@cindex containers + +Octave includes support for two different mechanaisms to contain +arbitrary data types in the same variable. Structures, which are C-like, +and are indexed with named fields, and cell arrays, where each element +of the array can have a different data type and or shape. + +@menu +* Data Structures:: +* Cell Arrays:: +* Comma Separated Lists:: +@end menu + +@node Data Structures +@section Data Structures +@cindex structures +@cindex data structures + +Octave includes support for organizing data in structures. The current +implementation uses an associative array with indices limited to +strings, but the syntax is more like C-style structures. Here are some +examples of using data structures in Octave. + +Elements of structures can be of any value type. For example, the three +expressions + +@example +@group +x.a = 1 +x.b = [1, 2; 3, 4] +x.c = "string" +@end group +@end example + +@noindent +create a structure with three elements. To print the value of the +structure, you can type its name, just as for any other variable: + +@example +@group +octave:2> x +x = +@{ + a = 1 + b = + + 1 2 + 3 4 + + c = string +@} +@end group +@end example + +@noindent +Note that Octave may print the elements in any order. + +Structures may be copied. + +@example +@group +octave:1> y = x +y = +@{ + a = 1 + b = + + 1 2 + 3 4 + + c = string +@} +@end group +@end example + +Since structures are themselves values, structure elements may reference +other structures. The following statements change the value of the +element @code{b} of the structure @code{x} to be a data structure +containing the single element @code{d}, which has a value of 3. + +@example +@group +octave:1> x.b.d = 3 +x.b.d = 3 +octave:2> x.b +ans = +@{ + d = 3 +@} +octave:3> x +x = +@{ + a = 1 + b = + @{ + d = 3 + @} + + c = string +@} +@end group +@end example + +Note that when Octave prints the value of a structure that contains +other structures, only a few levels are displayed. For example, + +@example +@group +octave:1> a.b.c.d.e = 1; +octave:2> a +a = +@{ + b = + @{ + c = + @{ + d: 1x1 struct + @} + @} +@} +@end group +@end example + +@noindent +This prevents long and confusing output from large deeply nested +structures. + +@DOCSTRING(struct_levels_to_print) + +Functions can return structures. For example, the following function +separates the real and complex parts of a matrix and stores them in two +elements of the same structure variable. + +@example +@group +octave:1> function y = f (x) +> y.re = real (x); +> y.im = imag (x); +> endfunction +@end group +@end example + +When called with a complex-valued argument, @code{f} returns the data +structure containing the real and imaginary parts of the original +function argument. + +@example +@group +octave:2> f (rand (2) + rand (2) * I) +ans = +@{ + im = + + 0.26475 0.14828 + 0.18436 0.83669 + + re = + + 0.040239 0.242160 + 0.238081 0.402523 +@} +@end group +@end example + +Function return lists can include structure elements, and they may be +indexed like any other variable. For example, + +@example +@group +octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) +x.u = + + -0.40455 -0.91451 + -0.91451 0.40455 + +x.s = + + 0.00000 0.00000 0.00000 + 0.00000 5.46499 0.00000 + 0.00000 0.00000 0.36597 + +x.v = + + -0.57605 0.81742 + -0.81742 -0.57605 +@end group +@end example + +It is also possible to cycle through all the elements of a structure in +a loop, using a special form of the @code{for} statement +(@pxref{The for Statement}) + +@menu +* Structure Arrays:: +* Creating Structures:: +* Manipulating Structures:: +@end menu + +@node Structure Arrays +@subsection Structure Arrays + +A structure array is a particular instance of a structure, where each of +the fields of the structure is represented by a cell array. Each of +these cell arrays has the same dimensions. An example of the creation of +a structure array is + +@example +@group +x(1).a = "string1" +x(2).a = "string2" +x(1).b = 1 +x(2).b = 2 +@end group +@end example + +@noindent +which creates a 2-by-1 structure array with two fields. As previously, +to print the value of the structure array, you can type its name: + +@example +@group +octave:2> x +x = +@{ + a = + + (, + [1] = string1 + [2] = string2 + ,) + + b = + + (, + [1] = 1 + [2] = 2 + ,) + +@} +@end group +@end example + +Individual elements of the structure array can be returned by indexing +the variable like @code{@var{x} (1)}, which returns a structure with the +two fields like + +@example +@group +octave:2> x(1) +ans = +@{ + a = string1 + b = 1 +@} +@end group +@end example + +Furthermore, the structure array can return a comma seperated list +(@pxref{Comma Separated Lists}), if indexed by one of itself field +names. For example + +@example +@group +octave:3> x.a +ans = + +(, + [1] = string1 + [2] = string2 +,) +@end group +@end example + +The function @code{size} with return the size of the structure. For +the example above + +@example +@group +octave:4> size(x) +ans = + + 1 2 +@end group +@end example + +Elements can be deleted from a structure array in a similar manner to a +numerial array, by assignment the elements to an empty matrix. For +example + +@example +@group +in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@}); +in (1, :) = [] +@result{} in = + { + call1 = + + (, + [1] = Inf + [2] = last + ,) + + call2 = + + (, + [1] = Inf + [2] = first + ,) + + } +@end group +@end example + +@node Creating Structures +@subsection Creating Structures + +As well as indexing a structure with ".", Octave can create a structure +with the @code{struct} command. @code{struct} takes pairs of arguments, +where the first argument in the pair is the fieldname to include in the +structure and the second is a scalar or cell array, representing the +values to include in the structure or structure array. For example + +@example +@group +struct ('field1', 1, 'field2', 2) +@result{} ans = + @{ + field1 = 1 + field2 = 2 + @} +@end group +@end example + +If the values passed to @code{struct} are a mix of scalar and cell +arrays, then the scalar arguments are expanded to create a +structure array with a consistent dimension. For example + +@example +@group +struct ('field1', @{1, 'one'@}, 'field2', @{2, 'two'@}, 'field3', 3); +@result{} ans = + @{ + field1 = + + (, + [1] = 1 + [2] = one + ,) + + field2 = + + (, + [1] = 2 + [2] = two + ,) + + field3 = + + (, + [1] = 3 + [2] = 3 + ,) + + @} +@end group +@end example + +@DOCSTRING(struct) + +@DOCSTRING(isstruct) + +Additional functions that can manipulate the fields of a structure are +listed below. + +@DOCSTRING(rmfield) + +@DOCSTRING(setfield) + +@DOCSTRING(orderfields) + +@node Manipulating Structures +@subsection Manipulating Structures + +Other functions that can manipulate the fields of a structure are given below. + +@DOCSTRING(fieldnames) + +@DOCSTRING(isfield) + +@DOCSTRING(getfield) + +@DOCSTRING(struct2cell) + +@DOCSTRING(substruct) + @node Cell Arrays -@chapter Cell Arrays -@cindex containers +@section Cell Arrays @cindex cell arrays It can be both necessary and convenient to store several variables of @@ -80,7 +476,7 @@ @end menu @node Creating Cell Arrays -@section Creating Cell Array +@subsection Creating Cell Array The introductory example showed how to create a cell array containing currently available variables. In many situations, however, it is useful @@ -138,7 +534,7 @@ @DOCSTRING(mat2cell) @node Indexing Cell Arrays -@section Indexing Cell Arrays +@subsection Indexing Cell Arrays As shown in the introductory example elements can be inserted from cell arrays using the @samp{@{} and @samp{@}} operators. Besides the change @@ -164,14 +560,135 @@ with a single variable as is the case with numerical arrays. Accessing multiple elements of a cell array with the @samp{@{} and -@samp{@}} operators will result in a comma-separated list of all -the requested elements. This list can then be used anywhere where a -comma-separated list is used, such as in the creation of a new -numerical array or cell array, or be passed as arguments to a -function. If all the accessed elements of a cell array are scalars or -column vectors, they can be concatenated into a new column vector -containing the elements, by surrounding the list with @code{[} and -@code{]} as in the following example +@samp{@}} operators will result in a comma-separated list (@pxref{Comma +Separated Lists}) of all the requested elements as discussed later. + +One distinction between @samp{@{} and @samp{(} to index cell arrays is +in the deletion of elements from the cell array. In a similar manner to +a numerical array the @samp{()} operator can be used to delete elements +from the cell array. The @samp{@{@}} operator however will remove the +elements of the cell array, but not delete the space for them. For example + +@example +@group +x = {'1', '2'; '3', '4'}; +x{1, :} = [] +@result x = + { + [1,1] = [](0x0) + [2,1] = 3 + [1,2] = [](0x0) + [2,2] = 4 + } + +x(1, :) = [] +@result {} x = + { + [1,1] = 3 + [1,2] = 4 + } +@end group +@end example + +@node Cell Arrays of Strings +@subsection Cell Arrays of Strings + +One common use of cell arrays is to store multiple strings in the same +variable. It is possible to store multiple strings in a character matrix +by letting each row be a string. This, however, introduces the problem +that all strings must be of equal length. Therefore it is recommended to +use cell arrays to store multiple strings. If, however, the character +matrix representation is required for an operation, it can be converted +to a cell array of strings using the @code{cellstr} function + +@example +a = ["hello"; "world"]; +c = cellstr (a) + @result{} c = + @{ + [1,1] = hello + [2,1] = world + @} +@end example + +One further advantage of using cell arrays to store multiple strings, is +that most functions for string manipulations included with Octave +supports this representation. As an example, it is possible to compare +one string with many others using the @code{strcmp} function. If one of +the arguments to this function is a string and the other is a cell array +of strings, each element of the cell array will be compared the string +argument, + +@example +c = @{"hello", "world"@}; +strcmp ("hello", c) + @result{} ans = + 1 0 +@end example + +@noindent +The following functions for string manipulation support cell arrays of +strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, +@code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc}, +@code{strvcat}, @code{strfind}, and @code{strmatch}. + +@DOCSTRING(cellstr) + +@DOCSTRING(iscellstr) + +@DOCSTRING(cellidx) + +@node Processing Data in Cell Arrays +@subsection Processing Data in Cell Arrays + +Data that is stored in a cell array can be processed in several ways +depending on the actual data. The most simple way to process that data +is to iterate through it using one or more @code{for} loops. The same +idea can be implemented easier through the use of the @code{cellfun} +function that calls a user specified function on all elements of a cell +array. + +@DOCSTRING(cellfun) + +An alternative is to convert the data to a different container, such as +a matrix or a data structure. Depending on the data this is possible +using the @code{cell2mat} and @code{cell2struct} functions. + +@DOCSTRING(cell2mat) + +@DOCSTRING(cell2struct) + +@node Comma Separated Lists +@section Comma Separated Lists +@cindex comma separated lists + +Comma separated lists are the basic argument type to all Octave +functions. In the example + +@example +max (@var{a}, @var{b}) +@end example + +@noindent +@code{@var{a}, @var{b}} is a somma separated list. Comma separated lists +can appear on both the right and left hand side of an equation. For +example + +@example +[@var{i}, @var{j}] = ceil (find (@var{x}, [], 'last')); +@end example + +@noindent +where @code{@var{i}, @var{j}} is equally a comma separated list. Comma +separated lists can not be directly manipulated by the user. However, +both structures are cell arrays can be converted into into comma +separated lists, which makes them useful to keep the input arguments and +return values of functions organized. Another example of where a comma +separated list can be used is in the creation of a new array. If all the +accessed elements of a cell array are scalars or column vectors, they +can be concatenated into a new column vector containing the elements, by +surrounding the list with @code{[} and @code{]} as in the following +example @example a = @{1, [2, 3], 4@}; @@ -228,70 +745,31 @@ @} @end example -@node Cell Arrays of Strings -@section Cell Arrays of Strings - -One common use of cell arrays is to store multiple strings in the same -variable. It is possible to store multiple strings in a character matrix -by letting each row be a string. This, however, introduces the problem -that all strings must be of equal length. Therefore it is recommended to -use cell arrays to store multiple strings. If, however, the character -matrix representation is required for an operation, it can be converted -to a cell array of strings using the @code{cellstr} function - -@example -a = ["hello"; "world"]; -c = cellstr (a) - @result{} c = - @{ - [1,1] = hello - [2,1] = world - @} -@end example - -One further advantage of using cell arrays to store multiple strings, is -that most functions for string manipulations included with Octave -supports this representation. As an example, it is possible to compare -one string with many others using the @code{strcmp} function. If one of -the arguments to this function is a string and the other is a cell array -of strings, each element of the cell array will be compared the string -argument, +A comma separated list can equally appear on the left-hand side of an +assignment. An example is @example -c = @{"hello", "world"@}; -strcmp ("hello", c) - @result{} ans = - 1 0 +@group +in @{1@} = ceil (rand (10, 1)); +in @{2@} = []; +in @{3@} = 'last'; +in @{4@} = 'first'; +out = cell (4, 1); +[out@{1:2@}] = find (in@{1 : 3@}); +[out@{3:4@}] = find (in@{[1, 2, 4]@}); +@end group @end example -@noindent -The following functions for string manipulation support cell arrays of -strings, @code{strcmp}, @code{strcmpi}, @code{strncmp}, @code{strncmpi}, -@code{str2double}, @code{str2mat}, @code{strappend}, @code{strtrunc}, -@code{strvcat}, @code{strfind}, and @code{strmatch}. - -@DOCSTRING(cellstr) - -@DOCSTRING(iscellstr) - -@DOCSTRING(cellidx) - -@node Processing Data in Cell Arrays -@section Processing Data in Cell Arrays +Structures arrays can equally be used to create comma separated +lists. This is done by addresses one of the fields of a structure +array. For example -Data that is stored in a cell array can be processed in several ways -depending on the actual data. The most simple way to process that data -is to iterate through it using one or more @code{for} loops. The same -idea can be implemented easier through the use of the @code{cellfun} -function that calls a user specified function on all elements of a cell -array. - -@DOCSTRING(cellfun) - -An alternative is to convert the data to a different container, such as -a matrix or a data structure. Depending on the data this is possible -using the @code{cell2mat} and @code{cell2struct} functions. - -@DOCSTRING(cell2mat) - -@DOCSTRING(cell2struct) +@example +@group +x = ceil (randn (10, 1)); +in = struct ('call1', @{x, Inf, 'last'@}, 'call2', @{x, Inf, 'first'@}); +out = struct ('call1', cell (2, 1), 'call2', cell (2, 1)); +[out.call1] = find (in.call1); +[out.call2] = find (in.call2); +@end group +@end example
--- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -132,8 +132,7 @@ * Data Types:: * Numeric Data Types:: * Strings:: -* Data Structures:: -* Cell Arrays:: +* Data Containers:: * Variables:: * Expressions:: Expressions. * Evaluation:: @@ -265,12 +264,11 @@ * String Conversions:: * Character Class Functions:: -Cell Arrays +Data Containers -* Creating Cell Arrays:: -* Indexing Cell Arrays:: -* Cell Arrays of Strings:: -* Processing Data in Cell Arrays:: +* Data Structures:: +* Cell Arrays:: +* Comma Separated Lists:: Variables @@ -580,7 +578,6 @@ @include data.texi @include numbers.texi @include strings.texi -@include struct.texi @include container.texi @include var.texi @include expr.texi
deleted file mode 100644 --- a/doc/interpreter/struct.txi +++ /dev/null @@ -1,208 +0,0 @@ -@c Copyright (C) 1996, 1997, 2007 John W. Eaton -@c This is part of the Octave manual. -@c For copying conditions, see the file gpl.texi. - -@c FIXME update for structure arrays -@c FIXME need discussion of comma-separated lists somewhere - -@node Data Structures -@chapter Data Structures -@cindex structures -@cindex data structures - -Octave includes support for organizing data in structures. The current -implementation uses an associative array with indices limited to -strings, but the syntax is more like C-style structures. Here are some -examples of using data structures in Octave. - -Elements of structures can be of any value type. For example, the three -expressions - -@example -@group -x.a = 1 -x.b = [1, 2; 3, 4] -x.c = "string" -@end group -@end example - -@noindent -create a structure with three elements. To print the value of the -structure, you can type its name, just as for any other variable: - -@example -@group -octave:2> x -x = -@{ - a = 1 - b = - - 1 2 - 3 4 - - c = string -@} -@end group -@end example - -@noindent -Note that Octave may print the elements in any order. - -Structures may be copied. - -@example -@group -octave:1> y = x -y = -@{ - a = 1 - b = - - 1 2 - 3 4 - - c = string -@} -@end group -@end example - -Since structures are themselves values, structure elements may reference -other structures. The following statements change the value of the -element @code{b} of the structure @code{x} to be a data structure -containing the single element @code{d}, which has a value of 3. - -@example -@group -octave:1> x.b.d = 3 -x.b.d = 3 -octave:2> x.b -ans = -@{ - d = 3 -@} -octave:3> x -x = -@{ - a = 1 - b = - @{ - d = 3 - @} - - c = string -@} -@end group -@end example - -Note that when Octave prints the value of a structure that contains -other structures, only a few levels are displayed. For example, - -@example -@group -octave:1> a.b.c.d.e = 1; -octave:2> a -a = -@{ - b = - @{ - c = - @{ - d: 1x1 struct - @} - @} -@} -@end group -@end example - -@noindent -This prevents long and confusing output from large deeply nested -structures. - -@DOCSTRING(struct_levels_to_print) - -Functions can return structures. For example, the following function -separates the real and complex parts of a matrix and stores them in two -elements of the same structure variable. - -@example -@group -octave:1> function y = f (x) -> y.re = real (x); -> y.im = imag (x); -> endfunction -@end group -@end example - -When called with a complex-valued argument, @code{f} returns the data -structure containing the real and imaginary parts of the original -function argument. - -@example -@group -octave:2> f (rand (2) + rand (2) * I) -ans = -@{ - im = - - 0.26475 0.14828 - 0.18436 0.83669 - - re = - - 0.040239 0.242160 - 0.238081 0.402523 -@} -@end group -@end example - -Function return lists can include structure elements, and they may be -indexed like any other variable. For example, - -@example -@group -octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) -x.u = - - -0.40455 -0.91451 - -0.91451 0.40455 - -x.s = - - 0.00000 0.00000 0.00000 - 0.00000 5.46499 0.00000 - 0.00000 0.00000 0.36597 - -x.v = - - -0.57605 0.81742 - -0.81742 -0.57605 -@end group -@end example - -It is also possible to cycle through all the elements of a structure in -a loop, using a special form of the @code{for} statement -(@pxref{The for Statement}) - -The following functions are available to give you information about -structures. - -@DOCSTRING(struct) - -@DOCSTRING(isstruct) - -@DOCSTRING(fieldnames) - -@DOCSTRING(isfield) - -@DOCSTRING(getfield) - -@DOCSTRING(orderfields) - -@DOCSTRING(rmfield) - -@DOCSTRING(setfield) - -@DOCSTRING(struct2cell) - -@DOCSTRING(substruct)