Namespaces
Variants
Views
Actions

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

From cppreference.com
m (stray }})
m
 
(21 intermediate revisions by 8 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 | num=1 | since={{cpp/std|{{{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 | num=2 | 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.
  
−
@1@ The new element is initialized as a copy of {{tt|value}}.
+
@1@ The new element is initialized as a copy of {{c|value}}.
 +
@2@ {{c|value}} is moved into the new element.
  
−
@2@ {{tt|value}} is moved into the new element.
+
{{cpp/container/note iterator invalidation|{{#var:cont}}|push_back}}
−
 
+
−
{{cpp/container/note_iterator_invalidation|{{{1|}}}|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 hreq}}
 
{{par hreq}}
−
{{par req concept | T | CopyInsertable | overload=1}}
+
{{par req named|T|CopyInsertable|overload=1}}
−
{{par req concept | T | MoveInsertable | overload=2}}
+
{{par req named|T|MoveInsertable|overload=2}}
−
{{par end}}  
+
{{par end}}
  
 
===Return value===
 
===Return value===
Line 30: Line 30:
  
 
===Complexity===
 
===Complexity===
−
{{#switch:{{{1|}}}
+
{{#switch:{{#var:cont}}
−
| vector = Amortized constant.
+
|vector=Amortized constant.
−
| deque | list = Constant.
+
|deque|list=Constant.
−
| {{included}}
+
|{{included}}
 
}}
 
}}
  
 
===Exceptions===
 
===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 (strong exception guarantee).
+
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: {{{1|}}} | vector |
+
{{#ifeq:{{#var:cont}}|vector|
−
{{rev begin}}
+
{{rrev|since=c++11|
−
{{rev | 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.
−
If {{tt|T}}'s move constructor is not {{c|noexcept}} and T is not {{concept|CopyInsertable}} into {{tt|*this}}, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.}}
+
−
{{rev end}}
+
 
}}
 
}}
−
{{#ifeq: {{{1|}}} | vector |
+
<!---->
 
===Notes===
 
===Notes===
−
Some implementations also throw {{lc|std::length_error}} when {{tt|push_back}} causes a reallocation that would exceed {{lc|max_size}}, due to implicitly calling an equivalent of {{lc|reserve(size()+1)}}.
+
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
−
| code=
+
|code=
−
#include <{{{1}}}>
+
#include <iomanip>
 
#include <iostream>
 
#include <iostream>
−
#include <iomanip>
+
#include <string>
−
+
#include <{{#var:cont}}>
 +
 
 
int main()
 
int main()
 
{
 
{
−
     std::{{{1}}}<std::string> numbers;
+
     std::{{#var:cont}}<std::string> letters;
 
   
 
   
−
     numbers.push_back("abc");
+
     letters.push_back("abc");
−
     std::string s = "def";
+
     std::string s{"def"};
−
     numbers.push_back(std::move(s));
+
     letters.push_back(std::move(s));
  
−
     std::cout << "{{{1}}} holds: ";
+
     std::cout << "std::{{#var:cont}} letters holds: ";
−
     for (auto&& i : numbers) std::cout << std::quoted(i) << ' ';
+
     for (auto&& e : letters)
−
     std::cout << "\nMoved-from string holds " << std::quoted(s) << '\n';
+
        std::cout << std::quoted(e) << ' ';
 +
 
 +
     std::cout << "\nMoved-from string s holds: " << std::quoted(s) << '\n';
 
}
 
}
−
| output={{{1}}} holds: "abc" "def"  
+
|p=true
−
Moved-from string holds ""
+
|output=
 +
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"