Writes values of data structures to a binary file opened by %OPEN.
Options
SEPARATOR = scalar or text |
Separator character as a literal character or a scalar giving an ASCII code (0-255); default * i.e. none |
TERMINATOR = string token |
Terminator to use at the end of a text (null, newline) default null |
POSITION = scalar |
File position at which to write the data; default 0 writes at the current position |
Parameters
DATA = texts, scalars, variates or matrices |
Data structures to write to the file |
FORMATTED = string tokens |
Output format to use when writing the structures (bit, byte, shortint, longint, real, double, string, text, rawtext, factor); default depends on the type of data structure |
NBYTES = scalars |
Saves the number of bytes written to the file |
Description
%WRITE writes values of data structures to the binary file opened by %OPEN. The data structures are specified by the DATA parameter.
The FORMATTED parameter specifies the format to be used to write the structures to the file. The available formats are:
bit the numbers (0,1) in the structure are combined as single bits into bytes (e.g. 1,0,0,1,0,1,0,1,0,1,0,0,1,1,1,1 would give the two bytes 0x41CF)
byte the numbers are written as a single byte (0 to 255)
shortint the numbers are written as a 2-byte signed integer (-31767 to 32767)
longint the numbers are written as 4-byte signed integer; default for a scalar
real the numbers are written as single precision (REAL*4) values (missing value = -1e37)
double the numbers are written as double precision (REAL*8) values (missing value = -1e307); default for a variate or matrix
string the texts are written with a single byte giving the length, followed by the ASCII bytes in UTF8 format
text the texts are written with 4 bytes giving the length, followed by the ASCII bytes in UTF8 format, default for a text
rawtext the texts are written as ASCII bytes in UTF8 format
factor the values are compressed into as few bytes as possible; the default for a factor
The factor format can be used only by factors. The number of bytes per item depends on the number of levels in the factor. For 1-3 levels, 4 items are combined per byte, for 4-15 levels, 2 items are combined per byte, for 16-255 levels, each item is written in a single byte, for 256-65535 levels, each item is written in a two bytes, otherwise each item is written in 4 bytes. A value of 0 is used to represent a missing value in the factor. The formats string, text and rawtext can be used only by texts.
The SEPARATOR and TERMINATOR options are used only for FORMAT=rawtext. The SEPARATOR option can specify a single ASCII character to be used between items. By default there is no separator. The TERMINATOR option specifies what to write after each string. The default setting null uses a null character (byte 0 as in C strings). With the newline setting, the two newline characters (bytes 13 and 10) are use to terminate strings.
The POSITION option can be used to reset the position where the values are written. The default of 0 writes the values at the current position in the file.
The NBYTES option saves the number of bytes that have been written to the file.
Options: SEPARATOR, TERMINATOR, POSITION.
Parameters: DATA, FORMATTED, NBYTES.
Action with RESTRICT
%WRITE ignores restrictions on DATA.
See also
Directives: %OPEN, %CLOSE, %FPOSITION.
Commands for: Program control.