1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.
@node Data Structures, Variables, Strings, Top
@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 = <structure>
@}
@}
@end group
@end example
@noindent
This prevents long and confusing output from large deeply nested
structures.
@defvr {Built-in Variable} struct_levels_to_print
You can tell Octave how many structure levels to display by setting the
built-in variable @code{struct_levels_to_print}. The default value is 2.
@end defvr
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 (3) + rand (3) * 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.
@deftypefn {Built-in Function} {} is_struct (@var{expr})
Return 1 if the value of the expression @var{expr} is a structure.
@end deftypefn
@deftypefn {Built-in Function} {} struct_contains (@var{expr}, @var{name})
Return 1 if the expression @var{expr} is a structure and it includes an
element named @var{name}. The first argument must be a structure and
the second must be a string.
@end deftypefn
@deftypefn {Built-in Function} {} struct_elements (@var{struct})
Return a list of strings naming the elements of the structure
@var{struct}. It is an error to call @code{struct_elements} with an
argument that is not a structure.
@end deftypefn
|
