bdlc::Queue< T > Class Template Reference

#include <bdlc_queue.h>

Classes
struct	InitialCapacity

Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (Queue, bdlb::HasPrintMethod)
	BSLMF_NESTED_TRAIT_DECLARATION (Queue, bslma::UsesBslmaAllocator)
	Queue (bslma::Allocator *basicAllocator=0)
	Queue (unsigned int initialLength, bslma::Allocator *basicAllocator=0)
	Queue (int initialLength, const T &initialValue, bslma::Allocator *basicAllocator=0)
	Queue (const InitialCapacity &numElements, bslma::Allocator *basicAllocator=0)
	Queue (const T *srcArray, int numElements, bslma::Allocator *basicAllocator=0)
	Queue (const Queue &original, bslma::Allocator *basicAllocator=0)
	~Queue ()
	Destroy this object.
Queue &	operator= (const Queue &rhs)
T &	operator[] (int index)
void	append (const T &item)
void	append (const Queue &srcQueue)
void	append (const Queue &srcQueue, int srcIndex, int numElements)
T &	back ()
T &	front ()
void	insert (int dstIndex, const T &item)
void	insert (int dstIndex, const Queue &srcQueue)
void	insert (int dstIndex, const Queue &srcQueue, int srcIndex, int numElements)
void	popBack ()
void	popFront ()
void	pushBack (const T &item)
void	pushFront (const T &item)
void	remove (int index)
void	remove (int index, int numElements)
void	removeAll (bsl::vector< T > *buffer=0)
void	replace (int dstIndex, const T &item)
void	replace (int dstIndex, const Queue &srcQueue, int srcIndex, int numElements)
void	reserveCapacity (int numElements)
void	reserveCapacityRaw (int numElements)
void	setLength (int newLength)
void	setLength (int newLength, const T &initialValue)
void	setLengthRaw (int newLength)
template<class STREAM >
STREAM &	bdexStreamIn (STREAM &stream, int version)
void	swap (int index1, int index2)
const T &	operator[] (int index) const
const T &	back () const
const T &	front () const
int	length () const
	Return the number of elements in this queue.
bsl::ostream &	print (bsl::ostream &stream, int level, int spacesPerLevel) const
bsl::ostream &	streamOut (bsl::ostream &stream) const
template<class STREAM >
STREAM &	bdexStreamOut (STREAM &stream, int version) const

Static Public Member Functions
static int	maxSupportedBdexVersion (int versionSelector)
static int	maxSupportedBdexVersion ()
static int	maxSupportedVersion ()

Detailed Description

template<class T>
class bdlc::Queue< T >

This class implements an efficient, in-place double-ended queue of values of parameterized type T. The physical capacity of this queue may grow, but never shrinks. Capacity may be reserved initially via a constructor, or at any time thereafter by using the reserveCapacity and reserveCapacityRaw methods. Note that there is no guarantee of contiguous storage of consecutive elements.

More generally, this container class supports a complete set of value semantics operations, including copy construction, assignment, equality comparison, ostream printing, and bdex serialization. (A precise operational definition of when two objects have the same value can be found in the description of operator== for the class.) This container is exception neutral with no guarantee of rollback: if an exception is thrown during the invocation of a method on a pre-existing object, the container is left in a valid state, but its value is undefined. In no event is memory leaked. Finally, aliasing (e.g., using all or part of an object as both source and destination) is supported in all cases.

See bdlc_queue

Constructor & Destructor Documentation

Queue() [1/6]

template<class T >

bdlc::Queue< T >::Queue ( bslma::Allocator *  basicAllocator = 0 )

explicit

Queue() [2/6]

template<class T >

bdlc::Queue< T >::Queue ( unsigned int  initialLength, bslma::Allocator *  basicAllocator = 0  )

explicit

Queue() [3/6]

template<class T >

bdlc::Queue< T >::Queue	(	int	initialLength,
		const T &	initialValue,
		bslma::Allocator *	basicAllocator = 0
	)

Create an in-place queue. By default, the queue is empty. Optionally specify the initialLength of the queue. Queue elements are initialized with the specified initialValue, or to 0.0 if initialValue is not specified. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless 0 <= initialLength.

Queue() [4/6]

template<class T >

bdlc::Queue< T >::Queue ( const InitialCapacity &  numElements, bslma::Allocator *  basicAllocator = 0  )

explicit

Create an in-place queue with sufficient initial capacity to accommodate up to the specified numElements values without subsequent reallocation. A valid reference returned by the operator[] method is guaranteed to remain valid unless the value returned by the length method exceeds numElements (which would potentially cause a reallocation). Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless 0 <= numElements.

