std::vector::at(3)

🎀 NAME 🎀

std::vector::at — bestie's fave bounds-checked element getter, from the C++ Standard Libary ✨ (yes that's the manual name, we don't gatekeep the spelling 💅)

---

🌸 Synopsis 🌸

reference at( size_type pos );             (1) (constexpr since C++20)
const_reference at( size_type pos ) const; (2) (constexpr since C++20)

Okay so picture this: you hand at a position pos and it hands you back a reference to the element at that exact spot — but like, with bounds checking 💅 it's giving responsible queen behavior. She checks first. She does not just rawdog the memory.

And if pos is not within the range of the container? She throws. Specifically, an exception of type std::out_of_range 😭 so you literally cannot pretend you didn't get warned.

---

🦋 Parameters 🦋

• pos — the position of the element you wanna return 🫶 that's the whole vibe, that's the whole parameter.

---

⭐ Return value ⭐

A reference to the requested element. Slay. That's it, that's the return value 💜

---

🔥 Exceptions 🔥

• std::out_of_range if pos >= size() 💀 like, she said what she said.

ngl bestie, this is the entire reason you use at instead of accidentally doing something cursed. respect the bounds or catch the throw 🙈

---

👑 Complexity 👑

Constant. O(1) energy. Main character efficiency, no notes ⭐

---

🌈 Example 🌈

// Run this code

#include <iostream>
#include <vector>
#include <stdexcept>

#ifdef __GNUG__
[[gnu::noinline]]
#endif
unsigned int runtime_six() // Emulate runtime input
{
    return 6u;
}

int main()
{
    std::vector<int> data = {1, 2, 4, 5, 5, 6};

    // Set element 1
    data.at(1) = 88;

    // Read element 2
    std::cout << "Element at index 2 has value " << data.at(2) << '\n';

    std::cout << "data size = " << data.size() << '\n';

    try
    {
        // Set element 6, where the index is determined at runtime
        data.at(runtime_six()) = 666;
    }
    catch (std::out_of_range const& exc)
    {
        std::cout << exc.what() << '\n';
    }

    // Print final values
    std::cout << "data:";
    for (int elem : data)
        std::cout << ' ' << elem;
    std::cout << '\n';
}

Possible output:

Element at index 2 has value 4
data size = 6
vector::_M_range_check: __n (which is 6) >= this->size() (which is 6)
data: 1 88 4 5 5 6

The way data.at(1) = 88 just works because it's a reference 🔥 and then data.at(runtime_six()) with 6u walks straight into the std::out_of_range catch block and prints the whole exc.what() message 😭 iconic honestly. And after all that drama, data is still 1 88 4 5 5 6 — element 2 is untouched at value 4 because index 2 holds the third element, which is 4. fr fr.

---

🧚 See also 🧚

• operator[] — access specified element (public member function) — the unbothered sibling who does not do bounds checking, so like… be careful bestie, iykyk 💅

---

okay that's the whole page, you ate that 💖 Brought to you by http://cppreference.com, dated 2024.06.10 — big kisses from your girl, now go write some bounds-checked code and catch your exceptions 🎀✨🦋