new expression

Crée et initialise des objets avec une durée de stockage dynamique, c'est-à-dire des objets dont la durée de vie n'est pas nécessairement limitée par la portée dans laquelle ils ont été créés.

Syntaxe

Explication

L'expression new tente d'allouer de la mémoire puis essaie de construire et d'initialiser soit un objet unique anonyme, soit un tableau anonyme d'objets dans la mémoire allouée. L'expression new retourne un pointeur prvalue vers l'objet construit ou, si un tableau d'objets a été construit, un pointeur vers l'élément initial du tableau.

Syntaxe (1) ou (3) est requise si type inclut des parenthèses :

new int(*[10])();    // erreur : interprété comme (new int) (*[10]) ()
new (int (*[10])()); // correct : alloue un tableau de 10 pointeurs vers des fonctions

De plus, type est analysé de manière gourmande : il sera pris en incluant chaque jeton qui peut faire partie d'un déclarateur :

new int + 1; // correct : analysé comme (new int) + 1, incrémente un pointeur retourné par new int
new int * 1; // erreur : analysé comme (new int*) (1)

Le new-initializer n'est pas facultatif si

• type est un tableau de taille inconnue ,

double* p = new double[]{1, 2, 3}; // crée un tableau de type double[3]
auto p = new auto('c');            // crée un objet unique de type char. p est un char*
auto q = new std::integral auto(1);         // OK : q est un int*
auto q = new std::floating_point auto(true) // ERREUR : contrainte de type non satisfaite
auto r = new std::pair(1, true); // OK : r est un std::pair<int, bool>*
auto r = new std::vector;        // ERREUR : le type d'élément ne peut pas être déduit

Tableaux dynamiques

