cugl::BinaryReader Class Reference

#include <CUBinaryReader.h>

Public Member Functions
	BinaryReader ()
	~BinaryReader ()
bool	init (const std::string file)
bool	init (const std::string file, unsigned int capacity)
bool	initWithAsset (const std::string file)
bool	initWithAsset (const std::string file, unsigned int capacity)
void	reset ()
void	close ()
bool	ready (unsigned int bytes=1) const
char	readChar ()
Uint8	readByte ()
Sint16	readSint16 ()
Uint16	readUint16 ()
Sint32	readSint32 ()
Uint32	readUint32 ()
Sint64	readSint64 ()
Uint64	readUint64 ()
float	readFloat ()
double	readDouble ()
size_t	read (char *buffer, size_t maximum, size_t offset=0)
size_t	read (Uint8 *buffer, size_t maximum, size_t offset=0)
size_t	read (Sint16 *buffer, size_t maximum, size_t offset=0)
size_t	read (Uint16 *buffer, size_t maximum, size_t offset=0)
size_t	read (Sint32 *buffer, size_t maximum, size_t offset=0)
size_t	read (Uint32 *buffer, size_t maximum, size_t offset=0)
size_t	read (Sint64 *buffer, size_t maximum, size_t offset=0)
size_t	read (Uint64 *buffer, size_t maximum, size_t offset=0)
size_t	read (float *buffer, size_t maximum, size_t offset=0)
size_t	read (double *buffer, size_t maximum, size_t offset=0)

Static Public Member Functions
static std::shared_ptr< BinaryReader >	alloc (const std::string file)
static std::shared_ptr< BinaryReader >	alloc (const std::string file, unsigned int capacity)
static std::shared_ptr< BinaryReader >	allocWithAsset (const std::string file)
static std::shared_ptr< BinaryReader >	allocWithAsset (const std::string file, unsigned int capacity)

Protected Member Functions
void	fill (unsigned int bytes=1)

Protected Attributes
std::string	_name
SDL_RWops *	_stream
Sint64	_ssize
Sint64	_scursor
char *	_buffer
Uint32	_capacity
Uint32	_bufsize
Sint32	_bufoff

Detailed Description

Simple cross-platform reader for binary files.

This class provides a simple Java-style reader for decoding binary files. All data is marshalled from network order, ensuring that the files are supported across multiple platforms.

Note that this reader does not refer to the integral types as short, int, long, etc. Those types are NOT cross-platform. For example, a long is 8 bytes on Unix/OS X, but 4 bytes on Win32 platforms.

By default, this class (and every class in the io package) accesses the application save directory {

See also

Application::getSaveDirectory()}. If you want to access another directory, you will need to specify an absolute path for the file name. Keep in mind that absolute paths are very dangerous on mobile devices, because they do not have proper file systems. You should confine all files to either the asset or the save directory.

Constructor & Destructor Documentation

BinaryReader()

cugl::BinaryReader::BinaryReader ( )

inline

Creates a binary reader with no assigned file.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate an object on the heap, use one of the static constructors instead.

~BinaryReader()

cugl::BinaryReader::~BinaryReader ( )

inline

Deletes this reader and all of its resources.

Calls to the destructor will close the file if it is not already closed.

Member Function Documentation

alloc() [1/2]

static std::shared_ptr< BinaryReader > cugl::BinaryReader::alloc ( const std::string  file )

inlinestatic

Returns a newly allocated reader for the given file.

The reader will have the default buffer capacity for reading chunks from the file.

If the file is a relative path, this reader will look for the file in the application save directory {

See also

Application::getSaveDirectory()}. If you wish to read a file in any other directory, you must provide an absolute path.

Parameters

file	the path (absolute or relative) to the file

Returns

a newly allocated reader for the given file.

alloc() [2/2]

static std::shared_ptr< BinaryReader > cugl::BinaryReader::alloc ( const std::string  file, unsigned int  capacity  )

inlinestatic

Returns a newly allocated reader for the given file with the specified capacity.

If the file is a relative path, this reader will look for the file in the application save directory {

See also

Application::getSaveDirectory()}. If you wish to read a file in any other directory, you must provide an absolute path.

