Class String

Class Documentation

class String

A virtual device for manipulating strings.

Device for streaming to and from a string. Do not use this class directly, rather use the string stream class instead. It has flexible memory storage and will grow as needed to (similar to the c++ string class) but the growing algorithm isn’t really intelligent - just jumps in leaps of 256.

Reading and writing are simplified. Two separate pointers are used to designate writing and reading locations on the internal buffer.

Reading does not remove or modify the internal buffer, it simply shifts the read location pointer along the string.

Writing always appends and reading has nothing to do whatsoever with the state of the write pointer.

Public Functions

explicit String(const char *str = "")

Initialises the string device.

Configures the strings buffer with the input character string. If unspecified, it leaves the internal buffer empty.

Parameters:

str – : the input string to store in the buffer.

virtual ~String()

Cleans up memory allocations.

Cleans up the memory allocated to the buffer.

const char *c_str()

Character string representation of the device’s contents.

This returns a null terminates string representing the contents of the device’s internal buffer.

Returns:

const char* : pointer to the device’s internal buffer.

std::string str()

String representation of the device’s contents.

This generates a c++ style string representing the contents of the device’s internal buffer.

Returns:

string : string representation of the device’s internal buffer.

void clear()

Clears the device’s internal buffers.

Clears the internal character buffer and resets read/write location pointers.

long read(char &c)

Read a character from the string device.

Reads a single character from the string device.

Parameters:

c – : character to read into from the string device.

Returns:

long : number of bytes written.

long read(char *s, unsigned long n)

Reads a character string from the string device.

Reads a character string from the string device.

Parameters:

  • s – : character string to read into from the string device.

  • n – : the number of bytes to read.

unsigned long remaining()

Specifies the number of characters remaining to be read..

Determines the number of unread characters left in the internal buffer.

Returns:

unsigned long : number of characters remaining.

long write(char c)

Write a character to the buffer.

Write a character to the buffer. It will automatically grow the buffer if necessary.

Parameters:

c – : the character to write.

Returns:

long : the number of bytes written.

long write(const char *s, unsigned long n)

Write a character string to the buffer.

Write a character string to the buffer. It will automatically grow the buffer if necessary.

Parameters:

  • s – : points to the beginning of the character string

  • n – : the number of characters to write.

Throws:

StandardException – : throws if flushing returned an error [debug mode only].

Returns:

long: the number of bytes written.

unsigned long size()

Number of characters stored in the buffer.

This returns the size of the buffer - note that this is different to the number of characters remaining to be read. It is the sum of both read and unread parts.

Returns:

unsigned long : number of characters stored in the buffer.

inline void flush()

Unused, but required api for an output device.

This is not used for string devices, but necessary for the concept definition of an output device.

inline bool open()

Unused, but required api for an ecl device.

This is not used for string devices, but necessary for the concept definition of an ecl device.

Returns:

bool : always returns true.

inline bool isOpen()

Unused, but required api for an ecl device.

Redundant api for the string device.

This is not used for string devices, but necessary for the concept definition of an ecl device.

Returns:

bool : always returns true.