View source for cpp/ranges/size

{{cpp/ranges/title|size}}
{{cpp/ranges/navbar}}

{{dcl begin}}
{{dcl header|ranges}}
{{dcl header|iterator}}
{{dcl|notes={{mark custpt}}|since=c++20|1=
inline namespace /* unspecified */ {
    inline constexpr auto size = /* unspecified */;
}
}}
{{dcl h|Call signature}}
{{dcl|since=c++20|1=
template< class T >
    requires /* see below */
constexpr auto size( T&& t );
}}
{{dcl end}}

Calculates the number of elements in {{c|t}} in constant time.

Given the [[cpp/language/expressions#Full-expressions|subexpression]] of which {{c|t}} denotes the (possibly [[cpp/language/implicit conversion#Temporary materialization|materialized]]) result object as {{c|E}}, and the type of {{c|E}} as {{tt|T}}:
* If {{tt|T}} is an array of unknown bound, {{c|ranges::size(E)}} is ill-formed.
* Otherwise, if {{tt|T}} is an array type, {{c|ranges::size(E)}} is [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to {{rev inl|until=c++23|{{box|{{lti|cpp/standard library/decay-copy}}{{sep}}{{c/core|(std::extent_v<T>)}}}}}}{{rev inl|since=c++23|{{c|auto(std::extent_v<T>)}}}}.
* Otherwise, if all following conditions are satisfied, {{c|ranges::size(E)}} is expression-equivalent to {{rev inl|until=c++23|{{box|{{lti|cpp/standard library/decay-copy}}{{sep}}{{c/core|(t.size())}}}}}}{{rev inl|since=c++23|{{c|auto(t.size())}}}}:
** {{c|ranges::disable_sized_range<std::remove_cv_t<T>>}} is {{c|false}}.
** {{rev inl|until=c++23|{{box|{{lti|cpp/standard library/decay-copy}}{{sep}}{{c/core|(t.size())}}}}}}{{rev inl|since=c++23|{{c|auto(t.size())}}}} is a valid expression of [[cpp/iterator/is-integer-like|integer-like type]].
* Otherwise, if all following conditions are satisfied, {{c|ranges::size(E)}} is expression-equivalent to {{rev inl|until=c++23|{{box|{{lti|cpp/standard library/decay-copy}}{{sep}}{{c/core|(size(t))}}}}}}{{rev inl|since=c++23|{{c|auto(size(t))}}}}:
** {{tt|T}} is a class or enumeration type.
** {{c|ranges::disable_sized_range<std::remove_cv_t<T>>}} is {{c|false}}.
** {{rev inl|until=c++23|{{box|{{lti|cpp/standard library/decay-copy}}{{sep}}{{c/core|(size(t))}}}}}}{{rev inl|since=c++23|{{c|auto(size(t))}}}} is a valid expression of integer-like type, where the meaning of {{tt|size}} is established as if by performing [[cpp/language/adl|argument-dependent lookup]] only.
* Otherwise, if all following conditions are satisfied, {{c|ranges::size(E)}} is expression-equivalent to {{box|{{lsi|cpp/ranges#to-unsigned-like}}{{sep}}{{c/core|(ranges::end(t) - ranges::begin(t))}}}}:
** {{tt|T}} models {{lconcept|forward_range}}.
** Given the type of {{c|ranges::begin(t)}} as {{tt|I}} and the type of {{c|ranges::end(t)}} as {{tt|S}}, both {{box/core|{{lconcept|sized_sentinel_for}}{{c/core|<S, I>}}}} and {{box/core|{{lconcept|forward_iterator}}{{c/core|<I>}}}} are modeled.
** {{box|{{lsi|cpp/ranges#to-unsigned-like}}{{sep}}{{c/core|(ranges::end(t) - ranges::begin(t))}}}} is a valid expression.
* Otherwise, {{c|ranges::size(E)}} is ill-formed.

Diagnosable ill-formed cases above result in [[cpp/language/sfinae|substitution failure]] when {{c|ranges::size(E)}} appears in the immediate context of a template instantiation.

{{cpp/ranges/cpo}}

===Notes===
Whenever {{c|ranges::size(e)}} is valid for an expression {{c|e}}, the return type is [[cpp/iterator/is-integer-like|integer-like]].

{{cpp/ranges/prv}}

The expression {{c|ranges::distance(e)}} can also be used to determine the size of a range {{c|e}}. Unlike {{c|ranges::size(e)}}, {{c|ranges::distance(e)}} works even if {{c|e}} is an unsized range, at the cost of having linear complexity in that case.

===Example===
{{example
|
|code=
#include <iostream>
#include <ranges>
#include <type_traits>
#include <vector>

int main()
{
    auto v = std::vector<int>{};
    std::cout << "ranges::size(v) == " << std::ranges::size(v) << '\n';
    
    auto il = {7};     // std::initializer_list
    std::cout << "ranges::size(il) == " << std::ranges::size(il) << '\n';
    
    int array[]{4, 5}; // array has a known bound
    std::cout << "ranges::size(array) == " << std::ranges::size(array) << '\n';
    
    static_assert(std::is_signed_v<decltype(std::ranges::size(v))> == false);
}
|output=
ranges::size(v) == 0
ranges::size(il) == 1
ranges::size(array) == 2
}}

===Defect reports===
{{dr list begin}}
{{dr list item|paper=P2602R2|std=C++20|before=there's machinery to prohibit certain non-member {{tt|size}} found by [[cpp/language/adl|ADL]]|after=removed such machinery}}
{{dr list end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/ranges/dsc ssize}}
{{dsc inc|cpp/ranges/dsc sized_range}}
{{dsc inc|cpp/iterator/ranges/dsc distance}}
{{dsc inc|cpp/iterator/dsc size}}
{{dsc end}}

{{langlinks|de|es|ja|ru|zh}}