Class representing a sequence of characters. More...

#include <String.hpp>

Public Types
enum	RETURN_CODE { NO_ERROR, INSUFFICIENT_BOUND, INSUFFICIENT_MEMORY, PRECONDITION_VIOLATED }
	Return codes used to report certain runtime errors. More...

Public Member Functions
	String ()
	Default constructor - creates empty managed unbounded String.
	String (FACE::UnsignedLong bound, RETURN_CODE &return_code)
	Managed constructor - creates empty managed bounded String of specified bound.
	String (const char *str)
	Unmanaged constructor.
	String (const String &str)
	Managed copy constructor.
String &	operator= (const String &str)
	Managed assignment operator.
	String (const char *str, RETURN_CODE &return_code)
	Managed C-string constructor.
	String (char *str, FACE::UnsignedLong length, FACE::UnsignedLong bound, RETURN_CODE &return_code)
	Unmanaged constructor.
	~String ()
	Frees any data managed by this String.
void	clear ()
	Clears this String's data.
RETURN_CODE	append (const String &str)
	Adds a copy of `str's` data to the current data.
RETURN_CODE	append (const FACE::Char &elem)
	Adds a copy of `elem` to the current data.
RETURN_CODE	reserve (FACE::UnsignedLong capacity)
	Attempt to reserve memory to store `capacity` characters.
FACE::UnsignedLong	length () const
	Returns the length of this String.
FACE::UnsignedLong	capacity () const
	Returns the capacity of this String.
FACE::UnsignedLong	bound () const
	Returns the bound of this String.
FACE::Boolean	is_managed () const
	Returns whether or not this String is managed.
FACE::Boolean	is_bounded () const
	Returns whether or not this String is bounded.
FACE::Boolean	is_valid () const
	Returns whether or not this String is in the invalid state.

char &	operator[] (FACE::UnsignedLong index)
	Returns a reference to the character at a given index.

char *	buffer ()
	Returns C-string representation of string data.

Static Public Attributes
static const unsigned int	UNBOUNDED_SENTINEL = UINT_MAX
	Constant representing the bound of an unbounded String.

Detailed Description

Class representing a sequence of characters.

A FACE::String is defined by three characteristics:

length - the current number of characters (excluding NUL) in the String
bound - the maximum number of characters (excluding NUL) the String can ever hold. This bound is logical, and is independent from the size of any underlying memory. A String's bound is fixed throughout the lifetime of the String. An "unbounded" String has an infinite bound, represented by FACE::String::UNBOUNDED_SENTINEL.
capacity - the number of characters (excluding NUL) a String has currently allocated memory for. This may vary by implementation, but length <= capacity <= bound is always true.

A "managed" String is responsible for and manages the lifetime of the memory for the data it represents. An "unmanaged" String essentially wraps a pointer to memory whose lifetime is managed elsewhere.

This class does not throw exceptions, but precondition violations and memory allocation failures can occur in constructors and other methods that cannot return a value. In these situations, a String object is put into a known "invalid state", used to indicate that an object has been constructed but is not valid and should not be used. In this invalid state:

length(), bound(), capacity() will return 0
buffer() will return NULL
is_managed() and is_bounded() will return FALSE The is_valid() method indicates whether or not an object is in this state.

Member Enumeration Documentation

enum FACE::String::RETURN_CODE

Return codes used to report certain runtime errors.

Enumerator:

NO_ERROR	No error has occurred.
INSUFFICIENT_BOUND	Executing a function would cause a String's length to exceed its bound.
INSUFFICIENT_MEMORY	A String is unable to allocate enough memory to perform some function.
PRECONDITION_VIOLATED	A precondition of some function has been violated.

Constructor & Destructor Documentation

FACE::String::String ( )

Default constructor - creates empty managed unbounded String.

No memory is allocated. After construction,

length() will return 0
capacity() will return 0
bound() will return UNBOUNDED_SENTINEL
buffer() will return the empty string

FACE::String::String	(	FACE::UnsignedLong	bound,
		RETURN_CODE &	return_code
	)

Managed constructor - creates empty managed bounded String of specified bound.

Memory may or may not be allocated.

       Preconditions:
        - bound != 0
        - bound != UNBOUNDED_SENTINEL
       When calling this function, if any of these preconditions are false,
        - return_code will be set to PRECONDITION_VIOLATED
        - this String is put into the invalid state

       While the implementation does not have to allocate memory equal in
       size to the requested bound, memory allocation may still fail. If no
       preconditions are violated and memory allocation fails:
        - return_code will be set to INSUFFICIENT_MEMORY
        - this String is put into the invalid state

       Otherwise:
        - return_code will be set to NO_ERROR
        - length() will return 0
        - capacity() will return the current capacity
        - bound() will return the specified bound
        - buffer() will return the empty string

FACE::String::String ( const char * str )

Unmanaged constructor.

After construction, this String does not manage its own data, but instead serves as a wrapper to the data pointed to by str.

The caller must ensure str is a NULL terminated string If this condition is violated, the result is implementation-defined behavior and may result in an attempt to access restricted memory.

The capacity of this String is equal to the length of the NULL terminated string str not counting the NULL terminator, because the externally managed memory has a fixed size, which is both a bound and a capacity.

After construction the following are true:

length() will return the length of the current string not counting the NULL terminator
capacity() will return the capacity which is equal to the length of the original string not counting the NULL terminator
bound() will return the same as capacity()
buffer() will return the address specified by str
Parameters:

str pointer to externally managed memory (must be NULL terminated)

FACE::String::String ( const String & str )

Managed copy constructor.

