/** \~russian ,       .
 *
 * @par :
 * @include file.fos
 *
 ** \~english This class provides support for reading and writing text files.
 *
 * @par Example:
 * @include file.fos
 *
 ** \~ @ingroup std
 */
class file
{
	/** \~russian         .
	 *
	 * @param  filename    .
	 * @param  mode         .  :
	 *                   <table>
	 *                    <tr><td>"r"</td><td>   .</td></tr>
	 *                    <tr><td>"w"</td><td>   .   .</td></tr>
	 *                    <tr><td>"a"</td><td>      (   ).</td></tr>
	 *                   </table>
	 *
	 * @return 0,    ; -1    .
	 *
	 ** \~english Opens file.
	 *
	 * @param filename  Path to the file.
	 * @param mode      String containing a file access mode. It can be:
	 *                   <table>
	 *                    <tr><td>"r"</td><td>Open the file for reading.</td></tr>
	 *                    <tr><td>"w"</td><td>Open the file for writing (overwrites existing files).</td></tr>
	 *                    <tr><td>"a"</td><td>Open the file for appending.</td></tr>
	 *                   </table>
	 *
	 * @return If the file is successfully opened, a zero value is returned.
	 *         Otherwise, -1 is returned.
	 *
	 */
	int open(const string &in filename, const string &in mode);

	/** \~russian  .
	 *
	 * @return 0,    ; -1    .
	 *
	 ** \~english Closes file.
	 *
	 * @return If the file is successfully closed, a zero value is returned.
     *         On failure, -1 is returned.
	 */
	int close();

	/** \~russian   . */
	/** \~english Returns the size of the file. */
	int getSize() const;

	/** \~russian   @c true,     . */
	/** \~english Returns @c true if the end of the file has been reached. */
	bool isEndOfFile() const;

	/** \~russian       .
	 *
	 * @param         length    .
	 * @param  [out]  str     ,      .
	 *
	 * @return    .
	 *               @a length,   ,
	 *              ,     .
	 *
	 * @see    #isEndOfFile
	 *
	 ** \~english Reads a specified number of bytes into the string.
	 */
	int readString(uint length, string &out str);

	/** \~russian    .
	 *
	 *     ,  
	 *       EOF.
	 *
	 * @param  [out]  str ,       .
	 *
	 * @return     .
	 *
	 ** \~english Reads to the next new-line character.
	 */
	int readLine(string &out str);

	/** \~russian    .
	 *
	 * @param   string   .
	 *
	 * @return    .
	 *             ,   ,     .
	 *
	 ** \~english Writes a string to the file.
	 *
	 * @param   string  String to be written.
	 *
	 * @return  The total number of characters successfully written.
	 *          If this number differs from the length of the input string,
	 *          it indicates an error.
	 */
	int writeString(const string &in string);

	/** \~russian    .
	 *
	 * @return    . -1    .
	 *
	 ** \~english Returns the current position of the file.
	 *
	 * @return On success, the current value of the position is returned.
	 *         If an error occurs, -1 is returned.
	 *
	 */
	int getPos() const;

	/** \~russian    .
	 *
	 * @param  pos  .
	 *
	 * @return 0   ; -1    .
	 *
	 ** \~english Sets the current position of the file.
	 *
	 * @param  pos  New position.
	 *
	 * @return If successful, the function returns a zero value.
     *         Otherwise, it returns -1.
	 */
	int setPos(int pos);

	/** \~russian        .
	 *
	 * @param  delta   ,     .
	 *
	 * @return 0   ; -1    .
	 *
	 ** \~english Changes current position of the file by adding @a delta to the current position.
	 *
	 * @param  delta  Number of bytes to offset from the current position.
	 *
	 * @return If successful, the function returns a zero value.
     *         Otherwise, it returns -1.
	 */
	int movePos(int delta);

	/** \~russian     (   )  . */
	/** \~english Reads next word (character sequence without whitespaces) from the file. */
	string@ readWord();

	/** \~russian      . */
	/** \~english Reads next integer number from the file. */
	int readNumber();
	uint8 readUint8();
	uint16 readUint16();
	uint32 readUint32();
	uint64 readUint64();
	/** \~russian  data == 0,           .
	 *      .
	 *        .
	 */
	uint readData(uint count, uint8[]& data);
	bool writeUint8(uint8 data);
	bool writeUint16(uint16 data);
	bool writeUint32(uint32 data);
	bool writeUint64(uint64 data);
	/** \~russian  count == 0     . */
	bool writeData(uint8[]& data, uint count);
}
