# std::basic_string<CharT,Traits,Allocator>::at

> C++ Atlas: `cppatlas.com/w/cpp/string/basic_string/at` | Source: https://en.cppreference.com/w/cpp/string/basic_string/at | Domain: Strings | Standards: C++20

Returns a reference to the character at specified location pos. Bounds checking is performed, exception of type std::out_of_range will be thrown on invalid access.

## Official Specification Summary (cppreference)

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

Returns a reference to the character at specified location `pos`. Bounds checking is performed, exception of type `std::out_of_range` will be thrown on invalid access.

### Parameters

- `pos` - position of the character to return

### Return value

Reference to the requested character.

### Exceptions

Throws `std::out_of_range` if `pos >= size()`.

If an exception is thrown for any reason, these functions have no effect (strong exception safety guarantee).

### Complexity

Constant.

### Example

```cpp
#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:

```text
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.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 847 | C++98 | there was no exception safety guarantee | added strong exception safety guarantee |
| LWG 2207 | C++98 | the behavior was undefined if `pos >= size()` is `true` | always throws an exception in this case |

### See also

- [`operator[]`](https://en.cppreference.com/w/cpp/string/basic_string/operator_at): accesses the specified character (public member function)
- [`at`](https://en.cppreference.com/w/cpp/string/basic_string_view/at): accesses the specified character with bounds checking (public member function of `std::basic_string_view<CharT,Traits>`)

---
Attribution: content from https://en.cppreference.com/w/cpp/string/basic_string/at (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.