CKTIS / C++
std::basic_string::push_back — append one code unit
Append one code unit to a string, directly or through an output iterator. Learn what growth can invalidate and how to preserve embedded nulls in bounded data.
Version: ISO C++23; implementation support may vary
Syntax
constexpr void push_back(CharT ch);std::basic_string::push_back is a non-const member declared in <string> and is constexpr since C++20. It takes one CharT by value (char for std::string), appends it even to an empty string, increases size() by one, and returns void. There is no string or range overload. s.append(1, ch) and s += ch have the same effect but return a reference to s. To append a valid range of n elements starting at p, use s.append(p, n).
One call adds one code unit, not necessarily a whole Unicode character, and does not encode or validate text. In std::string, an appended '\0' is content and counts toward size(). It is distinct from the extra terminator at s.data()[s.size()]. For data with embedded nulls, pass both data() and size() to a receiver that honors the length.
Appending is amortized constant time, but an individual call can allocate storage and move existing contents. Calling reserve() before a series of appends can reduce allocations. The mutation may invalidate pointers, references, and iterators to elements; reacquire them afterward, including any pointer from data(). Exceeding max_size() throws std::length_error, and allocation can also fail. If the call throws, the string is unchanged.
std::back_inserter(s) from <iterator> creates a std::back_insert_iterator output iterator. Assigning a value through it, as in *out++ = ch, calls s.push_back(ch) instead of overwriting an existing element. The adaptor refers to the string object, not its buffer. Keep the string alive while writing through the adaptor, and do not assume that the adaptor prevents allocations.
Examples
#include <algorithm>
#include <iostream>
#include <iterator>
#include <string>
#include <string_view>
int main() {
constexpr std::string_view payload{"4\0" "2", 3};
std::string record{"ID"};
record.push_back(':');
std::copy(payload.begin(), payload.end(), std::back_inserter(record));
const bool has_embedded_nul = record.size() == 6 && record.data()[4] == '\0';
std::cout << record.substr(0, 3) << '\n'
<< "size: " << static_cast<unsigned long long>(record.size()) << '\n'
<< "embedded NUL: " << std::boolalpha << has_embedded_nul << '\n';
}
Result
ID: size: 6 embedded NUL: true
`push_back(':')` adds the separator, then `std::copy` uses the adaptor to append all three elements of the explicitly sized range. The size check guards the read at index 4, confirming the embedded null without printing it.
Related lessons
- C++ · Lesson 46 · Advanced · Version: 3
- C++ · Lesson 53 · Advanced · Version: 3
- C++ · Lesson 58 · Advanced · Version: 3
Sources
- [string.append] — basic_string::append and push_back
- [string.op.append] — basic_string::operator+=
- [string.require] — basic_string general requirements
- [basic.string.general] — basic_string storage and terminator
- [string.capacity] — basic_string size, capacity and reserve
- [back.insert.iterator] — back_insert_iterator and back_inserter
- std::basic_string<CharT,Traits,Allocator>::push_back — cppreference
- N4950 — Working Draft, Standard for Programming Language C++