Declaration (see MFile.h):
template <class T> void operator>>(MVector<T>& dest);
Reads up to dest.cnt() elements of type T from the file and advances the file pointer.
Type of the elements of dest. Can be any type for which operator>>(T&) is defined.
The destination buffer for the read data. Must be properly resized first.
The dest buffer also defines the number of elements to read. The operator will read as many T-type elements as dest already holds (overwriting the existing elements), or as many elements as the file contains (the smaller of the two). For this, dest has to be resized properly before calling operator>>.
If the file is closed, the function fails with exception 2001 (unless the file was closed on error - no redundant error reports). If a memory error occurs (can happen if dest is shared and automatic unsharing fails), the function generates exception 2000 and returns. If the file is an online file, which was opened in fmOverwrite mode (recall that online files cannot be opened in fmAppend mode), the function generates exception 2001 as well. Online files can be read only in fmRead mode (unlike local files that can be read in any mode).
If dest is empty, the function simply returns without errors. Otherwise, the function reads elements of type T from the file one by one into the corresponding element of dest. The operator>> must be defined for the type T or else the program will not compile.
If the file ends before all of the requested elements are read, the dest vector is truncated, so that only the elements that were read successfully remain, and even that is only if the file ended after reading an integral number of elements. If, on the other hand, the End-Of-File was reached in the middle of reading an element (i.e. a non-integral number of elements was read), the function generates exception 2001, resets (empties) dest, and returns.
On any error, dest is reset (emptied), and the file is closed (unless it was already closed, of course).
On success, the position of the file pointer is advanced to the first byte after the end of the read data, and dest contains all the elements actually read. If the number of elements actually read is smaller than dest.cnt(), the dest vector is truncated accordingly (i.e. the unused elements are cut off). In particular, if the file pointer was at EOF when this function was called, then upon return the dest is empty (this is not an error).
- As a rule, reading n elements into a vector is equivalent to reading elements one by one (using operator>>) n times. The vector version is needed for convenience (no need for a manual loop), and for most predefined types it is also much more efficient, because it reads all the elements in a single I/O operation
- Since this is a function template, it can be specialized for any type, but it is not required - overloading operator>> for type T automatically defines a vector implementation (thanks to the template)
- 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.