get_text

Definition: sequence r = get_text(integer fn, integer option=-2)
Description: Reads an entire file into memory. Suitable for relatively small text files, for example configuration (ini) files, and most of the files used by editors and compilers, at least the text ones that is. It is not suitable for large files, over say 5MB, or any form of binary file (database, video, executable etc).

This routine is deliberately limited to 1GB - the absolute maximum string length is 1,610,612,711 characters, on 32-bit, see pHeap.e, so that is about 66% of the maximum possible theoretical limit.

Larger files should be processed [one char/byte/line at a time] by getc/gets/seek/puts, which have a (predicted) limit of 8192 TB, thousands of times larger than the biggest currently available hard drives.

fn should be an open file with read access (it does not actually matter whether it was opened in binary or text mode)

The following constants are automatically defined in psym.e/syminit():

Constant Value Description
GT_WHOLE_FILE -2 get whole file as one long string, plus final '\n' if missing.
GT_LF_STRIPPED -1 returns an array of '\n'-stripped lines.
GT_LF_LEFT 0 '\n' left on lines.
GT_LF_LAST +1 '\n' left on lines, and put on last line if missing.

 
GT_WHOLE_FILE (-2) leaves any embedded CR,LF,CRLF,LFCR as-is, whereas no CR are returned from the other options. GT_WHOLE_FILE is however the fastest way to read a large file (GT_WHOLE_FILE is what p.exw uses).

GT_LF_LEFT is the only way to tell if the original file had a trailing blank line, should that be in any way important.

Note: after get_text(fn[,option]), the result of where(fn) is formally undefined. The (platform-specific part of the) implementation is at liberty to set the current file pointer to the end of file, rewind to the start of file, or even leave the builtins\VM notion of file position inconsistent with the underlying OS notion of said. Should an application attempt anything else with fn other than close it, a seek() will be required.
Example:
fn = open("myapp.ini","r")
r = get_text(fn,GT_LF_STRIPPED)  -- r is eg {"debug=1", "Font=Courier","Window Position=960,0"}
close(fn)
Compatibility: There is no equivalent routine in RDS Eu.
OpenEuphoria has a read_lines() routine offering somewhat similar functionality, which is partly replicated.

Should you require a routine that is compatible across Phix, RDS Eu, and OpenEuphoria, may I suggest that you might want to copy/rename/adapt the older builtins\pfileio.e\h_get_text(), in a new and separate file, and probably accept a filename rather than a filenumber.