CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::TextReader Class Reference

#include <CUTextReader.h>

Inheritance diagram for cugl::TextReader:
cugl::JsonReader

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< TextReaderalloc (const std::string file)
 
static std::shared_ptr< TextReaderalloc (const std::string file, unsigned int capacity)
 
static std::shared_ptr< TextReaderallocWithAsset (const std::string file)
 
static std::shared_ptr< TextReaderallocWithAsset (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
filethe 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
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<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
filethe 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
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::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
filethe 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
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::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
filethe 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
filethe relative path to the file
capacitythe 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
datathe 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
datathe 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
datathe 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
datathe 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: