Fileclass | file.h[108] |
Superclass Tree | Subclass Tree | Global Objects | Property Summary | Method Summary | Property Details | Method Details |
intrinsic class
File : Object
File
Object
closeFile
getCharacterSet
getFileSize
getPos
readBytes
readFile
setCharacterSet
setPos
setPosEnd
writeBytes
writeFile
Inherited from Object
:
getPropList
getPropParams
getSuperclassList
isClass
isTransient
ofKind
propDefined
propInherited
propType
valToSymbol
closeFile ( ) | file.h[226] |
It's not strictly necessary to call closeFile() on a File, since the system will automatically do this work when the File object becomes unreachable and is discarded by the garbage collector. However, it is good practice to close a file explicitly by calling this method as soon as the program reaches a point at which it knows it's done with the file, because garbage collection might not run for a significant amount of time after the program is actually done with the file, in which case the system resources associated with the file would be needlessly retained for this extended time.
getCharacterSet ( ) | file.h[198] |
getFileSize ( ) | file.h[375] |
getPos ( ) | file.h[319] |
readBytes (byteArr, start?, cnt?) | file.h[299] |
Returns the number of bytes actually read into the byte array, which will be less than or equal to the number requested. If the number read is less than the number requested, it means that the end of the file was encountered, and only the returned number of bytes were available.
readFile ( ) | file.h[256] |
If the file is open in text mode, this reads a line of text from the file and returns a string with the text of the line read. A line of text is a sequence of characters terminated with a line-ending sequence, which is a carriage return, line feed, CR/LF pair, LF/CR pair, or a Unicode line terminator character (0x2028) if the file is being read with one of the Unicode encodings. If the line read ends in a line-ending sequence, the returned text will end in a '\n' character, regardless of which of the possible line-ending sequences is actually in the file, so the caller need not worry about the details of the external file's format. Every line read from the file will end in a '\n' except possibly the last line - if the file does not end with a line-ending sequence, then the last line read from the file will not end in a '\n' character. All bytes read from the file will be mapped to characters through the CharacterSet object currently in effect in the file, so the returned string will always be a standard Unicode string, regardless of the byte encoding of the file.
If the file is open in 'data' mode, this reads one data element using the private tads-specific data format. The result is a value of one of the types writable with writeFile() in 'data' mode. In order to read a 'data' file, the file must have been previously written in 'data' mode.
setCharacterSet (charset) | file.h[206] |
setPos (pos) | file.h[339] |
For files in 'text' and 'data' modes, a caller should NEVER set the file position to any value other than a value previously returned by getPos(), because other positions might violate the format constraints. For example, if you move the file position to a byte in the middle of a line-ending sequence in a text file, subsequent reading from the file might misinterpret the sequence as something other than a line ending, or as an extra line ending. If you move the position in a 'data' file to a byte in the middle of an integer value, reading from the file would misinterpret as a data type tag a byte that is part of the integer value instead. So it is never meaningful or safe to set an arbitrary byte offset in these file formats; only values known to be valid by virtue of having been returned from getPos() can be used here in these modes.
setPosEnd ( ) | file.h[348] |
writeBytes (byteArr, start?, cnt?) | file.h[311] |
No return value; if an error occurs writing the data, a FileIOException is thrown.
writeFile (val) | file.h[283] |
If the file is open in text mode, this writes text to the file, converting the given value to a string if necessary (and throwing an error if such a conversion is not possible), and translating the string to be written to bytes by mapping the string through the CharacterSet object currently in effect for the file. Note that no line-ending characters are automatically added to the output, so if the caller wishes to write line terminators, it should simply include a '\n' character at the end of each line.
If the file is open in 'data' mode, this writes the value, which must be a string, integer, enum, or 'true' value, in a private tads-specific data format that can later be read using the same format. The values are converted to the private binary format, which is portable across platforms: a file written in 'data' mode on one machine can be copied (byte-for-byte) to another machine, even one that uses different hardware and a different operating system, and read back in 'data' mode on the new machine to yield the original values written.