doc/info/numericalio.texi

   1 @menu
   2 * Introduction to numericalio::
   3 * Functions and Variables for plain-text input and output::
   4 * Functions and Variables for binary input and output::
   5 @end menu
   6
   7 @anchor{numericalio}
   8 @node Introduction to numericalio, Functions and Variables for plain-text input and output, Package numericalio, Package numericalio
   9 @section Introduction to numericalio
  10
  11 @code{numericalio} is a collection of functions to read and write files and streams.
  12 Functions for plain-text input and output
  13 can read and write numbers (integer, float, or bigfloat), symbols, and strings.
  14 Functions for binary input and output
  15 can read and write only floating-point numbers.
  16
  17 If there already exists a list, matrix, or array object to store input data,
  18 @code{numericalio} input functions can write data into that object.
  19 Otherwise, @code{numericalio} can guess, to some degree, the structure of an object
  20 to store the data, and return that object.
  21
  22 @opencatbox{Categories:}
  23 @category{File input}
  24 @category{File output}
  25 @category{Share packages}
  26 @category{Package numericalio}
  27 @closecatbox
  28
  29 @subsection Plain-text input and output
  30
  31 In plain-text input and output,
  32 it is assumed that each item to read or write is an atom:
  33 an integer, float, bigfloat, string, or symbol,
  34 and not a rational or complex number or any other kind of nonatomic expression.
  35 The @code{numericalio} functions may attempt to do something sensible faced with nonatomic expressions,
  36 but the results are not specified here and subject to change.
  37
  38 Atoms in both input and output files have the same format as
  39 in Maxima batch files or the interactive console.
  40 In particular, strings are enclosed in double quotes,
  41 backslash @code{\} prevents any special interpretation of the next character,
  42 and the question mark @code{?} is recognized at the beginning of a symbol
  43 to mean a Lisp symbol (as opposed to a Maxima symbol).
  44 No continuation character (to join broken lines) is recognized.
  45
  46 @subsection Separator flag values for input
  47
  48 The functions for plain-text input and output take an optional argument,
  49 @var{separator_flag}, that tells what character separates data.
  50
  51 For plain-text input, these values of @var{separator_flag} are recognized:
  52 @code{comma} for comma separated values,
  53 @code{pipe} for values separated by the vertical bar character @code{|},
  54 @code{semicolon} for values separated by semicolon @code{;},
  55 and @code{space} for values separated by space or tab characters.
  56 Equivalently, the separator may be specified as a string of one character:
  57 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
  58 @code{" "} (space), or @code{"    "} (tab).
  59
  60 If the file name ends in @code{.csv} and @var{separator_flag} is not specified,
  61 @code{comma} is assumed.
  62 If the file name ends in something other than @code{.csv} and @code{separator_flag} is not specified,
  63 @code{space} is assumed.
  64
  65 In plain-text input, multiple successive space and tab characters count as a single separator.
  66 However, multiple comma, pipe, or semicolon characters are significant.
  67 Successive comma, pipe, or semicolon characters (with or without intervening spaces or tabs)
  68 are considered to have @code{false} between the separators.
  69 For example, @code{1234,,Foo} is treated the same as @code{1234,false,Foo}.
  70
  71 @subsection Separator flag values for output
  72
  73 For plain-text output, @code{tab}, for values separated by the tab character,
  74 is recognized as a value of @var{separator_flag},
  75 as well as @code{comma}, @code{pipe}, @code{semicolon}, and @code{space}.
  76
  77 In plain-text output, @code{false} atoms are written as such;
  78 a list @code{[1234, false, Foo]} is written @code{1234,false,Foo},
  79 and there is no attempt to collapse the output to @code{1234,,Foo}.
  80
  81 @subsection Binary floating-point input and output
  82
  83 @code{numericalio} functions can read and write 8-byte IEEE 754 floating-point numbers.
  84 These numbers can be stored either least significant byte first or most significant byte first,
  85 according to the global flag set by @code{assume_external_byte_order}.
  86 If not specified, @code{numericalio} assumes the external byte order is most-significant byte first.
  87
  88 Other kinds of numbers are coerced to 8-byte floats;
  89 @code{numericalio} cannot read or write binary non-numeric data.
  90
  91 Some Lisp implementations do not recognize IEEE 754 special values
  92 (positive and negative infinity, not-a-number values, denormalized values).
  93 The effect of reading such values with @code{numericalio} is undefined.
  94
  95 @code{numericalio} includes functions to open a stream for reading or writing a stream of bytes.
  96
  97
  98 @node Functions and Variables for plain-text input and output, Functions and Variables for binary input and output, Introduction to numericalio, Package numericalio
  99 @section Functions and Variables for plain-text input and output
 100
 101 @anchor{read_matrix}
 102 @deffn {Function} read_matrix @
 103 @fname{read_matrix} (@var{S}) @
 104 @fname{read_matrix} (@var{S}, @var{M}) @
 105 @fname{read_matrix} (@var{S}, @var{separator_flag}) @
 106 @fname{read_matrix} (@var{S}, @var{M}, @var{separator_flag})
 107
 108 @code{read_matrix(@var{S})} reads the source @var{S} and returns its entire content as a matrix.
 109 The size of the matrix is inferred from the input data;
 110 each line of the file becomes one row of the matrix.
 111 If some lines have different lengths, @code{read_matrix} complains.
 112
 113 @code{read_matrix(@var{S}, @var{M})} read the source @var{S} into the matrix @var{M},
 114 until @var{M} is full or the source is exhausted.
 115 Input data are read into the matrix in row-major order;
 116 the input need not have the same number of rows and columns as @var{M}.
 117
 118 The source @var{S} may be a file name or a stream which for example allows skipping
 119 the very first line of a file (that may be useful, if you read CSV data, where the
 120 first line often contains the description of the columns):
 121 @example
 122 s : openr("data.txt");
 123 readline(s);  /* skip the first line */
 124 M : read_matrix(s, 'comma);  /* read the following (comma-separated) lines into matrix M */
 125 close(s);
 126 @end example
 127
 128 The recognized values of @var{separator_flag} are
 129 @code{comma}, @code{pipe}, @code{semicolon}, and @code{space}.
 130 Equivalently, the separator may be specified as a string of one character:
 131 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
 132 @code{" "} (space), or @code{"    "} (tab).
 133 If @var{separator_flag} is not specified, the file is assumed space-delimited.
 134
 135 See also @mrefcomma{openr} @mrefcomma{read_array} @mrefcomma{read_hashed_array}
 136 @mrefcomma{read_list} @mrefcomma{read_binary_matrix} @mref{write_data} and
 137 @mrefdot{read_nested_list}
 138
 139 @opencatbox{Categories:}
 140 @category{Package numericalio}
 141 @category{File input}
 142 @closecatbox
 143
 144 @end deffn
 145
 146 @anchor{read_array}
 147 @deffn {Function} read_array @
 148 @fname{read_array} (@var{S}, @var{A}) @
 149 @fname{read_array} (@var{S}, @var{A}, @var{separator_flag})
 150
 151 Reads the source @var{S} into the array @var{A},
 152 until @var{A} is full or the source is exhausted.
 153 Input data are read into the array in row-major order;
 154 the input need not conform to the dimensions of @var{A}.
 155
 156 The source @var{S} may be a file name or a stream.
 157
 158 The recognized values of @var{separator_flag} are
 159 @code{comma}, @code{pipe}, @code{semicolon}, and @code{space}.
 160 Equivalently, the separator may be specified as a string of one character:
 161 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
 162 @code{" "} (space), or @code{"    "} (tab).
 163 If @var{separator_flag} is not specified, the file is assumed space-delimited.
 164
 165 See also @mrefcomma{openr} @mrefcomma{read_matrix} @mrefcomma{read_hashed_array}
 166 @mrefcomma{read_list} @mref{read_binary_array} and @mrefdot{read_nested_list}
 167
 168 @opencatbox{Categories:}
 169 @category{Package numericalio}
 170 @category{File input}
 171 @closecatbox
 172
 173 @end deffn
 174
 175 @anchor{read_hashed_array}
 176 @deffn {Function} read_hashed_array @
 177 @fname{read_hashed_array} (@var{S}, @var{A}) @
 178 @fname{read_hashed_array} (@var{S}, @var{A}, @var{separator_flag})
 179
 180 Reads the source @var{S} and returns its entire content as a @mrefdot{hashed array}
 181 The source @var{S} may be a file name or a stream.
 182
 183 @code{read_hashed_array} treats the first item on each line as a hash key,
 184 and associates the remainder of the line (as a list) with the key.
 185 For example,
 186 the line @code{567 12 17 32 55} is equivalent to @code{A[567]: [12, 17, 32, 55]$}.
 187 Lines need not have the same numbers of elements.
 188
 189 The recognized values of @var{separator_flag} are
 190 @code{comma}, @code{pipe}, @code{semicolon}, and @code{space}.
 191 Equivalently, the separator may be specified as a string of one character:
 192 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
 193 @code{" "} (space), or @code{"    "} (tab).
 194 If @var{separator_flag} is not specified, the file is assumed space-delimited.
 195
 196 See also @mrefcomma{openr} @mrefcomma{read_matrix} @mrefcomma{read_array}
 197 @mref{read_list} and @mrefdot{read_nested_list}
 198
 199 @opencatbox{Categories:}
 200 @category{Package numericalio}
 201 @category{File input}
 202 @closecatbox
 203
 204 @end deffn
 205
 206 @anchor{read_nested_list}
 207 @deffn {Function} read_nested_list @
 208 @fname{read_nested_list} (@var{S}) @
 209 @fname{read_nested_list} (@var{S}, @var{separator_flag})
 210
 211 Reads the source @var{S} and returns its entire content as a nested list.
 212 The source @var{S} may be a file name or a stream.
 213
 214 @code{read_nested_list} returns a list which has a sublist for each
 215 line of input. Lines need not have the same numbers of elements.
 216 Empty lines are @i{not} ignored: an empty line yields an empty sublist.
 217
 218 The recognized values of @var{separator_flag} are
 219 @code{comma}, @code{pipe}, @code{semicolon}, and @code{space}.
 220 Equivalently, the separator may be specified as a string of one character:
 221 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
 222 @code{" "} (space), or @code{"    "} (tab).
 223 If @var{separator_flag} is not specified, the file is assumed space-delimited.
 224
 225 See also @mrefcomma{openr} @mrefcomma{read_matrix} @mrefcomma{read_array}
 226 @mref{read_list} and @mrefdot{read_hashed_array}
 227
 228 @opencatbox{Categories:}
 229 @category{Package numericalio}
 230 @category{File input}
 231 @closecatbox
 232
 233 @end deffn
 234
 235 @anchor{read_list}
 236 @deffn {Function} read_list @
 237 @fname{read_list} (@var{S}) @
 238 @fname{read_list} (@var{S}, @var{L}) @
 239 @fname{read_list} (@var{S}, @var{separator_flag}) @
 240 @fname{read_list} (@var{S}, @var{L}, @var{separator_flag})
 241
 242 @code{read_list(@var{S})} reads the source @var{S} and returns its entire content as a flat list.
 243
 244 @code{read_list(@var{S}, @var{L})} reads the source @var{S} into the list @var{L},
 245 until @var{L} is full or the source is exhausted.
 246
 247 The source @var{S} may be a file name or a stream.
 248
 249 The recognized values of @var{separator_flag} are
 250 @code{comma}, @code{pipe}, @code{semicolon}, and @code{space}.
 251 Equivalently, the separator may be specified as a string of one character:
 252 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
 253 @code{" "} (space), or @code{"    "} (tab).
 254 If @var{separator_flag} is not specified, the file is assumed space-delimited.
 255
 256 See also @mrefcomma{openr} @mrefcomma{read_matrix} @mrefcomma{read_array}
 257 @mrefcomma{read_nested_list} @mref{read_binary_list} and @mrefdot{read_hashed_array}
 258
 259 @opencatbox{Categories:}
 260 @category{Package numericalio}
 261 @category{File input}
 262 @closecatbox
 263
 264 @end deffn
 265
 266 @anchor{write_data}
 267 @deffn {Function} write_data @
 268 @fname{write_data} (@var{X}, @var{D}) @
 269 @fname{write_data} (@var{X}, @var{D}, @var{separator_flag})
 270
 271 Writes the object @var{X} to the destination @var{D}.
 272
 273 @code{write_data} writes a matrix in row-major order,
 274 with one line per row.
 275
 276 @code{write_data} writes an array created by @code{array} or @code{make_array}
 277 in row-major order, with a new line at the end of every slab.
 278 Higher-dimensional slabs are separated by additional new lines.
 279
 280 @code{write_data} writes a hashed array with each key followed by
 281 its associated list on one line.
 282
 283 @code{write_data} writes a nested list with each sublist on one line.
 284
 285 @code{write_data} writes a flat list all on one line.
 286
 287 The destination @var{D} may be a file name or a stream.
 288 When the destination is a file name,
 289 the global variable @code{file_output_append} governs
 290 whether the output file is appended or truncated.
 291 When the destination is a stream,
 292 no special action is taken by @code{write_data} after all the data are written;
 293 in particular, the stream remains open.
 294
 295 The recognized values of @var{separator_flag} are
 296 @code{comma}, @code{pipe}, @code{semicolon}, @code{space}, and @code{tab}.
 297 Equivalently, the separator may be specified as a string of one character:
 298 @code{","} (comma), @code{"|"} (pipe), @code{";"} (semicolon),
 299 @code{" "} (space), or @code{"    "} (tab).
 300 If @var{separator_flag} is not specified, the file is assumed space-delimited.
 301
 302 See also @mref{openw} and @mrefdot{read_matrix}
 303
 304 @opencatbox{Categories:}
 305 @category{Package numericalio}
 306 @category{File output}
 307 @closecatbox
 308
 309 @end deffn
 310
 311 @node Functions and Variables for binary input and output, , Functions and Variables for plain-text input and output, Package numericalio
 312 @section Functions and Variables for binary input and output
 313
 314 @anchor{assume_external_byte_order}
 315 @deffn {Function} assume_external_byte_order (@var{byte_order_flag})
 316 Tells @code{numericalio} the byte order for reading and writing binary data.
 317 Two values of @var{byte_order_flag} are recognized:
 318 @code{lsb} which indicates least-significant byte first, also called little-endian byte order;
 319 and @code{msb} which indicates most-significant byte first, also called big-endian byte order.
 320
 321 If not specified, @code{numericalio} assumes the external byte order is most-significant byte first.
 322
 323 @opencatbox{Categories:}
 324 @category{Package numericalio}
 325 @closecatbox
 326 @end deffn
 327
 328 @anchor{openr_binary}
 329 @deffn {Function} openr_binary (@var{file_name})
 330 Returns an input stream of 8-bit unsigned bytes to read the file named by @var{file_name}.
 331
 332 See also @mref{openw_binary} and @mrefdot{openr}
 333
 334 @opencatbox{Categories:}
 335 @category{Package numericalio}
 336 @category{File input}
 337 @closecatbox
 338 @end deffn
 339
 340 @anchor{openw_binary}
 341 @deffn {Function} openw_binary (@var{file_name})
 342 Returns an output stream of 8-bit unsigned bytes to write the file named by @var{file_name}.
 343
 344 See also @mrefcomma{openr_binary} @mref{opena_binary} and @mrefdot{openw}
 345
 346 @opencatbox{Categories:}
 347 @category{Package numericalio}
 348 @category{File output}
 349 @closecatbox
 350 @end deffn
 351
 352 @anchor{opena_binary}
 353 @deffn {Function} opena_binary (@var{file_name})
 354 Returns an output stream of 8-bit unsigned bytes to append the file named by @var{file_name}.
 355
 356 @opencatbox{Categories:}
 357 @category{Package numericalio}
 358 @category{File output}
 359 @closecatbox
 360 @end deffn
 361
 362 @anchor{read_binary_matrix}
 363 @deffn {Function} read_binary_matrix (@var{S}, @var{M})
 364 Reads binary 8-byte floating point numbers from the source @var{S} into the matrix @var{M}
 365 until @var{M} is full, or the source is exhausted.
 366 Elements of @var{M} are read in row-major order.
 367
 368 The source @var{S} may be a file name or a stream.
 369
 370 The byte order in elements of the source is specified by @code{assume_external_byte_order}.
 371
 372 See also @mrefdot{read_matrix}
 373
 374 @opencatbox{Categories:}
 375 @category{Package numericalio}
 376 @category{File input}
 377 @closecatbox
 378 @end deffn
 379
 380 @anchor{read_binary_array}
 381 @deffn {Function} read_binary_array (@var{S}, @var{A})
 382 Reads binary 8-byte floating point numbers from the source @var{S} into the array @var{A}
 383 until @var{A} is full, or the source is exhausted.
 384 @var{A} must be an array created by @code{array} or @code{make_array}.
 385 Elements of @var{A} are read in row-major order.
 386
 387 The source @var{S} may be a file name or a stream.
 388
 389 The byte order in elements of the source is specified by @code{assume_external_byte_order}.
 390
 391 See also @mrefdot{read_array}
 392
 393 @opencatbox{Categories:}
 394 @category{Package numericalio}
 395 @category{File input}
 396 @closecatbox
 397 @end deffn
 398
 399 @anchor{read_binary_list}
 400 @deffn {Function} read_binary_list @
 401 @fname{read_binary_list} (@var{S}) @
 402 @fname{read_binary_list} (@var{S}, @var{L})
 403
 404 @code{read_binary_list(@var{S})} reads the entire content of the source @var{S}
 405 as a sequence of binary 8-byte floating point numbers, and returns it as a list.
 406 The source @var{S} may be a file name or a stream.
 407
 408 @code{read_binary_list(@var{S}, @var{L})} reads 8-byte binary floating point numbers
 409 from the source @var{S} until the list @var{L} is full, or the source is exhausted.
 410
 411 The byte order in elements of the source is specified by @code{assume_external_byte_order}.
 412
 413 See also @mrefdot{read_list}
 414
 415 @opencatbox{Categories:}
 416 @category{Package numericalio}
 417 @category{File input}
 418 @closecatbox
 419 @end deffn
 420
 421 @anchor{write_binary_data}
 422 @deffn {Function} write_binary_data (@var{X}, @var{D})
 423
 424 Writes the object @var{X}, comprising binary 8-byte IEEE 754 floating-point numbers,
 425 to the destination @var{D}.
 426 Other kinds of numbers are coerced to 8-byte floats.
 427 @code{write_binary_data} cannot write non-numeric data.
 428
 429 The object @var{X} may be a list, a nested list, a matrix,
 430 or an array created by @code{array} or @code{make_array};
 431 @var{X} cannot be a hashed array or any other type of object.
 432 @code{write_binary_data} writes nested lists, matrices, and arrays in row-major order.
 433
 434 The destination @var{D} may be a file name or a stream.
 435 When the destination is a file name,
 436 the global variable @code{file_output_append} governs
 437 whether the output file is appended or truncated.
 438 When the destination is a stream,
 439 no special action is taken by @code{write_binary_data} after all the data are written;
 440 in particular, the stream remains open.
 441
 442 The byte order in elements of the destination
 443 is specified by @code{assume_external_byte_order}.
 444
 445 See also @mrefdot{write_data}
 446
 447 @opencatbox{Categories:}
 448 @category{Package numericalio}
 449 @category{File output}
 450 @closecatbox
 451 @end deffn