CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
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< BinaryReaderalloc (const std::string file)
 
static std::shared_ptr< BinaryReaderalloc (const std::string file, unsigned int capacity)
 
static std::shared_ptr< BinaryReaderallocWithAsset (const std::string file)
 
static std::shared_ptr< BinaryReaderallocWithAsset (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
filethe 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
filethe path (absolute or relative) to the file
capacitythe 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
filethe 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
filethe relative path to the file
capacitythe 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
bytesThe 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
filethe 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
filethe path (absolute or relative) to the file
capacitythe 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
filethe 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
filethe relative path to the file
capacitythe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bufferThe array to store the data when read
maximumThe maximum number of elements to read from the stream
offsetThe 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
bytesThe 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: