A class that allows the user to easily read from a file. More...

#include <omFileReader.h>

Inheritance diagram for om::io::FileReader:

Public Member Functions
	FileReader (const Char *filePath)
	Create a FileReader object that should read from the file at the specified path string. More...

	FileReader (const fs::UTF8String &filePath)
	Create a FileReader object that should read from the file at the specified path string. More...

	FileReader (const fs::Path &filePath)
	Create a FileReader object that should read from the file at the specified path. More...

	FileReader (const fs::File &file)
	Create a FileReader object that should read from the specified file. More...

	~FileReader ()
	Destroy a file reader and free all of it's resources (close the file). More...

Bool	open ()
	Open the file reader, allocating whatever resources needed to do so. More...

Bool	isOpen () const
	Return whether or not the file reader's file is open. More...

Bool	close ()
	Close the file writer, freeing all resources used during reading. More...

virtual Bool	canSeek () const
	Return whether or not this file reader can seek within the file. More...

virtual Bool	canSeek (Int64 relativeOffset) const
	Return whether or not this reader can seek by the specified amount in bytes. More...

virtual Int64	seek (Int64 relativeOffset)
	Move the current position in the file by the specified relative signed offset in bytes. More...

LargeIndex	seekAbsolute (LargeIndex newFilePosition)
	Seek to an absolute position in the file. More...

Bool	seekStart ()
	Rewind the file pointer to the beginning of the file. More...

Bool	seekEnd ()
	Seek to the end of the file. More...

virtual LargeIndex	getPosition () const
	Get the absolute position in the file of the file reader. More...

Bool	isAtEndOfFile () const
	Get whether or not the file writer is at the end of the file. More...

const fs::File &	getFile () const
	Get the file object that this file reader is reading from. More...

const fs::Path &	getURL () const
	Get the path to the file that this file reader is reading. More...

LargeSize	getFileSize () const
	Get the size of the file in bytes. More...

Bool	fileExists () const
	Get whether or not the file associated with this reader exists. More...

virtual LargeSize	getBytesRemaining () const
	Return the number of bytes remaining in the file. More...

virtual LargeSize	getCharactersRemaining () const
	Return the number of characters remaining in the stream. More...

Public Member Functions inherited from om::io::DataInputStream
virtual	~DataInputStream ()
	Destroy an input stream and free all of it's resources (close it). More...

Size	readData (data::DataBuffer &buffer, Size numBytes)
	Read the specified number of bytes from the stream and place them in the specified data buffer. More...

data::Data	readAllData ()
	Read as many bytes from the stream as possible and return them in a Data object. More...

Size	readAllData (data::DataBuffer &buffer)
	Read as many bytes from the stream as possible and place them in the specified data buffer. More...

Bool	hasBytesRemaining () const
	Return whether or not there are bytes remaining in the stream. More...

Public Member Functions inherited from om::io::StringInputStream
	StringInputStream ()
	Create a StringInputStream with the native endianness. More...

	StringInputStream (data::Endianness newEndianness)
	Create a StringInputStream with the specified input endianness. More...

virtual	~StringInputStream ()
	Destroy an input stream and free all of it's resources (close it). More...

Bool	hasCharactersRemaining () const
	Return whether or not there are bytes remaining in the stream. More...

Bool	readASCII (Char &value)
	Read a single ASCII character and place it in the input parameter. More...

Bool	readUTF32 (UTF32Char &value)
	Read a single UTF32 character and place it in the input parameter. More...

Size	readASCII (Char *buffer, Size numBytes)
	Read the specified number of ASCII characters and place them in the output buffer. More...

Size	readUTF8 (UTF8Char *buffer, Size numChars, Size capacity)
	Read the specified number of UTF-8 characters and place them in the output buffer. More...

Size	readUTF16 (UTF16Char *buffer, Size numChars, Size capacity)
	Read the specified number of UTF-16 characters and place them in the output buffer. More...

Size	readUTF32 (UTF32Char *buffer, Size numChars)
	Read the specified number of UTF-16 characters and place them in the output buffer. More...

Size	readASCII (data::StringBuffer &buffer, Size numChars)
	Read the specified number of characters from the stream and place them in the specified string buffer. More...

Size	readUTF8 (data::UTF8StringBuffer &buffer, Size numChars)
	Read the specified number of characters from the stream and place them in the specified UTF-8 string buffer. More...

Size	readUTF16 (data::UTF16StringBuffer &buffer, Size numChars)
	Read the specified number of characters from the stream and place them in the specified UTF-16 string buffer. More...

Size	readUTF32 (data::UTF32StringBuffer &buffer, Size numChars)
	Read the specified number of characters from the stream and place them in the specified UTF-32 string buffer. More...

data::String	readAllASCII ()

data::UTF8String	readAllUTF8 ()

data::UTF16String	readAllUTF16 ()

data::UTF32String	readAllUTF32 ()

