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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
|
<!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>Simple File I/O (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Simple File I/O (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Simple File I/O (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="Basic-Input-and-Output.html" rel="up" title="Basic Input and Output">
<link href="Terminal-Input.html" rel="prev" title="Terminal Input">
<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}
ul.mark-bullet {list-style-type: disc}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="subsection-level-extent" id="Simple-File-I_002fO">
<div class="nav-panel">
<p>
Previous: <a href="Terminal-Input.html" accesskey="p" rel="prev">Terminal Input</a>, Up: <a href="Basic-Input-and-Output.html" accesskey="u" rel="up">Basic Input and Output</a> [<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="Simple-File-I_002fO-1"><span>14.1.3 Simple File I/O<a class="copiable-link" href="#Simple-File-I_002fO-1"> ¶</a></span></h4>
<a class="index-entry-id" id="index-saving-data"></a>
<a class="index-entry-id" id="index-loading-data"></a>
<p>The <code class="code">save</code> and <code class="code">load</code> commands allow data to be written to and
read from disk files in various formats. The default format of files
written by the <code class="code">save</code> command can be controlled using the functions
<code class="code">save_default_options</code> and <code class="code">save_precision</code>.
</p>
<p>As an example the following code creates a 3-by-3 matrix and saves it
to the file ‘<samp class="samp">myfile.mat</samp>’.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">A = [ 1:3; 4:6; 7:9 ];
save myfile.mat A
</pre></div></div>
<p>Once one or more variables have been saved to a file, they can be
read into memory using the <code class="code">load</code> command.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">load myfile.mat
A
-| A =
-|
-| 1 2 3
-| 4 5 6
-| 7 8 9
</pre></div></div>
<a class="anchor" id="XREFsave"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-save"><span><strong class="def-name">save</strong> <code class="def-code-arguments">file</code><a class="copiable-link" href="#index-save"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save-1"><span><strong class="def-name">save</strong> <code class="def-code-arguments">options file</code><a class="copiable-link" href="#index-save-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save-2"><span><strong class="def-name">save</strong> <code class="def-code-arguments">options file <var class="var">v1</var> <var class="var">v2</var> …</code><a class="copiable-link" href="#index-save-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save-3"><span><strong class="def-name">save</strong> <code class="def-code-arguments">options file -struct <var class="var">STRUCT</var></code><a class="copiable-link" href="#index-save-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save-4"><span><strong class="def-name">save</strong> <code class="def-code-arguments">options file -struct <var class="var">STRUCT</var> <var class="var">f1</var> <var class="var">f2</var> …</code><a class="copiable-link" href="#index-save-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save-5"><span><strong class="def-name">save</strong> <code class="def-code-arguments">- <var class="var">v1</var> <var class="var">v2</var> …</code><a class="copiable-link" href="#index-save-5"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save-6"><span><code class="def-type"><var class="var">str</var> =</code> <strong class="def-name">save</strong> <code class="def-code-arguments">("-", <code class="code">"<var class="var">v1</var>"</code>, <code class="code">"<var class="var">v2</var>"</code>, …)</code><a class="copiable-link" href="#index-save-6"> ¶</a></span></dt>
<dd><p>Save the named variables <var class="var">v1</var>, <var class="var">v2</var>, …, in the file <var class="var">file</var>.
</p>
<p>If no variable names are listed, Octave saves all the variables in the current
scope. Otherwise, full variable names or pattern syntax can be used to specify
the variables to save. If the <samp class="option">-struct</samp> modifier is used then the
fields of the <strong class="strong">scalar</strong> struct are saved as if they were variables with
the corresponding field names. The <samp class="option">-struct</samp> option can be combined
with specific field names <var class="var">f1</var>, <var class="var">f2</var>, … to write only certain
fields to the file.
</p>
<p>The <code class="code">save</code> command may also be invoked using the functional form
</p>
<div class="example">
<pre class="example-preformatted">save ("-option1", ..., "file", "v1", ...)
</pre></div>
<p>where the <var class="var">options</var>, <var class="var">file</var>, and variable name arguments (<var class="var">v1</var>,
…) must be specified as character strings.
</p>
<p>Valid options for the <code class="code">save</code> command are listed in the following table.
Options that modify the output format override the format specified by
<code class="code">save_default_options</code>.
</p>
<dl class="table">
<dt><code class="code">-append</code></dt>
<dd><p>Append to the file instead of overwriting.
</p>
</dd>
<dt><code class="code">-ascii</code></dt>
<dd><p>Save a matrix in a text file without a header or any other information. The
matrix must be 2-D and only the real part of any complex value is written to
the file. Numbers are stored in single-precision format and separated by
spaces. Additional options for the <samp class="option">-ascii</samp> format are
</p>
<dl class="table">
<dt><code class="code">-double</code></dt>
<dd><p>Store numbers in double-precision format.
</p>
</dd>
<dt><code class="code">-tabs</code></dt>
<dd><p>Separate numbers with tabs.
</p></dd>
</dl>
</dd>
<dt><code class="code">-binary</code></dt>
<dd><p>Save the data in Octave’s binary data format.
</p>
</dd>
<dt><code class="code">-float-binary</code></dt>
<dd><p>Save the data in Octave’s binary data format using just single precision.
Use this format <strong class="strong">only</strong> if you know that all the values to be saved can
be represented in single precision.
</p>
</dd>
<dt><code class="code">-hdf5</code></dt>
<dd><p>Save the data in <small class="sc">HDF5</small> format. (<small class="sc">HDF5</small> is a free, portable, binary
format developed by the National Center for Supercomputing Applications at the
University of Illinois.) This format is only available if Octave was built
with a link to the <small class="sc">HDF5</small> libraries.
</p>
</dd>
<dt><code class="code">-float-hdf5</code></dt>
<dd><p>Save the data in <small class="sc">HDF5</small> format using just single precision. Use this
format <strong class="strong">only</strong> if you know that all the values to be saved can be
represented in single precision.
</p>
</dd>
<dt><code class="code">-text (default)</code></dt>
<dd><p>Save the data in Octave’s text data format. The
<a class="ref" href="#XREFsave_005fprecision"><code class="code">save_precision</code></a> function specifies the number
of significant figures to use when saving data (default: 17). The header of
the text data file can be configure with
<a class="ref" href="#XREFsave_005fheader_005fformat_005fstring"><code class="code">save_header_format_string</code></a>.
</p>
</dd>
<dt><code class="code">-v7.3</code></dt>
<dt><code class="code">-V7.3</code></dt>
<dt><code class="code">-7.3</code></dt>
<dd><p>Octave does <strong class="strong">not</strong> yet implement saving in <small class="sc">MATLAB</small>’s v7.3 binary
data format.
</p>
</dd>
<dt><code class="code">-v7</code></dt>
<dt><code class="code">-V7</code></dt>
<dt><code class="code">-7</code></dt>
<dt><code class="code">-mat7-binary</code></dt>
<dd><p>Save the data in <small class="sc">MATLAB</small>’s v7 binary data format.
</p>
</dd>
<dt><code class="code">-v6</code></dt>
<dt><code class="code">-V6</code></dt>
<dt><code class="code">-6</code></dt>
<dt><code class="code">-mat</code></dt>
<dt><code class="code">-mat-binary</code></dt>
<dd><p>Save the data in <small class="sc">MATLAB</small>’s v6 binary data format.
</p>
</dd>
<dt><code class="code">-v4</code></dt>
<dt><code class="code">-V4</code></dt>
<dt><code class="code">-4</code></dt>
<dt><code class="code">-mat4-binary</code></dt>
<dd><p>Save the data in <small class="sc">MATLAB</small>’s v4 binary data format.
</p>
</dd>
<dt><code class="code">-zip</code></dt>
<dt><code class="code">-z</code></dt>
<dd><p>Use the gzip algorithm to compress the file. This works on files that are
compressed with gzip outside of Octave, and gzip can also be used to convert
the files for backward compatibility. This option is only available if Octave
was built with a link to the zlib libraries.
</p></dd>
</dl>
<p>The list of variables to save may use wildcard patterns (glob patterns)
containing the following special characters:
</p>
<dl class="table">
<dt><code class="code">?</code></dt>
<dd><p>Match any single character.
</p>
</dd>
<dt><code class="code">*</code></dt>
<dd><p>Match zero or more characters.
</p>
</dd>
<dt><code class="code">[ <var class="var">list</var> ]</code></dt>
<dd><p>Match the list of characters specified by <var class="var">list</var>. If the first character
is <code class="code">!</code> or <code class="code">^</code>, match all characters except those specified by
<var class="var">list</var>. For example, the pattern <code class="code">[a-zA-Z]</code> will match all lower and
uppercase alphabetic characters.
</p>
<p>Wildcards may also be used in the field name specifications when using the
<samp class="option">-struct</samp> modifier (but not in the struct name itself).
</p>
</dd>
</dl>
<p>Programming Notes: If called with the special filename <code class="code">"-"</code> the data to
be saved is returned as a string rather than writing it to an actual file.
</p>
<p>When saving global variables the global status of the variable is also stored.
If the variable is restored at a later time using <code class="code">load</code>, it will be
restored as a global variable. Global status is <em class="emph">not</em> preserved if
using a <small class="sc">MATLAB</small> binary data file format or the <samp class="option">-ascii</samp> format.
</p>
<p>Example:
</p>
<p>The command
</p>
<div class="example">
<pre class="example-preformatted">save -binary data a b*
</pre></div>
<p>saves the variable ‘<samp class="samp">a</samp>’ and all variables beginning with ‘<samp class="samp">b</samp>’ to the
file <samp class="file">data</samp> in Octave’s binary format.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFload">load</a>, <a class="ref" href="#XREFsave_005fdefault_005foptions">save_default_options</a>, <a class="ref" href="#XREFsave_005fheader_005fformat_005fstring">save_header_format_string</a>, <a class="ref" href="#XREFsave_005fprecision">save_precision</a>, <a class="ref" href="#XREFcsvwrite">csvwrite</a>, <a class="ref" href="#XREFdlmwrite">dlmwrite</a>, <a class="ref" href="Binary-I_002fO.html#XREFfwrite">fwrite</a>.
</p></dd></dl>
<p>There are three functions that modify the behavior of <code class="code">save</code>.
</p>
<a class="anchor" id="XREFsave_005fdefault_005foptions"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-save_005fdefault_005foptions"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">save_default_options</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-save_005fdefault_005foptions"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save_005fdefault_005foptions-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">save_default_options</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-save_005fdefault_005foptions-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save_005fdefault_005foptions-2"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">save_default_options</strong> <code class="def-code-arguments">(<var class="var">new_val</var>, "local")</code><a class="copiable-link" href="#index-save_005fdefault_005foptions-2"> ¶</a></span></dt>
<dd><p>Query or set the internal variable that specifies the default options
for the <code class="code">save</code> command, and defines the default format.
</p>
<p>The default value is <code class="code">"-text"</code> (Octave’s own text-based file format).
See the documentation of the <code class="code">save</code> command for other choices.
</p>
<p>When called from inside a function with the <code class="code">"local"</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="#XREFsave">save</a>, <a class="ref" href="#XREFsave_005fheader_005fformat_005fstring">save_header_format_string</a>, <a class="ref" href="#XREFsave_005fprecision">save_precision</a>.
</p></dd></dl>
<a class="anchor" id="XREFsave_005fprecision"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-save_005fprecision"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">save_precision</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-save_005fprecision"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save_005fprecision-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">save_precision</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-save_005fprecision-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save_005fprecision-2"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">save_precision</strong> <code class="def-code-arguments">(<var class="var">new_val</var>, "local")</code><a class="copiable-link" href="#index-save_005fprecision-2"> ¶</a></span></dt>
<dd><p>Query or set the internal variable that specifies the number of digits to
keep when saving data in text format.
</p>
<p>The default value is 17 which is the minimum necessary for the lossless saving
and restoring of IEEE 754 double values; For IEEE 754 single values
the minimum value is 9. If file size is a concern, it is probably better to
choose a binary format for saving data rather than to reduce the precision of
the saved values.
</p>
<p>When called from inside a function with the <code class="code">"local"</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="#XREFsave_005fdefault_005foptions">save_default_options</a>.
</p></dd></dl>
<a class="anchor" id="XREFsave_005fheader_005fformat_005fstring"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-save_005fheader_005fformat_005fstring"><span><code class="def-type"><var class="var">val</var> =</code> <strong class="def-name">save_header_format_string</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-save_005fheader_005fformat_005fstring"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save_005fheader_005fformat_005fstring-1"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">save_header_format_string</strong> <code class="def-code-arguments">(<var class="var">new_val</var>)</code><a class="copiable-link" href="#index-save_005fheader_005fformat_005fstring-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-save_005fheader_005fformat_005fstring-2"><span><code class="def-type"><var class="var">old_val</var> =</code> <strong class="def-name">save_header_format_string</strong> <code class="def-code-arguments">(<var class="var">new_val</var>, "local")</code><a class="copiable-link" href="#index-save_005fheader_005fformat_005fstring-2"> ¶</a></span></dt>
<dd><p>Query or set the internal variable that specifies the format string used for
the comment line written at the beginning of text-format data files saved by
Octave.
</p>
<p>The format string is passed to <code class="code">strftime</code> and must begin with the
character ‘<samp class="samp">#</samp>’ and contain no newline characters. If the value of
<code class="code">save_header_format_string</code> is the empty string, the header comment is
omitted from text-format data files. The default value is
</p>
<div class="example smallexample">
<pre class="example-preformatted">"# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"
</pre></div>
<p>When called from inside a function with the <code class="code">"local"</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="Timing-Utilities.html#XREFstrftime">strftime</a>, <a class="ref" href="#XREFsave_005fdefault_005foptions">save_default_options</a>.
</p></dd></dl>
<a class="anchor" id="XREFload"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-load"><span><strong class="def-name">load</strong> <code class="def-code-arguments">file</code><a class="copiable-link" href="#index-load"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-load-1"><span><strong class="def-name">load</strong> <code class="def-code-arguments">options file</code><a class="copiable-link" href="#index-load-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-load-2"><span><strong class="def-name">load</strong> <code class="def-code-arguments">options file v1 v2 …</code><a class="copiable-link" href="#index-load-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-load-3"><span><code class="def-type">S =</code> <strong class="def-name">load</strong> <code class="def-code-arguments">("options", "file", "v1", "v2", …)</code><a class="copiable-link" href="#index-load-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-load-4"><span><strong class="def-name">load</strong> <code class="def-code-arguments">file options</code><a class="copiable-link" href="#index-load-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-load-5"><span><strong class="def-name">load</strong> <code class="def-code-arguments">file options v1 v2 …</code><a class="copiable-link" href="#index-load-5"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-load-6"><span><code class="def-type">S =</code> <strong class="def-name">load</strong> <code class="def-code-arguments">("file", "options", "v1", "v2", …)</code><a class="copiable-link" href="#index-load-6"> ¶</a></span></dt>
<dd><p>Load the named variables <var class="var">v1</var>, <var class="var">v2</var>, …, from the file <var class="var">file</var>.
</p>
<p>If no variables are specified then all variables found in the file will be
loaded. Otherwise, full variable names or pattern syntax can be used to
specify the variables to save. The format of the file is automatically
detected but may be overridden by supplying the appropriate option.
</p>
<p>The <code class="code">load</code> command may also be invoked using the functional form
</p>
<div class="example">
<pre class="example-preformatted">load ("-option1", ..., "file", "v1", ...)
</pre></div>
<p>where the <var class="var">options</var>, <var class="var">file</var>, and variable name arguments (<var class="var">v1</var>,
…) must be specified as character strings.
</p>
<p>Valid options for <code class="code">load</code> are listed in the following table.
</p>
<dl class="table">
<dt><code class="code">-ascii</code></dt>
<dd><p>Force Octave to assume the file contains columns of numbers in text format
without any header or other information. Data in the file will be loaded
as a single numeric matrix with the name of the variable derived from the
name of the file.
</p>
</dd>
<dt><code class="code">-binary</code></dt>
<dd><p>Force Octave to assume the file is in Octave’s binary format.
</p>
</dd>
<dt><code class="code">-hdf5</code></dt>
<dd><p>Force Octave to assume the file is in <small class="sc">HDF5</small> format. (<small class="sc">HDF5</small> is a free,
portable binary format developed by the National Center for Supercomputing
Applications at the University of Illinois.) Note that <code class="code">load</code> is only
designed to read <small class="sc">HDF5</small> files that were created by Octave with <code class="code">save</code>,
and attempts to read other <small class="sc">HDF5</small> files may fail or produce unpredictable
results. The <samp class="option">-hdf5</samp> option provides a limited ability to read files
created using <small class="sc">MATLAB</small>’s <samp class="option">-v7.3</samp> option (which saves in <small class="sc">HDF5</small>
format) although many data types are not yet supported. This format is only
available if Octave was built with a link to the <small class="sc">HDF5</small> libraries.
</p>
</dd>
<dt><code class="code">-text</code></dt>
<dd><p>Force Octave to assume the file is in Octave’s text format.
</p>
</dd>
<dt><code class="code">-v7.3</code></dt>
<dt><code class="code">-V7.3</code></dt>
<dt><code class="code">-7.3</code></dt>
<dd><p>Octave does <strong class="strong">not</strong> yet implement <small class="sc">MATLAB</small>’s v7.3 binary data format.
As the v7.3 format is an <small class="sc">HDF5</small> based format, the <code class="code">"-hdf5"</code> option
may be used to attempt to open a v7.3 format file, although most non-numeric
data types are not yet supported. Note that Octave <strong class="strong">can not</strong> currently
save in this format.
</p>
</dd>
<dt><code class="code">-v7</code></dt>
<dt><code class="code">-V7</code></dt>
<dt><code class="code">-7</code></dt>
<dt><code class="code">-mat7-binary</code></dt>
<dd><p>Force Octave to assume the file is in <small class="sc">MATLAB</small>’s version 7 binary format.
</p>
</dd>
<dt><code class="code">-v6</code></dt>
<dt><code class="code">-V6</code></dt>
<dt><code class="code">-6</code></dt>
<dt><code class="code">-mat</code></dt>
<dt><code class="code">-mat-binary</code></dt>
<dd><p>Force Octave to assume the file is in <small class="sc">MATLAB</small>’s version 6 binary format.
</p>
</dd>
<dt><code class="code">-v4</code></dt>
<dt><code class="code">-V4</code></dt>
<dt><code class="code">-4</code></dt>
<dt><code class="code">-mat4-binary</code></dt>
<dd><p>Force Octave to assume the file is in <small class="sc">MATLAB</small>’s version 4 binary format.
</p>
</dd>
</dl>
<p>The list of variables to load may use wildcard patterns (glob patterns)
containing the following special characters:
</p>
<dl class="table">
<dt><code class="code">?</code></dt>
<dd><p>Match any single character.
</p>
</dd>
<dt><code class="code">*</code></dt>
<dd><p>Match zero or more characters.
</p>
</dd>
<dt><code class="code">[ <var class="var">list</var> ]</code></dt>
<dd><p>Match the list of characters specified by <var class="var">list</var>. If the first character
is <code class="code">!</code> or <code class="code">^</code>, match all characters except those specified by
<var class="var">list</var>. For example, the pattern <code class="code">[a-zA-Z]</code> will match all lower and
uppercase alphabetic characters.
</p>
</dd>
</dl>
<p>If invoked with a single output argument, Octave assigns loaded data to the
output instead of inserting variables in the symbol table. If the data file
contains only numbers (TAB- or space-delimited columns), a matrix of values is
returned. Otherwise, <code class="code">load</code> returns a structure with members
corresponding to the names of the variables in the file.
</p>
<p>The <code class="code">load</code> command can read data stored in Octave’s text and binary
formats, <small class="sc">MATLAB</small>’s binary format, and many simple formats such as
comma-separated-values (CSV). If compiled with zlib support, it can also load
gzip-compressed files. It will automatically detect the type of file and do
conversion from different floating point formats (currently only IEEE big and
little endian, though other formats may be added in the future).
</p>
<p>Programming Note: If a variable that is not marked as global is loaded from a
file when a global symbol with the same name already exists, it is loaded in
the global symbol table. Also, if a variable is marked as global in a file and
a local symbol exists, the local symbol is moved to the global symbol table and
given the value from the file.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFsave">save</a>, <a class="ref" href="#XREFcsvread">csvread</a>, <a class="ref" href="#XREFdlmread">dlmread</a>, <a class="ref" href="Binary-I_002fO.html#XREFfread">fread</a>, <a class="ref" href="#XREFtextscan">textscan</a>.
</p></dd></dl>
<a class="anchor" id="XREFfileread"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-fileread"><span><code class="def-type"><var class="var">str</var> =</code> <strong class="def-name">fileread</strong> <code class="def-code-arguments">(<var class="var">filename</var>)</code><a class="copiable-link" href="#index-fileread"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-fileread-1"><span><code class="def-type"><var class="var">str</var> =</code> <strong class="def-name">fileread</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">param</var>, <var class="var">value</var>, …)</code><a class="copiable-link" href="#index-fileread-1"> ¶</a></span></dt>
<dd><p>Read the contents of <var class="var">filename</var> and return it as a string.
</p>
<p><var class="var">param</var>, <var class="var">value</var> are optional pairs of parameters and values. Valid
options are:
</p>
<dl class="table">
<dt><code class="code">"Encoding"</code></dt>
<dd><p>Specify encoding used when reading from the file. This is a character
string of a valid encoding identifier. The default is
<code class="code">"utf-8"</code>.
</p></dd>
</dl>
<p><strong class="strong">See also:</strong> <a class="ref" href="Opening-and-Closing-Files.html#XREFfopen">fopen</a>, <a class="ref" href="Binary-I_002fO.html#XREFfread">fread</a>, <a class="ref" href="Formatted-Input.html#XREFfscanf">fscanf</a>, <a class="ref" href="#XREFimportdata">importdata</a>, <a class="ref" href="#XREFtextscan">textscan</a>, <a class="ref" href="Status-of-Variables.html#XREFtype">type</a>.
</p></dd></dl>
<a class="anchor" id="XREFnative_005ffloat_005fformat"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-native_005ffloat_005fformat"><span><code class="def-type"><var class="var">fmtstr</var> =</code> <strong class="def-name">native_float_format</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-native_005ffloat_005fformat"> ¶</a></span></dt>
<dd><p>Return the native floating point format as a string.
</p></dd></dl>
<p>It is possible to write data to a file in a similar way to the
<code class="code">disp</code> function for writing data to the screen. The <code class="code">fdisp</code>
works just like <code class="code">disp</code> except its first argument is a file pointer
as created by <code class="code">fopen</code>. As an example, the following code writes
to data ‘<samp class="samp">myfile.txt</samp>’.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">fid = fopen ("myfile.txt", "w");
fdisp (fid, "3/8 is ");
fdisp (fid, 3/8);
fclose (fid);
</pre></div></div>
<p>See <a class="xref" href="Opening-and-Closing-Files.html">Opening and Closing Files</a>, for details on how to use <code class="code">fopen</code>
and <code class="code">fclose</code>.
</p>
<a class="anchor" id="XREFfdisp"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-fdisp"><span><strong class="def-name">fdisp</strong> <code class="def-code-arguments">(<var class="var">fid</var>, <var class="var">x</var>)</code><a class="copiable-link" href="#index-fdisp"> ¶</a></span></dt>
<dd><p>Display the value of <var class="var">x</var> on the stream <var class="var">fid</var>.
</p>
<p>For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi)
-| the value of pi is:
-| 3.1416
</pre></div></div>
<p>Note that the output from <code class="code">fdisp</code> always ends with a newline.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Terminal-Output.html#XREFdisp">disp</a>.
</p></dd></dl>
<p>Octave can also read and write matrices text files such as comma
separated lists.
</p>
<a class="anchor" id="XREFdlmwrite"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-dlmwrite"><span><strong class="def-name">dlmwrite</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">M</var>)</code><a class="copiable-link" href="#index-dlmwrite"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmwrite-1"><span><strong class="def-name">dlmwrite</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">M</var>, <var class="var">delim</var>, <var class="var">r</var>, <var class="var">c</var>)</code><a class="copiable-link" href="#index-dlmwrite-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmwrite-2"><span><strong class="def-name">dlmwrite</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">M</var>, <var class="var">key</var>, <var class="var">val</var> …)</code><a class="copiable-link" href="#index-dlmwrite-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmwrite-3"><span><strong class="def-name">dlmwrite</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">M</var>, "-append", …)</code><a class="copiable-link" href="#index-dlmwrite-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmwrite-4"><span><strong class="def-name">dlmwrite</strong> <code class="def-code-arguments">(<var class="var">fid</var>, …)</code><a class="copiable-link" href="#index-dlmwrite-4"> ¶</a></span></dt>
<dd><p>Write the numeric matrix <var class="var">M</var> to the text file <var class="var">file</var> using a
delimiter.
</p>
<p><var class="var">file</var> should be a filename or a writable file ID given by <code class="code">fopen</code>.
</p>
<p>The parameter <var class="var">delim</var> specifies the delimiter to use to separate values
on a row. If no delimiter is specified the comma character ‘<samp class="samp">,</samp>’ is
used.
</p>
<p>The value of <var class="var">r</var> specifies the number of delimiter-only lines to add to
the start of the file.
</p>
<p>The value of <var class="var">c</var> specifies the number of delimiters to prepend to each
line of data.
</p>
<p>If the argument <code class="code">"-append"</code> is given, append to the end of <var class="var">file</var>.
</p>
<p>In addition, the following keyword value pairs may appear at the end of
the argument list:
</p>
<dl class="table">
<dt><code class="code">"append"</code></dt>
<dd><p>Either <code class="code">"on"</code> or <code class="code">"off"</code>. See <code class="code">"-append"</code> above.
</p>
</dd>
<dt><code class="code">"delimiter"</code></dt>
<dd><p>See <var class="var">delim</var> above.
</p>
</dd>
<dt><code class="code">"newline"</code></dt>
<dd><p>The character(s) to separate each row. Three special cases exist for this
option. <code class="code">"unix"</code> is changed into <code class="code">"\n"</code>,
<code class="code">"pc"</code> is changed into <code class="code">"\r\n"</code>,
and <code class="code">"mac"</code> is changed into <code class="code">"\r"</code>. Any other
value is used directly as the newline separator.
</p>
</dd>
<dt><code class="code">"roffset"</code></dt>
<dd><p>See <var class="var">r</var> above.
</p>
</dd>
<dt><code class="code">"coffset"</code></dt>
<dd><p>See <var class="var">c</var> above.
</p>
</dd>
<dt><code class="code">"precision"</code></dt>
<dd><p>The precision to use when writing the file. It can either be a format
string (as used by fprintf) or a number of significant digits.
</p></dd>
</dl>
<div class="example">
<pre class="example-preformatted">dlmwrite ("file.csv", reshape (1:16, 4, 4));
</pre></div>
<div class="example">
<pre class="example-preformatted">dlmwrite ("file.tex", a, "delimiter", "&", "newline", "\n")
</pre></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdlmread">dlmread</a>, <a class="ref" href="#XREFcsvread">csvread</a>, <a class="ref" href="#XREFcsvwrite">csvwrite</a>.
</p></dd></dl>
<a class="anchor" id="XREFdlmread"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-dlmread"><span><code class="def-type"><var class="var">data</var> =</code> <strong class="def-name">dlmread</strong> <code class="def-code-arguments">(<var class="var">file</var>)</code><a class="copiable-link" href="#index-dlmread"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmread-1"><span><code class="def-type"><var class="var">data</var> =</code> <strong class="def-name">dlmread</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">sep</var>)</code><a class="copiable-link" href="#index-dlmread-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmread-2"><span><code class="def-type"><var class="var">data</var> =</code> <strong class="def-name">dlmread</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">sep</var>, <var class="var">r0</var>, <var class="var">c0</var>)</code><a class="copiable-link" href="#index-dlmread-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmread-3"><span><code class="def-type"><var class="var">data</var> =</code> <strong class="def-name">dlmread</strong> <code class="def-code-arguments">(<var class="var">file</var>, <var class="var">sep</var>, <var class="var">range</var>)</code><a class="copiable-link" href="#index-dlmread-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-dlmread-4"><span><code class="def-type"><var class="var">data</var> =</code> <strong class="def-name">dlmread</strong> <code class="def-code-arguments">(…, "emptyvalue", <var class="var">EMPTYVAL</var>)</code><a class="copiable-link" href="#index-dlmread-4"> ¶</a></span></dt>
<dd><p>Read numeric data from the text file <var class="var">file</var> which uses the delimiter
<var class="var">sep</var> between data values.
</p>
<p>If <var class="var">sep</var> is not defined the separator between fields is determined from
the file itself.
</p>
<p>The optional scalar arguments <var class="var">r0</var> and <var class="var">c0</var> define the starting row
and column of the data to be read. These values are indexed from zero,
i.e., the first data row corresponds to an index of zero.
</p>
<p>The <var class="var">range</var> parameter specifies exactly which data elements are read.
The first form of the parameter is a 4-element vector containing the upper
left and lower right corners <code class="code">[<var class="var">R0</var>,<var class="var">C0</var>,<var class="var">R1</var>,<var class="var">C1</var>]</code>
where the indices are zero-based. To specify the last column—the equivalent
of <code class="code">end</code> when indexing—use the specifier <code class="code">Inf</code>. Alternatively, a
spreadsheet style form such as <code class="code">"A2..Q15"</code> or <code class="code">"T1:AA5"</code> can be
used. The lowest alphabetical index <code class="code">'A'</code> refers to the first column.
The lowest row index is 1.
</p>
<p><var class="var">file</var> should be a filename or a file id given by <code class="code">fopen</code>. In the
latter case, the file is read until end of file is reached.
</p>
<p>The <code class="code">"emptyvalue"</code> option may be used to specify the value used to
fill empty fields. The default is zero. Note that any non-numeric values,
such as text, are also replaced by the <code class="code">"emptyvalue"</code>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFcsvread">csvread</a>, <a class="ref" href="#XREFtextscan">textscan</a>, <a class="ref" href="#XREFdlmwrite">dlmwrite</a>.
</p></dd></dl>
<a class="anchor" id="XREFcsvwrite"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-csvwrite"><span><strong class="def-name">csvwrite</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">x</var>)</code><a class="copiable-link" href="#index-csvwrite"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-csvwrite-1"><span><strong class="def-name">csvwrite</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">x</var>, <var class="var">dlm_opt1</var>, …)</code><a class="copiable-link" href="#index-csvwrite-1"> ¶</a></span></dt>
<dd><p>Write the numeric matrix <var class="var">x</var> to the file <var class="var">filename</var> in
comma-separated-value<!-- /@w --> (CSV) format.
</p>
<p>This function is equivalent to
</p>
<div class="example">
<pre class="example-preformatted">dlmwrite (<var class="var">filename</var>, <var class="var">x</var>, ",", <var class="var">dlm_opt1</var>, ...)
</pre></div>
<p>Any optional arguments are passed directly to <code class="code">dlmwrite</code>
(see <a class="pxref" href="#XREFdlmwrite"><code class="code">dlmwrite</code></a>).
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFcsvread">csvread</a>, <a class="ref" href="#XREFdlmwrite">dlmwrite</a>, <a class="ref" href="#XREFdlmread">dlmread</a>.
</p></dd></dl>
<a class="anchor" id="XREFcsvread"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-csvread"><span><code class="def-type"><var class="var">x</var> =</code> <strong class="def-name">csvread</strong> <code class="def-code-arguments">(<var class="var">filename</var>)</code><a class="copiable-link" href="#index-csvread"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-csvread-1"><span><code class="def-type"><var class="var">x</var> =</code> <strong class="def-name">csvread</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">dlm_opt1</var>, …)</code><a class="copiable-link" href="#index-csvread-1"> ¶</a></span></dt>
<dd><p>Read the comma-separated-value (CSV) file <var class="var">filename</var> into the matrix
<var class="var">x</var>.
</p>
<p>Note: only CSV files containing numeric data can be read.
</p>
<p>This function is equivalent to
</p>
<div class="example">
<pre class="example-preformatted"><var class="var">x</var> = dlmread (<var class="var">filename</var>, "," , <var class="var">dlm_opt1</var>, ...)
</pre></div>
<p>Any optional arguments are passed directly to <code class="code">dlmread</code>
(see <a class="pxref" href="#XREFdlmread"><code class="code">dlmread</code></a>).
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdlmread">dlmread</a>, <a class="ref" href="#XREFtextscan">textscan</a>, <a class="ref" href="#XREFcsvwrite">csvwrite</a>, <a class="ref" href="#XREFdlmwrite">dlmwrite</a>.
</p></dd></dl>
<p>Formatted data from can be read from, or written to, text files as well.
</p>
<a class="anchor" id="XREFtextread"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-textread"><span><code class="def-type">[<var class="var">a</var>, …] =</code> <strong class="def-name">textread</strong> <code class="def-code-arguments">(<var class="var">filename</var>)</code><a class="copiable-link" href="#index-textread"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textread-1"><span><code class="def-type">[<var class="var">a</var>, …] =</code> <strong class="def-name">textread</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">format</var>)</code><a class="copiable-link" href="#index-textread-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textread-2"><span><code class="def-type">[<var class="var">a</var>, …] =</code> <strong class="def-name">textread</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">format</var>, <var class="var">n</var>)</code><a class="copiable-link" href="#index-textread-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textread-3"><span><code class="def-type">[<var class="var">a</var>, …] =</code> <strong class="def-name">textread</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">format</var>, <var class="var">prop1</var>, <var class="var">value1</var>, …)</code><a class="copiable-link" href="#index-textread-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textread-4"><span><code class="def-type">[<var class="var">a</var>, …] =</code> <strong class="def-name">textread</strong> <code class="def-code-arguments">(<var class="var">filename</var>, <var class="var">format</var>, <var class="var">n</var>, <var class="var">prop1</var>, <var class="var">value1</var>, …)</code><a class="copiable-link" href="#index-textread-4"> ¶</a></span></dt>
<dd>
<p>This function is obsolete. Use <code class="code">textscan</code> instead.
</p>
<p>Read data from a text file.
</p>
<p>The file <var class="var">filename</var> is read and parsed according to <var class="var">format</var>. The
function behaves like <code class="code">strread</code> except it works by parsing a file
instead of a string. See the documentation of <code class="code">strread</code> for details.
</p>
<p>In addition to the options supported by <code class="code">strread</code>, this function
supports two more:
</p>
<ul class="itemize mark-bullet">
<li><code class="code">"headerlines"</code>:
The first <var class="var">value</var> number of lines of <var class="var">filename</var> are skipped.
</li><li><code class="code">"endofline"</code>:
Specify a single character or
<code class="code">"\r\n"</code>. If no value is given, it
will be inferred from the file. If set to <code class="code">""</code> (empty string) EOLs
are ignored as delimiters.
</li></ul>
<p>The optional input <var class="var">n</var> (format repeat count) specifies the number of
times the format string is to be used or the number of lines to be read,
whichever happens first while reading. The former is equivalent to
requesting that the data output vectors should be of length <var class="var">N</var>.
Note that when reading files with format strings referring to multiple
lines, <var class="var">n</var> should rather be the number of lines to be read than the
number of format string uses.
</p>
<p>If the format string is empty (not just omitted) and the file contains only
numeric data (excluding headerlines), textread will return a rectangular
matrix with the number of columns matching the number of numeric fields on
the first data line of the file. Empty fields are returned as zero values.
</p>
<p>Examples:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted"> Assume a data file like:
1 a 2 b
3 c 4 d
5 e
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted"> [a, b] = textread (f, "%f %s")
returns two columns of data, one with doubles, the other a
cellstr array:
a = [1; 2; 3; 4; 5]
b = {"a"; "b"; "c"; "d"; "e"}
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted"> [a, b] = textread (f, "%f %s", 3)
(read data into two culumns, try to use the format string
three times)
returns
a = [1; 2; 3]
b = {"a"; "b"; "c"}
</pre></div></div>
<div class="example">
<div class="group"><pre class="example-preformatted"> With a data file like:
1
a
2
b
[a, b] = textread (f, "%f %s", 2)
returns a = 1 and b = {"a"}; i.e., the format string is used
only once because the format string refers to 2 lines of the
data file. To obtain 2x1 data output columns, specify N = 4
(number of data lines containing all requested data) rather
than 2.
</pre></div></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFtextscan">textscan</a>, <a class="ref" href="#XREFload">load</a>, <a class="ref" href="#XREFdlmread">dlmread</a>, <a class="ref" href="Formatted-Input.html#XREFfscanf">fscanf</a>, <a class="ref" href="Numerical-Data-and-Strings.html#XREFstrread">strread</a>.
</p></dd></dl>
<a class="anchor" id="XREFtextscan"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-textscan"><span><code class="def-type"><var class="var">C</var> =</code> <strong class="def-name">textscan</strong> <code class="def-code-arguments">(<var class="var">fid</var>, <var class="var">format</var>)</code><a class="copiable-link" href="#index-textscan"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textscan-1"><span><code class="def-type"><var class="var">C</var> =</code> <strong class="def-name">textscan</strong> <code class="def-code-arguments">(<var class="var">fid</var>, <var class="var">format</var>, <var class="var">repeat</var>)</code><a class="copiable-link" href="#index-textscan-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textscan-2"><span><code class="def-type"><var class="var">C</var> =</code> <strong class="def-name">textscan</strong> <code class="def-code-arguments">(<var class="var">fid</var>, <var class="var">format</var>, <var class="var">param</var>, <var class="var">value</var>, …)</code><a class="copiable-link" href="#index-textscan-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textscan-3"><span><code class="def-type"><var class="var">C</var> =</code> <strong class="def-name">textscan</strong> <code class="def-code-arguments">(<var class="var">fid</var>, <var class="var">format</var>, <var class="var">repeat</var>, <var class="var">param</var>, <var class="var">value</var>, …)</code><a class="copiable-link" href="#index-textscan-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textscan-4"><span><code class="def-type"><var class="var">C</var> =</code> <strong class="def-name">textscan</strong> <code class="def-code-arguments">(<var class="var">str</var>, …)</code><a class="copiable-link" href="#index-textscan-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-textscan-5"><span><code class="def-type">[<var class="var">C</var>, <var class="var">position</var>, <var class="var">errmsg</var>] =</code> <strong class="def-name">textscan</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-textscan-5"> ¶</a></span></dt>
<dd><p>Read data from a text file or string.
</p>
<p>The string <var class="var">str</var> or file associated with <var class="var">fid</var> is read from and
parsed according to <var class="var">format</var>. The function is an extension of
<code class="code">strread</code> and <code class="code">textread</code>. Differences include: the ability to
read from either a file or a string, additional options, and additional
format specifiers.
</p>
<p>The input is interpreted as a sequence of words, delimiters (such as
whitespace), and literals. The characters that form delimiters and
whitespace are determined by the options. The format consists of format
specifiers interspersed between literals. In the format, whitespace forms
a delimiter between consecutive literals, but is otherwise ignored.
</p>
<p>The output <var class="var">C</var> is a cell array where the number of columns is determined
by the number of format specifiers.
</p>
<p>The first word of the input is matched to the first specifier of the format
and placed in the first column of the output; the second is matched to the
second specifier and placed in the second column and so forth. If there
are more words than specifiers then the process is repeated until all words
have been processed or the limit imposed by <var class="var">repeat</var> has been met (see
below).
</p>
<p>The string <var class="var">format</var> describes how the words in <var class="var">str</var> should be
parsed. As in <var class="var">fscanf</var>, any (non-whitespace) text in the format that is
not one of these specifiers is considered a literal. If there is a literal
between two format specifiers then that same literal must appear in the
input stream between the matching words.
</p>
<p>The following specifiers are valid:
</p>
<dl class="table">
<dt><code class="code">%f</code></dt>
<dt><code class="code">%f64</code></dt>
<dt><code class="code">%n</code></dt>
<dd><p>The word is parsed as a number and converted to double.
</p>
</dd>
<dt><code class="code">%f32</code></dt>
<dd><p>The word is parsed as a number and converted to single (float).
</p>
</dd>
<dt><code class="code">%d</code></dt>
<dt><code class="code">%d8</code></dt>
<dt><code class="code">%d16</code></dt>
<dt><code class="code">%d32</code></dt>
<dt><code class="code">%d64</code></dt>
<dd><p>The word is parsed as a number and converted to int8, int16, int32, or
int64. If no size is specified then int32 is used.
</p>
</dd>
<dt><code class="code">%u</code></dt>
<dt><code class="code">%u8</code></dt>
<dt><code class="code">%u16</code></dt>
<dt><code class="code">%u32</code></dt>
<dt><code class="code">%u64</code></dt>
<dd><p>The word is parsed as a number and converted to uint8, uint16, uint32, or
uint64. If no size is specified then uint32 is used.
</p>
</dd>
<dt><code class="code">%s</code></dt>
<dd><p>The word is parsed as a string ending at the last character before
whitespace, an end-of-line, or a delimiter specified in the options.
</p>
</dd>
<dt><code class="code">%q</code></dt>
<dd><p>The word is parsed as a "quoted string".
If the first character of the string is a double quote (") then the string
includes everything until a matching double quote—including whitespace,
delimiters, and end-of-line characters. If a pair of consecutive double
quotes appears in the input, it is replaced in the output by a single
double quote. For examples, the input "He said ""Hello""" would
return the value ’He said "Hello"’.
</p>
</dd>
<dt><code class="code">%c</code></dt>
<dd><p>The next character of the input is read.
This includes delimiters, whitespace, and end-of-line characters.
</p>
</dd>
<dt><code class="code">%[…]</code></dt>
<dt><code class="code">%[^…]</code></dt>
<dd><p>In the first form, the word consists of the longest run consisting of only
characters between the brackets. Ranges of characters can be specified by
a hyphen; for example, %[0-9a-zA-Z] matches all alphanumeric characters (if
the underlying character set is ASCII). Since <small class="sc">MATLAB</small> treats hyphens
literally, this expansion only applies to alphanumeric characters. To
include ’-’ in the set, it should appear first or last in the brackets; to
include ’]’, it should be the first character. If the first character is
’^’ then the word consists of characters <strong class="strong">not</strong> listed.
</p>
</dd>
<dt><code class="code">%N…</code></dt>
<dd><p>For %s, %c %d, %f, %n, %u, an optional width can be specified as %Ns, etc.
where N is an integer > 1. For %c, this causes exactly N characters to be
read instead of a single character. For the other specifiers, it is an
upper bound on the number of characters read; normal delimiters can cause
fewer characters to be read. For complex numbers, this limit applies to
the real and imaginary components individually. For %f and %n, format
specifiers like %N.Mf are allowed, where M is an upper bound on number of
characters after the decimal point to be considered; subsequent digits are
skipped. For example, the specifier %8.2f would read 12.345e6 as 1.234e7.
</p>
</dd>
<dt><code class="code">%*…</code></dt>
<dd><p>The word specified by the remainder of the conversion specifier is skipped.
</p>
</dd>
<dt><code class="code">literals</code></dt>
<dd><p>In addition the format may contain literal character strings; these will be
skipped during reading. If the input string does not match this literal,
the processing terminates.
</p></dd>
</dl>
<p>Parsed words corresponding to the first specifier are returned in the first
output argument and likewise for the rest of the specifiers.
</p>
<p>By default, if there is only one input argument, <var class="var">format</var> is <code class="t">"%f"</code>.
This means that numbers are read from the input into a single column vector.
If <var class="var">format</var> is explicitly empty (<code class="code">""</code>) then textscan will
return data in a number of columns matching the number of fields on the
first data line of the input. Either of these is suitable only when the
input is exclusively numeric.
</p>
<p>For example, the string
</p>
<div class="example smallexample">
<div class="group"><pre class="example-preformatted"><var class="var">str</var> = "\
Bunny Bugs 5.5\n\
Duck Daffy -7.5e-5\n\
Penguin Tux 6"
</pre></div></div>
<p>can be read using
</p>
<div class="example">
<pre class="example-preformatted"><var class="var">a</var> = textscan (<var class="var">str</var>, "%s %s %f");
</pre></div>
<p>The optional numeric argument <var class="var">repeat</var> can be used for limiting the
number of items read:
</p>
<dl class="table">
<dt>-1</dt>
<dd><p>Read all of the string or file until the end (default).
</p>
</dd>
<dt>N</dt>
<dd><p>Read until the first of two conditions occurs: 1) the format has been
processed N times, or 2) N lines of the input have been processed. Zero
(0) is an acceptable value for <var class="var">repeat</var>. Currently, end-of-line
characters inside %q, %c, and %[…]$ conversions do not contribute to
the line count. This is incompatible with <small class="sc">MATLAB</small> and may change in
future.
</p></dd>
</dl>
<p>The behavior of <code class="code">textscan</code> can be changed via property/value pairs.
The following properties are recognized:
</p>
<dl class="table">
<dt><code class="code">"BufSize"</code></dt>
<dd><p>This specifies the number of bytes to use for the internal buffer.
A modest speed improvement may be obtained by setting this to a large value
when reading a large file, especially if the input contains long strings.
The default is 4096, or a value dependent on <var class="var">n</var> if that is specified.
</p>
</dd>
<dt><code class="code">"CollectOutput"</code></dt>
<dd><p>A value of 1 or true instructs <code class="code">textscan</code> to concatenate consecutive
columns of the same class in the output cell array. A value of 0 or false
(default) leaves output in distinct columns.
</p>
</dd>
<dt><code class="code">"CommentStyle"</code></dt>
<dd><p>Specify parts of the input which are considered comments and will be
skipped. <var class="var">value</var> is the comment style and can be either (1) A string
or 1x1 cell string, to skip everything to the right of it; (2) A cell array
of two strings, to skip everything between the first and second strings.
Comments are only parsed where whitespace is accepted and do not act as
delimiters.
</p>
</dd>
<dt><code class="code">"Delimiter"</code></dt>
<dd><p>If <var class="var">value</var> is a string, any character in <var class="var">value</var> will be used to
split the input into words. If <var class="var">value</var> is a cell array of strings,
any string in the array will be used to split the input into words.
(default value = any whitespace.)
</p>
</dd>
<dt><code class="code">"EmptyValue"</code></dt>
<dd><p>Value to return for empty numeric values in non-whitespace delimited data.
The default is NaN. When the data type does not support NaN (int32 for
example), then the default is zero.
</p>
</dd>
<dt><code class="code">"EndOfLine"</code></dt>
<dd><p><var class="var">value</var> can be either an empty or one character specifying the
end-of-line character, or the pair
<code class="code">"\r\n"</code> (CRLF).
In the latter case, any of
<code class="code">"\r"</code>, <code class="code">"\n"</code> or
<code class="code">"\r\n"</code> is counted as a (single)
newline. If no value is given,
<code class="code">"\r\n"</code> is used.
</p>
</dd>
<dt><code class="code">"HeaderLines"</code></dt>
<dd><p>The first <var class="var">value</var> number of lines of <var class="var">fid</var> are skipped. Note that
this does not refer to the first non-comment lines, but the first lines of
any type.
</p>
</dd>
<dt><code class="code">"MultipleDelimsAsOne"</code></dt>
<dd><p>If <var class="var">value</var> is nonzero, treat a series of consecutive delimiters,
without whitespace in between, as a single delimiter. Consecutive
delimiter series need not be vertically aligned. Without this option, a
single delimiter before the end of the line does not cause the line to be
considered to end with an empty value, but a single delimiter at the start
of a line causes the line to be considered to start with an empty value.
</p>
</dd>
<dt><code class="code">"TreatAsEmpty"</code></dt>
<dd><p>Treat single occurrences (surrounded by delimiters or whitespace) of the
string(s) in <var class="var">value</var> as missing values.
</p>
</dd>
<dt><code class="code">"ReturnOnError"</code></dt>
<dd><p>If set to numerical 1 or true, return normally as soon as an error is
encountered, such as trying to read a string using <code class="code">%f</code>.
If set to 0 or false, return an error and no data.
</p>
</dd>
<dt><code class="code">"Whitespace"</code></dt>
<dd><p>Any character in <var class="var">value</var> will be interpreted as whitespace and trimmed;
The default value for whitespace is
<code class="code">"
\b\r\n\t"</code>
(note the space). Unless whitespace is set to <code class="code">""</code> (empty) AND at
least one <code class="code">"%s"</code> format conversion specifier is supplied, a space is
always part of whitespace.
</p>
</dd>
</dl>
<p>When the number of words in <var class="var">str</var> or <var class="var">fid</var> doesn’t match an exact
multiple of the number of format conversion specifiers, <code class="code">textscan</code>’s
behavior depends on whether the last character of the string or file is an
end-of-line as specified by the <code class="code">EndOfLine</code> option:
</p>
<dl class="table">
<dt>last character = end-of-line</dt>
<dd><p>Data columns are padded with empty fields, NaN or 0 (for integer fields) so
that all columns have equal length
</p>
</dd>
<dt>last character is not end-of-line</dt>
<dd><p>Data columns are not padded; <code class="code">textscan</code> returns columns of unequal
length
</p></dd>
</dl>
<p>The second output <var class="var">position</var> provides the location, in characters
from the beginning of the file or string, where processing stopped.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdlmread">dlmread</a>, <a class="ref" href="Formatted-Input.html#XREFfscanf">fscanf</a>, <a class="ref" href="#XREFload">load</a>, <a class="ref" href="Numerical-Data-and-Strings.html#XREFstrread">strread</a>, <a class="ref" href="#XREFtextread">textread</a>.
</p></dd></dl>
<p>The <code class="code">importdata</code> function has the ability to work with a wide
variety of data.
</p>
<a class="anchor" id="XREFimportdata"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-importdata"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">importdata</strong> <code class="def-code-arguments">(<var class="var">fname</var>)</code><a class="copiable-link" href="#index-importdata"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-importdata-1"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">importdata</strong> <code class="def-code-arguments">(<var class="var">fname</var>, <var class="var">delimiter</var>)</code><a class="copiable-link" href="#index-importdata-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-importdata-2"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">importdata</strong> <code class="def-code-arguments">(<var class="var">fname</var>, <var class="var">delimiter</var>, <var class="var">header_rows</var>)</code><a class="copiable-link" href="#index-importdata-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-importdata-3"><span><code class="def-type">[<var class="var">A</var>, <var class="var">delimiter</var>] =</code> <strong class="def-name">importdata</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-importdata-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-importdata-4"><span><code class="def-type">[<var class="var">A</var>, <var class="var">delimiter</var>, <var class="var">header_rows</var>] =</code> <strong class="def-name">importdata</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-importdata-4"> ¶</a></span></dt>
<dd><p>Import data from the file <var class="var">fname</var>.
</p>
<p>Input parameters:
</p>
<ul class="itemize mark-bullet">
<li><var class="var">fname</var>
The name of the file containing data.
</li><li><var class="var">delimiter</var>
The character separating columns of data. Use <code class="code">\t</code> for tab.
(Only valid for ASCII files)
</li><li><var class="var">header_rows</var>
The number of header rows before the data begins. (Only valid for ASCII
files)
</li></ul>
<p>Different file types are supported:
</p>
<ul class="itemize mark-bullet">
<li>ASCII table
<p>Import ASCII table using the specified number of header rows and the
specified delimiter.
</p>
</li><li>Image file
</li><li><small class="sc">MATLAB</small> file
</li><li>Spreadsheet files (depending on external software)
</li><li>WAV file
</li></ul>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFtextscan">textscan</a>, <a class="ref" href="#XREFdlmread">dlmread</a>, <a class="ref" href="#XREFcsvread">csvread</a>, <a class="ref" href="#XREFload">load</a>.
</p></dd></dl>
<p>After importing, the data may need to be transformed before further analysis.
The <code class="code">rescale</code> function can shift and normalize a data set to a specified
range.
</p>
<a class="anchor" id="XREFrescale"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-rescale"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">rescale</strong> <code class="def-code-arguments">(<var class="var">A</var>)</code><a class="copiable-link" href="#index-rescale"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-rescale-1"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">rescale</strong> <code class="def-code-arguments">(<var class="var">A</var>, <var class="var">l</var>, <var class="var">u</var>)</code><a class="copiable-link" href="#index-rescale-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-rescale-2"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">rescale</strong> <code class="def-code-arguments">(…, "inputmin", <var class="var">inmin</var>)</code><a class="copiable-link" href="#index-rescale-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-rescale-3"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">rescale</strong> <code class="def-code-arguments">(…, "inputmax", <var class="var">inmax</var>)</code><a class="copiable-link" href="#index-rescale-3"> ¶</a></span></dt>
<dd><p>Scale matrix elements to a specified range of values.
</p>
<p>When called with a single matrix argument <var class="var">A</var>, rescale elements to
occupy the interval [0, 1].
</p>
<p>The optional inputs <code class="code">[<var class="var">l</var>, <var class="var">u</var>]</code> will scale <var class="var">A</var> to the
interval with lower bound <var class="var">l</var> and upper bound <var class="var">u</var>.
</p>
<p>The optional input <code class="code">"inputmin"</code> replaces all elements less than
the specified value <var class="var">inmin</var> with <var class="var">inmin</var>. Similarly, the optional
input <code class="code">"inputmax"</code> replaces all elements greater than the specified
value <var class="var">inmax</var> with <var class="var">inmax</var>. If unspecified the minimum and maximum
are taken from the data itself (<code class="code"><var class="var">inmin</var> = min (A(:))</code><!-- /@w --> and
<code class="code"><var class="var">inmax</var> = max (A(:))</code><!-- /@w -->).
</p>
<p>Programming Notes:
The applied formula is
<var class="var">B</var> = <var class="var">l</var> + ((<var class="var">A</var> - <var class="var">inmin</var>) ./ (<var class="var">inmax</var> - <var class="var">inmin</var>))
.* (<var class="var">u</var> - <var class="var">l</var>)
</p>
<p>The class of the output matrix <var class="var">B</var> is single if the input <var class="var">A</var> is
single, but otherwise is of class double for inputs which are of double,
integer, or logical type.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Descriptive-Statistics.html#XREFbounds">bounds</a>, <a class="ref" href="Utility-Functions.html#XREFmin">min</a>, <a class="ref" href="Utility-Functions.html#XREFmax">max</a>.
</p></dd></dl>
<ul class="mini-toc">
<li><a href="Saving-Data-on-Unexpected-Exits.html" accesskey="1">Saving Data on Unexpected Exits</a></li>
</ul>
</div>
<hr>
<div class="nav-panel">
<p>
Previous: <a href="Terminal-Input.html">Terminal Input</a>, Up: <a href="Basic-Input-and-Output.html">Basic Input and Output</a> [<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>
|
