Class representing a sequence of elements of type T. More...

#include <Sequence.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
	Sequence ()
	Default constructor - creates empty managed unbounded Sequence.
	Sequence (FACE::UnsignedLong bound, RETURN_CODE &return_code)
	Managed constructor - creates empty Sequence of specified bound.
	Sequence (const Sequence &seq)
	Managed copy constructor.
Sequence &	operator= (const Sequence &seq)
	Managed assignment operator.
	Sequence (const T *arr, FACE::UnsignedLong length, RETURN_CODE &return_code)
	Managed C-style array constructor.
	Sequence (T *seq, FACE::UnsignedLong length, FACE::UnsignedLong bound, RETURN_CODE &return_code)
	Unmanaged constructor.
	~Sequence ()
	Frees any data managed by this Sequence.
void	clear ()
	Clears this String's data.
RETURN_CODE	append (const Sequence &seq)
	Adds a copy of `seq's` data to the current data.
RETURN_CODE	append (const T &elem)
	Adds a copy of `elem` to the current data.
RETURN_CODE	reserve (FACE::UnsignedLong capacity)
FACE::UnsignedLong	length () const
	Returns the length of this Sequence.
FACE::UnsignedLong	capacity () const
	Returns the capacity of this Sequence.
FACE::UnsignedLong	bound () const
	Returns the bound of this Sequence.
FACE::Boolean	is_managed () const
	Returns whether or not this Sequence is managed.
FACE::Boolean	is_bounded () const
	Returns whether or not this Sequence is bounded.
FACE::Boolean	is_valid () const
	Returns whether or not this Sequence is in the invalid state.

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

T *	buffer ()
	Returns pointer to contiguous memory for underlying data.

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

Detailed Description

template<typename T>
class FACE::Sequence< T >

Class representing a sequence of elements of type T.

A FACE::Sequence is defined by three characteristics:

length - the current number of elements in the Sequence
bound - the maximum number of elements the Sequence can ever hold. This bound is logical, and is independent from the size of any underlying memory. A Sequence's bound is fixed throughout the lifetime of the Sequence. An "unbounded" sequence has an infinite bound, represented by FACE::Sequence::UNBOUNDED_SENTINEL.
capacity - the number of elements the Sequence has currently allocated memory for. This may vary by implementation, but length <= capacity <= bound is always true. A "managed" Sequence is responsible for and manages the lifetime of the memory for the data it represents. An "unmanaged" Sequence essentially wraps a pointer to memory whose lifetime is managed elsewhere.

In general, Sequence method behavior is identical to String method behavior, except where otherwise noted. FACE::Sequence<T>::RETURN_CODE is used in place of FACE::String::RETURN_CODE.

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 Sequence 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.

Template Parameters:

the	element type

Member Enumeration Documentation

template<typename T>

enum FACE::Sequence::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 Sequence's length to exceed its bound.
INSUFFICIENT_MEMORY	A Sequence is unable to allocate enough memory to perform some function.
PRECONDITION_VIOLATED	A precondition of some function has been violated.

Constructor & Destructor Documentation

template<typename T>

FACE::Sequence< T >::Sequence ( )

inline

Default constructor - creates empty managed unbounded Sequence.

(see FACE::String Default constructor)

       After construction, the Sequence will be empty.

template<typename T>

FACE::Sequence< T >::Sequence	(	FACE::UnsignedLong	bound,
		RETURN_CODE &	return_code
	)

inline

Managed constructor - creates empty Sequence of specified bound.

(see FACE::String Managed constructor)

       If allocation is successful, the Sequence will be empty.

References FACE::Sequence< T >::NO_ERROR, FACE::Sequence< T >::PRECONDITION_VIOLATED, FACE::Sequence< T >::reserve(), and FACE::Sequence< T >::UNBOUNDED_SENTINEL.

template<typename T>

FACE::Sequence< T >::Sequence ( const Sequence< T > & seq )

inline

Managed copy constructor.

(see FACE::String Managed copy constructor)

References FACE::Sequence< T >::is_valid(), FACE::Sequence< T >::NO_ERROR, FACE::Sequence< T >::reserve(), and FACE::Sequence< T >::UNBOUNDED_SENTINEL.

template<typename T>

FACE::Sequence< T >::Sequence	(	const T *	arr,
		FACE::UnsignedLong	length,
		RETURN_CODE &	return_code
	)

inline

Managed C-style array constructor.

After construction, this Sequence manages its own data, which is a copy of the length elements pointed to by arr, and bound() will return length.

Preconditions:

arr != 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

The caller must ensure length * sizeof(T) is not greater than the size of the memory allocated at arr. If this condition is violated, the result is undefined behavior and may result in an attempt to access restricted memory.

Parameters:

arr	A pointer to the C-style array
length	The number of elements in the array
return_code	(see details)

References FACE::Sequence< T >::length(), FACE::Sequence< T >::NO_ERROR, FACE::Sequence< T >::PRECONDITION_VIOLATED, and FACE::Sequence< T >::reserve().

template<typename T>

FACE::Sequence< T >::Sequence	(	T *	seq,
		FACE::UnsignedLong	length,
		FACE::UnsignedLong	bound,
		RETURN_CODE &	return_code
	)

