Difference between revisions of "cpp/container/deque"
D41D8CD98F (Talk | contribs) (Undo revision 89343 by Timrae (talk) See Talk:cpp/container/deque) |
m (→Deduction guides: ~) |
||
(37 intermediate revisions by 16 users not shown) | |||
Line 3: | Line 3: | ||
{{dcl begin}} | {{dcl begin}} | ||
{{dcl header|deque}} | {{dcl header|deque}} | ||
− | {{dcl | num=1 | | + | {{dcl|num=1|1= |
template< | template< | ||
class T, | class T, | ||
− | class Allocator | + | class Allocator = std::allocator<T> |
> class deque; | > class deque; | ||
− | }} | + | }} |
− | {{dcl | num=2 |since=c++17|1= | + | {{dcl|num=2|since=c++17|1= |
namespace pmr { | namespace pmr { | ||
− | template <class T> | + | template< class T > |
using deque = std::deque<T, std::pmr::polymorphic_allocator<T>>; | using deque = std::deque<T, std::pmr::polymorphic_allocator<T>>; | ||
} | } | ||
Line 19: | Line 19: | ||
{{tt|std::deque}} (double-ended queue) is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end. In addition, insertion and deletion at either end of a deque never invalidates pointers or references to the rest of the elements. | {{tt|std::deque}} (double-ended queue) is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end. In addition, insertion and deletion at either end of a deque never invalidates pointers or references to the rest of the elements. | ||
− | As opposed to {{lc|std::vector}}, the elements of a deque are not stored contiguously: typical implementations use a sequence of individually allocated fixed-size arrays. | + | As opposed to {{lc|std::vector}}, the elements of a deque are not stored contiguously: typical implementations use a sequence of individually allocated fixed-size arrays, with additional bookkeeping, which means indexed access to deque must perform two pointer dereferences, compared to vector's indexed access which performs only one. |
− | The storage of a deque is automatically expanded and contracted as needed. Expansion of a deque is cheaper than the expansion of a {{lc|std::vector}} because it does not involve copying of the existing elements to a new memory location. | + | The storage of a deque is automatically expanded and contracted as needed. Expansion of a deque is cheaper than the expansion of a {{lc|std::vector}} because it does not involve copying of the existing elements to a new memory location. On the other hand, deques typically have large minimal memory cost; a deque holding just one element has to allocate its full internal array (e.g. 8 times the object size on 64-bit libstdc++; 16 times the object size or 4096 bytes, whichever is larger, on 64-bit libc++). |
The complexity (efficiency) of common operations on deques is as follows: | The complexity (efficiency) of common operations on deques is as follows: | ||
− | * Random access - constant {{math|O(1)}} | + | * Random access - constant {{math|O(1)}}. |
− | * Insertion or removal of elements at the end or beginning - constant {{math|O(1)}} | + | * Insertion or removal of elements at the end or beginning - constant {{math|O(1)}}. |
− | * Insertion or removal of elements - linear {{math|O(n)}} | + | * Insertion or removal of elements - linear {{math|O(n)}}. |
− | {{tt|std::deque}} meets the requirements of {{ | + | {{tt|std::deque}} meets the requirements of {{named req|Container}}, {{named req|AllocatorAwareContainer}}, {{named req|SequenceContainer}} and {{named req|ReversibleContainer}}. |
===Template parameters=== | ===Template parameters=== | ||
{{par begin}} | {{par begin}} | ||
− | {{par inc | cpp/container/param list T | deque}} | + | {{par inc|cpp/container/param list T|deque}} |
− | {{par inc | cpp/container/param list Allocator | deque}} | + | {{par inc|cpp/container/param list Allocator|deque}} |
{{par end}} | {{par end}} | ||
===Iterator invalidation=== | ===Iterator invalidation=== | ||
− | {{todo | + | {{todo|There are still a few inaccuracies in this section, refer to individual member function pages for more detail}} |
− | There are still a few inaccuracies in this section, refer to individual member function pages for more detail | + | |
− | {| class="dsctable" style="font-size:0. | + | {|class="dsctable" style="font-size:0.9em" |
− | ! Operations | + | !Operations |
− | ! Invalidated | + | !Invalidated |
|- | |- | ||
− | | All read only operations | + | |All read only operations. |
− | | Never | + | |Never. |
|- | |- | ||
− | | {{lc|swap}}, {{lc|std::swap}} | + | |{{lc|swap}}, {{lc|std::swap}} |
− | | The past-the-end iterator may be invalidated (implementation defined) | + | |The past-the-end iterator may be invalidated (implementation defined). |
|- | |- | ||
− | | {{lc|shrink_to_fit}}, {{lc|clear}}, {{lc|insert}}, {{lc|emplace}}, {{lc|push_front}}, {{lc|push_back}}, {{lc|emplace_front}}, {{lc|emplace_back}} | + | |{{lc|shrink_to_fit}}, {{lc|clear}}, {{lc|insert}}, {{lc|emplace}}, {{lc|push_front}},<br>{{lc|push_back}}, {{lc|emplace_front}}, {{lc|emplace_back}} |
− | | Always | + | |Always. |
|- | |- | ||
− | | {{lc|erase}} | + | |{{lc|erase}} |
− | | If erasing at begin - only erased elements<br> | + | |If erasing at begin - only erased elements.<br> |
− | If erasing at end - only erased elements and the past-the-end iterator<br> | + | If erasing at end - only erased elements and the past-the-end iterator.<br> |
− | Otherwise - all iterators are invalidated | + | Otherwise - all iterators are invalidated.<br><br> |
+ | {{rev inl|until=c++11|It is unspecified when the past-the-end iterator is invalidated.}}<br><br> | ||
+ | {{rev inl|since=c++11|The past-the-end iterator is also invalidated unless the erased<br> | ||
+ | elements are at the beginning of the container and the last element is not erased.}} | ||
|- | |- | ||
− | | {{lc|resize}} | + | |{{lc|resize}} |
− | | If the new size is smaller than the old one | + | |If the new size is smaller than the old one - only erased elements and the<br> past-the-end iterator.<br> |
− | If the new size is bigger than the old one | + | If the new size is bigger than the old one - all iterators are invalidated.<br> |
Otherwise - none iterators are invalidated. | Otherwise - none iterators are invalidated. | ||
|- | |- | ||
− | | {{lc|pop_front}} | + | |{{lc|pop_front}}, {{lc|pop_back}} |
− | + | |To the element erased.<br> | |
− | + | The past-the-end iterator<br> | |
− | + | {{rev inl|until=c++11|may be invalidated (implementation defined)}}<br> | |
− | | | + | {{rev inl|since=c++11|is also invalidated.}} |
|} | |} | ||
− | ==== | + | ====Invalidation notes==== |
* When inserting at either end of the deque, references are not invalidated by {{lc|insert}} and {{lc|emplace}}. | * When inserting at either end of the deque, references are not invalidated by {{lc|insert}} and {{lc|emplace}}. | ||
* {{lc|push_front}}, {{lc|push_back}}, {{lc|emplace_front}} and {{lc|emplace_back}} do not invalidate any references to elements of the deque. | * {{lc|push_front}}, {{lc|push_back}}, {{lc|emplace_front}} and {{lc|emplace_back}} do not invalidate any references to elements of the deque. | ||
Line 80: | Line 82: | ||
===Member types=== | ===Member types=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc hitem | Member type | Definition}} | + | {{dsc hitem|Member type|Definition}} |
− | {{dsc inc | cpp/container/dsc value_type | deque}} | + | {{dsc inc|cpp/container/dsc value_type|deque}} |
− | {{dsc inc | cpp/container/dsc allocator_type | deque}} | + | {{dsc inc|cpp/container/dsc allocator_type|deque}} |
− | {{dsc inc | cpp/container/dsc size_type | deque}} | + | {{dsc inc|cpp/container/dsc size_type|deque}} |
− | {{dsc inc | cpp/container/dsc difference_type | deque}} | + | {{dsc inc|cpp/container/dsc difference_type|deque}} |
− | {{dsc inc | cpp/container/dsc reference | deque}} | + | {{dsc inc|cpp/container/dsc reference|deque}} |
− | {{dsc inc | cpp/container/dsc const_reference | deque}} | + | {{dsc inc|cpp/container/dsc const_reference|deque}} |
− | {{dsc inc | cpp/container/dsc pointer | deque}} | + | {{dsc inc|cpp/container/dsc pointer|deque}} |
− | {{dsc inc | cpp/container/dsc const_pointer | deque}} | + | {{dsc inc|cpp/container/dsc const_pointer|deque}} |
− | {{dsc inc | cpp/container/dsc iterator | deque}} | + | {{dsc inc|cpp/container/dsc iterator|deque}} |
− | {{dsc inc | cpp/container/dsc const_iterator | deque}} | + | {{dsc inc|cpp/container/dsc const_iterator|deque}} |
− | {{dsc inc | cpp/container/dsc reverse_iterator | deque}} | + | {{dsc inc|cpp/container/dsc reverse_iterator|deque}} |
− | {{dsc inc | cpp/container/dsc const_reverse_iterator | deque}} | + | {{dsc inc|cpp/container/dsc const_reverse_iterator|deque}} |
{{dsc end}} | {{dsc end}} | ||
===Member functions=== | ===Member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc inc | cpp/container/dsc constructor | deque}} | + | {{dsc inc|cpp/container/dsc constructor|deque}} |
− | {{dsc inc | cpp/container/dsc destructor | deque}} | + | {{dsc inc|cpp/container/dsc destructor|deque}} |
− | {{dsc inc | cpp/container/dsc operator{{=}} | deque}} | + | {{dsc inc|cpp/container/dsc operator{{=}}|deque}} |
− | {{dsc inc | cpp/container/dsc assign | deque}} | + | {{dsc inc|cpp/container/dsc assign|deque}} |
− | {{dsc inc | cpp/container/dsc get_allocator | deque}} | + | {{dsc inc|cpp/container/dsc assign_range|deque}} |
+ | {{dsc inc|cpp/container/dsc get_allocator|deque}} | ||
− | {{dsc h2 | Element access}} | + | {{dsc h2|Element access}} |
− | {{dsc inc | cpp/container/dsc at | deque}} | + | {{dsc inc|cpp/container/dsc at|deque}} |
− | {{dsc inc | cpp/container/dsc operator_at | deque}} | + | {{dsc inc|cpp/container/dsc operator_at|deque}} |
− | {{dsc inc | cpp/container/dsc front | deque}} | + | {{dsc inc|cpp/container/dsc front|deque}} |
− | {{dsc inc | cpp/container/dsc back | deque}} | + | {{dsc inc|cpp/container/dsc back|deque}} |
− | {{dsc h2 | Iterators}} | + | {{dsc h2|Iterators}} |
− | {{dsc inc | cpp/container/dsc begin | deque}} | + | {{dsc inc|cpp/container/dsc begin|deque}} |
− | {{dsc inc | cpp/container/dsc end | deque}} | + | {{dsc inc|cpp/container/dsc end|deque}} |
− | {{dsc inc | cpp/container/dsc rbegin | deque}} | + | {{dsc inc|cpp/container/dsc rbegin|deque}} |
− | {{dsc inc | cpp/container/dsc rend | deque}} | + | {{dsc inc|cpp/container/dsc rend|deque}} |
− | {{dsc h2 | Capacity}} | + | {{dsc h2|Capacity}} |
− | {{dsc inc | cpp/container/dsc empty | deque}} | + | {{dsc inc|cpp/container/dsc empty|deque}} |
− | {{dsc inc | cpp/container/dsc size | deque}} | + | {{dsc inc|cpp/container/dsc size|deque}} |
− | {{dsc inc | cpp/container/dsc max_size | deque}} | + | {{dsc inc|cpp/container/dsc max_size|deque}} |
− | {{dsc inc | cpp/container/dsc shrink_to_fit | deque}} | + | {{dsc inc|cpp/container/dsc shrink_to_fit|deque}} |
− | {{dsc h2 | Modifiers}} | + | {{dsc h2|Modifiers}} |
− | {{dsc inc | cpp/container/dsc clear | deque}} | + | {{dsc inc|cpp/container/dsc clear|deque}} |
− | {{dsc inc | cpp/container/dsc insert | deque}} | + | {{dsc inc|cpp/container/dsc insert|deque}} |
− | {{dsc inc | cpp/container/dsc emplace | deque}} | + | {{dsc inc|cpp/container/dsc insert_range|deque}} |
− | {{dsc inc | cpp/container/dsc erase | deque}} | + | {{dsc inc|cpp/container/dsc emplace|deque}} |
− | {{dsc inc | cpp/container/dsc push_back | deque}} | + | {{dsc inc|cpp/container/dsc erase|deque}} |
− | {{dsc inc | cpp/container/dsc emplace_back | deque}} | + | {{dsc inc|cpp/container/dsc push_back|deque}} |
− | {{dsc inc | cpp/container/dsc pop_back | deque}} | + | {{dsc inc|cpp/container/dsc emplace_back|deque}} |
− | {{dsc inc | cpp/container/dsc push_front | deque}} | + | {{dsc inc|cpp/container/dsc append_range|deque}} |
− | {{dsc inc | cpp/container/dsc emplace_front | deque}} | + | {{dsc inc|cpp/container/dsc pop_back|deque}} |
− | {{dsc inc | cpp/container/dsc pop_front | deque}} | + | {{dsc inc|cpp/container/dsc push_front|deque}} |
− | {{dsc inc | cpp/container/dsc resize | deque}} | + | {{dsc inc|cpp/container/dsc emplace_front|deque}} |
− | {{dsc inc | cpp/container/dsc swap | deque}} | + | {{dsc inc|cpp/container/dsc prepend_range|deque}} |
+ | {{dsc inc|cpp/container/dsc pop_front|deque}} | ||
+ | {{dsc inc|cpp/container/dsc resize|deque}} | ||
+ | {{dsc inc|cpp/container/dsc swap|deque}} | ||
{{dsc end}} | {{dsc end}} | ||
===Non-member functions=== | ===Non-member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc inc | cpp/container/dsc operator_cmp | deque}} | + | {{dsc inc|cpp/container/dsc operator_cmp|deque}} |
− | {{dsc inc | cpp/container/dsc swap2 | deque}} | + | {{dsc inc|cpp/container/dsc swap2|deque}} |
+ | {{dsc inc|cpp/container/dsc erase seq|deque}} | ||
{{dsc end}} | {{dsc end}} | ||
− | === | + | {{rrev|since=c++17| |
+ | ==={{rl|deduction guides|Deduction guides}}=== | ||
+ | }} | ||
+ | ===Notes=== | ||
+ | {{ftm begin|std=1|comment=1}} | ||
+ | {{ftm|__cpp_lib_containers_ranges|value=202202L|std=C++23|Ranges construction and insertion for containers}} | ||
+ | {{ftm end}} | ||
+ | |||
+ | ===Example=== | ||
{{example | {{example | ||
− | + | |code= | |
− | + | ||
− | + | ||
#include <deque> | #include <deque> | ||
+ | #include <iostream> | ||
int main() | int main() | ||
Line 154: | Line 168: | ||
// Create a deque containing integers | // Create a deque containing integers | ||
std::deque<int> d = {7, 5, 16, 8}; | std::deque<int> d = {7, 5, 16, 8}; | ||
− | + | ||
// Add an integer to the beginning and end of the deque | // Add an integer to the beginning and end of the deque | ||
d.push_front(13); | d.push_front(13); | ||
d.push_back(25); | d.push_back(25); | ||
− | + | ||
// Iterate and print values of deque | // Iterate and print values of deque | ||
− | for(int n : d) | + | for (int n : d) |
− | std::cout << n << ' | + | std::cout << n << ' '; |
− | + | std::cout << '\n'; | |
} | } | ||
− | + | |output= | |
− | 13 | + | 13 7 5 16 8 25 |
− | 7 | + | |
− | 5 | + | |
− | 16 | + | |
− | 8 | + | |
− | 25 | + | |
}} | }} | ||
− | + | ===Defect reports=== | |
− | + | {{dr list begin}} | |
− | + | {{dr list item|wg=lwg|dr=230|std=C++98|before={{tt|T}} was not required to be {{named req|CopyConstructible}}<br>(an element of type {{tt|T}} might not be able to be constructed)|after={{tt|T}} is also required to<br>be {{named req|CopyConstructible}}}} | |
− | + | {{dr list end}} | |
− | + | ||
− | + | ===See also=== | |
− | + | {{dsc begin}} | |
− | + | {{dsc inc|cpp/container/dsc queue}} | |
+ | {{dsc end}} | ||
+ | |||
+ | {{langlinks|de|es|fr|it|ja|pl|pt|ru|zh}} |
Latest revision as of 22:51, 13 November 2023
Defined in header <deque>
|
||
template< class T, |
(1) | |
namespace pmr { template< class T > |
(2) | (since C++17) |
std::deque
(double-ended queue) is an indexed sequence container that allows fast insertion and deletion at both its beginning and its end. In addition, insertion and deletion at either end of a deque never invalidates pointers or references to the rest of the elements.
As opposed to std::vector, the elements of a deque are not stored contiguously: typical implementations use a sequence of individually allocated fixed-size arrays, with additional bookkeeping, which means indexed access to deque must perform two pointer dereferences, compared to vector's indexed access which performs only one.
The storage of a deque is automatically expanded and contracted as needed. Expansion of a deque is cheaper than the expansion of a std::vector because it does not involve copying of the existing elements to a new memory location. On the other hand, deques typically have large minimal memory cost; a deque holding just one element has to allocate its full internal array (e.g. 8 times the object size on 64-bit libstdc++; 16 times the object size or 4096 bytes, whichever is larger, on 64-bit libc++).
The complexity (efficiency) of common operations on deques is as follows:
- Random access - constant O(1).
- Insertion or removal of elements at the end or beginning - constant O(1).
- Insertion or removal of elements - linear O(n).
std::deque
meets the requirements of Container, AllocatorAwareContainer, SequenceContainer and ReversibleContainer.
Contents |
[edit] Template parameters
T | - | The type of the elements.
| ||||
Allocator | - | An allocator that is used to acquire/release memory and to construct/destroy the elements in that memory. The type must meet the requirements of Allocator. The behavior is undefined(until C++20)The program is ill-formed(since C++20) if Allocator::value_type is not the same as T .
|
[edit] Iterator invalidation
This section is incomplete Reason: There are still a few inaccuracies in this section, refer to individual member function pages for more detail |
Operations | Invalidated |
---|---|
All read only operations. | Never. |
swap, std::swap | The past-the-end iterator may be invalidated (implementation defined). |
shrink_to_fit, clear, insert, emplace, push_front, push_back, emplace_front, emplace_back |
Always. |
erase | If erasing at begin - only erased elements. If erasing at end - only erased elements and the past-the-end iterator. |
resize | If the new size is smaller than the old one - only erased elements and the past-the-end iterator. If the new size is bigger than the old one - all iterators are invalidated. |
pop_front, pop_back | To the element erased. The past-the-end iterator |
[edit] Invalidation notes
- When inserting at either end of the deque, references are not invalidated by insert and emplace.
- push_front, push_back, emplace_front and emplace_back do not invalidate any references to elements of the deque.
- When erasing at either end of the deque, references to non-erased elements are not invalidated by erase, pop_front and pop_back.
- A call to resize with a smaller size does not invalidate any references to non-erased elements.
- A call to resize with a bigger size does not invalidate any references to elements of the deque.
[edit] Member types
Member type | Definition | ||||
value_type
|
T
| ||||
allocator_type
|
Allocator
| ||||
size_type
|
Unsigned integer type (usually std::size_t) | ||||
difference_type
|
Signed integer type (usually std::ptrdiff_t) | ||||
reference
|
value_type& | ||||
const_reference
|
const value_type& | ||||
pointer
|
| ||||
const_pointer
|
| ||||
iterator
|
LegacyRandomAccessIterator to value_type
| ||||
const_iterator
|
LegacyRandomAccessIterator to const value_type | ||||
reverse_iterator
|
std::reverse_iterator<iterator> | ||||
const_reverse_iterator
|
std::reverse_iterator<const_iterator> |
[edit] Member functions
constructs the deque (public member function) | |
destructs the deque (public member function) | |
assigns values to the container (public member function) | |
assigns values to the container (public member function) | |
(C++23) |
assigns a range of values to the container (public member function) |
returns the associated allocator (public member function) | |
Element access | |
access specified element with bounds checking (public member function) | |
access specified element (public member function) | |
access the first element (public member function) | |
access the last element (public member function) | |
Iterators | |
(C++11) |
returns an iterator to the beginning (public member function) |
(C++11) |
returns an iterator to the end (public member function) |
(C++11) |
returns a reverse iterator to the beginning (public member function) |
(C++11) |
returns a reverse iterator to the end (public member function) |
Capacity | |
checks whether the container is empty (public member function) | |
returns the number of elements (public member function) | |
returns the maximum possible number of elements (public member function) | |
(DR*) |
reduces memory usage by freeing unused memory (public member function) |
Modifiers | |
clears the contents (public member function) | |
inserts elements (public member function) | |
(C++23) |
inserts a range of elements (public member function) |
(C++11) |
constructs element in-place (public member function) |
erases elements (public member function) | |
adds an element to the end (public member function) | |
(C++11) |
constructs an element in-place at the end (public member function) |
(C++23) |
adds a range of elements to the end (public member function) |
removes the last element (public member function) | |
inserts an element to the beginning (public member function) | |
(C++11) |
constructs an element in-place at the beginning (public member function) |
(C++23) |
adds a range of elements to the beginning (public member function) |
removes the first element (public member function) | |
changes the number of elements stored (public member function) | |
swaps the contents (public member function) |
[edit] Non-member functions
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values of two deque s (function template) |
specializes the std::swap algorithm (function template) | |
erases all elements satisfying specific criteria (function template) |
Deduction guides |
(since C++17) |
[edit] Notes
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_lib_containers_ranges |
202202L | (C++23) | Ranges construction and insertion for containers |
[edit] Example
#include <deque> #include <iostream> int main() { // Create a deque containing integers std::deque<int> d = {7, 5, 16, 8}; // Add an integer to the beginning and end of the deque d.push_front(13); d.push_back(25); // Iterate and print values of deque for (int n : d) std::cout << n << ' '; std::cout << '\n'; }
Output:
13 7 5 16 8 25
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 230 | C++98 | T was not required to be CopyConstructible(an element of type T might not be able to be constructed)
|
T is also required tobe CopyConstructible |
[edit] See also
adapts a container to provide queue (FIFO data structure) (class template) |