# std::allocator_traits<Alloc>::allocate_at_least

> C++ Atlas: `cppatlas.com/w/cpp/memory/allocator_traits/allocate_at_least` | Source: https://en.cppreference.com/w/cpp/memory/allocator_traits/allocate_at_least | Domain: Memory management | Standards: 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};.

## Official Specification Summary (cppreference)

```cpp
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

> Note: This section is incomplete Reason: no example

### See also

- [`allocate_at_least`](https://en.cppreference.com/w/cpp/memory/allocator/allocate_at_least) (C++23): allocates uninitialized storage at least as large as requested size (public member function of `std::allocator<T>`)

---
Attribution: content from https://en.cppreference.com/w/cpp/memory/allocator_traits/allocate_at_least (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.