Declaration (see MFile.h):
MFile& operator<<(const T& src);
Writes a single element of type T (see Details) to the file, and advances the file pointer accordingly.
Return type: MFile&
The data to write to the file (of any supported type).
This function always returns *this reference, to allow operator<< chains (which is more convenient and reduces the amount of code).
By default, T can be any of the following types: bool, char, MChar, Int8, UInt8, Int8, Int16, UInt16, Int32, UInt32, Int64, UInt64, float, double, MNum, MFileSize, MLocusElem, MSizeElem. MPointElem, MString, and string literals (char and wchar_t arrays).
However, operator<< can be overloaded for any other type using the predefined operator<< (see Example in operator>>(T&)).
If the file is closed, operator<< generates exception 2001 and returns. That being said, if the file was closed due to error, operator<< returns without generating an exception to avoid redundant error reports. If the file was opened in fmRead mode, the function generates exception 2001 as well. Writing works only in fmOverwrite and fmAppend modes (see open).
Otherwise (if none of the above error conditions are met), the function writes src to the associated file, starting from the current position (see getPos). The position of the file pointer is advanced to the first byte after the end of the written data. The amount of data written depends on the type of src. For example, for UInt8 the data is just one byte, but for a more complex type like MString it can even be of variable length. The data written with operator<< should be read only with operator>>, because the data is often written in a specialized format that can only be understood by Elgrint's apps. That being said, UInt8 type (byte) is guaranteed to be written as-is, and thus usable by any app on any platform.
If the data is being written at EOF (End-Of-File), i.e. it is being appended to the file, the file is automatically expanded, and its size increases accordingly (see getSize). If the data is written inside the file's boundaries (which is only allowed in local files), the new data replaces the existing one. Such writing should be done with care to avoid format corruption. Remember that different values may occupy different number of bytes in the file even if they are of the same type (although so far this is only true for MString variables).
If an I/O error occurs during writing (including the case where the drive runs out of space), the function generates exception 2007 and returns (the file may become corrupt in this case). The file is closed on any error (unless it was already closed), so isOpen can be used to check for errors.
- Writing to an HTTP stream is allowed, but the data is not really written to any actual file, only sent to the server. Whatever happens to this data there depends on the server
- If the size of the file changes due to writing, MSys::getFileInfo may return the old size until the file is closed. getSize, however, always returns the most current size
- The wchar_t type is not explicitly supported (though it is usually implicitly converted to int), because it may have different meaning (and different size) on different platforms and different compilers. In fact, it may not even be supported by some compilers. Use MChar for fully portable character representation
- The long double type is not explicitly supported for now (may be supported in the future)
- operator<< is not a template, so it cannot be specialized, but it can be overloaded (which is even easier)
- Must not be used in global or static scope (i.e. outside of the MAppMain scope)
Let us know
Please Contact us to report any errors on this page, or to suggest any improvements.