data::Endianness	getEndianness () const
	Get the endianness to assume when reading from the stream. More...

void	setEndianness (data::Endianness newEndianness)
	Set the endianness to assume when reading from the stream. More...

Protected Member Functions
virtual Size	readChars (Char *buffer, Size numChars)
	Read the specified number of characters from the stream and place them in the specified output buffer. More...

virtual Size	readUTF8Chars (UTF8Char *buffer, Size numChars, Size capacity)
	Read the specified number of UTF-8 characters from the stream and place them in the specified output buffer. More...

virtual Size	readUTF16Chars (UTF16Char *buffer, Size numChars, Size capacity)
	Read the specified number of UTF-16 characters from the stream and place them in the specified output buffer. More...

virtual Size	readUTF32Chars (UTF32Char *buffer, Size numChars)
	Read the specified number of UTF-32 characters from the stream and place them in the specified output buffer. More...

virtual Size	readData (UByte *buffer, Size numBytes)
	Read the specified number of bytes from the stream and place them in the buffer given by a pointer. More...

Detailed Description

A class that allows the user to easily read from a file.

This purpose of this class is to read from a file in an object oriented and flexible manner. It allows the user to read individual bytes (characters), a sequence of characters, and raw data. One can open and close the file reader, and manipulate it's position in the file by seeking an absolute position or moving relatively. It wraps C's standard file in/out.

Constructor & Destructor Documentation

om::io::FileReader::FileReader ( const Char * filePath )

Create a FileReader object that should read from the file at the specified path string.

om::io::FileReader::FileReader ( const fs::UTF8String & filePath )

Create a FileReader object that should read from the file at the specified path string.

om::io::FileReader::FileReader ( const fs::Path & filePath )

Create a FileReader object that should read from the file at the specified path.

om::io::FileReader::FileReader ( const fs::File & file )

Create a FileReader object that should read from the specified file.

om::io::FileReader::~FileReader ( )

inline

Destroy a file reader and free all of it's resources (close the file).

Member Function Documentation

Bool om::io::FileReader::open ( )

Open the file reader, allocating whatever resources needed to do so.

This method opens a stream for reading from a file, and allocates the necessary resources to do so. If the file is already open, then this method does nothing. If an error occurs during opening the file reader, such that the file is unable to be opened, then a IOException is thrown. If the file path specified in the constructor points to a file that does not exist, then a FileNotFoundException is thrown.

Bool om::io::FileReader::isOpen ( ) const

inline

Return whether or not the file reader's file is open.

This method gets a boolean value from the file reader indicating whether or not the file is currently open. If the file is open, then TRUE is returned, and if it is closed, FALSE is returned.

Returns: whether or not the file reader is open

Bool om::io::FileReader::close ( )

Close the file writer, freeing all resources used during reading.

This method closes the file reader, and ensures that all resources that it used to perform output are freed (such as files, etc.). If the file reader is currently open, then this method guarantees that the reader is closed. If the file is unable to be closed, the method returns FALSE. If the file reader is already closed when the method is called, then nothing is done. This method is automatically called by the class's destructor when a file reader is destroyed.

virtual Bool om::io::FileReader::canSeek ( ) const

virtual

Return whether or not this file reader can seek within the file.

This method returns TRUE if the file reader is opened and points to a valid file. Otherwise FALSE is returned.

Implements om::io::DataInputStream.

virtual Bool om::io::FileReader::canSeek ( Int64 relativeOffset ) const

virtual

Return whether or not this reader can seek by the specified amount in bytes.

Since some streams may not support rewinding, this method can be used to determine if a given seek operation can succeed. The method can also be used to determine if the end of a stream has been reached, a seek past the end of a file will fail.

Implements om::io::DataInputStream.

virtual Int64 om::io::FileReader::seek ( Int64 relativeOffset )

virtual

Move the current position in the file by the specified relative signed offset in bytes.

The method attempts to seek in the file by the specified amount and returns the signed amount that the position in the file was changed by in bytes. A negative offset indicates that the position should be moved in reverse and a positive offset indicates that the position should be moved forwards. The file must be open for the seek operation to succeed.

Implements om::io::DataInputStream.

LargeIndex om::io::FileReader::seekAbsolute ( LargeIndex newFilePosition )

Seek to an absolute position in the file.

This method attempts to seek to the specified absolute position in the file, and then returns the resulting position in the file of the file reader after the method call. Positions within a file are specified with 0 representing the beginning of the file, and each positive increment of 1 representing a position 1 more byte further in the file. If the file is not open when the method is called, no seek operation is performed and the current position in the file is returned.

Parameters

newFilePosition - The desired position in the file to seek to.

Returns: the resulting position in the file after the method call.

Bool om::io::FileReader::seekStart ( )

Rewind the file pointer to the beginning of the file.

This method moves the position in the file of the file reader to the beginning of the file. The method returns whether or not the seek operation was successful. The seek operation can fail if seeking is not allowed or the file is not open.