Parameters

file	the path (absolute or relative) to the file
capacity	the buffer capacity for reading chunks

Returns

a newly allocated reader for the given file with the specified capacity.

allocWithAsset() [1/2]

static std::shared_ptr< BinaryReader > cugl::BinaryReader::allocWithAsset ( const std::string  file )

inlinestatic

Returns a newly allocated reader for the given file.

The reader will have the default buffer capacity for reading chunks from the file.

This initializer assumes that the file name is a relative path. It will search the application assert directory {

See also

Application::getAssetDirectory()} for the file and return false if it cannot find it there.

Parameters

file	the relative path to the file

Returns

a newly allocated reader for the given file.

allocWithAsset() [2/2]

static std::shared_ptr< BinaryReader > cugl::BinaryReader::allocWithAsset ( const std::string  file, unsigned int  capacity  )

inlinestatic

Returns a newly allocated reader for the given file with the specified capacity.

This initializer assumes that the file name is a relative path. It will search the application assert directory {

See also

Application::getAssetDirectory()} for the file and return false if it cannot find it there.

Parameters

file	the relative path to the file
capacity	the buffer capacity for reading chunks

Returns

a newly allocated reader for the given file with the specified capacity.

close()

void cugl::BinaryReader::close

(

)

Closes the stream, releasing all resources

Any attempts to read from a closed stream will fail. Calling this method on a previously closed stream has no effect.

fill()

void cugl::BinaryReader::fill ( unsigned int  bytes = 1 )

protected

Fills the storage buffer to capacity

This cuts down on the number of reads to the file by allowing us to read from the file in predefined chunks.

Parameters

bytes

The minimum number of bytes to ensure in the stream

init() [1/2]

bool cugl::BinaryReader::init

(

const std::string

file

)

Initializes a reader for the given file.

The reader will have the default buffer capacity for reading chunks from the file.

If the file is a relative path, this reader will look for the file in the application save directory {

See also

Application::getSaveDirectory()}. If you wish to read a file in any other directory, you must provide an absolute path.

Parameters

file	the path (absolute or relative) to the file

Returns

true if the reader is initialized properly, false otherwise.

init() [2/2]

bool cugl::BinaryReader::init	(	const std::string	file,
		unsigned int	capacity
	)

Initializes a reader for the given file with the specified capacity.

If the file is a relative path, this reader will look for the file in the application save directory {

See also

Application::getSaveDirectory()}. If you wish to read a file in any other directory, you must provide an absolute path.

Parameters

file	the path (absolute or relative) to the file
capacity	the buffer capacity for reading chunks

Returns

true if the reader is initialized properly, false otherwise.

initWithAsset() [1/2]

bool cugl::BinaryReader::initWithAsset

(

const std::string

file

)

Initializes a reader for the given file.

The reader will have the default buffer capacity for reading chunks from the file.

This initializer assumes that the file name is a relative path. It will search the application assert directory {

See also

Application::getAssetDirectory()} for the file and return false if it cannot find it there.

Parameters

file	the relative path to the file

Returns

true if the reader is initialized properly, false otherwise.

initWithAsset() [2/2]

bool cugl::BinaryReader::initWithAsset	(	const std::string	file,
		unsigned int	capacity
	)

Initializes a reader for the given file with the specified capacity.

This initializer assumes that the file name is a relative path. It will search the application assert directory {

See also

Application::getAssetDirectory()} for the file and return false if it cannot find it there.

Parameters

file	the relative path to the file
capacity	the buffer capacity for reading chunks

Returns

true if the reader is initialized properly, false otherwise.

read() [1/10]

