std::allocator<T>::allocate_at_least

constexpr std::allocation_result<T*, std::size_t>
    allocate_at_least( std::size_t n );

Выделяет count * sizeof(T) байт неинициализированного хранилища, где count — неопределённое целое значение, не меньшее n, вызывая ::operator new (возможно, с дополнительным аргументом std::align_val_t), однако момент и способ вызова этой функции не определены.

Затем эта функция создаёт в хранилище массив типа T[count] и начинает его время жизни, но не начинает время жизни ни одного из его элементов.

Чтобы использовать эту функцию в константном выражении, выделенное хранилище должно быть освобождено в ходе вычисления того же выражения.

Использование этой функции некорректно, если T является неполным типом.

Параметры

Возвращаемое значение

std::allocation_result<T*>{p, count}, где p указывает на первый элемент массива из count объектов типа T, элементы которого ещё не были сконструированы.

Исключения

Выбрасывает std::bad_array_new_length, если std::numeric_limits<std::size_t>::max() / sizeof(T) < n, или std::bad_alloc, если выделение памяти завершается неудачей.

Примечания

allocate_at_least предназначена в основном для контейнеров с непрерывным хранением, например std::vector и std::basic_string, чтобы сократить количество перераспределений памяти, по возможности приводя их ёмкость в соответствие с фактически выделенным размером.

Формулировка «момент и способ не определены» позволяет объединять или устранять выделения памяти в куче, выполняемые контейнерами стандартной библиотеки, хотя такие оптимизации запрещены для прямых вызовов ::operator new. Например, это реализовано в libc++ ([1] и [2]).

После вызова allocate_at_least и до конструирования элементов арифметика указателей для T* корректно определена в пределах выделенного массива, но поведение не определено при обращении к элементам.

Пример

#include <memory>
#include <print>

int main()
{
    const std::size_t count{69};
    std::allocator<int> alloc;
    std::allocation_result res{alloc.allocate_at_least(count)};
    std::print("count: {}\n"
               "res.ptr: {}\n"
               "res.count: {}\n", count, res.ptr, res.count);

    /* construct, use, then destroy elements */

    alloc.deallocate(res.ptr, res.count);
}

count: 69
res.ptr: 0x555a486a0960
res.count: 96

См. также