Namespaces
Variants
Views
Actions

Difference between revisions of "Template:cpp/container/push back"

From cppreference.com
m (Update links.)
m
 
(39 intermediate revisions by 12 users not shown)
Line 1: Line 1:
−
{{cpp/container/{{{1|}}}/title | push_back}}
+
{{#vardefine:cont|{{{1|vector}}}}}<!--
−
{{cpp/container/{{{1|}}}/navbar}}
+
-->{{cpp/container/{{#var:cont}}/title|push_back}}
 +
{{cpp/container/{{#var:cont}}/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl | notes={{cpp/container/mark since c++11 | {{{1|}}} }} |
+
{{dcl|num=1|notes={{#ifeq:{{#var:cont}}|vector|{{mark constexpr since c++20}}}}|
 
void push_back( const T& value );
 
void push_back( const T& value );
 
}}
 
}}
−
{{dcl | notes={{mark since c++11}} |
+
{{dcl|num=2|since=c++11|notes={{#ifeq:{{#var:cont}}|vector|{{mark constexpr since c++20}}}}|
 
void push_back( T&& value );
 
void push_back( T&& value );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
Appends the given element {{tt|value}} to the end of the container.  
+
Appends the given element {{c|value}} to the end of the container.
  
−
{{cpp/container/note_iterator_invalidation|{{{1|}}}|push_back}}
+
@1@ The new element is initialized as a copy of {{c|value}}.
 +
@2@ {{c|value}} is moved into the new element.
 +
 
 +
{{cpp/container/note iterator invalidation|{{#var:cont}}|push_back}}
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | value | the value of the element to append}}
+
{{par|value|the value of the element to append}}
−
{{par end}}  
+
{{par hreq}}
−
 
+
{{par req named|T|CopyInsertable|overload=1}}
−
===Requirements===
+
{{par req named|T|MoveInsertable|overload=2}}
−
1) {{tt|value}} shall be {{concept|CopyInsertable}}
+
{{par end}}
−
 
+
−
2) {{tt|value}} shall be {{concept|MoveInsertable}}
+
  
 
===Return value===
 
===Return value===
Line 28: Line 30:
  
 
===Complexity===
 
===Complexity===
−
Constant.
+
{{#switch:{{#var:cont}}
 +
|vector=Amortized constant.
 +
|deque|list=Constant.
 +
|{{included}}
 +
}}
  
 +
===Exceptions===
 +
If an exception is thrown (which can be due to {{tt|Allocator::allocate()}} or element copy/move constructor/assignment), this function has no effect ([[cpp/language/exceptions#Exception safety|strong exception guarantee]]).
 +
{{#ifeq:{{#var:cont}}|vector|
 +
{{rrev|since=c++11|
 +
If the move constructor of {{tt|T}} is not {{c|noexcept}} and {{tt|T}} is not {{named req|CopyInsertable}} into {{c|*this}}, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.
 +
}}
 +
<!---->
 +
===Notes===
 +
Some implementations throw {{lc|std::length_error}} when {{tt|push_back}} causes a reallocation that exceeds {{lc|max_size}} (due to an implicit call to an equivalent of {{lc|reserve}}{{tt|(}}{{lc|size}}{{tt|() + 1))}}.
 +
}}
 +
<!---->
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| The following code uses {{tt|push_back}} to add several integers to a {{c|std::{{{1}}}<int>}}:
+
|code=
−
| code=
+
#include <iomanip>
−
#include <{{{1}}}>
+
 
#include <iostream>
 
#include <iostream>
−
+
#include <string>
 +
#include <{{#var:cont}}>
 +
 
 
int main()
 
int main()
 
{
 
{
−
     std::{{{1}}}<int> numbers;
+
     std::{{#var:cont}}<std::string> letters;
 
   
 
   
−
     numbers.push_back(42);
+
     letters.push_back("abc");
−
     numbers.push_back(314159);  
+
     std::string s{"def"};
 +
    letters.push_back(std::move(s));
  
−
     for (int i : numbers) { // c++11 range-based for loop
+
    std::cout << "std::{{#var:cont}} letters holds: ";
−
         std::cout << i << '\n';
+
     for (auto&& e : letters)
−
    }
+
         std::cout << std::quoted(e) << ' ';
  
−
     return 0;
+
     std::cout << "\nMoved-from string s holds: " << std::quoted(s) << '\n';
 
}
 
}
−
| output=
+
|p=true
−
42
+
|output=
−
314159
+
std::{{#var:cont}} letters holds: "abc" "def"
 +
Moved-from string s holds: ""
 
}}
 
}}
  
 
===See also===
 
===See also===
−
 
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/container/dsc emplace_back |{{{1|}}}}}
+
{{dsc inc|cpp/container/dsc emplace_back|{{#var:cont}}}}
−
{{#ifeq: {{{1|}}} | vector ||{{dsc inc | cpp/container/dsc push_front |{{{1|}}}}} }}
+
{{#ifeq:{{#var:cont}}|vector||{{dsc inc|cpp/container/dsc push_front|{{#var:cont}}}}}}
−
{{dsc inc | cpp/container/dsc pop_back |{{{1|}}}}}
+
{{dsc inc|cpp/container/dsc pop_back|{{#var:cont}}}}
 +
{{dsc inc|cpp/iterator/dsc back_inserter}}
 
{{dsc end}}
 
{{dsc end}}

Latest revision as of 17:47, 29 August 2024

 
C++
 
Containers library
 
std::vector
Member types
Member functions
Non-member functions
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)
Deduction guides(C++17)
 
void push_back( const T& value );
 (1) (constexpr since C++20)
void push_back( T&& value );
 (2) (since C++11)
(constexpr since C++20)

Appends the given element value to the end of the container.

1) The new element is initialized as a copy of value.
2) value is moved into the new element.

If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise only the end() iterator is invalidated.

Contents

[edit] Parameters

value - the value of the element to append
Type requirements
-
T must meet the requirements of CopyInsertable in order to use overload (1).
-
T must meet the requirements of MoveInsertable in order to use overload (2).

[edit] Return value

(none)

[edit] Complexity

Amortized constant.

[edit] Exceptions

If an exception is thrown (which can be due to Allocator::allocate() or element copy/move constructor/assignment), this function has no effect (strong exception guarantee).

If the move constructor of T is not noexcept and T is not CopyInsertable into *this, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.

(since C++11)

Notes

Some implementations throw std::length_error when push_back causes a reallocation that exceeds max_size (due to an implicit call to an equivalent of reserve(size() + 1)).

[edit] Example

Run this code
#include <iomanip>
#include <iostream>
#include <string>
#include <vector>
 
int main()
{
    std::vector<std::string> letters;
 
    letters.push_back("abc");
    std::string s{"def"};
    letters.push_back(std::move(s));
 
    std::cout << "std::vector letters holds: ";
    for (auto&& e : letters)
        std::cout << std::quoted(e) << ' ';
 
    std::cout << "\nMoved-from string s holds: " << std::quoted(s) << '\n';
}

Possible output: 

std::vector letters holds: "abc" "def"
Moved-from string s holds: ""

[edit] See also

(C++11)
 constructs an element in-place at the end
(public member function of std::vector<T,Allocator>) [edit]
removes the last element
(public member function of std::vector<T,Allocator>) [edit]
creates a std::back_insert_iterator of type inferred from the argument
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=Template:cpp/container/push_back&oldid=175584"