File Management

File management and serialization in QDL is encapsulated in a number of classes, all of which are derived from the Abstract File class. The classes in this section, collectively referred to as the file management classes, can be used to:

• Read and write, a.k.a serialization
  • Perform console I/O through standard input and output (traditionally, the keyboard and text screen)
    See Class Console In and Class Console Out.
  • Save and load binary disk files.
    See Class File Stream.
  • Save and load text files.
    See Class Text File Stream.
  • Serialize to or from a section of memory.
    See Class Memory Stream.
  • Store configuration settings in data segments that can be accessed like files.
    See Class Config Stream.
  • Transfer data across threads or processes using a pipe.
    See Class Pipe Stream
  • Write data to a debug log
    See Class Debug Log
• Get and set information concerning directories
  See Class File System
• Manipulate and analyze paths
  See Class Path String 

In this documentation, whatever you are reading from or writing to using these classes is referred to as a "stream".

The Abstract Stream class

The Abstract File class contains the functions that are common to all file management classes. Its members are:

Abstract Function Write (Byte: UInt8);
Abstract Function Write (Data: @ []UInt8; Size: Integer);

These functions write one or more bytes of data to the stream.

Enum String Modes {
	WideChars = 1, BigEndian = 2,
};

Function CharMode: String Modes;
Abstract Function SetCharMode (NewMode: String Modes);

CharMode returns the current character input/output mode; SetCharMode changes it.  All stream types have a character mode, but not all stream types (notably, Text File Stream) support changing the mode after the file has been opened.  The string mode persists between access to different streams through the same stream object.

The string mode affects the behaviour of the WriteString, ReadString, Print and ReadLine functions.

The mode is made up of zero or more of these flags:

• WideChars: Use wide (16-bit) characters.  If this flag is not present, 8-bit characters are used.
• BigEndian: Use big-endian (more significant byte first) characters.  If this flag is not present, little-endian characters are used.

The default mode little-endian, regardless of platform.  WideChars is used if Chars are wide.

Final Function Write8  (Data: Int8);
Final Function Write8  (Data: UInt8);
Final Function Write16 (Data: Int16);
Final Function Write16 (Data: UInt16);
Final Function Write32 (Data: Int32);
Final Function Write32 (Data: UInt32);
Final Function Write64 (Data: Int64);
Final Function Write64 (Data: UInt64);
Final Function WriteSingle (Data: Single);
Final Function WriteDouble (Data: Double);
Final Function WriteString (Data: @ String);

These functions perform platform-independent writes of integer, floating-point, and string data. For integer types, the data is output in low- to high-byte order. For strings, the string length (16 bits, unsigned, LSB first) is written followed by the contents of the string. If the compiler supports strings larger than 64K, strings are truncated to 64K-1 characters.  Floating-point types are stored as follows:

• The mantissa makes up the lower-order bits, followed by the exponent, followed by the sign as the highest-order bit.
• The number is output in low-order-byte to high-order-byte order.
• The Single type contains 32 bits: 1 for the sign, 8 for the exponent, and 23 for the mantissa. Its range is +/– 3.4E38 with at least 7 digits of precision.
• The Double type contains 64 bits: 1 for the sign, 11 for the exponent, and 52 for the mantissa. Its range is +/– 1.7E308 with at least 15 digits of precision.

These functions are Final because they are the same regardless of stream type; they call a Write() function to carry out the writing.

Abstract Function Read (Byte: @ UInt8) Returns Boolean;
Abstract Function Read (Data: @ []UInt8; Size: Integer) Returns Boolean;

These functions, the counterpart to the Write() functions, read one or more bytes of data from the stream. The Boolean return value indicates whether all the bytes requested could be read; False is returned on end-of-file (EOF). Read errors not caused by an EOF should cause an exception to be thrown.

