std::out_of_range
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <stdexcept> | ||
class out_of_range; | ||
Defines a type of object to be thrown as exception. It reports errors that are consequence of attempt to access elements out of defined range.
It may be thrown by the member functions ofstd::bitset andstd::basic_string, bystd::stoi andstd::stod families of functions, and by the bounds-checked member access functions (e.g.std::vector::at andstd::map::at).
All member functions ofstd::out_of_range areconstexpr: it is possible to create and usestd::out_of_range objects in the evaluation of a constant expression.However, | (since C++26) |
Inheritance diagram
Contents |
[edit]Member functions
(constructor) | constructs a newout_of_range object with the given message(public member function) |
operator= | replaces theout_of_range object(public member function) |
std::out_of_range::out_of_range
out_of_range(conststd::string& what_arg); | (1) | (constexpr since C++26) |
out_of_range(constchar* what_arg); | (2) | (constexpr since C++26) |
out_of_range(const out_of_range& other); | (3) | (noexcept since C++11) (constexpr since C++26) |
std::out_of_range thenstd::strcmp(what(), other.what())==0. No exception can be thrown from the copy constructor.Parameters
| what_arg | - | explanatory string |
| other | - | another exception object to copy |
Exceptions
Notes
Because copyingstd::out_of_range is not permitted to throw exceptions, this message is typically stored internally as a separately-allocated reference-counted string. This is also why there is no constructor takingstd::string&&: it would have to copy the content anyway.
Before the resolution ofLWG issue 254, the non-copy constructor can only acceptstd::string. It makes dynamic allocation mandatory in order to construct astd::string object.
After the resolution ofLWG issue 471, a derived standard exception class must have a publicly accessible copy constructor. It can be implicitly defined as long as the explanatory strings obtained bywhat() are the same for the original object and the copied object.
std::out_of_range::operator=
out_of_range& operator=(const out_of_range& other); | (noexcept since C++11) (constexpr since C++26) | |
Assigns the contents with those ofother. If*this andother both have dynamic typestd::out_of_range thenstd::strcmp(what(), other.what())==0 after assignment. No exception can be thrown from the copy assignment operator.
Parameters
| other | - | another exception object to assign with |
Return value
*this
Notes
After the resolution ofLWG issue 471, a derived standard exception class must have a publicly accessible copy assignment operator. It can be implicitly defined as long as the explanatory strings obtained bywhat() are the same for the original object and the copied object.
Inherited fromstd::logic_error
Inherited fromstd::exception
Member functions
[virtual] | destroys the exception object (virtual public member function of std::exception)[edit] |
[virtual] | returns an explanatory string (virtual public member function of std::exception)[edit] |
[edit]Notes
The standard error conditionstd::errc::result_out_of_range typically indicates the condition where the result, rather than the input, is out of range, and is more closely related tostd::range_error andERANGE.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_constexpr_exceptions | 202502L | (C++26) | constexpr exception types |
[edit]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 254 | C++98 | the constructor acceptingconstchar* was missing | added |
| LWG 471 | C++98 | the explanatory strings ofstd::out_of_range'scopies were implementation-defined | they are the same as that of the original std::out_of_range object |
[edit]See also
| accesses the specified character with bounds checking (public member function of std::basic_string<CharT,Traits,Allocator>)[edit] | |
| accesses the specified character with bounds checking (public member function of std::basic_string_view<CharT,Traits>)[edit] | |
| access specified element with bounds checking (public member function of std::deque<T,Allocator>)[edit] | |
| access specified element with bounds checking (public member function of std::map<Key,T,Compare,Allocator>)[edit] | |
| access specified element with bounds checking (public member function of std::unordered_map<Key,T,Hash,KeyEqual,Allocator>)[edit] | |
| access specified element with bounds checking (public member function of std::vector<T,Allocator>)[edit] | |
| access specified element with bounds checking (public member function of std::array<T,N>)[edit] | |
(C++26) | access specified element with bounds checking (public member function of std::span<T,Extent>)[edit] |