size_t cugl::BinaryReader::read	(	char *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of characters from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of characters read from the stream

read() [2/10]

size_t cugl::BinaryReader::read	(	double *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of doubles from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of doubles read from the stream

read() [3/10]

size_t cugl::BinaryReader::read	(	float *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of floats from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of floats read from the stream

read() [4/10]

size_t cugl::BinaryReader::read	(	Sint16 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of 16 bit signed integers from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of 16 bit signed integers read from the stream

read() [5/10]

size_t cugl::BinaryReader::read	(	Sint32 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of 32 bit signed integers from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of 32 bit signed integers read from the stream

read() [6/10]

size_t cugl::BinaryReader::read	(	Sint64 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of 32 bit signed integers from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of 32 bit signed integers read from the stream

read() [7/10]

size_t cugl::BinaryReader::read	(	Uint16 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of 16 bit unsigned integers from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of 16 bit unsigned integers read from the stream

read() [8/10]

size_t cugl::BinaryReader::read	(	Uint32 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of 32 bit unsigned integers from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of 32 bit unsigned integers read from the stream

read() [9/10]

size_t cugl::BinaryReader::read	(	Uint64 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of 32 bit unsigned integers from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

The values are marshalled from network order, ensuring that the binary file is compatible against all platforms.

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of 32 bit unsigned integers read from the stream

read() [10/10]

size_t cugl::BinaryReader::read	(	Uint8 *	buffer,
		size_t	maximum,
		size_t	offset = 0
	)

Reads a sequence of bytes from the stream.

The function will attempt to read up to maximum number of elements. It will return the actual number of elements read (which may be 0).

Parameters

buffer	The array to store the data when read
maximum	The maximum number of elements to read from the stream
offset	The offset to start in the buffer array

Returns

the number of bytes read from the stream

readByte()

Uint8 cugl::BinaryReader::readByte

(

)

Returns a single byte from the stream

Returns

a single byte from the stream

readChar()

char cugl::BinaryReader::readChar

(

)

Returns a single character from the stream

Returns

a single character from the stream

readDouble()

double cugl::BinaryReader::readDouble

(

)

Returns a single double from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single double from the stream

readFloat()

float cugl::BinaryReader::readFloat

(

)

Returns a single float from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single float from the stream

readSint16()

Sint16 cugl::BinaryReader::readSint16

(

)

Returns a single 16 bit signed integer from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single 16 bit signed integer from the stream

readSint32()

Sint32 cugl::BinaryReader::readSint32

(

)

Returns a single 32 bit signed integer from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single 32 bit signed integer from the stream

readSint64()

Sint64 cugl::BinaryReader::readSint64

(

)

Returns a single 32 bit signed integer from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single 32 bit signed integer from the stream

readUint16()

Uint16 cugl::BinaryReader::readUint16

(

)

Returns a single 16 bit unsigned integer from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single 16 bit unsigned integer from the stream

readUint32()

Uint32 cugl::BinaryReader::readUint32

(

)

Returns a single 32 bit unsigned integer from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single 32 bit unsigned integer from the stream

readUint64()

Uint64 cugl::BinaryReader::readUint64

(

)

Returns a single 32 bit unsigned integer from the stream

The value is marshalled from network order, ensuring that the binary file is compatible against all platforms.

Returns

a single 32 bit unsigned integer from the stream

ready()

bool cugl::BinaryReader::ready

(

unsigned int

bytes = 1

)

const

Returns true if there is still data to read.

This method will return false if the stream is closed, or if there are too few bytes remaining.

Parameters

bytes

The number of bytes required

Returns

true if there is enough data left to read

reset()

void cugl::BinaryReader::reset

(

)

Resets the stream back to the beginning

This allows the stream to be read a second time. It may even be called if the stream has been closed.

Member Data Documentation

_buffer

char* cugl::BinaryReader::_buffer

protected

The temporary transfer buffer

_bufoff

Sint32 cugl::BinaryReader::_bufoff

protected

The current offset in the read buffer

_bufsize

Uint32 cugl::BinaryReader::_bufsize

protected

The buffer capacity

_capacity

Uint32 cugl::BinaryReader::_capacity

protected

The buffer capacity

_name

std::string cugl::BinaryReader::_name

protected

The (full) path for the file

_scursor

Sint64 cugl::BinaryReader::_scursor

protected

The cursor into the SDL I/O stream

_ssize

Sint64 cugl::BinaryReader::_ssize

protected

The SDL I/O stream size

_stream

SDL_RWops* cugl::BinaryReader::_stream

protected

The SDL I/O stream for reading

---

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

• cugl/include/cugl/io/CUBinaryReader.h