std::allocator_traits<Alloc>:: allocate_at_least

static constexpr std:: allocation_result < pointer, size_type > allocate_at_least ( Alloc & a, size_type n ) ;		(since C++23)

allocate_at_least calls a. allocate_at_least ( n ) and returns its result if the call is well-formed, otherwise, it is equivalent to return { a. allocate ( n ) , n } ; .

allocator_at_least tries to allocate a storage for at least n value_type objects, and provides a fallback mechanism that allocates a storage for exact n objects.

Parameters

a	-	an allocator used for allocating storage
n	-	the lower bound of number of objects to allocate storage for

Return value

a. allocate_at_least ( n ) if it is well-formed.

Otherwise, std:: allocation_result < pointer, size_type > { a. allocate ( n ) , n } .

Exceptions

Throws what and when the selected allocation function throws.

Notes

The allocate_at_least member function of Allocator types are mainly provided for contiguous containers, e.g. std::vector and std::basic_string , in order to reduce reallocation by making their capacity match the actually allocated size when possible. Because allocate_at_least provides a fallback mechanism, it can be directly used where appropriate.

Given an allocator object a of type Alloc , let result denote the value returned from std:: allocator_traits < Alloc > :: allocate_at_least ( a, n ) , the storage should be deallocated by a. deallocate ( result. ptr , m ) (typically called via std:: allocator_traits < Alloc > :: deallocate ( a, result. ptr , m ) ) in order to avoid memory leak.

The argument m used in deallocation must be not less than n and not greater than result. count , otherwise, the behavior is undefined. Note that n is always equal to result. count if the allocator does not provide allocate_at_least , which means that m is required to be equal to n .

Feature-test macro	Value	Std	Feature
__cpp_lib_allocate_at_least	202302L	(C++23)	allocate_at_least etc.

Example

This section is incomplete Reason: no example

See also

allocate_at_least (C++23)

allocates uninitialized storage at least as large as requested size (public member function of std::allocator<T> )