std::uses_allocator

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Memory management library

voidify

(exposition only*)

Allocators

allocator
allocator_traits (C++11)
allocation_result (C++23)
scoped_allocator_adaptor (C++11)
pmr::polymorphic_allocator (C++17)

allocator_arg (C++11)
uses_allocator (C++11)
uses_allocator_construction_args (C++20)
make_obj_using_allocator (C++20)
uninitialized_construct_using_allocator (C++20)

Uninitialized memory algorithms

uninitialized_copy
uninitialized_fill
uninitialized_move (C++17)
uninitialized_copy_n (C++11)
uninitialized_fill_n
uninitialized_move_n (C++17)
construct_at (C++20)

uninitialized_default_construct (C++17)
uninitialized_value_construct (C++17)
destroy (C++17)
uninitialized_default_construct_n (C++17)
uninitialized_value_construct_n (C++17)
destroy_n (C++17)
destroy_at (C++17)

Constrained uninitialized memory algorithms

ranges::uninitialized_copy (C++20)
ranges::uninitialized_fill (C++20)
ranges::uninitialized_move (C++20)
ranges::uninitialized_copy_n (C++20)
ranges::uninitialized_fill_n (C++20)
ranges::uninitialized_move_n (C++20)
ranges::construct_at (C++20)

ranges::uninitialized_default_construct (C++20)
ranges::uninitialized_value_construct (C++20)
ranges::destroy (C++20)
ranges::uninitialized_default_construct_n (C++20)
ranges::uninitialized_value_construct_n (C++20)
ranges::destroy_n (C++20)
ranges::destroy_at (C++20)

Memory resources

pmr::memory_resource (C++17)
pmr::get_default_resource (C++17)
pmr::set_default_resource (C++17)
pmr::new_delete_resource (C++17)
pmr::pool_options (C++17)

pmr::null_memory_resource (C++17)
pmr::synchronized_pool_resource (C++17)
pmr::unsynchronized_pool_resource (C++17)
pmr::monotonic_buffer_resource (C++17)

Explicit lifetime management
start_lifetime_as (C++23)
start_lifetime_as_array (C++23)

Types for composite class design
indirect (C++26)
polymorphic (C++26)

Uninitialized storage(until C++20)

raw_storage_iterator (until C++20*)
get_temporary_buffer (until C++20*)

return_temporary_buffer (until C++20*)

Garbage collector support(until C++23)

declare_reachable (C++11)(until C++23)
declare_no_pointers (C++11)(until C++23)
pointer_safety (C++11)(until C++23)

undeclare_reachable (C++11)(until C++23)
undeclare_no_pointers (C++11)(until C++23)
get_pointer_safety (C++11)(until C++23)

Low level memory
management

operator newoperator new[]

operator deleteoperator delete[]

(C++11)

(C++11)

(C++17)

(C++20)

(C++17)

(C++11)

(C++11)

(C++11)

(until C++17*)

(C++11)

(C++17)

(C++26)

(C++26)

enable_shared_from_this

(C++11)

(C++11)

(C++11)

(C++23)

(C++23)

(C++11)

(C++20)

(C++11)

(C++11)

(C++20)

is_sufficiently_aligned

(C++26)

C Library

malloc
calloc
realloc

free
aligned_alloc (C++17)

[edit]

Defined in header`<memory>`
template<class T,class Alloc> struct uses_allocator;		(since C++11)

IfT has a nested typeallocator_type which is convertible fromAlloc, the member constantvalue istrue. Otherwisevalue isfalse.

[edit]Helper variable template

template<class T,class Alloc> constexprbool uses_allocator_v= uses_allocator<T, Alloc>::value;		(since C++17)

[edit]

Inherited fromstd::integral_constant

Member constants

value

[static]

true ifT uses allocatorAlloc,false otherwise
(public static member constant)

Member functions

operator bool	converts the object tobool, returnsvalue (public member function)
operator() (C++14)	returnsvalue (public member function)

Member types

Type	Definition
`value_type`	bool
`type`	std::integral_constant<bool, value>

[edit]Uses-allocator construction

There are three conventions of passing an allocatoralloc to a constructor of some typeT:

IfT does not use a compatible allocator (std::uses_allocator_v<T, Alloc> isfalse), thenalloc is ignored.
Otherwise,std::uses_allocator_v<T, Alloc> istrue, and

ifT uses theleading-allocator convention (is invocable asT(std::allocator_arg, alloc, args...)), then uses-allocator construction uses this form.
ifT uses thetrailing-allocator convention (is invocable asT(args..., alloc)), then uses-allocator construction uses this form.
Otherwise, the program is ill-formed (this meansstd::uses_allocator_v<T, Alloc> istrue, but the type does not follow either of the two allowed conventions).

As a special case,std::pair is treated as a uses-allocator type even thoughstd::uses_allocator isfalse for pairs (unlike e.g.std::tuple): see pair-specific overloads ofstd::pmr::polymorphic_allocator::construct andstd::scoped_allocator_adaptor::construct(until C++20)std::uses_allocator_construction_args(since C++20).

The utility functionsstd::make_obj_using_allocator, andstd::uninitialized_construct_using_allocator may be used to explicitly create an object following the above protocol, andstd::uses_allocator_construction_args can be used to prepare the argument list that matches the flavor of uses-allocator construction expected by the type.

(since C++20)

[edit]Specializations

Given aprogram-defined typeT that does not have a nestedallocator_type, a program can specializestd::uses_allocator to derive fromstd::true_type forT if any of the following requirements is satisfied:

T has a constructor which takesstd::allocator_arg_t as the first argument, andAlloc as the second argument.
T has a constructor which takesAlloc as the last argument.

In the above,Alloc is a type that satisfiesAllocator or is a pointer type convertible tostd::experimental::pmr::memory_resource*(library fundamentals TS).

The following specializations are already provided by the standard library:

std::uses_allocator<std::tuple> (C++11)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::queue> (C++11)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::priority_queue> (C++11)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::stack> (C++11)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::flat_map> (C++23)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::flat_set> (C++23)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::flat_multimap> (C++23)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::flat_multiset> (C++23)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::function> (C++11)(until C++17)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::promise> (C++11)	specializes thestd::uses_allocator type trait (class template specialization)[edit]
std::uses_allocator<std::packaged_task> (C++11)(until C++17)	specializes thestd::uses_allocator type trait (class template specialization)[edit]

[edit]Notes

This type trait is used bystd::tuple,std::scoped_allocator_adaptor, andstd::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.

[edit]See also

allocator_argallocator_arg_t (C++11)	a tag used to select allocator-aware constructors (tag)[edit]
uses_allocator_construction_args (C++20)	prepares the argument list matching the flavor of uses-allocator construction required by the given type (function template)[edit]
make_obj_using_allocator (C++20)	creates an object of the given type by means of uses-allocator construction (function template)[edit]
uninitialized_construct_using_allocator (C++20)	creates an object of the given type at specified memory location by means of uses-allocator construction (function template)[edit]
scoped_allocator_adaptor (C++11)	implements multi-level allocator for multi-level containers (class template)[edit]