Si type est un type tableau, toutes les dimensions autres que la première doivent être spécifiées comme des expressions constantes entières (jusqu'en C++14) expressions constantes converties de type std::size_t (depuis C++14) positives, mais (uniquement lors de l'utilisation des syntaxes sans parenthèses (2) et (4) ) la première dimension peut être une expression de type entier, de type énumération, ou de type classe avec une unique fonction de conversion non explicite vers un type entier ou énumération (jusqu'en C++14) toute expression convertible en std::size_t (depuis C++14) . C'est la seule façon de créer directement un tableau avec une taille définie à l'exécution, ces tableaux sont souvent appelés tableaux dynamiques :

int n = 42;
double a[n][5]; // erreur
auto p1 = new  double[n][5];  // OK
auto p2 = new  double[5][n];  // erreur : seule la première dimension peut être non constante
auto p3 = new (double[n][5]); // erreur : la syntaxe (1) ne peut pas être utilisée pour les tableaux dynamiques

La première dimension de zéro est acceptable, et la fonction d'allocation est appelée.

Allocation

L'expression new alloue de la mémoire en appelant la fonction d'allocation appropriée. Si type est un type non-tableau, le nom de la fonction est operator new . Si type est un type tableau, le nom de la fonction est operator new [ ] .

Comme décrit dans la fonction d'allocation , le programme C++ peut fournir des remplacements globaux et spécifiques à la classe pour ces fonctions. Si l'expression new commence avec l'opérateur optionnel :: , comme dans :: new T ou :: new T [ n ] , les remplacements spécifiques à la classe seront ignorés (la fonction est recherchée dans la portée globale). Sinon, si T est un type classe, la recherche commence dans la portée de classe de T .

Lors de l'appel de la fonction d'allocation, l'expression new transmet le nombre d'octets demandé comme premier argument, de type std::size_t , qui correspond exactement à sizeof ( T ) pour un type T non-tableau.

L'allocation de tableau peut fournir une surcharge non spécifiée, qui peut varier d'un appel à new au suivant, sauf si la fonction d'allocation sélectionnée est la forme standard non-allouante. Le pointeur retourné par l'expression new sera décalé de cette valeur par rapport au pointeur retourné par la fonction d'allocation. De nombreuses implémentations utilisent la surcharge de tableau pour stocker le nombre d'objets dans le tableau, qui est utilisé par l'expression delete [ ] pour appeler le nombre correct de destructeurs. De plus, si l'expression new est utilisée pour allouer un tableau de char , unsigned char , ou std::byte (depuis C++17) , elle peut demander de la mémoire supplémentaire à la fonction d'allocation si nécessaire pour garantir un alignement correct des objets de tous les types dont la taille n'excède pas celle du tableau demandé, si un tel objet est ultérieurement placé dans le tableau alloué.

Placement new

Si des placement-args sont fournis, ils sont passés à la fonction d'allocation comme arguments supplémentaires. De telles fonctions d'allocation sont appelées « placement new », d'après la fonction d'allocation standard void * operator new ( std:: size_t , void * ) , qui retourne simplement son second argument inchangé. Ceci est utilisé pour construire des objets dans un stockage alloué :

// dans n'importe quel bloc de portée...
{
    // Allouer statiquement le stockage avec une durée de stockage automatique
    // qui est suffisamment grand pour n'importe quel objet de type « T ».
    alignas(T) unsigned char buf[sizeof(T)];
    T* tptr = new(buf) T; // Construire un objet « T », en le plaçant directement dans votre
                          // stockage pré-alloué à l'adresse mémoire « buf ».
    tptr->~T();           // Vous devez appeler **manuellement** le destructeur de l'objet
                          // si ses effets secondaires sont nécessaires au programme.
}                         // Quitter ce bloc de portée désalloue automatiquement « buf ».

Note : cette fonctionnalité est encapsulée par les fonctions membres des Allocator classes.

new T;      // appelle operator new(sizeof(T))
            // (C++17) ou operator new(sizeof(T), std::align_val_t(alignof(T))))
new T[5];   // appelle operator new[](sizeof(T)*5 + overhead)
            // (C++17) ou operator new(sizeof(T)*5+overhead, std::align_val_t(alignof(T))))
new(2,f) T; // appelle operator new(sizeof(T), 2, f)
            // (C++17) ou operator new(sizeof(T), std::align_val_t(alignof(T)), 2, f)

Si une fonction d'allocation non levante (par exemple, celle sélectionnée par new ( std:: nothrow ) T ) renvoie un pointeur nul en raison d'un échec d'allocation, alors l'expression new retourne immédiatement, elle ne tente pas d'initialiser un objet ou d'appeler une fonction de désallocation. Si un pointeur nul est passé comme argument à une expression de placement non allouante new , ce qui amène la fonction d'allocation de placement standard non allouante sélectionnée à renvoyer un pointeur nul, le comportement est indéfini.

Initialisation

L'objet créé par une expression new est initialisé selon les règles suivantes.

Si type n'est pas un type tableau, l'objet unique est construit dans la zone mémoire acquise :

• Si new-initializer est absent, l'objet est default-initialized .
• Si new-initializer est une liste d'expressions entre parenthèses, l'objet est direct-initialized .

Si type est un type tableau, un tableau d'objets est initialisé :

• Si new-initializer est absent, chaque élément est default-initialized .

• Même si la première dimension est zéro, les contraintes sémantiques de l'initialisation par défaut d'un élément hypothétique doivent toujours être satisfaites.

• Si new-initializer est une paire de parenthèses, chaque élément est value-initialized .

• Même si la première dimension est zéro, les contraintes sémantiques de l'initialisation à la valeur d'un élément hypothétique doivent toujours être satisfaites.

Échec d'initialisation

Si l'initialisation se termine en lançant une exception (par exemple depuis le constructeur), le programme recherche une fonction de désallocation correspondante, puis :

• Si une fonction de désallocation appropriée peut être trouvée, la fonction de désallocation est appelée pour libérer la mémoire dans laquelle l'objet était en cours de construction. Après cela, l'exception continue de se propager dans le contexte de l'expression new .
• Si aucune fonction de désallocation correspondante non ambiguë ne peut être trouvée, la propagation de l'exception n'entraîne pas la libération de la mémoire de l'objet. Cela n'est approprié que si la fonction d'allocation appelée n'alloue pas de mémoire, sinon cela risque de provoquer une fuite de mémoire.

La portée de la recherche de la fonction de désallocation correspondante est déterminée comme suit :

• Si l'expression new ne commence pas par :: , et que le type alloué est soit un type classe T soit un tableau de type classe T , une recherche du nom de la fonction de désallocation est effectuée dans la portée de classe de T .
• Sinon, ou si rien n'est trouvé dans la portée de classe de T , le nom de la fonction de désallocation est recherché en le cherchant dans la portée globale .

Pour une fonction d'allocation non-placement, la recherche normale de fonction de désallocation est utilisée pour trouver la fonction de désallocation correspondante (voir delete-expression ).

Pour une fonction d'allocation de placement, la fonction de désallocation correspondante doit avoir le même nombre de paramètres, et chaque type de paramètre à l'exception du premier est identique au type de paramètre correspondant de la fonction d'allocation (après transformations de paramètres ).

• Si la recherche trouve une seule fonction de désallocation correspondante, cette fonction sera appelée ; sinon, aucune fonction de désallocation ne sera appelée.
• Si la recherche trouve une fonction de désallocation non-placement et que cette fonction, considérée comme une fonction de désallocation placement, aurait été sélectionnée comme correspondance pour la fonction d'allocation, le programme est mal formé.

Dans tous les cas, la fonction de désallocation correspondante (si elle existe) doit être non supprimée et (depuis C++11) accessible depuis le point où l'expression new apparaît.

struct S
{
    // Fonction d'allocation avec placement :
    static void* operator new(std::size_t, std::size_t);
    // Fonction de désallocation sans placement :
    static void operator delete(void*, std::size_t);
};
S* p = new (0) S; // erreur : la fonction de désallocation sans placement correspond
                  //        à la fonction d'allocation avec placement

Si une fonction de désallocation est appelée dans une new expression (en raison d'un échec d'initialisation), les arguments passés à cette fonction sont déterminés comme suit :

• Le premier argument est la valeur (de type void * ) retournée par l'appel de la fonction d'allocation.
• Les autres arguments (uniquement pour les fonctions de désallocation de placement) sont les placement-args passés à la fonction d'allocation de placement.

Si l'implémentation est autorisée à introduire un objet temporaire ou à effectuer une copie de tout argument dans le cadre de l'appel à la fonction d'allocation, il n'est pas spécifié si le même objet est utilisé dans l'appel à la fois aux fonctions d'allocation et de désallocation.

Fuites de mémoire

Les objets créés par les expressions new (objets avec durée de stockage dynamique) persistent jusqu'à ce que le pointeur retourné par l'expression new soit utilisé dans une expression delete correspondante. Si la valeur originale du pointeur est perdue, l'objet devient inaccessible et ne peut être désalloué : une fuite de mémoire se produit.

Cela peut se produire si le pointeur est assigné à :

int* p = new int(7); // int alloué dynamiquement avec la valeur 7
p = nullptr; // fuite de mémoire

ou si le pointeur sort de la portée :

void f()
{
    int* p = new int(7);
} // fuite de mémoire

ou en raison d'une exception :

void f()
{
    int* p = new int(7);
    g();      // peut lever une exception
    delete p; // correct si aucune exception
} // fuite mémoire si g() lève une exception

Pour simplifier la gestion des objets alloués dynamiquement, le résultat d'une expression new est souvent stocké dans un pointeur intelligent : std::auto_ptr (jusqu'à C++17) std::unique_ptr , ou std::shared_ptr (depuis C++11) . Ces pointeurs garantissent que l'expression delete est exécutée dans les situations décrites ci-dessus.

Notes

Itanium C++ ABI exige que la surcharge d'allocation de tableau soit nulle si le type d'élément du tableau créé est trivialement destructible. MSVC fait de même.

Certaines implémentations (par exemple MSVC avant VS 2019 v16.7) nécessitent une surcharge d'allocation de tableau non nulle pour le placement de tableau non-allouant new si le type d'élément n'est pas trivialement destructible, ce qui n'est plus conforme depuis CWG issue 2382 .

Une expression de placement de tableau new non-allouante qui crée un tableau de unsigned char , ou de std::byte (depuis C++17) peut être utilisée pour créer implicitement des objets dans une région de stockage donnée : elle met fin à la durée de vie des objets chevauchant le tableau, puis crée implicitement des objets de types à durée de vie implicite dans le tableau.

std::vector offre des fonctionnalités similaires pour les tableaux dynamiques unidimensionnels.

Mots-clés

new

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

Voir aussi

• constructeur
• copie élision
• constructeur par défaut
• delete
• destructeur
• initialisation
  • initialisation d'agrégat
  • initialisation par défaut
  • initialisation directe
  • initialisation de liste
  • initialisation de valeur