Bool om::io::FileReader::seekEnd ( )

Seek to the end of the file.

This method sets the current position in the file of the file reader to be the end of the file. The method returns whether or not the seek operation was successful. The seek operation can fail if seeking is not allowed or the file is not open.

virtual LargeIndex om::io::FileReader::getPosition ( ) const

virtual

Get the absolute position in the file of the file reader.

This method queries and returns the current position in the file of the file reader. Positions within a file are specified with 0 representing the beginning of the file, and each positive increment of 1 representing a position 1 more byte further in the file. If the file is not open when the method is called, then a IOException is thrown.

Returns: the current position in the file of the file reader.

Implements om::io::DataInputStream.

Bool om::io::FileReader::isAtEndOfFile ( ) const

Get whether or not the file writer is at the end of the file.

This method queries whether or not the file writer is at the end of the file. If it is, then TRUE is returned, otherwise FALSE is returned. If the file is not open when the method is called, then a IOException is thrown.

Returns: whether or not the file reader is at the end of the file.

const fs::File& om::io::FileReader::getFile ( ) const

inline

Get the file object that this file reader is reading from.

This method returns a constant reference to a file object representing the file that this file reader is associated with.

Returns: the file this file reader is associated with.

const fs::Path& om::io::FileReader::getURL ( ) const

inline

Get the path to the file that this file reader is reading.

This method returns a constant reference to a string representing the path to the file that this file reader is associated with.

Returns: the path to the file this file reader is associated with.

LargeSize om::io::FileReader::getFileSize ( ) const

inline

Get the size of the file in bytes.

This method queries and returns the size of the file in bytes. The file does not have to be open to do this, but it does have to exist. If the file does not exist, then a IOException is thrown.

Returns: the total size of the file in bytes.

Bool om::io::FileReader::fileExists ( ) const

inline

Get whether or not the file associated with this reader exists.

This method checks whether or not the file pointed to by the path queried by getURL() exists. It then returns TRUE if the file exists or returns FALSE if the file does not exist.

Returns: whether or not the file associated with this file reader exists.

virtual LargeSize om::io::FileReader::getBytesRemaining ( ) const

virtual

Return the number of bytes remaining in the file.

The value returned must only be a lower bound on the number of bytes remaining in the stream. If there are bytes remaining, it must return at least 1.

Implements om::io::DataInputStream.

virtual LargeSize om::io::FileReader::getCharactersRemaining ( ) const

virtual

Return the number of characters remaining in the stream.

The value returned must only be a lower bound on the number of characters remaining in the stream. If there are characters remaining, it must return at least 1.

Implements om::io::StringInputStream.

virtual Size om::io::FileReader::readChars	(	Char *	buffer,
		Size	number
	)

protectedvirtual

Read the specified number of characters from the stream and place them in the specified output buffer.

Implements om::io::StringInputStream.

virtual Size om::io::FileReader::readUTF8Chars	(	UTF8Char *	buffer,
		Size	numChars,
		Size	capacity
	)

protectedvirtual

Read the specified number of UTF-8 characters from the stream and place them in the specified output buffer.

If the number of unicode code points exceeds the capacity of the buffer, as many characters are read as possible. The number of code points read is returned.

Implements om::io::StringInputStream.

virtual Size om::io::FileReader::readUTF16Chars	(	UTF16Char *	buffer,
		Size	numChars,
		Size	capacity
	)

protectedvirtual

Read the specified number of UTF-16 characters from the stream and place them in the specified output buffer.

If the number of unicode code points exceeds the capacity of the buffer, as many characters are read as possible. The number of code points read is returned.

Implements om::io::StringInputStream.

virtual Size om::io::FileReader::readUTF32Chars	(	UTF32Char *	buffer,
		Size	numChars
	)

protectedvirtual

Read the specified number of UTF-32 characters from the stream and place them in the specified output buffer.

If the number of unicode code points exceeds the capacity of the buffer, as many characters are read as possible. The number of code points read is returned.

Implements om::io::StringInputStream.

virtual Size om::io::FileReader::readData	(	UByte *	buffer,
		Size	numBytes
	)

protectedvirtual

Read the specified number of bytes from the stream and place them in the buffer given by a pointer.

The buffer must be large enough to hold the specified number of bytes. The number of bytes read can be less than the desired number if an error is encountered or the end of the stream is reached.

If the method succeeds, the return value will equal the parameter numBytes and the stream will be advanced by that many bytes. Otherwise, the return value will be less than the parameter numBytes, indicating the amount that the stream position changed.

Parameters

buffer	- a pointer to a buffer where the read data should be placed.
numBytes	- the number of bytes of data to read from the stream.

Returns: the number of bytes that were actually read and placed in the buffer.

Implements om::io::DataInputStream.

The documentation for this class was generated from the following file:

omFileReader.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation