# std::allocator_traits<Alloc>::allocate_at_least

From cppreference.com
< cpp‎ | memory‎ | allocator traits

[[nodiscard]] 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 | Comment
--- | --- | --- | ---
`__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>`)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/memory/allocator_traits/allocate_at_least&oldid=156506"