<new>Operadores e enumerações de

  • Artigo

enum align_val_t

enum class align_val_t : size_t {};

operator delete

A função que é chamada por uma expressão delete para alocar o armazenamento de objetos individuais.

void operator delete(void* ptr) noexcept;
void operator delete(void *, void*) noexcept;
void operator delete(void* ptr, const std::nothrow_t&) noexcept;

Parâmetros

ptr
O ponteiro cujo valor será renderizado como inválido pela exclusão.

Comentários

A primeira função é chamada por uma expressão delete para renderizar o valor de ptr inválido. O programa pode definir uma função com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++. O comportamento necessário é aceitar um valor de ptr que é nullptr ou que foi retornado por uma chamada anterior para operator new.

O comportamento padrão para um valor nullptr em ptr é não fazer nada. Qualquer outro valor de ptr deve ser um valor retornado anteriormente por uma chamada new descrita anteriormente. O comportamento padrão para um valor não nulo de ptr é recuperar o armazenamento alocado pela chamada anterior. Não é especificado em quais condições parte ou todo esse armazenamento recuperado será alocado por uma chamada subsequente para operator new, ou para qualquer uma das funções calloc, malloc ou realloc.

A segunda função será chamada por uma expressão delete de posicionamento correspondente a uma expressão new da forma new( std::size_t ). Ela não faz nada.

A terceira função será chamada por uma expressão delete de posicionamento correspondente a uma expressão new da forma new( std::size_t, const std::nothrow_t& ). O programa pode definir uma função com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++. O comportamento necessário é aceitar um valor de ptr que é nullptr ou que foi retornado por uma chamada anterior para operator new. O comportamento padrão é avaliar delete( ptr ).

Exemplo

Confira operator new para ver um exemplo que usa operator delete.

operator delete[]

A função que é chamada por uma expressão delete para desalocar o armazenamento para uma matriz de objetos.

void operator delete[](void* ptr) noexcept;
void operator delete[](void *, void*) noexcept;
void operator delete[](void* ptr, const std::nothrow_t&) noexcept;

Parâmetros

ptr
O ponteiro cujo valor será renderizado como inválido pela exclusão.

Comentários

A primeira função é chamada por uma expressão delete[] para renderizar o valor de ptr inválido. O programa pode ser substituído porque pode definir uma função com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++. O comportamento necessário é aceitar um valor de ptr que é nullptr ou que foi retornado por uma chamada anterior para operator new[]. O comportamento padrão para um valor nulo de ptr é fazer nada. Qualquer outro valor de ptr deve ser um valor retornado anteriormente por uma chamada descrita anteriormente. O comportamento padrão para um valor não nulo de ptr é recuperar o armazenamento alocado pela chamada anterior. Não é especificado em quais condições parte ou todo esse armazenamento recuperado será alocado por uma chamada subsequente para operator new, ou para qualquer uma das funções calloc, malloc ou realloc.

A segunda função será chamada por uma expressão delete[] de posicionamento correspondente a uma expressão new[] da forma new[]( std::size_t ). Ela não faz nada.

A terceira função será chamada por uma expressão delete[] de posicionamento correspondente a uma expressão new[] da forma new[]( std::size_t, const std::nothrow_t& ). O programa pode definir uma função com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++. O comportamento necessário é aceitar um valor de ptr que é nullptr ou que foi retornado por uma chamada anterior para o operador new[]. O comportamento padrão é avaliar delete[]( ptr ).

Exemplo

Confira operator new[] para ver exemplos do uso de operator delete[].

operator new

A função que é chamada por uma expressão new para alocar o armazenamento de objetos individuais.

void* operator new(std::size_t count);
void* operator new(std::size_t count, const std::nothrow_t&) noexcept;
void* operator new(std::size_t count, void* ptr) noexcept;

Parâmetros

count
O número de bytes de armazenamento a ser alocado.

ptr
O ponteiro a ser retornado.

Valor retornado

Um ponteiro para o endereço de byte mais baixo do armazenamento alocado recentemente. Ou ptr, se estiver usando a terceira forma da função.

Comentários

A primeira função é chamada por uma expressão new para alocar count bytes de armazenamento adequadamente alinhados para representar qualquer objeto desse tamanho. Essa função é substituível. Significa que o programa pode definir uma função alternativa com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++.

É o comportamento necessário para retornar um ponteiro não nulo apenas se o armazenamento puder ser alocado conforme solicitado. Cada alocação produz um ponteiro para o armazenamento separado de qualquer outro armazenamento alocado. A ordem e a proximidade de armazenamento alocado por chamadas sucessivas não estão especificadas. O valor armazenado inicial não é especificado. O ponteiro retornado aponta para o início (o endereço mais baixo de byte) do armazenamento alocado. Se count for zero, o valor retornado não será comparado de modo igual a qualquer outro valor retornado pela função.

O comportamento padrão é executar um loop. Dentro do loop, a função primeiro tenta alocar o armazenamento solicitado. Não é especificado se a tentativa envolve uma chamada para malloc. Se a tentativa de alocação for bem-sucedida, a função retornará um ponteiro para o armazenamento alocado. Caso contrário, a função chama a função designada do tipo new_handler. Se a função chamada retornar, o loop se repete. O loop é encerrado quando uma tentativa de alocar o armazenamento solicitado é bem-sucedida ou quando uma função chamada não retorna.

O comportamento necessário de uma função do tipo new_handler é realizar uma das seguintes operações:

  • Disponibilizar mais armazenamento para alocação e retornar.

  • Chame abort ou exit.

  • Lança um objeto do tipo bad_alloc.

