help mata mm_insheet()
-------------------------------------------------------------------------------


Title

    mm_insheet() -- Read spreadsheet file into string matrix (and vice versa)


Syntax

        string matrix mm_insheet(filename [, delimiter, line1, line2])


        string matrix mm_infile(filename [, line1, line2])


        void          mm_outsheet(filename , s[, mode, delimiter])


    where

              filename:  string scalar filename
             delimiter:  string scalar delimiter
                 line1:  real scalar line1
                 line2:  real scalar line2
                     s:  string matrix s
                  mode:  string scalar containing "", "replace" or "append"


Description

    mm_insheet() returns as a string matrix the contents of a spreadsheet
    file (ASCII) in which columns are separated by, e.g., tabs or commas and
    rows are separated by the newline character. filename specifies the
    filename. delimiter specifies the character used to separate the values.
    The default value for delimiter is char(9) (the tab-character).

    mm_infile() returns as a string matrix the contents of a free-format file
    (ASCII) in which columns are separated by one or more blanks and rows are
    separated by the newline character.

    Specifying line1 (and line2) with mm_insheet() or mm_infile() indicates
    that the file be read starting with line number line1 (and ending with
    line number line2).

    mm_outsheet() writes string matrix s into an ASCII file. Rows are
    separated by the newline character.  Columns are separated by delimiter.
    The default value for delimiter is char(9) (the tab-character).
    mm_outsheet() aborts with error if the file indicated by fn already
    exists and mode is omitted or mode="". Specify mode="replace" to replace
    an existing file or mode="append" to append to an existing file.


Remarks

    mm_outsheet() can only be used with string matrices. To export a real
    matrix, type mm_outsheet(filename, strofreal(R)) where R is the real
    matrix (see [M-5] strofreal()).


Conformability

    mm_insheet(filename, delimiter, line1, line2):
      filename:  1 x 1
     delimiter:  1 x 1
         line1:  1 x 1
         line2:  1 x 1
        result:  r x c

    mm_infile(filename, line1, line2):
      filename:  1 x 1
         line1:  1 x 1
         line2:  1 x 1
        result:  r x c

    mm_outsheet(filename, s, mode, delimiter):
      filename:  1 x 1
             s:  r x c
          mode:  1 x 1
     delimiter:  1 x 1
        result:  void


Diagnostics

    mm_insheet() and mm_infile() abort with error if the file indicated by
    filename does not exist.

    mm_insheet() and mm_infile() return a 0 x 0 result if the file indicated
    by filename contains 0 bytes.

    The number of columns in the matrix returned by mm_insheet() or
    mm_infile() is determined by the maximum number of elements per line
    found the input file. If an individual input line contains less than the
    maximum number of elements, an appropriate number of empty elements is
    appended to the right of the row.

    mm_outsheet() creates a file containing 0 bytes if s is a void string
    matrix (see [M-2] void).


Source code

    mm_insheet.mata, mm_infile.mata, mm_outsheet.mata


Author

    Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch


Also see