BinaryFile Class Reference

A utility class for reading and writing binary files. More...

Inherits SmartPointerContainer< SmartPointerType, enableWeak >.

List of all members.

Public Member Functions
	BinaryFile () throw ()
	Creates a null object.
	BinaryFile (Text const &path, const bool bigEndian=PLANK_BIGENDIAN) throw ()
	Creates a binary file reader from the given path.
	BinaryFile (Text const &path, const bool writable, const bool clearContents, const bool bigEndian=PLANK_BIGENDIAN) throw ()
	Creates a binary file reader from the given path.
	BinaryFile (const char *path, const bool bigEndian=PLANK_BIGENDIAN) throw ()
	Creates a binary file reader from the given path.
	BinaryFile (const char *path, const bool writable, const bool clearContents, const bool bigEndian=PLANK_BIGENDIAN) throw ()
	Creates a binary file reader from the given path.
	BinaryFile (ByteArray const &bytes, const bool writable=false) throw ()
	Memory stream.
	BinaryFile (FilePathArray const &fileArray, const int multiMode, const bool bigEndian=PLANK_BIGENDIAN) throw ()
	Creates a multiple binary file reader from the array of files.
	BinaryFile (BinaryFile const &copy) throw ()
	Copy constructor.
BinaryFile &	operator= (BinaryFile const &other) throw ()
	Assignment operator.
LongLong	getPosition () throw ()
	Gets the position of the file stream.
void	setPosition (const LongLong position) throw ()
	Sets the position of the file stream.
void	setEof () throw ()
	Sets the position of the file stream to the end of the file.
bool	isEof () const throw ()
	Determines if the file stream is positioned at its end.
template<class ValueType >
ValueType	read () throw ()
	Reads a numerical value from the file.
template<class ValueType >
void	read (ValueType &value) throw ()
	Reads a value or array from the file.
template<class ValueType >
void	write (const ValueType value) throw ()
	Write a numerical value to the file.
Static Public Member Functions
static BinaryFile	fromWeak (Weak const &weak) throw ()
	Get a weakly linked copy of this object.
static int	chunkID (const char *const fourCharCode) throw ()
	Creates a chunk name identifier.

---

Detailed Description

A utility class for reading and writing binary files.

See also:

TextFile

---

Constructor & Destructor Documentation

BinaryFile::BinaryFile

(

)

throw () [inline]

Creates a null object.

This can't be used for reading or writing.

BinaryFile::BinaryFile	(	Text const &	path,
		const bool	bigEndian = PLANK_BIGENDIAN
	)		throw () [inline]

Creates a binary file reader from the given path.

Parameters:

path	The path of the file to read or write (this must already exist).
bigEndian	If true this will create a file where the multi-byte numerical values are written in big endian format otherwise it will use little endian (i.e., the default on most platforms). This argument defaults to the default endianness of runtime environment.

BinaryFile::BinaryFile	(	Text const &	path,
		const bool	writable,
		const bool	clearContents,
		const bool	bigEndian = PLANK_BIGENDIAN
	)		throw () [inline]

Creates a binary file reader from the given path.

Parameters:

path	The path of the file to read or write (this must already exist).
writable	If true this creates a readable and writable file, otherwise it is a read-only file.
clearContents	If false then an exisiting file's contents will be retained AND the write operations will always be appended to the end of the file. If true the file's contents will be erased and write operations can be repositioned. It is safer to update an existing file by using a temporary file and copy the contents when all the changes are complete. This must be false if writable is also false.
bigEndian	If true this will create a file where the multi-byte numerical values are written in big endian format otherwise it will use little endian (i.e., the default on most platforms). This argument defaults to the default endianness of runtime environment.

BinaryFile::BinaryFile	(	const char *	path,
		const bool	bigEndian = PLANK_BIGENDIAN
	)		throw () [inline]

Creates a binary file reader from the given path.

Parameters:

path	The path of the file to read or write (this must already exist).
bigEndian	If true this will create a file where the multi-byte numerical values are written in big endian format otherwise it will use little endian (i.e., the default on most platforms). This argument defaults to the default endianness of runtime environment.

BinaryFile::BinaryFile	(	const char *	path,
		const bool	writable,
		const bool	clearContents,
		const bool	bigEndian = PLANK_BIGENDIAN
	)		throw () [inline]

Creates a binary file reader from the given path.

Parameters:

path	The path of the file to read or write (this must already exist).
writable	If true this creates a readable and writable file, otherwise it is a read-only file.
clearContents	If false then an exisiting file's contents will be retained AND the write operations will always be appended to the end of the file. If true the file's contents will be erased and write operations can be repositioned. It is safer to update an existing file by using a temporary file and copy the contents when all the changes are complete. This must be false if writable is also false.
bigEndian	If true this will create a file where the multi-byte numerical values are written in big endian format otherwise it will use little endian (i.e., the default on most platforms). This argument defaults to the default endianness of runtime environment.

BinaryFile::BinaryFile

(

BinaryFile const &

copy

)

throw () [inline]

Copy constructor.

Note that a deep copy is not made, the copy will refer to exactly the same data.

---

Member Function Documentation

static int BinaryFile::chunkID

(

const char *const

fourCharCode

)

throw () [inline, static]

Creates a chunk name identifier.

A convenience function for creating an interger to write to a file for chunk IDs in many IFF-type files.

static BinaryFile BinaryFile::fromWeak

(

Weak const &

weak

)

throw () [inline, static]

Get a weakly linked copy of this object.

This will return a blank/empty/null object of this type if the original has already been deleted.

LongLong BinaryFile::getPosition

(

)

throw () [inline]

Gets the position of the file stream.

bool BinaryFile::isEof

(

)

const throw () [inline]

Determines if the file stream is positioned at its end.

BinaryFile& BinaryFile::operator=

(

BinaryFile const &

other

)

throw () [inline]

Assignment operator.

template<class ValueType >

ValueType BinaryFile::read

(

)

throw () [inline]

Reads a numerical value from the file.

This must be one of: char, short, int, long or LongLong (and their unsigned versions). This is read in the endian format specified in the constructor.

template<class ValueType >

void BinaryFile::read

(

ValueType &

value

)

throw () [inline]

Reads a value or array from the file.

This must be one of: char, short, int, long or LongLong (and their unsigned versions) or a NumericalArray of a built-in type. This is read in the endian format specified in the constructor.

void BinaryFile::setEof

(

)

throw () [inline]

Sets the position of the file stream to the end of the file.

void BinaryFile::setPosition

(

const LongLong

position

)

throw () [inline]

Sets the position of the file stream.

0 is the start of the stream.

template<class ValueType >

void BinaryFile::write

(

const ValueType

value

)

throw () [inline]

Write a numerical value to the file.

This must be one of: char, short, int, long or LongLong (and their unsigned versions). This is written in the endian format specified in the constructor.

---

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

• plonk_BinaryFile.h