Mercurial > octave

comparison doc/interpreter/container.txi @ 31788:b482ed13ac1a stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Use hyphen in "comma-separated list". * container.txi, octave.texi, graphics.cc, deal.m, importdata.m, test.m: Use hyphen in "comma-separated list".
author Rik <rik@octave.org>
date Fri, 27 Jan 2023 14:27:10 -0800
parents 597f3ee61a48
children a4506463f341
comparison
equal deleted inserted replaced
31786:4ccdb13c160a 31788:b482ed13ac1a
23 Octave includes support for three different mechanisms to contain arbitrary 23 Octave includes support for three different mechanisms to contain arbitrary
24 data types in the same variable: Structures, which are C-like, and are indexed 24 data types in the same variable: Structures, which are C-like, and are indexed
25 with named fields; containers.Map objects, which store data in key/value pairs; 25 with named fields; containers.Map objects, which store data in key/value pairs;
26 and cell arrays, where each element of the array can have a different data type 26 and cell arrays, where each element of the array can have a different data type
27 and or shape. Multiple input arguments and return values of functions are 27 and or shape. Multiple input arguments and return values of functions are
28 organized as another data container, the comma separated list. 28 organized as another data container, the comma-separated list.
29 29
30 @menu 30 @menu
31 * Structures:: 31 * Structures::
32 * containers.Map:: 32 * containers.Map::
33 * Cell Arrays:: 33 * Cell Arrays::
34 * Comma Separated Lists:: 34 * Comma-Separated Lists::
35 @end menu 35 @end menu
36 36
37 @node Structures 37 @node Structures
38 @section Structures 38 @section Structures
39 @cindex structures 39 @cindex structures
298 b = 1 298 b = 1
299 @} 299 @}
300 @end group 300 @end group
301 @end example 301 @end example
302 302
303 Furthermore, the structure array can return a comma separated list of 303 Furthermore, the structure array can return a comma-separated list of
304 field values (@pxref{Comma Separated Lists}), if indexed by one of its 304 field values (@pxref{Comma-Separated Lists}), if indexed by one of its
305 own field names. For example: 305 own field names. For example:
306 306
307 @example 307 @example
308 @group 308 @group
309 x.a 309 x.a
311 ans = string1 311 ans = string1
312 ans = string2 312 ans = string2
313 @end group 313 @end group
314 @end example 314 @end example
315 315
316 Here is another example, using this comma separated list on the 316 Here is another example, using this comma-separated list on the
317 left-hand side of an assignment: 317 left-hand side of an assignment:
318 318
319 @example 319 @example
320 @group 320 @group
321 [x.a] = deal ("new string1", "new string2"); 321 [x.a] = deal ("new string1", "new string2");
804 @end group 804 @end group
805 @end example 805 @end example
806 806
807 Accessing multiple elements of a cell array with the @samp{@{} and 807 Accessing multiple elements of a cell array with the @samp{@{} and
808 @samp{@}} operators will result in a comma-separated list of all the 808 @samp{@}} operators will result in a comma-separated list of all the
809 requested elements (@pxref{Comma Separated Lists}). Using the 809 requested elements (@pxref{Comma-Separated Lists}). Using the
810 @samp{@{} and @samp{@}} operators the first two rows in the above 810 @samp{@{} and @samp{@}} operators the first two rows in the above
811 example can be swapped back like this: 811 example can be swapped back like this:
812 812
813 @example 813 @example
814 @group 814 @group
941 941
942 @DOCSTRING(cell2mat) 942 @DOCSTRING(cell2mat)
943 943
944 @DOCSTRING(cell2struct) 944 @DOCSTRING(cell2struct)
945 945
946 @node Comma Separated Lists 946 @node Comma-Separated Lists
947 @section Comma Separated Lists 947 @section Comma-Separated Lists
948 @cindex comma separated lists 948 @cindex comma-separated lists
949 @cindex cs-lists 949 @cindex cs-lists
950 950
951 Comma separated lists @footnote{Comma-separated lists are also sometimes 951 Comma-separated lists @footnote{Comma-separated lists are also sometimes
952 informally referred to as @dfn{cs-lists}.} are the basic argument type 952 informally referred to as @dfn{cs-lists}.} are the basic argument type
953 to all Octave functions - both for input and return arguments. In the 953 to all Octave functions - both for input and return arguments. In the
954 example 954 example
955 955
956 @example 956 @example
957 max (@var{a}, @var{b}) 957 max (@var{a}, @var{b})
958 @end example 958 @end example
959 959
960 @noindent 960 @noindent
961 @samp{@var{a}, @var{b}} is a comma separated list. Comma separated lists 961 @samp{@var{a}, @var{b}} is a comma-separated list. Comma-separated lists
962 can appear on both the right and left hand side of an assignment. For 962 can appear on both the right and left hand side of an assignment. For
963 example 963 example
964 964
965 @example 965 @example
966 @group 966 @group
968 [@var{i}, @var{j}] = find (@var{x}, 2, "last"); 968 [@var{i}, @var{j}] = find (@var{x}, 2, "last");
969 @end group 969 @end group
970 @end example 970 @end example
971 971
972 @noindent 972 @noindent
973 Here, @samp{@var{x}, 2, "last"} is a comma separated list constituting 973 Here, @samp{@var{x}, 2, "last"} is a comma-separated list constituting
974 the input arguments of @code{find}. @code{find} returns a comma 974 the input arguments of @code{find}. @code{find} returns a comma
975 separated list of output arguments which is assigned element by 975 separated list of output arguments which is assigned element by
976 element to the comma separated list @samp{@var{i}, @var{j}}. 976 element to the comma-separated list @samp{@var{i}, @var{j}}.
977 977
978 Another example of where comma separated lists are used is in the 978 Another example of where comma-separated lists are used is in the
979 creation of a new array with @code{[]} (@pxref{Matrices}) or the 979 creation of a new array with @code{[]} (@pxref{Matrices}) or the
980 creation of a cell array with @code{@{@}} (@pxref{Basic Usage of Cell 980 creation of a cell array with @code{@{@}} (@pxref{Basic Usage of Cell
981 Arrays}). In the expressions 981 Arrays}). In the expressions
982 982
983 @example 983 @example
986 c = @{4, 5, 6, 7@}; 986 c = @{4, 5, 6, 7@};
987 @end group 987 @end group
988 @end example 988 @end example
989 989
990 @noindent 990 @noindent
991 both @samp{1, 2, 3, 4} and @samp{4, 5, 6, 7} are comma separated lists. 991 both @samp{1, 2, 3, 4} and @samp{4, 5, 6, 7} are comma-separated lists.
992 992
993 Comma separated lists cannot be directly manipulated by the 993 Comma-separated lists cannot be directly manipulated by the
994 user. However, both structure arrays and cell arrays can be converted 994 user. However, both structure arrays and cell arrays can be converted
995 into comma separated lists, and thus used in place of explicitly 995 into comma-separated lists, and thus used in place of explicitly
996 written comma separated lists. This feature is useful in many ways, 996 written comma-separated lists. This feature is useful in many ways,
997 as will be shown in the following subsections. 997 as will be shown in the following subsections.
998 998
999 @menu 999 @menu
1000 * Comma Separated Lists Generated from Cell Arrays:: 1000 * Comma-Separated Lists Generated from Cell Arrays::
1001 * Comma Separated Lists Generated from Structure Arrays:: 1001 * Comma-Separated Lists Generated from Structure Arrays::
1002 @end menu 1002 @end menu
1003 1003
1004 @node Comma Separated Lists Generated from Cell Arrays 1004 @node Comma-Separated Lists Generated from Cell Arrays
1005 @subsection Comma Separated Lists Generated from Cell Arrays 1005 @subsection Comma-Separated Lists Generated from Cell Arrays
1006 1006
1007 As has been mentioned above (@pxref{Indexing Cell Arrays}), elements 1007 As has been mentioned above (@pxref{Indexing Cell Arrays}), elements
1008 of a cell array can be extracted into a comma separated list with the 1008 of a cell array can be extracted into a comma-separated list with the
1009 @code{@{} and @code{@}} operators. By surrounding this list with 1009 @code{@{} and @code{@}} operators. By surrounding this list with
1010 @code{[} and @code{]}, it can be concatenated into an array. For example: 1010 @code{[} and @code{]}, it can be concatenated into an array. For example:
1011 1011
1012 @example 1012 @example
1013 @group 1013 @group
1050 printf ("%s ", c@{:@}); 1050 printf ("%s ", c@{:@});
1051 @print{} GNU Octave is Free Software 1051 @print{} GNU Octave is Free Software
1052 @end group 1052 @end group
1053 @end example 1053 @end example
1054 1054
1055 If used on the left-hand side of an assignment, a comma separated list 1055 If used on the left-hand side of an assignment, a comma-separated list
1056 generated with @code{@{@}} can be assigned to. An example is 1056 generated with @code{@{@}} can be assigned to. An example is
1057 1057
1058 @example 1058 @example
1059 in@{1@} = [10, 20, 30]; 1059 in@{1@} = [10, 20, 30];
1060 in@{2@} = inf; 1060 in@{2@} = inf;
1079 [6,1] = first 1079 [6,1] = first
1080 @} 1080 @}
1081 @end example 1081 @end example
1082 1082
1083 1083
1084 @node Comma Separated Lists Generated from Structure Arrays 1084 @node Comma-Separated Lists Generated from Structure Arrays
1085 @subsection Comma Separated Lists Generated from Structure Arrays 1085 @subsection Comma-Separated Lists Generated from Structure Arrays
1086 Structure arrays can equally be used to create comma separated 1086 Structure arrays can equally be used to create comma-separated
1087 lists. This is done by addressing one of the fields of a structure 1087 lists. This is done by addressing one of the fields of a structure
1088 array. For example: 1088 array. For example:
1089 1089
1090 @example 1090 @example
1091 @group 1091 @group