File: Basic-Usage-and-Examples.html

package info (click to toggle)
octave 10.3.0-2
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 145,388 kB
  • sloc: cpp: 335,976; ansic: 82,241; fortran: 20,963; objc: 9,402; sh: 8,756; yacc: 4,392; lex: 4,333; perl: 1,544; java: 1,366; awk: 1,259; makefile: 660; xml: 192
file content (268 lines) | stat: -rw-r--r-- 11,049 bytes parent folder | download
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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Basic Usage and Examples (GNU Octave (version 10.3.0))</title>

<meta name="description" content="Basic Usage and Examples (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Basic Usage and Examples (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Structures.html" rel="up" title="Structures">
<link href="Structure-Arrays.html" rel="next" title="Structure Arrays">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<div class="subsection-level-extent" id="Basic-Usage-and-Examples">
<div class="nav-panel">
<p>
Next: <a href="Structure-Arrays.html" accesskey="n" rel="next">Structure Arrays</a>, Up: <a href="Structures.html" accesskey="u" rel="up">Structures</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Basic-Usage-and-Examples-1"><span>6.1.1 Basic Usage and Examples<a class="copiable-link" href="#Basic-Usage-and-Examples-1"> &para;</a></span></h4>

<p>Here are some examples of using data structures in Octave.
</p>
<p>Elements of structures can be of any value type.  For example, the three
expressions
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">x.a = 1;
x.b = [1, 2; 3, 4];
x.c = &quot;string&quot;;
</pre></div></div>

<a class="index-entry-id" id="index-_002e-structure-field-access"></a>
<p>create a structure with three elements.  The &lsquo;<samp class="samp">.</samp>&rsquo; character separates
the structure name (in the example above <code class="code">x</code>) from the field name and
indicates to Octave that this variable is a structure.  To print the value
of the structure you can type its name, just as for any other variable:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">x
     &rArr; x =

         scalar structure containing the fields:

           a =  1
           b =

              1   2
              3   4

           c = string
</pre></div></div>

<p>Note that Octave may print the elements in any order.
</p>
<p>Structures may be copied just like any other variable:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">y = x
     &rArr; y =

         scalar structure containing the fields:

           a =  1
           b =

              1   2
              3   4

           c = string
</pre></div></div>

<p>Since structures are themselves values, structure elements may reference
other structures, as well.  The following statement adds the field <code class="code">d</code>
to the structure <code class="code">x</code>.  The value of field <code class="code">d</code> is itself a data
structure containing the single field <code class="code">a</code>, which has a value of 3.
</p>
<div class="example">
<pre class="example-preformatted">x.d.a = 3;
x.d
     &rArr; ans =

         scalar structure containing the fields:

           a =  3

x
     &rArr; x =

         scalar structure containing the fields:

           a =  1
           b =

              1   2
              3   4

           c = string
           d =

             scalar structure containing the fields:

               a =  3
</pre></div>

<p>Note that when Octave prints the value of a structure that contains
other structures, only a few levels are displayed.  For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">a.b.c.d.e = 1;
a
     &rArr; a =

         scalar structure containing the fields:

           b =

             scalar structure containing the fields:

               c =

                 scalar structure containing the fields:

                   d: 1x1 scalar struct
</pre></div></div>

<p>This prevents long and confusing output from large deeply nested
structures.  The number of levels to print for nested structures may be
set with the function <code class="code">struct_levels_to_print</code>, and the function
<code class="code">print_struct_array_contents</code> may be used to enable printing of the
contents of structure arrays.
</p>
<a class="anchor" id="XREFstruct_005flevels_005fto_005fprint"></a><span style="display:block; margin-top:-4.5ex;">&nbsp;</span>


<dl class="first-deftypefn">
<dt class="deftypefn" id="index-struct_005flevels_005fto_005fprint"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">struct_levels_to_print</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-struct_005flevels_005fto_005fprint"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-struct_005flevels_005fto_005fprint-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">struct_levels_to_print</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-struct_005flevels_005fto_005fprint-1"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-struct_005flevels_005fto_005fprint-2"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">struct_levels_to_print</strong> <code class="def-code-arguments">(<var class="var">new_val</var>, &quot;local&quot;)</code><a class="copiable-link" href="#index-struct_005flevels_005fto_005fprint-2"> &para;</a></span></dt>
<dd><p>Query or set the internal variable that specifies the number of
structure levels to display.
</p>
<p>When called from inside a function with the <code class="code">&quot;local&quot;</code> option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFprint_005fstruct_005farray_005fcontents">print_struct_array_contents</a>.
</p></dd></dl>


<a class="anchor" id="XREFprint_005fstruct_005farray_005fcontents"></a><span style="display:block; margin-top:-4.5ex;">&nbsp;</span>


<dl class="first-deftypefn">
<dt class="deftypefn" id="index-print_005fstruct_005farray_005fcontents"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">print_struct_array_contents</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-print_005fstruct_005farray_005fcontents"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-print_005fstruct_005farray_005fcontents-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">print_struct_array_contents</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-print_005fstruct_005farray_005fcontents-1"> &para;</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-print_005fstruct_005farray_005fcontents-2"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">print_struct_array_contents</strong> <code class="def-code-arguments">(<var class="var">new_val</var>, &quot;local&quot;)</code><a class="copiable-link" href="#index-print_005fstruct_005farray_005fcontents-2"> &para;</a></span></dt>
<dd><p>Query or set the internal variable that specifies whether to print struct
array contents.
</p>
<p>If true, values of struct array elements are printed.  This variable does
not affect scalar structures whose elements are always printed.  In both
cases, however, printing will be limited to the number of levels specified
by <var class="var">struct_levels_to_print</var>.
</p>
<p>When called from inside a function with the <code class="code">&quot;local&quot;</code> option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFstruct_005flevels_005fto_005fprint">struct_levels_to_print</a>.
</p></dd></dl>


<p>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 <code class="code">y</code>.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">function y = f (x)
  y.re = real (x);
  y.im = imag (x);
endfunction
</pre></div></div>

<p>When called with a complex-valued argument, the function <code class="code">f</code> returns
the data structure containing the real and imaginary parts of the original
function argument.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">f (rand (2) + rand (2) * I)
     &rArr; ans =

         scalar structure containing the fields:

           re =

              0.040239  0.242160
              0.238081  0.402523

           im =

              0.26475  0.14828
              0.18436  0.83669
</pre></div></div>

<p>Function return lists can include structure elements, and they may be
indexed like any other variable.  For example:
</p>
<div class="example">
<pre class="example-preformatted">[ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]);
x

     &rArr; x =

         scalar structure containing the fields:

           u =

             -0.40455  -0.91451
             -0.91451   0.40455

           s =

              0.00000   0.00000   0.00000
              0.00000   5.46499   0.00000
              0.00000   0.00000   0.36597

           v =

             -0.57605   0.81742
             -0.81742  -0.57605
</pre></div>

<p>It is also possible to cycle through all the elements of a structure in
a loop, using a special form of the <code class="code">for</code> statement
(see <a class="pxref" href="Looping-Over-Structure-Elements.html">Looping Over Structure Elements</a>).
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Structure-Arrays.html">Structure Arrays</a>, Up: <a href="Structures.html">Structures</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>