View source for cpp/memory/uses allocator

{{cpp/title|uses_allocator}}
{{cpp/memory/navbar}}
{{ddcl|header=memory|since=c++11|
template< class T, class Alloc >
struct uses_allocator;
}}

If {{tt|T}} has a nested type {{tt|allocator_type}} which is convertible from {{tt|Alloc}}, the member constant {{c|value}} is {{c|true}}. Otherwise {{c|value}} is {{c|false}}.

===Helper variable template===
{{ddcl|since=c++17|1=
template< class T, class Alloc >
constexpr bool uses_allocator_v = uses_allocator<T, Alloc>::value;
}}

{{cpp/types/integral_constant/inherit|{{tt|T}} uses allocator {{tt|Alloc}}}}

===Uses-allocator construction===
There are three conventions of passing an allocator {{c|alloc}} to a constructor of some type {{tt|T}}:
* If {{tt|T}} does not use a compatible allocator ({{c|std::uses_allocator_v<T, Alloc>}} is {{c|false}}), then {{tt|alloc}} is ignored.
* Otherwise, {{c|std::uses_allocator_v<T, Alloc>}} is {{c|true}}, and
:* if {{tt|T}} uses the ''leading-allocator convention'' (is invocable as {{c|T(std::allocator_arg, alloc, args...)}}), then uses-allocator construction uses this form.
:* if {{tt|T}} uses the ''trailing-allocator convention'' (is invocable as {{c|T(args..., alloc)}}), then uses-allocator construction uses this form.
:* Otherwise, the program is ill-formed (this means {{c|std::uses_allocator_v<T, Alloc>}} is {{c|true}}, but the type does not follow either of the two allowed conventions).
* As a special case, {{lc|std::pair}} is treated as a uses-allocator type even though {{tt|std::uses_allocator}} is {{c|false}} for pairs (unlike e.g. {{lc|std::tuple}}): see pair-specific overloads of {{rev inl|until=c++20|{{lc|std::pmr::polymorphic_allocator::construct}} and {{lc|std::scoped_allocator_adaptor::construct}}}}{{rev inl|since=c++20|{{lc|std::uses_allocator_construction_args}}}}.

{{rrev|since=c++20|
The utility functions {{lc|std::make_obj_using_allocator}}, and {{lc|std::uninitialized_construct_using_allocator}} may be used to explicitly create an object following the above protocol, and {{lc|std::uses_allocator_construction_args}} can be used to prepare the argument list that matches the flavor of uses-allocator construction expected by the type.
}}

===Specializations===
Given a {{lsd|cpp/language/type#Program-defined type}} {{tt|T}} that does not have a nested {{tt|allocator_type}}, a program can specialize {{tt|std::uses_allocator}} to derive from {{lc|std::true_type}} for {{tt|T}} if any of the following requirements is satisfied:
* {{tt|T}} has a constructor which takes {{lc|std::allocator_arg_t}} as the first argument, and {{tt|Alloc}} as the second argument.
* {{tt|T}} has a constructor which takes {{tt|Alloc}} as the last argument.

In the above, {{tt|Alloc}} is a type that satisfies {{named req|Allocator}}{{rev inl|since=libfund_ts| or is a pointer type convertible to {{lc|std::experimental::pmr::memory_resource*}}}}.

The following specializations are already provided by the standard library:

{{dsc begin}}
{{dsc inc|cpp/utility/tuple/dsc uses_allocator}}
{{dsc inc|cpp/container/dsc uses_allocator|queue}}
{{dsc inc|cpp/container/dsc uses_allocator|priority_queue}}
{{dsc inc|cpp/container/dsc uses_allocator|stack}}
{{dsc inc|cpp/container/dsc uses_allocator|flat_map}}
{{dsc inc|cpp/container/dsc uses_allocator|flat_set}}
{{dsc inc|cpp/container/dsc uses_allocator|flat_multimap}}
{{dsc inc|cpp/container/dsc uses_allocator|flat_multiset}}
{{dsc inc|cpp/utility/functional/function/dsc uses_allocator}}
{{dsc inc|cpp/thread/promise/dsc uses_allocator}}
{{dsc inc|cpp/thread/packaged_task/dsc uses_allocator}}
{{dsc end}}

===Notes===
This type trait is used by {{lc|std::tuple}}, {{lc|std::scoped_allocator_adaptor}}, and {{lc|std::pmr::polymorphic_allocator}}. It may also be used by custom allocators or wrapper types to determine whether the object or member being constructed is itself capable of using an allocator (e.g. is a container), in which case an allocator should be passed to its constructor.

===See also===
{{dsc begin}}
{{dsc inc|cpp/memory/dsc allocator_arg}}
{{dsc inc|cpp/memory/dsc uses_allocator_construction_args}}
{{dsc inc|cpp/memory/dsc make_obj_using_allocator}}
{{dsc inc|cpp/memory/dsc uninitialized_construct_using_allocator}}
{{dsc inc|cpp/memory/dsc scoped_allocator_adaptor}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pt|ru|zh}}