C++ concepts: Allocator

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

C++ concepts

Basic
DefaultConstructible CopyAssignable CopyConstructible	MoveAssignable (C++11) MoveConstructible (C++11) Destructible
Library-Wide
EqualityComparable LessThanComparable Swappable (C++11) ValueSwappable (C++11)	NullablePointer (C++11) Hash (C++11) Allocator
Container
Container SequenceContainer ReversibleContainer	AssociativeContainer AllocatorAwareContainer UnorderedAssociativeContainer (C++11)
Container Elements
CopyInsertable (C++11) MoveInsertable (C++11)	EmplaceConstructible (C++11)
Iterator
Iterator OutputIterator InputIterator	ForwardIterator BidirectionalIterator RandomAccessIterator
Stream I/O
FormattedInputFunction UnformattedInputFunction	FormattedOutputFunction UnformattedOutputFunction
Random Numbers
SeedSequence (C++11) RandomNumberEngine (C++11)	RandomNumberDistribution (C++11) UniformRandomNumberGenerator (C++11) RandomNumberEngineAdaptor (C++11)
Concurrency
BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11)	Mutex (C++11) TimedMutex (C++11)
Other
CharTraits pos_type off_type Clock (C++11)	UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) TrivialClock (C++11)

 

Encapsulates a memory allocation and deallocation strategy.

Every standard library component that may need to allocate or release storage, from std::string, std::vector, and every container except std::array, to std::shared_ptr and std::function, does so through an Allocator: an object of a class type that satisfies the following requirements.

Some requirements are optional: the template std::allocator_traits supplies the default implementations for all optional requirements, and all standard library containers and other allocator-aware classes access the allocator through std::allocator_traits, not directly.

Requirements

Given

• A, an Allocator for type T
• B, the same Allocator for type U
• ptr, a value of type allocator_traits<A>::pointer, obtained by calling allocator_traits<A>::allocate()
• cptr, a value of type allocator_traits<A>::const_pointer, obtained by conversion from ptr
• vptr, a value of type allocator_traits<A>::void_pointer, obtained by conversion from ptr
• cvptr, a value of type allocator_traits<A>::const_void_pointer, obtained by conversion from cptr or from vptr
• xptr, a dereferencable pointer to some type X

Expression	Requirements	Return type
A::pointer (optional)	Satisfies NullablePointer and RandomAccessIterator
A::const_pointer (optional)	A::pointer is convertible to A::const_pointer. Satisfies NullablePointer and RandomAccessIterator
A::void_pointer (optional)	A::pointer is convertible to A::void_pointer B::void_pointer and A::void_pointer are the same type. Satisfies NullablePointer
A::const_void_pointer (optional)	A::pointer, A::const_pointer, and A::void_pointer are convertible to A::const_void_pointer B::const_void_pointer and A::const_void_pointer are the same type. Satisfies NullablePointer
A::value_type		the type T
A::size_type (optional)	A::size_type can represent the size of the largest object A can allocate	unsigned integer type
A::difference_type (optional)	A::difference_type can represent the difference of any two pointers to the objects allocated by A	signed integer type
A::template rebind<U>::other (optional[1])	for any U, B::template rebind<T>::other is A	the type B
*ptr		T&
*cptr	*cptr and *ptr identify the same object	const T&
ptr->m	same as (*ptr).m, if (*ptr).m is well-defined	the type of T::m
cptr->m	same as (*cptr).m, if (*cptr).m is well-defined	the type of T::m
static_cast<A::pointer>(vptr)	static_cast<A::pointer>(vptr) == ptr	A::pointer
static_cast<A::const_pointer>(cvptr)	static_cast<A::const_pointer>(vptr) == cptr	A::const_pointer
a.allocate(n)	allocates storage suitable for n objects of type T, but does not construct them. May throw exceptions.	A::pointer
a.allocate(n, cptr) (optional)	same as a.allocate(n), but may use cptr in unspecified manner to aid locality	A::pointer
a.deallocate(ptr, n)	deallocates storage previously allocated by a call to a.allocate(n). Does not call destructors, if any objects were constructed, they must be destroyed before calling a.deallocate(). Does not throw exceptions.	(not used)
a.max_size() (optional)	the largest value that can be passed to A::allocate()	A::size_type
a1 == a2	returns true only if the storage allocated by the allocator a1 can be deallocated through a2. Establishes reflexive, symmetric, and transitive relationship. Does not throw exceptions.	bool
a1 != a2	same as !(a1==a2)	bool
A a1(a)	Copy-constructs a1 such that a1 == a. Does not throw exceptions.
A a(b)	Constructs a such that B(a)==b and A(b)==a. Does not throw exceptions.
A a1(std::move(a))	Constructs a1 such that it equals the prior value of a. Does not throw exceptions.
A a(std::move(b))	Constructs a such that it equals the prior value of A(b). Does not throw exceptions.
a.construct(xptr, args) (optional)	Constructs an object of type X in previously-allocated storage at the address pointed to by xptr, using args as the constructor arguments
a.destroy(xptr) (optional)	Destructs an object of type X pointed to by xptr, but does not deallocate any storage.
a.select_on_container_copy_construction() (optional)	Provides an instance of A to be used by the container that is copy-constructed from the one that uses a currently. Usually returns either a copy of a or a default-constructed A().	A
a.propagate_on_container_copy_assignment (optional)	true if the allocator of type A needs to be copied when the container that uses it is copy-assigned	std::true_type or std::false_type or derived from such
a.propagate_on_container_move_assignment (optional)	true if the allocator of type A needs to be copied when the container that uses it is move-assigned	std::true_type or std::false_type or derived from such
a.propagate_on_container_swap (optional)	true if the allocators of type A need to be swapped when two containers that use them are swapped	std::true_type or std::false_type or derived from such

Notes: [1] rebind is only optional (provided by std::allocator_traits) if this allocator is a template of the form SomeAllocator<T, Args>, where Args is zero or more additional template parameters.