std::basic_...::push_back(3)

🌸 std::basic_string::push_back — section 3 of the C++ Standard Library man pages 🎀

Hey bestie, ok so listen — this is the man page for std::basic_string::push_back, and honestly? It's giving "tiny function, big main character energy." 💅 It's the one little member function whose whole entire job is: put a character at the end of your string. That's it. That's the whole vibe. And she does it flawlessly.

---

✨ NAME ✨

std::basic_string::push_back — which, yeah, is exactly what it sounds like: std::basic_string::push_back. No plot twist, no lore, just the name matching the name. 🫶

---

🌈 Synopsis 🌈

void push_back( CharT ch );  (constexpr since C++20)

What it does: appends the given character ch to the end of the string. That's the whole thing, bestie. One character, added to the end, no cap. ✨

---

🦋 Parameters 🦋

• ch — the character you want to append 💖

---

🎀 Return value 🎀

(none)

Like, she returns nothing. She's not here for a reward, she's here to do the job. void and unbothered. 😌

---

⭐ Complexity ⭐

Amortized constant. So like, usually literally instant, and on average you're so fine. Go off. 🔥

---

💀 Exceptions 💀

Ok real talk, but also pay attention here:

• If the operation would make size() > max_size(), it throws std::length_error. That's your hard limit, no cap, can't push past it. 🚫
• If an exception is thrown for any reason, this function has no effect — that's the strong exception safety guarantee. So it's like nothing ever happened. Iconic rollback behaviour, honestly. 🙈

---

🧚 Example 🧚

// Run this code

#include <iomanip>
#include <iostream>
#include <string>

int main()
{
    std::string str{"Short string"};
    std::cout << "1) " << std::quoted(str) << ", size: " << str.size() << '\n';

    str.push_back('!');
    std::cout << "2) " << std::quoted(str) << ", size: " << str.size() << '\n';
}

---

🍓 Output 🍓

1) "Short string", size: 12
2) "Short string!", size: 13

See how the size went from 12 to 13? That's her. That's the push_back effect. She added exactly one ! and the string ate. 😭👑

---

🔥 Defect reports 🔥

So the following behavior-changing defect reports were applied retroactively to previously published C++ standards — meaning yes, your old code was living a different timeline. ⏳

• LWG 7 — applied to C++98. Behavior as published: (1) the description was missing in the C++ standard, and (2) the parameter type was const CharT. Correct behavior: (1) description added, and (2) changed to CharT.
• LWG 847 — applied to C++98. Behavior as published: there was no exception safety guarantee. Correct behavior: added strong exception safety guarantee.

---

💜 See also 💜

• pop_back — removes the last character (public member function). She's the opposite twin, the take it back of the family. 😌

---

ngl bestie, the whole lesson is: push_back adds one char to the end, it's amortized constant, it throws std::length_error if you'd blow past max_size(), and it's got your back with the strong exception safety guarantee. Go forth and append. 🫶✨

---

💖 that's the whole page!! 💖 brought to you by http://cppreference.com, dated 2024.06.10 — std::basic_...::push_back(3), logging off, mwah 💅🎀