After construction, this String manages its own data, which is a copy of str's data, and has the same bound as str. If sufficient memory cannot be allocated, this String is put into the invalid state.

FACE::String::String	(	const char *	str,
		RETURN_CODE &	return_code
	)

Managed C-string constructor.

After successful construction, this String manages its own data, which is a copy of str, and bound() will return str's length.

Preconditions:

str != NULL When calling this function, if any of these preconditions are false,
return_code will be set to PRECONDITION_VIOLATED
this String is put into the invalid state

If no preconditions are violated and memory allocation fails:

return_code will be set to INSUFFICIENT_MEMORY
this String is put into the invalid state

Parameters:

str	A NUL-terminated string.
return_code	(see details)

FACE::String::String	(	char *	str,
		FACE::UnsignedLong	length,
		FACE::UnsignedLong	bound,
		RETURN_CODE &	return_code
	)

Unmanaged constructor.

After construction, this String does not manage its own data, but instead serves as a wrapper to the data pointed to by str.

The caller must ensure bound (plus space for NUL) is not greater than the size of the memory allocated at str. If this condition is violated, the result is implementation-defined behavior and may result in an attempt to access restricted memory.

The capacity of this String is equal to its bound, because the externally managed memory has a fixed size, which is both a bound and a capacity.

Preconditions:

str != NULL
length <= bound
bound != 0 (no empty unmanaged strings)
bound != UNBOUNDED_SENTINEL (no unbounded unmanaged strings) When calling this function, if any of these preconditions are false:
return_code will be set to PRECONDITION_VIOLATED
this String is put into the invalid state

Otherwise:

return_code will be set to NO_ERROR
length() will return the specified length
capacity() will return the specified capacity (bound)
bound() will return the specified bound
buffer() will return a pointer to the externally managed memory

Parameters:

str	pointer to externally managed memory
length	the number of characters (excluding the NUL character) in the memory pointed to by `str`
bound	the number of characters (excluding the NUL character) the externally managed memory can hold. Also serves as a capacity.
return_code	(see details)

FACE::String::~String ( )

Frees any data managed by this String.

Member Function Documentation

String& FACE::String::operator= ( const String & str )

Managed assignment operator.

After assignment, this String's data is a copy of str's data, and bound() will return str's bound. After assignment, this String's data is managed. If sufficient memory cannot be allocated, this String is put into the invalid state.

Returns:: a reference to this String

void FACE::String::clear ( )

Clears this String's data.

All data is cleared, and this String's length will be set to 0. Memory allocation remains unchanged.

RETURN_CODE FACE::String::append ( const String & str )

Adds a copy of str's data to the current data.

This is one of two String functions that may reallocate managed memory. If append is successful, the length of this String changes accordingly; capacity may or may not be changed. If append is unsuccessful, the state of this String is unchanged.

Return values:

INSUFFICIENT_BOUND	if append would exceed logical bound
INSUFFICIENT_MEMORY	if append exceeds available memory
NO_ERROR	otherwise

RETURN_CODE FACE::String::append ( const FACE::Char & elem )

Adds a copy of elem to the current data.

This is one of two String functions that may reallocate managed memory. If append is successful, the length of this String changes accordingly; capacity may or may not be changed. If append is unsuccessful, the state of this String is unchanged.

Return values:

INSUFFICIENT_BOUND	if append would exceed logical bound
INSUFFICIENT_MEMORY	if append exceeds available memory
NO_ERROR	otherwise

RETURN_CODE FACE::String::reserve ( FACE::UnsignedLong capacity )

Attempt to reserve memory to store capacity characters.

This function is useful when an instance is constructed as a managed-unbounded string with an implementation-defined capacity in order to perform potential reallocation at a known point of program execution, such as during program initialization.

On success, the implementation can store a string value of capacity capacity. The function may succeed without reallocation if the implementation-defined capacity exceeds capacity and the implementation does not reallocate to a smaller capacity.

Parameters:

capacity number of elements to reserve storage for

Preconditions:

is_valid() == true
is_managed() == true
is_bounded() == false When calling this function, if any of these preconditions are false this String is put into the invalid state.

Return values:

PRECONDITION_VIOLATED	if any preconditions are false
INSUFFICIENT_MEMORY	if memory allocation fails
NO_ERROR	otherwise

char& FACE::String::operator[] ( FACE::UnsignedLong index )

Returns a reference to the character at a given index.

If index is out of range, '\0' is returned. Strings use a zero-based index.

Parameters:

index The index of the element to be retrieved

Returns:: a reference to the desired element.

char* FACE::String::buffer ( )

Returns C-string representation of string data.

Returns a pointer to a NUL-terminated (C-style) string equivalent to this String's underlying string data.

FACE::UnsignedLong FACE::String::length ( ) const

Returns the length of this String.

FACE::UnsignedLong FACE::String::capacity ( ) const

Returns the capacity of this String.

FACE::UnsignedLong FACE::String::bound ( ) const

Returns the bound of this String.

FACE::Boolean FACE::String::is_managed ( ) const

Returns whether or not this String is managed.

Return values:

TRUE	if this String manages its own memory
FALSE	otherwise

FACE::Boolean FACE::String::is_bounded ( ) const

Returns whether or not this String is bounded.

Equivalent to bound() != UNBOUNDED_SENTINEL Unmanaged strings are always bounded.

FACE::Boolean FACE::String::is_valid ( ) const

Returns whether or not this String is in the invalid state.

(see class details)

Field Documentation

const unsigned int FACE::String::UNBOUNDED_SENTINEL = UINT_MAX

static

Constant representing the bound of an unbounded String.

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation