#include <CUTextReader.h>

Inheritance diagram for cugl::TextReader:

Public Member Functions
	TextReader ()

	~TextReader ()

bool	init (const std::string &file)

bool	init (const char *file)

bool	init (const Pathname &file)

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

bool	init (const char *file, unsigned int capacity)

bool	init (const Pathname &file, unsigned int capacity)

bool	initWithAsset (const std::string &file)

bool	initWithAsset (const char *file)

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

bool	initWithAsset (const char *file, unsigned int capacity)

void	reset ()

void	close ()

bool	ready () const

char	read ()

std::string &	read (std::string &data)

std::string	readUTF8 ()

std::string &	readUTF8 (std::string &data)

std::string	readLine ()

std::string &	readLine (std::string &data)

std::string	readAll ()

std::string &	readAll (std::string &data)

void	skip ()

Static Public Member Functions
static std::shared_ptr< TextReader >	alloc (const std::string &file)

static std::shared_ptr< TextReader >	alloc (const char *file)

static std::shared_ptr< TextReader >	alloc (const Pathname &file)

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

static std::shared_ptr< TextReader >	alloc (const char *file, unsigned int capacity)

static std::shared_ptr< TextReader >	alloc (const Pathname &file, unsigned int capacity)

static std::shared_ptr< TextReader >	allocWithAsset (const std::string &file)

static std::shared_ptr< TextReader >	allocWithAsset (const char *file)

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

static std::shared_ptr< TextReader >	allocWithAsset (const char *file, unsigned int capacity)

Protected Member Functions
void	fill ()

Protected Attributes
std::string	_name

SDL_RWops *	_stream

Sint64	_ssize

Sint64	_scursor

std::string	_sbuffer

char *	_cbuffer

Uint32	_capacity

Sint32	_bufoff

Detailed Description

Simple text-based reader for ASCII or UTF8 files.

This class provides a simple Java-style reader for reading from text files. It supports both ASCII and UTF8 encoding. No other encodings are supported (nor should they be since they are not cross-platform).

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

cugl::TextReader::TextReader ( )

inline

Creates a text 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.

cugl::TextReader::~TextReader ( )

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

static std::shared_ptr<TextReader> cugl::TextReader::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.

static std::shared_ptr<TextReader> cugl::TextReader::alloc ( const char * 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.

static std::shared_ptr<TextReader> cugl::TextReader::alloc ( const Pathname & 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.

static std::shared_ptr<TextReader> cugl::TextReader::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.

static std::shared_ptr<TextReader> cugl::TextReader::alloc	(	const char *	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.

static std::shared_ptr<TextReader> cugl::TextReader::alloc	(	const Pathname &	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.

static std::shared_ptr<TextReader> cugl::TextReader::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.

static std::shared_ptr<TextReader> cugl::TextReader::allocWithAsset ( const char * 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.

static std::shared_ptr<TextReader> cugl::TextReader::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.

static std::shared_ptr<TextReader> cugl::TextReader::allocWithAsset	(	const char *	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.

void cugl::TextReader::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.

void cugl::TextReader::fill ( )

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.

bool cugl::TextReader::init ( const std::string & file )

inline

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.

bool cugl::TextReader::init ( const char * file )

inline

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.

bool cugl::TextReader::init ( const Pathname & 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.

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

inline

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.

bool cugl::TextReader::init	(	const char *	file,
		unsigned int	capacity
	)

inline

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.

bool cugl::TextReader::init	(	const Pathname &	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.

bool cugl::TextReader::initWithAsset ( const std::string & file )

inline

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.

bool cugl::TextReader::initWithAsset ( const char * 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.

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

inline

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.

bool cugl::TextReader::initWithAsset	(	const char *	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.

char cugl::TextReader::read ( )

Returns a single ASCII character from the stream

The value returned is a single byte character. This means that it is not safe to call this method on UTF8 files, as the value returned may be a control point and not a complete character.

Returns: a single ASCII character from the stream

std::string& cugl::TextReader::read ( std::string & data )

Returns the argument with an ASCII character appended from the stream.

The argument is modified to receive the newly read data at the end.

The value appended is a single byte character. This means that it is not safe to call this method on UTF8 files, as the value returned may be a control point and not a complete character.

Parameters

data	the argument to modify

Returns: the argument with an ASCII character appended from the stream.

std::string cugl::TextReader::readAll ( )

Returns the unread remainder of the stream

This method will exhaust the stream of all characters, but will not close it. Future attempts to read the stream will fail.

Returns: the unread remainder of the stream

std::string& cugl::TextReader::readAll ( std::string & data )

Returns the argument with the remainder of the stream appended.

The argument is modified to receive the newly read data at the end.

This method will exhaust the stream of all characters, but will not close it. Future attempts to read the stream will fail.

Parameters

data	the argument to modify

Returns: the argument with the remainder of the stream appended.

std::string cugl::TextReader::readLine ( )

Returns a single line for text from the stream

A line of text is indicated by the newline character '
', regardless of the platform. Therefore, this class should not be used to read files with Windows-style line feeds. If the reader reaches the end of the file without encountering a newline, it will return the remainder of the file.

Returns: a single line for text from the stream

std::string& cugl::TextReader::readLine ( std::string & data )

Returns the argument with a single line appended from the stream.

The argument is modified to receive the newly read data at the end.

A line of text is indicated by the newline character '
', regardless of the platform. Therefore, this class should not be used to read files with Windows-style line feeds. If the reader reaches the end of the file without encountering a newline, it will append the remainder of the file.

Parameters

data	the argument to modify

Returns: the argument with a single line appended from the stream.

std::string cugl::TextReader::readUTF8 ( )

Returns a single UTF8 character from the stream

Because of the way UTF8 values are encoded, the resulting value may be anywhere from 1 to 4 bytes. That is why the result is returned as a variable length string.

Returns: a single UTF8 character from the stream

std::string& cugl::TextReader::readUTF8 ( std::string & data )

Returns the argument with a UTF8 character appended from the stream.

The argument is modified to receive the newly read data at the end.

Because of the way UTF8 values are encoded, the resulting value may be anywhere from 1 to 4 bytes.

Parameters

data	the argument to modify

Returns: the argument with a UTF8 character appended from the stream.

bool cugl::TextReader::ready ( ) const

inline

Returns true if there is still data to read.

This method will return false if the stream is closed.

Returns: true if there is still data to read

void cugl::TextReader::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.

void cugl::TextReader::skip ( )

Skips over any whitespace in the stream.

This method will move the read head until it reaches a non-whitespace character or the end of the file, which ever comes first.

Member Data Documentation

Sint32 cugl::TextReader::_bufoff

protected

The current offset in the read buffer

Uint32 cugl::TextReader::_capacity

protected

The buffer capacity

char* cugl::TextReader::_cbuffer

protected

The temporary transfer buffer

std::string cugl::TextReader::_name

protected

The (full) path for the file

std::string cugl::TextReader::_sbuffer

protected

The buffer for storing data read from the stream

Sint64 cugl::TextReader::_scursor

protected

The cursor into the SDL I/O stream

Sint64 cugl::TextReader::_ssize

protected

The SDL I/O stream size

SDL_RWops* cugl::TextReader::_stream

protected

The SDL I/O stream for reading

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

io/CUTextReader.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation