[#BloombergLP-bdlc-Queue]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlc.adoc[bdlc]::Queue
:relfileprefix: ../../
:mrdocs:

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.

== Synopsis

Declared in `<bdlc_queue.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<class T>
class Queue;
----

== Description

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.

== Types

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/Queue/InitialCapacity.adoc[`InitialCapacity`] 
| Enable uniform use of an optional integral constructor argument to specify the initial internal capacity (in elements). For example, ` Queue<unsigned int> x(Queue::InitialCapacity(8)); ` instantiates an object `x` with an initial capacity of 8 elements, but with a logical length of 0 elements.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/Queue/2constructor-0d.adoc[`Queue`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlc/Queue/2destructor.adoc[`~Queue`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/bdlc/Queue/operator_assign.adoc[`operator=`] 
| Assign to this queue the value of the specified `rhs` queue and return a reference to this modifiable queue.
| xref:BloombergLP/bdlc/Queue/append-0b.adoc[`append`] 
| `append` overloads
| xref:BloombergLP/bdlc/Queue/back-07.adoc[`back`] 
| `back` overloads
| xref:BloombergLP/bdlc/Queue/bdexStreamIn.adoc[`bdexStreamIn`] 
| 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.
| xref:BloombergLP/bdlc/Queue/bdexStreamOut.adoc[`bdexStreamOut`] 
| 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.
| xref:BloombergLP/bdlc/Queue/front-06.adoc[`front`] 
| `front` overloads
| xref:BloombergLP/bdlc/Queue/insert-0f.adoc[`insert`] 
| `insert` overloads
| xref:BloombergLP/bdlc/Queue/length.adoc[`length`] 
| Return the number of elements in this queue.
| xref:BloombergLP/bdlc/Queue/operator_subs-02.adoc[`operator[]`] 
| Subscript operators
| xref:BloombergLP/bdlc/Queue/popBack.adoc[`popBack`] 
| 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) `
| xref:BloombergLP/bdlc/Queue/popFront.adoc[`popFront`] 
| 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) `
| xref:BloombergLP/bdlc/Queue/print.adoc[`print`] 
| 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.
| xref:BloombergLP/bdlc/Queue/pushBack.adoc[`pushBack`] 
| 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); `
| xref:BloombergLP/bdlc/Queue/pushFront.adoc[`pushFront`] 
| 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); `
| xref:BloombergLP/bdlc/Queue/remove-0f.adoc[`remove`] 
| `remove` overloads
| xref:BloombergLP/bdlc/Queue/removeAll.adoc[`removeAll`] 
| 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).
| xref:BloombergLP/bdlc/Queue/replace-0d.adoc[`replace`] 
| `replace` overloads
| xref:BloombergLP/bdlc/Queue/reserveCapacity.adoc[`reserveCapacity`] 
| 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.
| xref:BloombergLP/bdlc/Queue/reserveCapacityRaw.adoc[`reserveCapacityRaw`] 
| 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.
| xref:BloombergLP/bdlc/Queue/setLength-0b0.adoc[`setLength`] 
| `setLength` overloads
| xref:BloombergLP/bdlc/Queue/setLengthRaw.adoc[`setLengthRaw`] 
| 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.
| xref:BloombergLP/bdlc/Queue/streamOut.adoc[`streamOut`] 
| 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`.
| xref:BloombergLP/bdlc/Queue/swap.adoc[`swap`] 
| Swap efficiently the values at the specified indices `index1` and `index2`. The behavior is undefined unless `0 <= index1 < length()` and `0 <= index2 < length()`.
| xref:BloombergLP/bdlc/Queue/2conversion-0c.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Queue, HasPrintMethod>`] 
| Declare that this type has a `print` method.
| xref:BloombergLP/bdlc/Queue/2conversion-04.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<Queue, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/Queue/maxSupportedBdexVersion-04.adoc[`maxSupportedBdexVersion`] 
| `maxSupportedBdexVersion` overloads
| xref:BloombergLP/bdlc/Queue/maxSupportedVersion.adoc[`maxSupportedVersion`] 
| 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.)
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlc/operator_not_eq-0f.adoc[`operator!=`]
| Return `true` if the specified `lhs` and `rhs` queues do not have the same value, and `false` otherwise. Two queues do not have the same value if they have different lengths or differ in at least one index position.
| xref:BloombergLP/bdlc/operator_eq-0b.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` queues have the same value, and `false` otherwise. Two queues have the same value if they have the same length and the same element value at each respective index position.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#