O comportamento padrão de uma função new_handler é lançar um objeto do tipo bad_alloc. Um valor nullptr designa a função padrão new_handler.

A ordem e a proximidade de armazenamento alocadas por chamadas sucessivas para operator new não são especificadas, assim como os valores iniciais armazenados lá.

Para liberar o armazenamento alocado pela primeira forma de operator new, chame operator delete.

A segunda função é chamada por uma expressão de substituição new para alocar count bytes de armazenamento adequadamente alinhados para representar qualquer objeto desse tamanho. Essa função é substituível. Significa que o programa pode definir uma função alternativa com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++.

O comportamento padrão será retornar operator new( count ) se a função for bem-sucedida. Caso contrário, ele retornará nullptr.

Para liberar o armazenamento alocado pela segunda forma de operator new (ou seja, se não retornou nullptr), chame operator delete.

A terceira função é chamada por uma expressão new de posicionamento não alocadora da forma new ( ptr ) T. Aqui, ptr consiste em um ponteiro de objeto único. Ele pode ser útil para criar um objeto em um endereço conhecido. A função retorna ptr. Você deve chamar o destruidor explicitamente nesse objeto.

Se você chamar o posicionamento não alocador new, não chame delete. Em vez disso, chame o desalocador para a memória que você forneceu, se necessário, depois de chamar o destruidor para o objeto.

Para obter informações sobre o comportamento de lançamento ou não lançamento de new, confira Os operadores new e delete.

Exemplo

// new_op_new.cpp
// compile with: /EHsc
#include<new>
#include<iostream>

using namespace std;

class MyClass {
    int member{ 0 };
public:
    MyClass() {
        cout << "MyClass at 0x" << this << " constructed.\n";
    };

    ~MyClass() {
        cout << "MyClass at 0x" << this << " destroyed.\n";
    };
};

int main( )
{
    // The first form of new / delete
    MyClass* fPtr1 = new MyClass;
    delete fPtr1;

    // The second form (fail returns nullptr) of new / delete
    MyClass* fPtr2 = new(nothrow) MyClass[2];
    if (fPtr2)
        delete fPtr2;

    // The third form (non-allocating placement) of new / delete
    char x[sizeof(MyClass)]; // x is automatic
    MyClass* fPtr3 = new(&x[0]) MyClass;
    fPtr3->~MyClass(); // Requires explicit destructor call
    // no delete because x is on the stack
}

operator new[]

A função de alocação que é chamada por uma expressão new para alocar o armazenamento para uma matriz de objetos.

void* operator new[](std::size_t count);
void* operator new[](std::size_t count, const std::nothrow_t&) noexcept;
void* operator new[](std::size_t count, void* ptr) noexcept;

Parâmetros

count
O número de bytes de armazenamento a ser alocado para o objeto de matriz.

ptr
O ponteiro a ser retornado.

Valor retornado

Um ponteiro para o endereço de byte mais baixo do armazenamento alocado recentemente. Ou ptr, quando a terceira forma for usada.

Comentários

A primeira função é chamada por uma expressão new[] para alocar count bytes de armazenamento adequadamente alinhados para representar qualquer objeto de matriz desse tamanho ou menor. O programa pode definir uma função com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++. O comportamento necessário é o mesmo usado para operator new. O comportamento padrão é retornar operator new( count ) se houver êxito. Caso contrário, ele gera uma exceção std::bad_alloc (ou uma exceção derivada de std::bad_alloc). Para liberar o armazenamento alocado por essa forma de operator new[], chame operator delete[].

A segunda função é chamada por uma expressão new[] de substituição para alocar count bytes de armazenamento adequadamente alinhados para representar qualquer objeto de matriz desse tamanho. O programa pode definir uma função com essa assinatura de função que substitui a versão padrão definida pela biblioteca padrão C++. O comportamento padrão será retornar operator new( count ) se a função for bem-sucedida. Caso contrário, ele retornará nullptr. Para liberar o armazenamento alocado por essa forma de operator new[], chame operator delete[]. Para obter mais informações sobre o comportamento de lançamento ou não lançamento de new, confira Os operadores new e delete.

A terceira função é chamada por uma expressão new[] de posicionamento não alocadora da forma new( ptr ) T[ N ]. Essa forma não aloca memória. Ele constrói os objetos na memória passada por meio do parâmetro ptr. A função retorna ptr. Você deve chamar o destruidor explicitamente para cada objeto criado. Você é responsável por fornecer memória suficiente para ptr. Não invoque delete[] no valor retornado pela expressão new. Em vez disso, desaloque ptr, se necessário, depois de chamar os destruidores.

Exemplo

// new_op_array.cpp
// compile with: /EHsc
#include <new>
#include <iostream>

using namespace std;

class MyClass {
    int member{ 0 };
public:
    MyClass() {
        cout << "MyClass at 0x" << this << " constructed.\n";
    };

    ~MyClass() {
        cout << "MyClass at 0x" << this << " destroyed.\n";
    };
};

int main() {
    // The first form of array new / delete
    MyClass* fPtr1 = new MyClass[2];
    delete[] fPtr1;

    // The second form (fail returns nullptr) of array new / delete
    MyClass* fPtr2 = new(nothrow) MyClass[2];
    if (fPtr2)
        delete[] fPtr2;

    // The third form (non-allocating placement) of array new / delete
    char x[2 * sizeof(MyClass) + sizeof(int)]; // x is automatic

    MyClass* fPtr3 = new(&x[0]) MyClass[2];
    fPtr3[1].~MyClass(); // Requires explicit destructor calls
    fPtr3[0].~MyClass(); // Recommended in reverse construction order
    // Don't delete[] fPtr3 here.
    // delete[] &x[0] not required because x is on the stack
}