### 76.2 Functions and Variables for plain-text input and output

Function: read_matrix
`read_matrix` (S)
`read_matrix` (S, M)
`read_matrix` (S, separator_flag)
`read_matrix` (S, M, separator_flag)

  `read_matrix(S)` reads the source S and returns its entire content as a matrix. The size of the matrix is inferred from the input data; each line of the file becomes one row of the matrix. If some lines have different lengths, `read_matrix` complains.

  `read_matrix(S, M)` read the source S into the matrix M, until M is full or the source is exhausted. Input data are read into the matrix in row-major order; the input need not have the same number of rows and columns as M.

  The source S may be a file name or a stream which for example allows skipping the very first line of a file (that may be useful, if you read CSV data, where the first line often contains the description of the columns):

      s : openr("data.txt");
      readline(s);  /* skip the first line */
      M : read_matrix(s, 'comma);  /* read the following (comma-separated) lines into matrix M */
      close(s);

  The recognized values of separator_flag are `comma`, `pipe`, `semicolon`, and `space`. Equivalently, the separator may be specified as a string of one character: `","` (comma), `"|"` (pipe), `";"` (semicolon), `" "` (space), or `" "` (tab). If separator_flag is not specified, the file is assumed space-delimited.

  See also `openr`, `read_array`, `read_hashed_array`, `read_list`, `read_binary_matrix`, `write_data` and `read_nested_list`.

  Categories:Package numericalio ·File input ·

Function: read_array
`read_array` (S, A)
`read_array` (S, A, separator_flag)

  Reads the source S into the array A, until A is full or the source is exhausted. Input data are read into the array in row-major order; the input need not conform to the dimensions of A.

  The source S may be a file name or a stream.

  The recognized values of separator_flag are `comma`, `pipe`, `semicolon`, and `space`. Equivalently, the separator may be specified as a string of one character: `","` (comma), `"|"` (pipe), `";"` (semicolon), `" "` (space), or `" "` (tab). If separator_flag is not specified, the file is assumed space-delimited.

  See also `openr`, `read_matrix`, `read_hashed_array`, `read_list`, `read_binary_array` and `read_nested_list`.

  Categories:Package numericalio ·File input ·

Function: read_hashed_array
`read_hashed_array` (S, A)
`read_hashed_array` (S, A, separator_flag)

  Reads the source S and returns its entire content as a `hashed array`. The source S may be a file name or a stream.

  `read_hashed_array` treats the first item on each line as a hash key, and associates the remainder of the line (as a list) with the key. For example, the line `567 12 17 32 55` is equivalent to `A[567]: [12, 17, 32, 55]$`. Lines need not have the same numbers of elements.

  The recognized values of separator_flag are `comma`, `pipe`, `semicolon`, and `space`. Equivalently, the separator may be specified as a string of one character: `","` (comma), `"|"` (pipe), `";"` (semicolon), `" "` (space), or `" "` (tab). If separator_flag is not specified, the file is assumed space-delimited.

  See also `openr`, `read_matrix`, `read_array`, `read_list` and `read_nested_list`.

  Categories:Package numericalio ·File input ·

Function: read_nested_list
`read_nested_list` (S)
`read_nested_list` (S, separator_flag)

  Reads the source S and returns its entire content as a nested list. The source S may be a file name or a stream.

  `read_nested_list` returns a list which has a sublist for each line of input. Lines need not have the same numbers of elements. Empty lines are not ignored: an empty line yields an empty sublist.

  The recognized values of separator_flag are `comma`, `pipe`, `semicolon`, and `space`. Equivalently, the separator may be specified as a string of one character: `","` (comma), `"|"` (pipe), `";"` (semicolon), `" "` (space), or `" "` (tab). If separator_flag is not specified, the file is assumed space-delimited.

  See also `openr`, `read_matrix`, `read_array`, `read_list` and `read_hashed_array`.

  Categories:Package numericalio ·File input ·

Function: read_list
`read_list` (S)
`read_list` (S, L)
`read_list` (S, separator_flag)
`read_list` (S, L, separator_flag)

  `read_list(S)` reads the source S and returns its entire content as a flat list.

  `read_list(S, L)` reads the source S into the list L, until L is full or the source is exhausted.

  The source S may be a file name or a stream.

  The recognized values of separator_flag are `comma`, `pipe`, `semicolon`, and `space`. Equivalently, the separator may be specified as a string of one character: `","` (comma), `"|"` (pipe), `";"` (semicolon), `" "` (space), or `" "` (tab). If separator_flag is not specified, the file is assumed space-delimited.

  See also `openr`, `read_matrix`, `read_array`, `read_nested_list`, `read_binary_list` and `read_hashed_array`.

  Categories:Package numericalio ·File input ·

Function: write_data
`write_data` (X, D)
`write_data` (X, D, separator_flag)

  Writes the object X to the destination D.

  `write_data` writes a matrix in row-major order, with one line per row.

  `write_data` writes an array created by `array` or `make_array` in row-major order, with a new line at the end of every slab. Higher-dimensional slabs are separated by additional new lines.

  `write_data` writes a hashed array with each key followed by its associated list on one line.

  `write_data` writes a nested list with each sublist on one line.

  `write_data` writes a flat list all on one line.

  The destination D may be a file name or a stream. When the destination is a file name, the global variable `file_output_append` governs whether the output file is appended or truncated. When the destination is a stream, no special action is taken by `write_data` after all the data are written; in particular, the stream remains open.

  The recognized values of separator_flag are `comma`, `pipe`, `semicolon`, `space`, and `tab`. Equivalently, the separator may be specified as a string of one character: `","` (comma), `"|"` (pipe), `";"` (semicolon), `" "` (space), or `" "` (tab). If separator_flag is not specified, the file is assumed space-delimited.

  See also `openw` and `read_matrix`.

  Categories:Package numericalio ·File output ·