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