|
3294
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
4167
|
5 @node Data Structures |
|
3294
|
6 @chapter Data Structures |
|
|
7 @cindex structures |
|
|
8 @cindex data structures |
|
|
9 |
|
|
10 Octave includes support for organizing data in structures. The current |
|
|
11 implementation uses an associative array with indices limited to |
|
|
12 strings, but the syntax is more like C-style structures. Here are some |
|
|
13 examples of using data structures in Octave. |
|
|
14 |
|
|
15 Elements of structures can be of any value type. For example, the three |
|
|
16 expressions |
|
|
17 |
|
|
18 @example |
|
|
19 @group |
|
|
20 x.a = 1 |
|
|
21 x.b = [1, 2; 3, 4] |
|
|
22 x.c = "string" |
|
|
23 @end group |
|
|
24 @end example |
|
|
25 |
|
|
26 @noindent |
|
|
27 create a structure with three elements. To print the value of the |
|
|
28 structure, you can type its name, just as for any other variable: |
|
|
29 |
|
|
30 @example |
|
|
31 @group |
|
|
32 octave:2> x |
|
|
33 x = |
|
|
34 @{ |
|
|
35 a = 1 |
|
|
36 b = |
|
|
37 |
|
|
38 1 2 |
|
|
39 3 4 |
|
|
40 |
|
|
41 c = string |
|
|
42 @} |
|
|
43 @end group |
|
|
44 @end example |
|
|
45 |
|
|
46 @noindent |
|
|
47 Note that Octave may print the elements in any order. |
|
|
48 |
|
|
49 Structures may be copied. |
|
|
50 |
|
|
51 @example |
|
|
52 @group |
|
|
53 octave:1> y = x |
|
|
54 y = |
|
|
55 @{ |
|
|
56 a = 1 |
|
|
57 b = |
|
|
58 |
|
|
59 1 2 |
|
|
60 3 4 |
|
|
61 |
|
|
62 c = string |
|
|
63 @} |
|
|
64 @end group |
|
|
65 @end example |
|
|
66 |
|
|
67 Since structures are themselves values, structure elements may reference |
|
|
68 other structures. The following statements change the value of the |
|
|
69 element @code{b} of the structure @code{x} to be a data structure |
|
|
70 containing the single element @code{d}, which has a value of 3. |
|
|
71 |
|
|
72 @example |
|
|
73 @group |
|
|
74 octave:1> x.b.d = 3 |
|
|
75 x.b.d = 3 |
|
|
76 octave:2> x.b |
|
|
77 ans = |
|
|
78 @{ |
|
|
79 d = 3 |
|
|
80 @} |
|
|
81 octave:3> x |
|
|
82 x = |
|
|
83 @{ |
|
|
84 a = 1 |
|
|
85 b = |
|
|
86 @{ |
|
|
87 d = 3 |
|
|
88 @} |
|
|
89 |
|
|
90 c = string |
|
|
91 @} |
|
|
92 @end group |
|
|
93 @end example |
|
|
94 |
|
|
95 Note that when Octave prints the value of a structure that contains |
|
|
96 other structures, only a few levels are displayed. For example, |
|
|
97 |
|
|
98 @example |
|
|
99 @group |
|
|
100 octave:1> a.b.c.d.e = 1; |
|
|
101 octave:2> a |
|
|
102 a = |
|
|
103 @{ |
|
|
104 b = |
|
|
105 @{ |
|
|
106 c = <structure> |
|
|
107 @} |
|
|
108 @} |
|
|
109 @end group |
|
|
110 @end example |
|
|
111 |
|
|
112 @noindent |
|
|
113 This prevents long and confusing output from large deeply nested |
|
|
114 structures. |
|
|
115 |
|
3361
|
116 @DOCSTRING(struct_levels_to_print) |
|
3294
|
117 |
|
|
118 Functions can return structures. For example, the following function |
|
|
119 separates the real and complex parts of a matrix and stores them in two |
|
|
120 elements of the same structure variable. |
|
|
121 |
|
|
122 @example |
|
|
123 @group |
|
|
124 octave:1> function y = f (x) |
|
|
125 > y.re = real (x); |
|
|
126 > y.im = imag (x); |
|
|
127 > endfunction |
|
|
128 @end group |
|
|
129 @end example |
|
|
130 |
|
|
131 When called with a complex-valued argument, @code{f} returns the data |
|
|
132 structure containing the real and imaginary parts of the original |
|
|
133 function argument. |
|
|
134 |
|
|
135 @example |
|
|
136 @group |
|
|
137 octave:2> f (rand (2) + rand (2) * I); |
|
|
138 ans = |
|
|
139 @{ |
|
|
140 im = |
|
|
141 |
|
|
142 0.26475 0.14828 |
|
|
143 0.18436 0.83669 |
|
|
144 |
|
|
145 re = |
|
|
146 |
|
|
147 0.040239 0.242160 |
|
|
148 0.238081 0.402523 |
|
|
149 @} |
|
|
150 @end group |
|
|
151 @end example |
|
|
152 |
|
|
153 Function return lists can include structure elements, and they may be |
|
|
154 indexed like any other variable. For example, |
|
|
155 |
|
|
156 @example |
|
|
157 @group |
|
|
158 octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]) |
|
|
159 x.u = |
|
|
160 |
|
|
161 -0.40455 -0.91451 |
|
|
162 -0.91451 0.40455 |
|
|
163 |
|
|
164 x.s = |
|
|
165 |
|
|
166 0.00000 0.00000 0.00000 |
|
|
167 0.00000 5.46499 0.00000 |
|
|
168 0.00000 0.00000 0.36597 |
|
|
169 |
|
|
170 x.v = |
|
|
171 |
|
|
172 -0.57605 0.81742 |
|
|
173 -0.81742 -0.57605 |
|
|
174 @end group |
|
|
175 @end example |
|
|
176 |
|
|
177 It is also possible to cycle through all the elements of a structure in |
|
|
178 a loop, using a special form of the @code{for} statement |
|
|
179 (@pxref{The for Statement}) |
|
|
180 |
|
|
181 The following functions are available to give you information about |
|
|
182 structures. |
|
|
183 |
|
4029
|
184 @DOCSTRING(isstruct) |
|
3294
|
185 |
|
3361
|
186 @DOCSTRING(struct_contains) |
|
3294
|
187 |
|
3361
|
188 @DOCSTRING(struct_elements) |