Queue() [5/6]

template<class T >

bdlc::Queue< T >::Queue	(	const T *	srcArray,
		int	numElements,
		bslma::Allocator *	basicAllocator = 0
	)

Create an in-place queue initialized with the specified numElements leading values from the specified srcArray. Optionally specify the basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless 0 <= numElements. Note that srcArray must refer to sufficient memory to hold numElements values.

Queue() [6/6]

template<class T >

bdlc::Queue< T >::Queue	(	const Queue< T > &	original,
		bslma::Allocator *	basicAllocator = 0
	)

Create an in-place queue initialized to the value of the specified original queue. Optionally specify the basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

~Queue()

template<class T >

bdlc::Queue< T >::~Queue

(

)

Member Function Documentation

append() [1/3]

template<class T >

void bdlc::Queue< T >::append

(

const Queue< T > &

srcQueue

)

Append to the end of this queue the sequence of values in the specified srcQueue. Note that this function is logically equivalent to:

insert(length(), srcQueue);

append() [2/3]

template<class T >

void bdlc::Queue< T >::append	(	const Queue< T > &	srcQueue,
		int	srcIndex,
		int	numElements
	)

Append to the end of this queue the specified numElements value in the specified srcQueue starting at the specified index position srcIndex. Note that this function is logically equivalent to:

insert(length(), srcQueue, srcIndex, numElements);

The behavior is undefined unless 0 <= srcIndex, 0 <= numElements, and srcIndex + numElements <= srcQueue.length().

append() [3/3]

template<class T >

void bdlc::Queue< T >::append ( const T &  item )

inline

Append to the end of this queue the value of the specified item. Note that this function is a synonym for pushBack and is logically equivalent to (but generally more efficient than):

insert(length(), item);

back() [1/2]

template<class T >

T & bdlc::Queue< T >::back ( )

inline

Return a reference to the modifiable value at the back of this queue. The reference will remain valid as long as the queue is not destroyed or modified (e.g., via insert, remove, or append). The behavior is undefined if the queue is empty. Note that this function is logically equivalent to:

operator[](length() - 1)

back() [2/2]

template<class T >

const T & bdlc::Queue< T >::back ( ) const

inline

Return a reference to the non-modifiable element at the back of this queue. The reference will remain valid as long as this queue is not destroyed or modified (e.g., via insert, remove, or append). The behavior is undefined if this queue is empty. Note that this function is logically equivalent to:

  operator[](length() - 1)

bdexStreamIn()

template<class T >

template<class STREAM >

STREAM & bdlc::Queue< T >::bdexStreamIn	(	STREAM &	stream,
		int	version
	)

Assign to this object the value read from the specified input stream using the specified version format, and return a reference to stream. If stream is initially invalid, this operation has no effect. If version is not supported, this object is unaltered and stream is invalidated, but otherwise unmodified. If version is supported but stream becomes invalid during this operation, this object has an undefined, but valid, state. Note that no version is read from stream. See the bslx package-level documentation for more information on BDEX streaming of value-semantic types and containers.

bdexStreamOut()

template<class T >

template<class STREAM >

STREAM & bdlc::Queue< T >::bdexStreamOut	(	STREAM &	stream,
		int	version
	)		const

Write the value of this object, using the specified version format, to the specified output stream, and return a reference to stream. If stream is initially invalid, this operation has no effect. If version is not supported, stream is invalidated, but otherwise unmodified. Note that version is not written to stream. See the bslx package-level documentation for more information on BDEX streaming of value-semantic types and containers.

BSLMF_NESTED_TRAIT_DECLARATION() [1/2]

template<class T >

bdlc::Queue< T >::BSLMF_NESTED_TRAIT_DECLARATION	(	Queue< T >	,
		bdlb::HasPrintMethod
	)

BSLMF_NESTED_TRAIT_DECLARATION() [2/2]

template<class T >

bdlc::Queue< T >::BSLMF_NESTED_TRAIT_DECLARATION	(	Queue< T >	,
		bslma::UsesBslmaAllocator
	)

front() [1/2]

template<class T >

T & bdlc::Queue< T >::front ( )

inline

Return a reference to the modifiable value at the front of this queue. The reference will remain valid as long as the queue is not destroyed or modified (e.g., via insert, remove, or append). The behavior is undefined if the queue is empty. Note that this function is logically equivalent to:

operator[](0)

front() [2/2]

template<class T >

const T & bdlc::Queue< T >::front ( ) const

inline

