std::allocator<T>:: allocate_at_least

Alloue count * sizeof ( T ) octets de stockage non initialisé, où count est une valeur entière non spécifiée non inférieure à n , en appelant :: operator new (éventuellement avec un argument supplémentaire std::align_val_t ), mais il n'est pas spécifié quand et comment cette fonction est appelée.

Ensuite, cette fonction crée un tableau de type T [ count ] dans le stockage et commence sa durée de vie, mais ne commence pas la durée de vie d'aucun de ses éléments.

Pour utiliser cette fonction dans une expression constante, le stockage alloué doit être désalloué lors de l'évaluation de la même expression.

L'utilisation de cette fonction est mal formée si T est un type incomplet .

Paramètres

Valeur de retour

std:: allocation_result < T * > { p, count } , où p pointe vers le premier élément d'un tableau de count objets de type T dont les éléments n'ont pas encore été construits.

Exceptions

Lance std::bad_array_new_length si std:: numeric_limits < std:: size_t > :: max ( ) / sizeof ( T ) < n , ou std::bad_alloc si l'allocation échoue.

Notes

allocate_at_least est principalement fourni pour les conteneurs contigus, par exemple std::vector et std::basic_string , afin de réduire les réallocations en faisant correspondre leur capacité à la taille réellement allouée lorsque cela est possible.

La formulation « non spécifiée quand et comment » permet de combiner ou optimiser les allocations de tas effectuées par les conteneurs de la bibliothèque standard, même si de telles optimisations sont interdites pour les appels directs à :: operator new . Par exemple, cela est implémenté par libc++ ( [1] et [2] ).

Après l'appel de allocate_at_least et avant la construction des éléments, l'arithmétique des pointeurs de T * est bien définie au sein du tableau alloué, mais le comportement est indéfini si les éléments sont accédés.

Exemple

#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

Voir aussi