Namespaces
Variants
Views
Actions

Difference between revisions of "Template:cpp/container/at"

From cppreference.com
m
m (→‎Example: fix the output.)
 
(39 intermediate revisions by 11 users not shown)
Line 1: Line 1:
−
{{cpp/container/{{{1|}}}/title | at}}
+
{{#vardefine:cont|{{{1|inplace_vector}}}}}<!--
−
{{cpp/container/{{{1|}}}/navbar}}
+
-->{{cpp/container/{{#var:cont}}/title|at}}
−
{{ddcl list begin}}
+
{{cpp/container/{{#var:cont}}/navbar}}
−
{{ddcl list item | notes={{cpp/container/mark since c++11 | {{{1|}}} }} |
+
{{dcl begin}}
−
reference       at( size_type pos );
+
{{#switch:{{#var:cont}}
 +
|array=
 +
{{dcl|num=1|since=c++11|notes={{mark constexpr since c++17}}|
 +
reference at( size_type pos );
 
}}
 
}}
−
{{ddcl list item | notes={{cpp/container/mark since c++11 | {{{1|}}} }} |
+
{{dcl|num=2|since=c++11|notes={{mark constexpr since c++14}}|
 +
const_reference at( size_type pos ) const;
 +
}}
 +
|vector=
 +
{{dcl|num=1|notes={{mark constexpr since c++20}}|
 +
reference at( size_type pos );
 +
}}
 +
{{dcl|num=2|notes={{mark constexpr since c++20}}|
 +
const_reference at( size_type pos ) const;
 +
}}
 +
|inplace_vector=
 +
{{dcl|num=1|since=c++26|
 +
constexpr reference at( size_type pos );
 +
}}
 +
{{dcl|num=2|since=c++26|
 
constexpr const_reference at( size_type pos ) const;
 
constexpr const_reference at( size_type pos ) const;
 
}}
 
}}
−
{{ddcl list end}}
+
|span=
 +
{{dcl|since=c++26|
 +
constexpr reference at( size_type pos ) const;
 +
}}
 +
|
 +
{{dcl|num=1|since={{cpp/std|{{#var:cont}}}}|
 +
reference at( size_type pos );
 +
}}
 +
{{dcl|num=2|since={{cpp/std|{{#var:cont}}}}|
 +
const_reference at( size_type pos ) const;
 +
}}
 +
}}
 +
{{dcl end}}
  
−
Returns a reference to the element at specified location {{tt|pos}}. Bounds checking is performed, exception of type {{c|std::out_of_range}} will be thrown on invalid access.
+
Returns a reference to the element at specified location {{c|pos}}, with bounds checking.
 +
 
 +
If {{c|pos}} is not within the range of the {{#switch:{{#var:cont}}|span=span|container}}, an exception of type {{lc|std::out_of_range}} is thrown.
  
 
===Parameters===
 
===Parameters===
−
{{param list begin}}
+
{{par begin}}
−
{{param list item | pos | position of the element to return}}
+
{{par|pos|position of the element to return}}
−
{{param list end}}
+
{{par end}}
  
 
===Return value===
 
===Return value===
−
reference to the requested element
+
Reference to the requested element, i.e. {{#ifeq:{{#var:cont}}|span|{{c|*(data() + pos)}}|{{c|*(a.begin() + pos)}}}}.
  
 
===Exceptions===
 
===Exceptions===
−
 
+
{{lc|std::out_of_range}} if {{c|1=pos >= size()}}.
−
{{c|std::out_of_range}} if {{c|!(pos < size())}}.
+
  
 
===Complexity===
 
===Complexity===
−
Constant
+
Constant.
−
 
+
<!---->
 +
{{#ifeq:{{#var:cont}}|span|
 
===Notes===
 
===Notes===
−
Const version is marked as constexpr since c++14
+
{{feature test macro|__cpp_lib_span|std=C++26|value=202311L|{{tt|std::span::at}}}}
 +
}}
 +
<!---->
 +
===Example===
 +
{{example
 +
|code=
 +
#include <chrono>
 +
#include <cstddef>
 +
#include <iostream>
 +
#include <{{#var:cont}}>
 +
#include <stdexcept>
  
−
===See also===
+
int main()
 +
{
 +
    {{#switch:{{#var:cont}}
 +
    |deque|vector=
 +
    std::{{#var:cont}}<int> data{1, 2, 4, 5, 5, 6};
 +
    |array|inplace_vector=
 +
    std::{{#var:cont}}<int, 6> data{1, 2, 4, 5, 5, 6};
 +
    |span=
 +
    int x[]{1, 2, 4, 5, 5, 6};
 +
    std::span data(x);
 +
    }}
  
−
{{dcl list begin}}
+
    // Set element 1
−
{{dcl list template | cpp/container/dcl list operator_at |{{{1|}}}}}
+
    data.at(1) = 88;
−
{{dcl list end}}
+
 
 +
    // Read element 2
 +
    std::cout << "Element at index 2 has value " << data.at(2) << '\n';
 +
 
 +
    std::cout << "data size = " << data.size() << '\n';
 +
 
 +
    try
 +
    {
 +
        // Try to set an element at random position >= size()
 +
        auto moon_phase = []
 +
        {
 +
            return std::chrono::system_clock::now().time_since_epoch().count() % 8;
 +
        };
 +
        data.at(data.size() + moon_phase()) = 13;
 +
    }
 +
    catch(const std::out_of_range& ex)
 +
    {
 +
        std::cout << ex.what() << '\n';
 +
    }
 +
 
 +
    // Print final values
 +
    std::cout << "data:";
 +
    for (int elem : data)
 +
        std::cout << ' ' << elem;
 +
    std::cout << '\n';
 +
}
 +
|p=true
 +
|output=
 +
Element at index 2 has value 4
 +
data size = 6
 +
{{#switch:{{#var:cont}}
 +
|vector=vector::_M_range_check: __n (which is 8) >= this->size() (which is 6)
 +
|deque=deque::_M_range_check: __n (which is 8) >= this->size() (which is 6)
 +
|array=array::at: __n (which is 8) >= _Nm (which is 6)
 +
|#default=std::out_of_range: pos (which is 8) >= size() (which is 6)
 +
}}
 +
data: 1 88 4 5 5 6
 +
}}
 +
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/container/dsc operator at|{{#var:cont}}}}
 +
{{dsc end}}

Latest revision as of 01:32, 16 August 2024

 
C++
 
Containers library
 
std::inplace_vector
Member types
Member functions
Non-member functions
 
constexpr reference at( size_type pos );
 (1) (since C++26)
constexpr const_reference at( size_type pos ) const;
 (2) (since C++26)

Returns a reference to the element at specified location pos, with bounds checking.

If pos is not within the range of the container, an exception of type std::out_of_range is thrown.

Contents

[edit] Parameters

pos - position of the element to return

[edit] Return value

Reference to the requested element, i.e. *(a.begin() + pos).

[edit] Exceptions

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

[edit] Complexity

Constant.

[edit] Example

Run this code
#include <chrono>
#include <cstddef>
#include <iostream>
#include <inplace_vector>
#include <stdexcept>
 
int main()
{
    std::inplace_vector<int, 6> 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
    {
        // Try to set an element at random position >= size()
        auto moon_phase = []
        {
            return std::chrono::system_clock::now().time_since_epoch().count() % 8;
        };
        data.at(data.size() + moon_phase()) = 13;
    }
    catch(const std::out_of_range& ex)
    {
        std::cout << ex.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
std::out_of_range: pos (which is 8) >= size() (which is 6)
data: 1 88 4 5 5 6

[edit] See also

 access specified element
(public member function of std::inplace_vector<T,N>) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=Template:cpp/container/at&oldid=175253"