Return a reference to the non-modifiable element at the front of this queue. The reference will remain valid as long as this queue is not destroyed or modified (e.g., via insert, remove, or append). The behavior is undefined if this queue is empty. Note that this function is logically equivalent to:

  operator[](0)

insert() [1/3]

template<class T >

void bdlc::Queue< T >::insert ( int  dstIndex, const Queue< T > &  srcQueue  )

inline

Insert the specified srcQueue into this queue at the specified dstIndex. All current values with indices at or above dstIndex are shifted up by srcQueue.length() index positions. The behavior is undefined unless 0 <= dstIndex <= length().

insert() [2/3]

template<class T >

void bdlc::Queue< T >::insert	(	int	dstIndex,
		const Queue< T > &	srcQueue,
		int	srcIndex,
		int	numElements
	)

Insert the specified numElements values starting at the specified srcIndex position from the specified srcQueue into this queue at the specified dstIndex. All current values with indices at or above dstIndex are shifted up by numElements index positions. The behavior is undefined unless 0 <= dstIndex <= length(), 0 <= srcIndex, 0 <= numElements, and srcIndex + numElements <= srcQueue.length().

insert() [3/3]

template<class T >

void bdlc::Queue< T >::insert	(	int	dstIndex,
		const T &	item
	)

Insert the specified item into this queue at the specified dstIndex. All current values with indices at or above dstIndex are shifted up by one index position. The behavior is undefined unless 0 <= dstIndex <= length().

length()

template<class T >

int bdlc::Queue< T >::length ( ) const

inline

maxSupportedBdexVersion() [1/2]

template<class T >

int bdlc::Queue< T >::maxSupportedBdexVersion ( )

inlinestatic

Return the most current BDEX streaming version number supported by this class.

Deprecated:

Use maxSupportedBdexVersion(int) instead.

maxSupportedBdexVersion() [2/2]

template<class T >

int bdlc::Queue< T >::maxSupportedBdexVersion ( int  versionSelector )

inlinestatic

Return the maximum valid BDEX format version, as indicated by the specified versionSelector, to be passed to the bdexStreamOut method. Note that it is highly recommended that versionSelector be formatted as "YYYYMMDD", a date representation. Also note that versionSelector should be a compile-time-chosen value that selects a format version supported by both externalizer and unexternalizer. See the bslx package-level documentation for more information on BDEX streaming of value-semantic types and containers.

maxSupportedVersion()

template<class T >

int bdlc::Queue< T >::maxSupportedVersion ( )

inlinestatic

Return the most current bdex streaming version number supported by this class. (See the package-group-level documentation for more information on bdex streaming of container types.)

Deprecated:

Use maxSupportedBdexVersion instead.

operator=()

template<class T >

Queue< T > & bdlc::Queue< T >::operator=

(

const Queue< T > &

rhs

)

Assign to this queue the value of the specified rhs queue and return a reference to this modifiable queue.

operator[]() [1/2]

template<class T >

T & bdlc::Queue< T >::operator[] ( int  index )

inline

Return a reference to the modifiable element at the specified index position in this queue. The reference will remain valid as long as this queue is not destroyed or modified (e.g., via insert, remove, or append). The behavior is undefined unless 0 <= index < length().

operator[]() [2/2]

template<class T >

const T & bdlc::Queue< T >::operator[] ( int  index ) const

inline

Return a reference to the non-modifiable element at the specified index position in this queue. The reference will remain valid as long as this queue is not destroyed or modified (e.g., via insert, remove, or append). The behavior is undefined unless 0 <= index < length().

popBack()

template<class T >

void bdlc::Queue< T >::popBack ( )

inline

Remove the value from the back of this queue efficiently (in O[1] time). The behavior is undefined if this queue is empty. Note that this function is logically equivalent to (but more efficient than):

remove(length() - 1)

popFront()

template<class T >

void bdlc::Queue< T >::popFront ( )

inline

Remove the value from the front of this queue efficiently (in O[1] time). The behavior is undefined if this queue is empty. Note that this function is logically equivalent to (but more efficient than):

  remove(0)

print()

template<class T >

bsl::ostream & bdlc::Queue< T >::print	(	bsl::ostream &	stream,
		int	level,
		int	spacesPerLevel
	)		const

Format this object to the specified output stream at the optionally specified indentation level and return a reference to the modifiable stream. If level is specified, optionally specify spacesPerLevel, the number of spaces per indentation level for this and all of its nested objects. Each line is indented by the absolute value of level * spacesPerLevel. If level is negative, suppress indentation of the first line. If spacesPerLevel is negative, suppress line breaks and format the entire output on one line. If stream is initially invalid, this operation has no effect. Note that a trailing newline is provided in multi-line mode only.

