Class representing a sequence of characters. More...

#include <String.hpp>

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

Public Member Functions
	String ()
	Default constructor - creates empty managed unbounded String.
	String (UnsignedLong bound, RETURN_CODE &return_code)
	Managed constructor - creates empty managed bounded String of specified bound.
	String (const char *str)
	Unmanaged constructor.
	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 (const String &str)
	Managed copy constructor.
	~String ()
	If not Safety Base profile or stricter, this destructor frees any data managed by this String.
String &	operator= (const String &str)
	Managed assignment operator.
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 char *str)
	Adds a copy of a C-string's data to the current data.
RETURN_CODE	append (char c)
	Adds a character to the current data.
RETURN_CODE	reserve (UnsignedLong capacity)
	Attempt to reserve memory to store `capacity` characters.
char &	operator[] (UnsignedLong index)
	Returns a reference to the character at a given index.
const char &	operator[] (UnsignedLong index) const
	Returns a const reference to the character at a given index.
char *	buffer ()
	Returns a pointer to the underlying character buffer.
const char *	buffer () const
	Returns a const pointer to the underlying character buffer.
UnsignedLong	length () const
	Returns the length of this String.
UnsignedLong	capacity () const
	Returns the capacity of this String.
UnsignedLong	bound () const
	Returns the bound of this String.
Boolean	is_managed () const
	Returns whether or not this String is managed.
Boolean	is_bounded () const
	Returns whether or not this String is bounded.
Boolean	is_valid () const
	Returns whether or not this String is valid.

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_MEMORY	A String is unable to allocate enough memory to perform some function.
INSUFFICIENT_BOUND	Executing a function would cause a String's length to exceed its bound.
PRECONDITION_VIOLATED	A precondition of some function has been violated.
INVALID_PARAM	A parameter to a function is invalid.

Constructor & Destructor Documentation

FACE::String::String ( )

inline

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 For SafetyBase and stricter compliance levels, the String will be in an invalid state after construction, and is_valid() will return FALSE.

References UNBOUNDED_SENTINEL.

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

inline

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

       @param bound The maximum number of characters this String can hold.
       @param[out] return_code Set to PRECONDITION_VIOLATED if bound is 0
       or UNBOUNDED_SENTINEL.

References bound(), INSUFFICIENT_MEMORY, NO_ERROR, PRECONDITION_VIOLATED, and UNBOUNDED_SENTINEL.

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

inline

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 char *	str,
		RETURN_CODE &	return_code
	)

inline

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)

References INSUFFICIENT_MEMORY, NO_ERROR, and PRECONDITION_VIOLATED.

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

inline

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)

References bound(), length(), NO_ERROR, and PRECONDITION_VIOLATED.

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

inline

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.

References is_valid(), and UNBOUNDED_SENTINEL.

FACE::String::~String ( )

inline

If not Safety Base profile or stricter, this destructor frees any data managed by this String.

Member Function Documentation

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

inline

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

References is_valid(), and UNBOUNDED_SENTINEL.

void FACE::String::clear ( )

inline

Clears this String's data.

If this String is managed, its length is set to 0. The capacity is unchanged. If unmanaged, this method has no effect.

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

inline

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

Parameters:

str	The String to append.

Returns:: A return code indicating success or failure.

References INSUFFICIENT_BOUND, is_valid(), NO_ERROR, PRECONDITION_VIOLATED, reserve(), and UNBOUNDED_SENTINEL.

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

inline

Adds a copy of a C-string's data to the current data.

Parameters:

str	The C-string to append.

Returns:: A return code indicating success or failure.

References INSUFFICIENT_BOUND, INVALID_PARAM, NO_ERROR, PRECONDITION_VIOLATED, reserve(), and UNBOUNDED_SENTINEL.

RETURN_CODE FACE::String::append ( char c )

inline

Adds a character to the current data.

Parameters:

c	The character to append.

Returns:: A return code indicating success or failure.

References INSUFFICIENT_BOUND, NO_ERROR, PRECONDITION_VIOLATED, reserve(), and UNBOUNDED_SENTINEL.

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

inline

Attempt to reserve memory to store capacity characters.

This method only applies to unbounded, managed Strings.

Parameters:

capacity The desired new capacity.

Returns:: A return code indicating success or failure.

References capacity(), INSUFFICIENT_MEMORY, NO_ERROR, PRECONDITION_VIOLATED, and UNBOUNDED_SENTINEL.

Referenced by append().

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

inline

Returns a reference to the character at a given index.

If index is out of range, a reference to a static null character is returned.

Parameters:

index The index of the character to return.

Returns:: A reference to the character.

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

inline

Returns a const reference to the character at a given index.

(see FACE::String::operator[])

char* FACE::String::buffer ( )

inline

Returns a pointer to the underlying character buffer.

If the String is invalid, returns NULL.

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

inline

Returns a const pointer to the underlying character buffer.

If the String is invalid, returns an empty string literal.

UnsignedLong FACE::String::length ( ) const

inline

Returns the length of this String.

Referenced by String().

UnsignedLong FACE::String::capacity ( ) const

inline

Returns the capacity of this String.

Referenced by reserve().

UnsignedLong FACE::String::bound ( ) const

inline

Returns the bound of this String.

Referenced by String().

Boolean FACE::String::is_managed ( ) const

inline

Returns whether or not this String is managed.

A managed String owns and manages its memory. An unmanaged String wraps a buffer whose lifetime is managed elsewhere.

Boolean FACE::String::is_bounded ( ) const

inline

Returns whether or not this String is bounded.

References UNBOUNDED_SENTINEL.

Boolean FACE::String::is_valid ( ) const

inline

Returns whether or not this String is valid.

An invalid String can result from a failed constructor call or a precondition violation in a method.

Referenced by append(), operator=(), and String().

Field Documentation

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

static

Constant representing the bound of an unbounded String.

This value is returned by bound() for an unbounded String, and is used as a sentinel value in constructors that take a bound parameter to indicate an unbounded String. Unbounded are not supported in SafetyBase or stricter compliance levels.

Referenced by append(), is_bounded(), operator=(), reserve(), and String().

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation