cugl::BinaryWriter Class Reference

#include <CUBinaryWriter.h>

Public Member Functions
	BinaryWriter ()
	~BinaryWriter ()
bool	init (const std::string file)
bool	init (const std::string file, unsigned int capacity)
void	flush ()
void	close ()
void	write (char c)
void	writeUint8 (Uint8 c)
void	writeSint16 (Sint16 n)
void	writeUint16 (Uint16 n)
void	writeSint32 (Sint32 n)
void	writeUint32 (Uint32 n)
void	writeSint64 (Sint64 n)
void	writeUint64 (Uint64 n)
void	writeFloat (float n)
void	writeDouble (double n)
void	write (const char *array, size_t length, size_t offset=0)
void	write (const Uint8 *array, size_t length, size_t offset=0)
void	write (const Sint16 *array, size_t length, size_t offset=0)
void	write (const Uint16 *array, size_t length, size_t offset=0)
void	write (const Sint32 *array, size_t length, size_t offset=0)
void	write (const Uint32 *array, size_t length, size_t offset=0)
void	write (const Sint64 *array, size_t length, size_t offset=0)
void	write (const Uint64 *array, size_t length, size_t offset=0)
void	write (const float *array, size_t length, size_t offset=0)
void	write (const double *array, size_t length, size_t offset=0)

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

Protected Attributes
std::string	_name
SDL_RWops *	_stream
char *	_cbuffer
Uint32	_capacity
Sint32	_bufoff

Detailed Description

Simple cross-platform writer for binary files.

This class provides a simple Java-style writer for encoding binary files. All data is marshalled to network order, ensuring that the files are the same across multiple platforms.

Note that this writer 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

BinaryWriter()

cugl::BinaryWriter::BinaryWriter ( )

inline

Creates a binary writer 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.

~BinaryWriter()

cugl::BinaryWriter::~BinaryWriter ( )

inline

Deletes this writer 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< BinaryWriter > cugl::BinaryWriter::alloc ( const std::string  file )

inlinestatic

Returns a newly allocated writer for the given file.

The writer will have the default buffer capacity for writing chunks to 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 write a file in any other directory, you must provide an absolute path. Be warned, however, that write priviledges are heavily restricted on mobile platforms.

Parameters

file	the path (absolute or relative) to the file

Returns

a newly allocated writer for the given file.

alloc() [2/2]

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

inlinestatic

Returns a newly allocated writer 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 write a file in any other directory, you must provide an absolute path. Be warned, however, that write priviledges are heavily restricted on mobile platforms.

Parameters

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

Returns

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

close()

void cugl::BinaryWriter::close

(

)

Closes the stream, releasing all resources

The contents of the buffer are flushed before the file is closed. Any attempts to write to a closed stream will fail. Calling this method on a previously closed stream has no effect.

flush()

void cugl::BinaryWriter::flush

(

)

Flushes the contents of the write buffer to the file.

It is usually unnecessary to call this method. It is called automatically when the buffer fills, or just before the file is closed.

init() [1/2]

bool cugl::BinaryWriter::init

(

const std::string

file

)

Initializes a writer for the given file.

The writer will have the default buffer capacity for writing chunks to 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 write a file in any other directory, you must provide an absolute path. Be warned, however, that write priviledges are heavily restricted on mobile platforms.

Parameters

file	the path (absolute or relative) to the file

Returns

true if the writer is initialized properly, false otherwise.

init() [2/2]

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

Initializes a writer 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 write a file in any other directory, you must provide an absolute path. Be warned, however, that write priviledges are heavily restricted on mobile platforms.

Parameters

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

Returns

true if the writer is initialized properly, false otherwise.

write() [1/11]

void cugl::BinaryWriter::write

(

char

c

)

Writes a character to the binary file.

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

c	the character to write

write() [2/11]

void cugl::BinaryWriter::write	(	const char *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of characters to the binary file.

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of characters to write
length	the number of characters to write
offset	the initial offset into the array

write() [3/11]

void cugl::BinaryWriter::write	(	const double *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of doubles to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of doubles to write
length	the number of doubles to write
offset	the initial offset into the array

write() [4/11]

void cugl::BinaryWriter::write	(	const float *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of floats to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of floats to write
length	the number of floats to write
offset	the initial offset into the array

write() [5/11]

void cugl::BinaryWriter::write	(	const Sint16 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of 16 bit signed integers to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of 16 bit signed integers to write
length	the number of 16 bit signed integers to write
offset	the initial offset into the array

write() [6/11]

void cugl::BinaryWriter::write	(	const Sint32 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of 32 bit signed integers to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of 32 bit signed integers to write
length	the number of 32 bit signed integers to write
offset	the initial offset into the array

write() [7/11]

void cugl::BinaryWriter::write	(	const Sint64 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of 64 bit signed integers to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of 64 bit signed integers to write
length	the number of 64 bit signed integers to write
offset	the initial offset into the array

write() [8/11]

void cugl::BinaryWriter::write	(	const Uint16 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of 16 bit unsigned integers to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of 16 bit unsigned integers shorts to write
length	the number of 16 bit unsigned integers shorts to write
offset	the initial offset into the array

write() [9/11]

void cugl::BinaryWriter::write	(	const Uint32 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of 32 bit unsigned integers to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of 32 bit unsigned integers shorts to write
length	the number of 32 bit unsigned integers shorts to write
offset	the initial offset into the array

write() [10/11]

void cugl::BinaryWriter::write	(	const Uint64 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of 64 bit unsigned integers to the binary file.

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

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of 64 bit unsigned integers shorts to write
length	the number of 64 bit unsigned integers shorts to write
offset	the initial offset into the array

write() [11/11]

void cugl::BinaryWriter::write	(	const Uint8 *	array,
		size_t	length,
		size_t	offset = 0
	)

Writes an array of bytes to the binary file.

The array is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

array	the array of bytes to write
length	the number of bytes to write
offset	the initial offset into the array

writeDouble()

void cugl::BinaryWriter::writeDouble

(

double

n

)

Writes a double to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the double to write

writeFloat()

void cugl::BinaryWriter::writeFloat

(

float

n

)

Writes a float to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the float to write

writeSint16()

void cugl::BinaryWriter::writeSint16

(

Sint16

n

)

Writes a single 16 bit signed integer to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the 16 bit signed integer to write

writeSint32()

void cugl::BinaryWriter::writeSint32

(

Sint32

n

)

Writes a single 32 bit signed integer to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the 32 bit signed integer to write

writeSint64()

void cugl::BinaryWriter::writeSint64

(

Sint64

n

)

Writes a single 64 bit signed integer to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the 64 bit signed integer to write

writeUint16()

void cugl::BinaryWriter::writeUint16

(

Uint16

n

)

Writes a single 16 bit unsigned integer to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the 16 bit unsigned integer to write

writeUint32()

void cugl::BinaryWriter::writeUint32

(

Uint32

n

)

Writes a single 32 bit unsigned integer to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the 32 bit unsigned integer to write

writeUint64()

void cugl::BinaryWriter::writeUint64

(

Uint64

n

)

Writes a single 64 bit unsigned integer to the binary file.

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

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

n	the 64 bit unsigned integer to write

writeUint8()

void cugl::BinaryWriter::writeUint8

(

Uint8

c

)

Writes a byte to the binary file.

The value is written to the internal buffer, but is not necessarily flushed automatically. It will be written when the buffer reaches capacity or the file is closed.

Parameters

c	the byte to write

Member Data Documentation

_bufoff

Sint32 cugl::BinaryWriter::_bufoff

protected

The current offset in the writer buffer

_capacity

Uint32 cugl::BinaryWriter::_capacity

protected

The buffer capacity

_cbuffer

char* cugl::BinaryWriter::_cbuffer

protected

The buffer for cutting down on file access

_name

std::string cugl::BinaryWriter::_name

protected

The (full) path for the file

_stream

SDL_RWops* cugl::BinaryWriter::_stream

protected

The SDL I/O stream for writing

---

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

• cugl/include/cugl/io/CUBinaryWriter.h