>  Docs Center  >  Libraries  >  Motley  >  MGH_TXT_RESTORE

MGH_TXT_RESTORE

MGH_TXT_RESTORE

Name


  MGH_TXT_RESTORE

Purpose


  Read the contents of a text file into a string array.

Category


Calling Sequence


  Result = MGH_TXT_RESTORE(file)

Positional Parameters


  file (input, scalar string)
    File name

Keyword Parameters


  COMPRESS (input, switch)
    Set this keyword to indicate that the data in the file are compressed.
  COUNT (output, scalar integer)
    Set this keyword to a named variable to return the number of
    lines read from the file
  MAX_LINES (input, scalar integer)
    This keyword has an effect only for method 2. It specifies the
    maximum number of lines in the file. If the file is longer than
    this, then the routine will stop with an error.
  METHOD (input, scalar integer)
    This keyword specifies the method to be used to read the file.
    Acceptable values are:
      0 - Read lines one at a time, accumulating them in a string
          array. Extend the array as necessary in increments of
          70% or so (see code). Trim the result before returning.
      1 - Read the file once to count the lines, create a result
          array of the required size, then read the file again.
      2 - Create a result array of size MAX_LINES, read the file,
          then trim the result. This method may return fewer lines
          than the other methods, as all empty lines are trimmed
          from the end.
      3 - As 0, but accumulate the results in an MGH_Vector object
          then move them into a string array at the end.
    The default (last time I looked) is method 1.

Return Value


  The function returns a string array, each element corresponding to
  a line in the file. Empty lines are represented by null
  strings. If the file is empty, then the function returns a single
  null string.
###########################################################################
  This software is provided subject to the following conditions:
  1. NIWA makes no representations or warranties regarding the
    accuracy of the software, the use to which the software may
    be put or the results to be obtained from the use of the
    software. Accordingly NIWA accepts no liability for any loss
    or damage (whether direct of indirect) incurred by any person
    through the use of or reliance on the software.
  2. NIWA is to be acknowledged as the original author of the
    software where the software is used or presented in any form.
###########################################################################

Modification History


  Mark Hadfield, 1993-04:
    Written as TXT_RESTORE, inspired by the GETFILE routine in the
    JHUAPL library.
  Mark Hadfield, 1998-06:
    Switched to the two-pass method, as described above. For large
    files this is MUCH faster than the method used in GETFILE,
    viz. appending each line to the output array as it is read.
  Mark Hadfield, 1999-10:
    Switched to a single-pass method using an MGH_Vector
    object. The two-pass method is retained as an option.
  Mark Hadfield, 2000-08:
    Renamed MGH_TXT_RESTORE and moved into my public library (mainly
    because it's an example of using MGH_Vector).
  Mark Hadfield, 2002-12:
    - Added keywords METHOD and MAX_LINES, and eliminated the old
      TWO_PASS keyword. There are now 4 methods available.
    - The two-pass method, now method 1, has been modified to use
      MGH_FILE_LINES, which calls FILE_LINES if the file is
      uncompressed and counts lines with an IDL while lopp
      if it is compressed.
  Mark Hadfield, 2003-06:
    - Upgraded to IDL 6.0. The two-pass method, now calls FILE_LINES
      in all cases



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us