std::basic_string::at(3)

🎀 std::basic_string::at(3) — C++ Standard Libary bestie page 🎀

okay so this is the std::basic_string::at(3) page from the C++ Standard Libary — yes, that’s the manual name, and we’re rolling with it. 💅 It’s all about grabbing one character from a basic_string with bounds checking, and honestly? iconic behavior.

💖 NAME 💖

std::basic_string::at - std::basic_string::at

that’s it, that’s the name. recursive main character energy, but we move. ✨

✨ Synopsis ✨

CharT& at( size_type pos );             (1) (constexpr since C++20)
const CharT& at( size_type pos ) const; (2) (constexpr since C++20)

okay so this function returns a reference to the character at specified location pos. Bounds checking is performed, and an exception of type std::out_of_range will be thrown on invalid access. no silent chaos, periodt. 🔥

🌸 Parameters 🌸

• pos — position of the character to return. that’s the one, bestie.

🦋 Return value 🦋

Reference to the requested character. simple, iconic, done. ✨

😭 Exceptions 😭

• Throws std::out_of_range if pos >= size(). do not ignore this. 🚨
• If an exception is thrown for any reason, these functions have no effect (strong exception safety guarantee). so even when it goes wrong, it leaves your string alone — we love a clean exit. 💖

⚡ Complexity ⚡

Constant. no scaling drama, just constant. 👑

🧚 Example 🧚

// Run this code

#include <iostream>
#include <stdexcept>
#include <string>

int main()
{
    std::string s("message"); // for capacity

    s = "abc";
    s.at(2) = 'x'; // OK
    std::cout << s << '\n';

    std::cout << "string size = " << s.size() << '\n';
    std::cout << "string capacity = " << s.capacity() << '\n';

    try
    {
        // This will throw since the requested offset is greater than the current size.
        s.at(3) = 'x';
    }
    catch (std::out_of_range const& exc)
    {
        std::cout << exc.what() << '\n';
    }
}

🌈 Possible output 🌈

abx
string size = 3
string capacity = 7
basic_string::at

📜 Defect reports 📜

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 847 — applied to C++98.
  • Behavior as published: there was no exception safety guarantee.
  • Correct behavior: added strong exception safety guarantee.

👀 See also 👀

• operator[] — accesses the specified character (public member function).
• at — accesses the specified character with bounds checking (public member function of std::basic_string_view<CharT,Traits>).

---

that’s the whole page, bestie 🫶 — source: http://cppreference.com, version/date: 2024.06.10, and it’s the std::basic_string::at(3) manual page. go forth and check your bounds 💅🌈