Difference between revisions of "cpp/iterator/size"
From cppreference.com
m (→Notes: + feature test macro, extended.) |
m (→Overloads: c/core) |
||
(16 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
− | {{cpp/title| size | ssize}} | + | {{cpp/title|size|ssize}} |
{{cpp/iterator/navbar}} | {{cpp/iterator/navbar}} | ||
{{dcl begin}} | {{dcl begin}} | ||
− | {{ | + | {{cpp/iterator/range access headers}} |
− | + | {{dcla|num=1|since=c++17| | |
− | + | template< class C > | |
− | + | constexpr auto size( const C& c ) -> decltype(c.size()); | |
− | {{ | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | template <class C> | + | |
− | constexpr auto size(const C& c) -> decltype(c.size()); | + | |
}} | }} | ||
− | {{ | + | {{dcla|num=2|since=c++20| |
− | template <class C> | + | template< class C > |
− | constexpr auto ssize(const C& c) | + | constexpr auto ssize( const C& c ) |
-> std::common_type_t<std::ptrdiff_t, | -> std::common_type_t<std::ptrdiff_t, | ||
std::make_signed_t<decltype(c.size())>>; | std::make_signed_t<decltype(c.size())>>; | ||
}} | }} | ||
− | {{ | + | {{dcla|num=3|since=c++17| |
− | template <class T, std::size_t N> | + | template< class T, std::size_t N > |
− | constexpr std::size_t size(const T (&array)[N]) noexcept; | + | constexpr std::size_t size( const T (&array)[N] ) noexcept; |
}} | }} | ||
− | {{ | + | {{dcla|num=4|since=c++20| |
− | template <class T, std::ptrdiff_t N> | + | template< class T, std::ptrdiff_t N > |
− | constexpr std::ptrdiff_t ssize(const T (&array)[N]) noexcept; | + | constexpr std::ptrdiff_t ssize( const T (&array)[N] ) noexcept; |
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
Line 38: | Line 25: | ||
Returns the size of the given range. | Returns the size of the given range. | ||
− | @1 | + | @1,2@ Returns {{c|c.size()}}, converted to the return type if necessary. |
− | @3 | + | @3,4@ Returns {{c|N}}. |
===Parameters=== | ===Parameters=== | ||
{{par begin}} | {{par begin}} | ||
− | {{par | c | a container or view with a {{tt|size}} member function}} | + | {{par|c|a container or view with a {{tt|size}} member function}} |
− | {{par | array | an array of arbitrary type}} | + | {{par|array|an array of arbitrary type}} |
{{par end}} | {{par end}} | ||
===Return value=== | ===Return value=== | ||
− | + | @1@ {{c|c.size()}} | |
+ | @2@ {{c multi|static_cast<std::common_type_t<std::ptrdiff_t,| std::make_signed_t<decltype(c.size())>>>(c.size())}} | ||
+ | @3,4@ {{c|N}} | ||
===Exceptions=== | ===Exceptions=== | ||
− | @1 | + | @1,2@ {{cpp/impldef exception item}} |
===Overloads=== | ===Overloads=== | ||
Line 57: | Line 46: | ||
{{rrev|since=c++20| | {{rrev|since=c++20| | ||
− | Overloads of {{tt|size}} found by [[cpp/language/adl|argument-dependent lookup]] can be used to customize the behavior of {{c|std::ranges::size}}, {{c|std::ranges::ssize}}, and {{c|std::ranges::empty}}. | + | Overloads of {{tt|size}} found by [[cpp/language/adl|argument-dependent lookup]] can be used to customize the behavior of {{c/core|std::ranges::size}}, {{c/core|std::ranges::ssize}}, and {{c/core|std::ranges::empty}}. |
}} | }} | ||
===Possible implementation=== | ===Possible implementation=== | ||
− | {{eq | + | {{eq impl |
− | + | |title1=size (1)|ver1=1|1= | |
− | template <class C> | + | template<class C> |
constexpr auto size(const C& c) -> decltype(c.size()) | constexpr auto size(const C& c) -> decltype(c.size()) | ||
{ | { | ||
return c.size(); | return c.size(); | ||
} | } | ||
− | + | |title2=ssize (2)|ver2=2|2= | |
− | template <class C> | + | template<class C> |
− | constexpr auto ssize(const C& c) | + | constexpr auto ssize(const C& c) |
-> std::common_type_t<std::ptrdiff_t, | -> std::common_type_t<std::ptrdiff_t, | ||
− | std::make_signed_t<decltype(c.size())>> | + | std::make_signed_t<decltype(c.size())>> |
{ | { | ||
using R = std::common_type_t<std::ptrdiff_t, | using R = std::common_type_t<std::ptrdiff_t, | ||
Line 78: | Line 67: | ||
return static_cast<R>(c.size()); | return static_cast<R>(c.size()); | ||
} | } | ||
− | + | |title3=size (3)|ver3=3|3= | |
− | template <class T, std::size_t N> | + | template<class T, std::size_t N> |
constexpr std::size_t size(const T (&array)[N]) noexcept | constexpr std::size_t size(const T (&array)[N]) noexcept | ||
{ | { | ||
return N; | return N; | ||
} | } | ||
− | + | |title4=ssize (4)|ver4=4|4= | |
− | template <class T, std::ptrdiff_t N> | + | template<class T, std::ptrdiff_t N> |
constexpr std::ptrdiff_t ssize(const T (&array)[N]) noexcept | constexpr std::ptrdiff_t ssize(const T (&array)[N]) noexcept | ||
{ | { | ||
return N; | return N; | ||
} | } | ||
− | |||
}} | }} | ||
===Notes=== | ===Notes=== | ||
− | {{ | + | {{ftm begin|std=1|comment=1}} |
− | + | {{ftm|std=C++17|value=201411L|__cpp_lib_nonmember_container_access|{{tt|std::size()}}, {{lc|std::data}} and {{lc|std::empty}}}} | |
− | {{ | + | {{ftm|std=C++20|value=201902L|__cpp_lib_ssize|{{tt|std::ssize()}} {{vl|2,4}} and unsigned {{ltf|cpp/container/span/size|std::span::size}}}} |
+ | {{ftm end}} | ||
===Example=== | ===Example=== | ||
{{example | {{example | ||
− | + | |code= | |
− | + | #include <cassert> | |
+ | #include <cstring> | ||
#include <iostream> | #include <iostream> | ||
#include <vector> | #include <vector> | ||
− | |||
− | int main() | + | int main() |
{ | { | ||
− | std::vector<int> v | + | // Works with containers |
− | std::cout << std::size(v) << '\n'; | + | std::vector<int> v{3, 1, 4}; |
+ | assert(std::size(v) == 3); | ||
+ | |||
+ | // And works with built-in arrays too | ||
+ | int a[]{-5, 10, 15}; | ||
+ | // Returns the number of elements (not bytes) as opposed to sizeof | ||
+ | assert(std::size(a) == 3); | ||
+ | std::cout << "size of a[]: " << sizeof a << '\n'; // 12, if sizeof(int) == 4 | ||
+ | |||
+ | // Provides a safe way (compared to sizeof) of getting string buffer size | ||
+ | const char str[] = "12345"; | ||
+ | // These are fine and give the correct result | ||
+ | assert(std::size(str) == 6); | ||
+ | assert(sizeof(str) == 6); | ||
+ | |||
+ | // But use of sizeof here is a common source of bugs | ||
+ | const char* str_decayed = "12345"; | ||
+ | // std::cout << std::size(str_decayed) << '\n'; // Usefully fails to compile | ||
+ | std::cout << sizeof(str_decayed) << '\n'; // Prints the size of the pointer! | ||
+ | |||
+ | // Since C++20 the signed size (std::ssize) is available | ||
+ | auto i = std::ssize(v); | ||
+ | for (--i; i != -1; --i) | ||
+ | std::cout << v[i] << (i ? ' ' : '\n'); | ||
+ | assert(i == -1); | ||
− | + | // Note that the string literal includes the ending null character, which | |
− | std:: | + | // will be part of the constructed characters array. This makes std::size |
+ | // behave differently from std::strlen and std::string::size: | ||
+ | constexpr char symbols[] = "0123456789"; | ||
− | + | static_assert(std::size(symbols) == 11); | |
− | + | static_assert(std::string(symbols).size() == 10); | |
− | + | assert(std::strlen(symbols) == 10); | |
− | + | ||
− | + | ||
− | + | ||
} | } | ||
− | + | |p=true<!--sizeof pointer and int--> | |
− | + | |output= | |
− | + | size of a[]: 12 | |
− | 4 1 3 | + | 8 |
− | + | 4 1 3 | |
}} | }} | ||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc inc | cpp/types/dsc ptrdiff_t}} | + | {{dsc inc|cpp/types/dsc ptrdiff_t}} |
− | {{dsc inc | cpp/types/dsc size_t}} | + | {{dsc inc|cpp/types/dsc size_t}} |
− | {{dsc inc | cpp/ranges/dsc size}} | + | {{dsc inc|cpp/ranges/dsc size}} |
− | {{dsc inc | cpp/ranges/dsc ssize}} | + | {{dsc inc|cpp/ranges/dsc ssize}} |
{{dsc end}} | {{dsc end}} | ||
{{langlinks|es|ja|ru|zh}} | {{langlinks|es|ja|ru|zh}} |
Latest revision as of 22:02, 1 November 2024
Defined in header <array>
|
||
Defined in header <deque>
|
||
Defined in header <flat_map>
|
||
Defined in header <flat_set>
|
||
Defined in header <forward_list>
|
||
Defined in header <inplace_vector>
|
||
Defined in header <iterator>
|
||
Defined in header <list>
|
||
Defined in header <map>
|
||
Defined in header <regex>
|
||
Defined in header <set>
|
||
Defined in header <span>
|
||
Defined in header <string>
|
||
Defined in header <string_view>
|
||
Defined in header <unordered_map>
|
||
Defined in header <unordered_set>
|
||
Defined in header <vector>
|
||
template< class C > constexpr auto size( const C& c ) -> decltype(c.size()); |
(1) | (since C++17) |
template< class C > constexpr auto ssize( const C& c ) |
(2) | (since C++20) |
template< class T, std::size_t N > constexpr std::size_t size( const T (&array)[N] ) noexcept; |
(3) | (since C++17) |
template< class T, std::ptrdiff_t N > constexpr std::ptrdiff_t ssize( const T (&array)[N] ) noexcept; |
(4) | (since C++20) |
Returns the size of the given range.
1,2) Returns c.size(), converted to the return type if necessary.
3,4) Returns N.
Contents |
[edit] Parameters
c | - | a container or view with a size member function
|
array | - | an array of arbitrary type |
[edit] Return value
1) c.size()
2) static_cast<std::common_type_t<std::ptrdiff_t,
std::make_signed_t<decltype(c.size())>>>(c.size())
std::make_signed_t<decltype(c.size())>>>(c.size())
3,4) N
[edit] Exceptions
1,2) May throw implementation-defined exceptions.
[edit] Overloads
Custom overloads of size
may be provided for classes and enumerations that do not expose a suitable size()
member function, yet can be detected.
Overloads of |
(since C++20) |
[edit] Possible implementation
size (1) |
---|
template<class C> constexpr auto size(const C& c) -> decltype(c.size()) { return c.size(); } |
ssize (2) |
template<class C> constexpr auto ssize(const C& c) -> std::common_type_t<std::ptrdiff_t, std::make_signed_t<decltype(c.size())>> { using R = std::common_type_t<std::ptrdiff_t, std::make_signed_t<decltype(c.size())>>; return static_cast<R>(c.size()); } |
size (3) |
template<class T, std::size_t N> constexpr std::size_t size(const T (&array)[N]) noexcept { return N; } |
ssize (4) |
template<class T, std::ptrdiff_t N> constexpr std::ptrdiff_t ssize(const T (&array)[N]) noexcept { return N; } |
[edit] Notes
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_lib_nonmember_container_access |
201411L | (C++17) | std::size() , std::data and std::empty
|
__cpp_lib_ssize |
201902L | (C++20) | std::ssize() (2,4) and unsigned std::span::size()
|
[edit] Example
Run this code
#include <cassert> #include <cstring> #include <iostream> #include <vector> int main() { // Works with containers std::vector<int> v{3, 1, 4}; assert(std::size(v) == 3); // And works with built-in arrays too int a[]{-5, 10, 15}; // Returns the number of elements (not bytes) as opposed to sizeof assert(std::size(a) == 3); std::cout << "size of a[]: " << sizeof a << '\n'; // 12, if sizeof(int) == 4 // Provides a safe way (compared to sizeof) of getting string buffer size const char str[] = "12345"; // These are fine and give the correct result assert(std::size(str) == 6); assert(sizeof(str) == 6); // But use of sizeof here is a common source of bugs const char* str_decayed = "12345"; // std::cout << std::size(str_decayed) << '\n'; // Usefully fails to compile std::cout << sizeof(str_decayed) << '\n'; // Prints the size of the pointer! // Since C++20 the signed size (std::ssize) is available auto i = std::ssize(v); for (--i; i != -1; --i) std::cout << v[i] << (i ? ' ' : '\n'); assert(i == -1); // Note that the string literal includes the ending null character, which // will be part of the constructed characters array. This makes std::size // behave differently from std::strlen and std::string::size: constexpr char symbols[] = "0123456789"; static_assert(std::size(symbols) == 11); static_assert(std::string(symbols).size() == 10); assert(std::strlen(symbols) == 10); }
Possible output:
size of a[]: 12 8 4 1 3
[edit] See also
signed integer type returned when subtracting two pointers (typedef) | |
unsigned integer type returned by the sizeof operator (typedef) | |
(C++20) |
returns an integer equal to the size of a range (customization point object) |
(C++20) |
returns a signed integer equal to the size of a range (customization point object) |