cugl::TextReader Class Reference

#include <CUTextReader.h>

Inheritance diagram for cugl::TextReader:

Public Member Functions
	TextReader ()
	~TextReader ()
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 () 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 std::string file, unsigned int capacity)
static std::shared_ptr< TextReader >	allocWithAsset (const std::string file)
static std::shared_ptr< TextReader >	allocWithAsset (const std::string 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

TextReader()

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.

~TextReader()

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

alloc() [1/2]

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.

alloc() [2/2]

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.

allocWithAsset() [1/2]

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.

allocWithAsset() [2/2]

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.

close()

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.

fill()

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.

init() [1/2]

bool cugl::TextReader::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::TextReader::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::TextReader::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::TextReader::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/2]

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

read() [2/2]

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.

readAll() [1/2]

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

readAll() [2/2]

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.

readLine() [1/2]

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

readLine() [2/2]

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.

readUTF8() [1/2]

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

readUTF8() [2/2]

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.

ready()

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

reset()

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.

skip()

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

_bufoff

Sint32 cugl::TextReader::_bufoff

protected

The current offset in the read buffer

_capacity

Uint32 cugl::TextReader::_capacity

protected

The buffer capacity

_cbuffer

char* cugl::TextReader::_cbuffer

protected

The temporary transfer buffer

_name

std::string cugl::TextReader::_name

protected

The (full) path for the file

_sbuffer

std::string cugl::TextReader::_sbuffer

protected

The buffer for storing data read from the stream

_scursor

Sint64 cugl::TextReader::_scursor

protected

The cursor into the SDL I/O stream

_ssize

Sint64 cugl::TextReader::_ssize

protected

The SDL I/O stream size

_stream

SDL_RWops* cugl::TextReader::_stream

protected

The SDL I/O stream for reading

---

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

• include/cugl/io/CUTextReader.h