Namespaces
Variants
Views
Actions

std::allocate_at_least

From cppreference.com
< cpp‎ | memory
 
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++14)
(C++11)

(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)

Elementary string conversions
(C++17)
(C++17)

Stacktrace
 
Dynamic memory management
Smart pointers
(C++11)
(C++11)
(C++11)
(until C++17)
(C++11)
(C++23)
Allocators
allocate_at_least
(C++23)
Memory resources
Uninitialized storage
Uninitialized memory algorithms
Constrained uninitialized memory algorithms
Garbage collection support
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
Miscellaneous
(C++20)
(C++11)
(C++11)
 
Defined in header <memory>
template< class Alloc >

[[nodiscard]] constexpr std::allocation_result<
    typename std::allocator_traits<Alloc>::pointer>

    allocate_at_least( Alloc& a, std::size_t n );
(since C++23)

std::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};.

For an Allocator a, std::allocator_at_least tries to allocate a storage for at least n Alloc::value_type objects, and provides a fallback mechanism (like those provided by std::allocator_traits) that allocates a storage for exact n objects.

Contents

[edit] Parameters

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

[edit] Return value

a.allocate_at_least(n) if it is well-formed, otherwise, {a.allocate(n), n}.

[edit] Exceptions

Throws what and when the selected allocation function throws.

[edit] 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 std::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::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 support allocate_at_least, which means that m is required to be equal to n.

[edit] Example

[edit] See also

allocates uninitialized storage at least as large as requested size
(public member function of std::allocator<T>) [edit]
provides information about allocator types
(class template) [edit]