std::list::emplace_front(3)

💅 std::list::emplace_front(3) — the C++ Standard Library glow-up

Okay bestie, so this is the std::list::emplace_front page from the C++ Standard Libary manual — yes it's literally spelled "Libary" up top, we don't talk about it 💀 — and I'm gonna walk you through it like we're texting at 2am. Buckle up, it's giving "niche but iconic."

---

✨ NAME ✨

std::list::emplace_front — which is, and I cannot stress this enough, literally std::list::emplace_front. The manual is out here being its own name. Main character energy fr fr. 👑

---

🌸 SYNOPSIS 🌸

So the signature has been through a couple eras, like all of us. Watch:

template< class... Args >                   (since C++11)
void emplace_front( Args&&... args );       (until C++17)
template< class... Args >                   (since C++17)
reference emplace_front( Args&&... args );

What it does, plain and simple: it inserts a brand new element at the beginning of the container. The element is constructed through std::allocator_traits::construct, which typically uses placement-new to construct the element in-place right at the location the container hands over. The args... get forwarded to the constructor as std::forward<Args>(args).... Chef's kiss. 🎀

And the part that's a whole vibe: no iterators or references are invalidated. None. Zero. Nada. Your iterators are safe, your references are safe, everyone's fine, we love to see it. 😭💖

---

🦋 PARAMETERS 🦋

• args — the arguments you're forwarding to the constructor of the element. That's it, that's the parameter. Slay.

---

🌈 TYPE REQUIREMENTS 🌈

• T (the container's element type) must meet the requirements of EmplaceConstructible. No shortcuts, bestie, that's the whole requirement. 📋

Note: the original page has a lone dash bullet with no text before this item. Consider it the universe's little mystery. 🫶

---

⭐ RETURN VALUE ⭐

• (none) — until C++17
• A reference to the inserted element — since C++17

The glow-up from void to reference is real. Character development. 💅

---

🧚 COMPLEXITY 🧚

Constant. O(1) energy. Fast, effortless, unbothered. 🔥

---

👑 EXCEPTIONS 👑

If an exception is thrown for any reason, this function has no effect — that's the strong exception safety guarantee. So if things go sideways, it's like it never even happened. We love a clean exit. 💀✨

---

🍓 SEE ALSO 🍓

• push_front — inserts an element to the beginning. (public member function) — the classic, the og, the reliable one. 🫶

---

That's the whole page, bestie, no notes. Source: http://cppreference.com, version dated 2024.06.10, and we are so grateful for this documentation, fr fr. Go forth and emplace_front responsibly — or don't, I'm a manpage, not a cop. 💜🌈✨