changeset 12596:5161d02c96b7 stable

doc: Add help text for dynamic naming "(var)" of structure fields. * container.txi: Add help text. Rename "Data Structures" to just "Structures" * octave.texi: Rename "Data Structures" to just "Structures"
author Rik <octave@nomad.inbox5.com>
date Tue, 12 Apr 2011 13:48:07 -0700
parents 68eb9713b550
children e12a7c0a1fc5
files doc/interpreter/container.txi doc/interpreter/octave.texi
diffstat 2 files changed, 49 insertions(+), 11 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/container.txi	Tue Apr 12 09:56:13 2011 -0700
+++ b/doc/interpreter/container.txi	Tue Apr 12 13:48:07 2011 -0700
@@ -28,13 +28,13 @@
 another data container, the comma separated list.
 
 @menu
-* Data Structures::
+* Structures::
 * Cell Arrays::
 * Comma Separated Lists::
 @end menu
 
-@node Data Structures
-@section Data Structures
+@node Structures
+@section Structures
 @cindex structures
 @cindex data structures
 
@@ -370,12 +370,50 @@
 
 @node Creating Structures
 @subsection Creating Structures
+@cindex dynamic naming
 
-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:
+Besides the index operator ".", Octave can use dynamic naming "(var)" or the
+@code{struct} function to create structures.  Dynamic naming uses the string
+value of a variable as the field name.  For example,
+@example
+@group
+a = "field2";
+x.a = 1;
+x.(a) = 2;
+x
+     @result{} x =
+        @{
+          a =  1
+          field2 =  2
+        @}
+@end group
+@end example
+
+More realistically, all of the functions that operate on strings can be used
+to build the correct field name before it is entered into the data structure.
+
+@example
+@group
+names = ["Bill"; "Mary"; "John"];
+ages  = [37; 26; 31];
+for i = 1:rows (names)
+  database.(names(i,:)) = ages(i);
+endfor
+database
+     @result{} database =
+        @{
+          Bill =  37
+          Mary =  26
+          John =  31
+        @}
+@end group
+@end example
+
+The third way to create structures is 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
@@ -414,7 +452,7 @@
 @end example
 
 If you want to create a struct which contains a cell array as an
-individual field, you have to put it into another cell array like in
+individual field, you must wrap it in another cell array as shown in
 the following example:
 
 @example
--- a/doc/interpreter/octave.texi	Tue Apr 12 09:56:13 2011 -0700
+++ b/doc/interpreter/octave.texi	Tue Apr 12 13:48:07 2011 -0700
@@ -326,11 +326,11 @@
 
 Data Containers
 
-* Data Structures::
+* Structures::
 * Cell Arrays::
 * Comma Separated Lists::
 
-Data Structures
+Structures
 
 * Basic Usage and Examples::
 * Structure Arrays::