Final Function Read8 (Data: @ Int8) Returns Boolean;
Final Function Read8 (Data: @ UInt8) Returns Boolean;
Final Function Read16 (Data: @ Int16) Returns Boolean;
Final Function Read16 (Data: @ UInt16) Returns Boolean;
Final Function Read32 (Data: @ Int32) Returns Boolean;
Final Function Read32 (Data: @ UInt32) Returns Boolean;
Final Function Read64 (Data: @ Int64) Returns Boolean;
Final Function Read64 (Data: @ UInt64) Returns Boolean;
Final Function ReadSingle (Data: @ Single) Returns Boolean;
Final Function ReadDouble (Data: @ Double) Returns Boolean;
Final Function ReadString (Data: @ String) Returns Boolean;

These functions perform platform-independent reads of integers, floating-point numbers or strings. True is returned on success; False on EOF. These functions are Final because they are the same regardless of stream type; they call the Read() functions to carry out the reading.

Enum Modes Inhertis Integer {
	Read = 1,       // Data can be read
	Write = 2,      // Data can be written
	Input = 1,      // Alias for Read
	Output = 2,     // Alias for Write
	ReadPos = 4,    // Read position can be determined
	WritePos = 8,   // Write position can be determined
	ReadSeek = 16,  // Read position can be determined and changed
	WriteSeek = 32, // Write position can be determined and changed
	Text = 64       // Text-file translation enabled
};
Function Mode(): Modes;

This function returns the abilities of the currently open file. If no file is open, 0 is returned.  If the mode includes ReadSeek, ReadPos should be present also.  If the mode includes WriteSeek, WritePos should be present also.  Derived classes may have additional modes starting with bit 8 (256).

Abstract Function Print (Args...: String): Integer;

This function prints out a series of strings to the stream, without writing size information or a terminator character. This function is most useful for outputting text to the screen or to a text file.

Abstract Function ReadLine (Data: String @): Boolean;

This function reads characters from the stream until encountering a newline ('\n') character, or EOF. The return value specifies what caused the function to stop reading (True because of a newline, False because of EOF.) The function may also stop because the maximum length of a string has been reached; in this case the return value is still True. The newline character is removed from the string read.

Function AtEOF(): Boolean;

This function returns True if the end-of-file was passed in the last read operation; False otherwise. Note that AtEOF will return True only after a read function has failed due to EOF.

Enum Seek Offsets {
	Start, Current, End
};

Abstract Function SetReadPos (Location: Int64 "[From]" Offset: Seek Offsets (Start));
Abstract Function GetReadPos (): Int64;

GetReadPos determines and returns the position in the stream from which subsequent reads will start.  It will fail if the Mode does not include ReadPos.  SetReadPos "seeks" to a position in the stream, from which subsequent reads will start. It will fail if the Mode does not include ReadSeek.  On failure, the functions should throw exceptions.

Abstract Function SetWritePos (Location: Int64 "[From]" Offset: Seek Offsets (Start));
Abstract Function GetWritePos (): Int64;

GetWritePos determines and returns the position in the stream from which subsequent writes will start.  It will fail if the Mode does not include WritePos.  SetWritePos "seeks" to a position in the stream, from which subsequent reads will start. It will fail if the Mode does not include WriteSeek.  On failure, the functions should throw exceptions.

Abstract Function Flush Returns Boolean;

For buffered streams, this function flushes the internal buffers. For output streams, this means that outputted data is immediately written, instead of being stored up in a buffer for a burst write operation.

Function Transfer (ToWhere: Abstract File @; MaxBytes: Int64) Returns Int64;

This function reads bytes from the stream and outputs them to another stream. Transferring stops either at EOF, or after the specified number of bytes are copied. The default implementation transfers small (size is implementation-dependant) blocks of data at a time; the function can be overridden in derived classes to provide more efficient data transfer. The function returns the number of bytes that were actually transferred.

Abstract Function GetEOFPos () Returns Int64;

This function returns the position of EOF, which should also be the size of the file.  This function fails, throwing an exception, if the Mode does not include ReadPos or WritePos.  This function should not change the seek position.