pushBack()

template<class T >

void bdlc::Queue< T >::pushBack

(

const T &

item

)

Append the specified item to the back of this queue efficiently (in O[1] time when memory reallocation is not required). Note that this function is logically equivalent to (but generally more efficient than):

  insert(length(), item);

pushFront()

template<class T >

void bdlc::Queue< T >::pushFront

(

const T &

item

)

Insert the specified item into the front of this queue efficiently (in O[1] time when memory reallocation is not required). Note that this function is logically equivalent to (but generally more efficient than):

  insert(0, item);

remove() [1/2]

template<class T >

void bdlc::Queue< T >::remove

(

int

index

)

Remove from this queue the value at the specified index. All values with initial indices above index are shifted down by one index position. The behavior is undefined unless 0 <= index < length().

remove() [2/2]

template<class T >

void bdlc::Queue< T >::remove	(	int	index,
		int	numElements
	)

Remove from this queue, beginning at the specified index, the specified numElements values. All values with initial indices at or above index + numElements are shifted down by numElements index positions. The behavior is undefined unless 0 <= index, 0 <= numElements, and index + numElements <= length().

removeAll()

template<class T >

void bdlc::Queue< T >::removeAll

(

bsl::vector< T > *

buffer = 0

)

Remove all elements from this queue. If the optionally specified buffer is not 0, append to buffer a copy of each element removed (in front-to-back order of the elements in the queue prior to the invocation of this method).

replace() [1/2]

template<class T >

void bdlc::Queue< T >::replace	(	int	dstIndex,
		const Queue< T > &	srcQueue,
		int	srcIndex,
		int	numElements
	)

Replace the specified numElements values beginning at the specified dstIndex in this queue with values from the specified srcQueue beginning at the specified srcIndex. The behavior is undefined unless 0 <= dstIndex, 0 <= numElements, dstIndex + numElements <= length(), 0 <= srcIndex, and srcIndex + numElements <= srcQueue.length(). Note that this function is logically equivalent to (but more efficient than):

  insert(dstIndex, srcQueue, srcIndex, numElements);
  remove(dstIndex + numElements, numElements);

replace() [2/2]

template<class T >

void bdlc::Queue< T >::replace	(	int	dstIndex,
		const T &	item
	)

Replace the element at the specified dstIndex in this queue with the specified item. The behavior is undefined unless 0 <= dstIndex < length(). Note that this function is logically equivalent to (but more efficient than):

  insert(dstIndex, item);
  remove(dstIndex + 1);

reserveCapacity()

template<class T >

void bdlc::Queue< T >::reserveCapacity

(

int

numElements

)

Reserve sufficient internal capacity to accommodate up to the specified numElements values without subsequent reallocation. Note that if numElements <= length(), this operation has no effect.

reserveCapacityRaw()

template<class T >

void bdlc::Queue< T >::reserveCapacityRaw

(

int

numElements

)

Reserve sufficient and minimal internal capacity to accommodate up to the specified numElements values without subsequent reallocation. Beware, however, that repeated calls to this function may invalidate bounds on runtime complexity otherwise guaranteed by this container. Note that if numElements <= length(), this operation has no effect.

setLength() [1/2]

template<class T >

void bdlc::Queue< T >::setLength

(

int

newLength

)

setLength() [2/2]

template<class T >

void bdlc::Queue< T >::setLength	(	int	newLength,
		const T &	initialValue
	)

Set the length of this queue to the specified newLength. If newLength is less than the current length, elements at index positions at or above newLength are removed. Otherwise any new elements (at or above the current length) are initialized to the specified initialValue, or to 0.0 if initialValue is not specified. The behavior is undefined unless 0 <= newLength.

setLengthRaw()

template<class T >

void bdlc::Queue< T >::setLengthRaw

(

int

newLength

)

Set the length of this queue to the specified newLength. If newLength is less than the current length, elements at index positions at or above newLength are removed. If newLength is equal to the current length, this function has no effect. Otherwise new elements at or above the current length are not initialized to any value.

streamOut()

template<class T >

bsl::ostream & bdlc::Queue< T >::streamOut ( bsl::ostream &  stream ) const

inline

Write the elements of this queue out to the specified stream. Note that for this method to compile, operator<< has to be defined for arguments stream and type T.

swap()

template<class T >

void bdlc::Queue< T >::swap	(	int	index1,
		int	index2
	)

Swap efficiently the values at the specified indices index1 and index2. The behavior is undefined unless 0 <= index1 < length() and 0 <= index2 < length().

---

The documentation for this class was generated from the following file:

• bdlc_queue.h