File I/O

The following two commands allow saving/loading strings to/from files, as binary data or in 'plain text' format. Plain text means that no text formatting information is included in the file. The binary content of such a file however, is not always as 'plain' as a text editor may make it seem. Plain text files may be partly, or fully unreadable to e.g. a disk editor - depends on the encoding of the text data. Checking for a ByteOrderMark and performing the appropriate decoding is required for text files containing unicode strings.


[1]
strData.saveTo( fName, {,uFormat} {addBOM} ) save to file
  Returns strData / <err>
  strFName A strX object or Director string containing the full path to the file to be created/overwritten.
  uFormat Symbol format of the file. Possible values are 0, #u7, #u8, #u16, #u16b
  addBOM Boolean. When true, the Xtra will write the uFormat's BOM to the file. Byte Order Mark is a 'stamp', prefixed to the string's binary data, that describes both the encoding and byte order of the data that follows.
     
  Description With this command, the Xtra attempts to format the data according to uFormat and addBOM, and then write the data to the file fName. If either operation fails, an <err> is returned. Otherwise, the original strData is returned.

uFormat:
0 save the string's raw data (SDS or DDS) to the file. addBOM is ignored.
#u8 (default), #u7, #u16, #u16b encode strData, and, if addBOM is true, prefix the result with the BOM data.
     
  Examples _s("abc αβγ", 1253).saveTo("c:\test.txt", #u7, 1)
     
  Notes fName can be a unicode string - the Xtra supports unicode filenames.

[2]
strFName.load({,uFormat} {,CP} ) load file
  Returns <strX> / <err>
  strFName A strX object containing the full path to the file to be read.
  uFormat Symbol format of the file. Possible values are #s, #d, #u7, #u8 (default), #u16, #u16b
  CP Integer CodePage to be set as the CP of the resulting <str>
     
  Description With this command, the Xtra attempts to access the file strFName, and read its entire content.
If the attempt fails, an <err> will be returned.
If the attempt is successful, the Xtra will process the retrieved data, according to uFormat:

uFormat:
0 or #s No processing. Returns an <strS> whose content is the file's data (raw, binary)
#d No processing. Returns an <strD> whose content is the file's data and its length fileSize/2, or an <err> if the file size is not even.
#u8 (default), #u7, #u16, #u16b Try to uFormat-decode the file.
Return <strD> if successful, or an <err> if the decoding fails.
     
  Examples

_d("abc αβγ ", 1253).app("αβγ",1251).saveTo("c:\test.txt") -- #u8, with BOM

_s("c:\test.txt").load().pop() -- automatically discover encoding

_s("c:\test.txt").load(0).pop() -- read and return raw data

     
  Notes strFName can be a unicode xStr - the Xtra supports unicode filenames.