inline

Unmanaged constructor.

(see FACE::String::String)

       The caller must ensure @p bound + sizeof(T) is not greater than the
       size of the memory allocated at @p seq. If this condition is
       violated, the result is undefined behavior and may result in an
       attempt to access restricted memory.

       @param seq pointer to externally managed memory
       @param length the number of elements in the memory pointed to by
              @p seq
       @param bound the number of elements the externally
              managed memory can hold. Also serves as a capacity.
       @param return_code (see details)

References FACE::Sequence< T >::NO_ERROR, and FACE::Sequence< T >::PRECONDITION_VIOLATED.

template<typename T>

FACE::Sequence< T >::~Sequence ( )

inline

Frees any data managed by this Sequence.

Member Function Documentation

template<typename T>

Sequence& FACE::Sequence< T >::operator= ( const Sequence< T > & seq )

inline

Managed assignment operator.

( see FACE::String::operator=)

       @param seq The source Sequence to copy from.
       @return a reference to this Sequence

References FACE::Sequence< T >::is_valid(), FACE::Sequence< T >::NO_ERROR, and FACE::Sequence< T >::reserve().

template<typename T>

void FACE::Sequence< T >::clear ( )

inline

Clears this String's data.

(see FACE::String::clear)

template<typename T>

RETURN_CODE FACE::Sequence< T >::append ( const Sequence< T > & seq )

inline

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

(see FACE::String::append)

References FACE::Sequence< T >::INSUFFICIENT_BOUND, FACE::Sequence< T >::is_valid(), FACE::Sequence< T >::NO_ERROR, FACE::Sequence< T >::PRECONDITION_VIOLATED, FACE::Sequence< T >::reserve(), and FACE::Sequence< T >::UNBOUNDED_SENTINEL.

template<typename T>

RETURN_CODE FACE::Sequence< T >::append ( const T & elem )

inline

Adds a copy of elem to the current data.

(see FACE::String::append)

References FACE::Sequence< T >::INSUFFICIENT_BOUND, FACE::Sequence< T >::NO_ERROR, FACE::Sequence< T >::PRECONDITION_VIOLATED, FACE::Sequence< T >::reserve(), and FACE::Sequence< T >::UNBOUNDED_SENTINEL.

template<typename T>

RETURN_CODE FACE::Sequence< T >::reserve ( FACE::UnsignedLong capacity )

inline

(see FACE::String::reserve)

References FACE::Sequence< T >::capacity(), FACE::Sequence< T >::INSUFFICIENT_BOUND, FACE::Sequence< T >::INSUFFICIENT_MEMORY, FACE::Sequence< T >::NO_ERROR, FACE::Sequence< T >::PRECONDITION_VIOLATED, and FACE::Sequence< T >::UNBOUNDED_SENTINEL.

Referenced by FACE::Sequence< T >::append(), FACE::Sequence< T >::operator=(), and FACE::Sequence< T >::Sequence().

template<typename T>

T& FACE::Sequence< T >::operator[] ( FACE::UnsignedLong index )

inline

Returns a reference to the element at a given index.

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

       If @p index is out of range, the behavior is implementation-defined.

template<typename T>

T* FACE::Sequence< T >::buffer ( )

inline

Returns pointer to contiguous memory for underlying data.

To avoid accessing restricted memory, the caller should avoid dereferencing memory beyond buffer() + length() * sizeof(T).

template<typename T>

FACE::UnsignedLong FACE::Sequence< T >::length ( ) const

inline

Returns the length of this Sequence.

Referenced by FACE::Sequence< T >::Sequence().

template<typename T>

FACE::UnsignedLong FACE::Sequence< T >::capacity ( ) const

inline

Returns the capacity of this Sequence.

Referenced by FACE::Sequence< T >::reserve().

template<typename T>

FACE::UnsignedLong FACE::Sequence< T >::bound ( ) const

inline

Returns the bound of this Sequence.

template<typename T>

FACE::Boolean FACE::Sequence< T >::is_managed ( ) const

inline

Returns whether or not this Sequence is managed.

(see FACE::String::is_managed)

template<typename T>

FACE::Boolean FACE::Sequence< T >::is_bounded ( ) const

inline

Returns whether or not this Sequence is bounded.

(see FACE::String::is_bounded)

References FACE::Sequence< T >::UNBOUNDED_SENTINEL.

template<typename T>

FACE::Boolean FACE::Sequence< T >::is_valid ( ) const

inline

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

(see class details)

Referenced by FACE::Sequence< T >::append(), FACE::Sequence< T >::operator=(), and FACE::Sequence< T >::Sequence().

Field Documentation

template<typename T>

const unsigned int FACE::Sequence< T >::UNBOUNDED_SENTINEL = UINT_MAX

static

Constant representing the bound of an unbounded Sequence.

Referenced by FACE::Sequence< T >::append(), FACE::Sequence< T >::is_bounded(), FACE::Sequence< T >::reserve(), and FACE::Sequence< T >::Sequence().

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

template<typename T> class FACE::Sequence< T >

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation

template<typename T>
class FACE::Sequence< T >