Funções <memory>

addressof

Obtém o endereço verdadeiro de um objeto.

template <class T>
T* addressof(
    T& value) noexcept;    // before C++17

template <class T>
constexpr T* addressof(
    T& value) noexcept;    // C++17

template <class T>
const T* addressof(
    const T&& value) = delete;   // C++17

Parâmetros

value
O objeto ou a função para o qual obter o endereço verdadeiro.

Valor de retorno

O endereço real do objeto ou da função referenciado por value, mesmo se houver um operator&() sobrecarregado.

Comentários

align

Ajusta o armazenamento do tamanho fornecido (alinhado pela especificação de alinhamento fornecido) no primeiro endereço possível do armazenamento fornecido.

void* align(
    size_t alignment, // input
    size_t size,      // input
    void*& ptr,       // input/output
    size_t& space     // input/output
);

Parâmetros

alignment
O limite de alinhamento ser tentado.

size
O tamanho em bytes para o armazenamento alinhado.

ptr
O endereço inicial do pool de armazenamento contíguo disponível a ser usado. Esse parâmetro também será um parâmetro de saída e será definido para conter o novo endereço inicial se o alinhamento for bem-sucedido. Se align() for malsucedido, esse parâmetro não será modificado.

space
O espaço total disponível para align() a ser usado ao criar o armazenamento alinhado. Esse parâmetro também é um parâmetro de saída e contém o espaço ajustado deixado no buffer de armazenamento após o armazenamento alinhado e qualquer sobrecarga associada é subtraída.

Se align() for malsucedido, esse parâmetro não será modificado.

Valor de retorno

Um ponteiro ptr se o buffer alinhado solicitado não se ajustar no espaço disponível, do contrário, será o novo valor de NULL.

Comentários

Os parâmetros modificados ptr e space permitem que você chame align() repetidamente no mesmo buffer, possivelmente com valores diferentes para alignment e size. O snippet de código a seguir mostra um uso de align().

#include <type_traits> // std::alignment_of()
#include <memory>
//...
char buffer[256]; // for simplicity
size_t alignment = std::alignment_of<int>::value;
void * ptr = buffer;
std::size_t space = sizeof(buffer); // Be sure this results in the true size of your buffer

while (std::align(alignment, sizeof(MyObj), ptr, space)) {
    // You now have storage the size of MyObj, starting at ptr, aligned on
    // int boundary. Use it here if you like, or save off the starting address
    // contained in ptr for later use.
    // ...
    // Last, move starting pointer and decrease available space before
    // the while loop restarts.
    ptr = reinterpret_cast<char*>(ptr) + sizeof(MyObj);
    space -= sizeof(MyObj);
}
// At this point, align() has returned a null pointer, signaling it is not
// possible to allow more aligned storage in this buffer.

allocate_shared

Cria um shared_ptr para objetos alocados e construídos para um determinado tipo usando um alocador especificado. Retorna o shared_ptr.

template <class T, class Allocator, class... Args>
shared_ptr<T> allocate_shared(
    Allocator alloc,
    Args&&... args);

Parâmetros

alloc
O alocador usado para criar objetos.

args
O zero ou mais argumentos que se tornam os objetos.

Comentários

A função cria o objeto shared_ptr<T>, um ponteiro para T(args...) conforme alocado e construído por alloc.

atomic_compare_exchange_strong

template<class T>
bool atomic_compare_exchange_strong(
    shared_ptr<T>* u,
    shared_ptr<T>* v,
    shared_ptr<T> w);

atomic_compare_exchange_weak

template<class T>
bool atomic_compare_exchange_weak(
    shared_ptr<T>* u,
    shared_ptr<T>* v,
    shared_ptr<T> w);

atomic_compare_exchange_strong_explicit

template<class T>
bool atomic_compare_exchange_strong_explicit(
    shared_ptr<T>* u,
    shared_ptr<T>* v,
    shared_ptr<T> w,
    memory_order success,
    memory_order failure);

atomic_compare_exchange_weak_explicit

template<class T>
bool atomic_compare_exchange_weak_explicit(
    shared_ptr<T>* u,
    shared_ptr<T>* v,
    shared_ptr<T> w,
    memory_order success,
    memory_order failure);

atomic_exchange

template<class T>
shared_ptr<T> atomic_exchange(
    shared_ptr<T>* u,
    shared_ptr<T> r);

atomic_exchange_explicit

template<class T>
shared_ptr<T> atomic_exchange_explicit(
    shared_ptr<T>* u,
    shared_ptr<T> r,
    memory_order mo);

atomic_is_lock_free

template<class T>
bool atomic_is_lock_free(
    const shared_ptr<T>* u);

atomic_load

template<class T>
shared_ptr<T> atomic_load(
    const shared_ptr<T>* u);

atomic_load_explicit

template<class T>
shared_ptr<T> atomic_load_explicit(
    const shared_ptr<T>* u,
    memory_order mo);

atomic_store

template<class T>
void atomic_store(
    shared_ptr<T>* u,
    shared_ptr<T> r);

atomic_store_explicit

template<class T>
void atomic_store_explicit(
    shared_ptr<T>* u,
    shared_ptr<T> r,
    memory_order mo);

const_pointer_cast

Conversão constante para shared_ptr.

template <class T, class Other>
shared_ptr<T> const_pointer_cast(
    const shared_ptr<Other>& sp) noexcept;

template <class T, class Other>
shared_ptr<T> const_pointer_cast(
    shared_ptr<Other>&& sp) noexcept;

Parâmetros

T
O tipo controlado pelo ponteiro compartilhado retornado.

Other
O tipo controlado pelo ponteiro compartilhado de argumento.

sp
O ponteiro compartilhado de argumento.

Comentários

A função de modelo retornará um objeto shared_ptr vazio se const_cast<T*>(sp.get()) retornar um ponteiro nulo, do contrário, ele retornará um objeto shared_ptr<T> que possua o recurso de propriedade do sp. A expressão const_cast<T*>(sp.get()) deve ser válida.

Exemplo

// std__memory__const_pointer_cast.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp0(new int);
    std::shared_ptr<const int> sp1 =
        std::const_pointer_cast<const int>(sp0);

    *sp0 = 3;
    std::cout << "sp1 == " << *sp1 << std::endl;

    return (0);
}

sp1 == 3

declare_no_pointers

Informa um coletor de lixo que os caracteres no bloco de memória definido por um ponteiro de endereço básico e o tamanho de bloco não contêm ponteiros rastreáveis.

void declare_no_pointers(
    char* ptr,
    size_t size);

Parâmetros

ptr
O endereço do primeiro caractere que não contém mais ponteiros rastreáveis.

size
O tamanho de bloco que começa em ptr que não contém ponteiros rastreáveis.

Comentários

A função informa a qualquer coletor de lixo que os endereços no intervalo [ptr, ptr + size) não contêm mais ponteiros rastreáveis. (Quaisquer ponteiros para armazenamento alocado não devem ser desreferenciados, a menos que sejam acessíveis.)

declare_reachable

Informa a coleta de lixo que o endereço indicado é para armazenamento alocado e é alcançável.

void declare_reachable(
    void* ptr);

Parâmetros

ptr
Um ponteiro para uma área de armazenamento acessível, alocada e válida.

Comentários

Se ptr não for nulo, a função informará a qualquer coletor de lixo que ptr estará acessível daqui em diante, ou seja, apontará para um armazenamento alocado válido.

default_delete

Exclui objetos alocados com operator new. Adequado para uso com unique_ptr.

struct default_delete
{
    constexpr default_delete() noexcept = default;

    template <class Other, class = typename enable_if<is_convertible<Other*, T*>::value, void>::type>>
    default_delete(const default_delete<Other>&) noexcept;

    void operator()(T* ptr) const noexcept;
};

Parâmetros

ptr
Ponteiro para o objeto a ser excluído.

Other
O tipo dos elementos na matriz a ser excluída.

Comentários

O modelo de classe descreve um apagador que exclui objetos escalares alocados com operator new, adequado para uso com modelo de classe unique_ptr. Ela também tem a especialização explícita default_delete<T[]>.

destroy_at

template <class T>
void destroy_at(
    T* location);

Mesmo que location->~T().

destroy

template <class ForwardIterator>
void destroy(
    ForwardIterator first,
    ForwardIterator last);

Mesmo que:

for (; first != last; ++first)
    destroy_at(addressof(*first));

destroy_n

template <class ForwardIterator, class Size>
ForwardIterator destroy_n(
    ForwardIterator first,
    Size count);

Mesmo que:

for (; count > 0; (void)++first, --count)
    destroy_at(addressof(*first));
return first;

dynamic_pointer_cast

Conversão dinâmica para shared_ptr.

template <class T, class Other>
shared_ptr<T> dynamic_pointer_cast(
    const shared_ptr<Other>& sp) noexcept;

template <class T, class Other>
shared_ptr<T> dynamic_pointer_cast(
    shared_ptr<Other>&& sp) noexcept;

Parâmetros

T
O tipo controlado pelo ponteiro compartilhado retornado.

Other
O tipo controlado pelo ponteiro compartilhado de argumento.

sp
O ponteiro compartilhado de argumento.

Comentários

A função de modelo retornará um objeto shared_ptr vazio se dynamic_cast<T*>(sp.get()) retornar um ponteiro nulo, do contrário, ele retornará um objeto shared_ptr<T> que possua o recurso de propriedade do sp. A expressão dynamic_cast<T*>(sp.get()) deve ser válida.

Exemplo

// std__memory__dynamic_pointer_cast.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

struct base
{
    virtual ~base() {}
    int value;
};

struct derived
    : public base
{
};

int main()
{
    std::shared_ptr<base> sp0(new derived);
    std::shared_ptr<derived> sp1 =
        std::dynamic_pointer_cast<derived>(sp0);

    sp0->value = 3;
    std::cout << "sp1->value == " << sp1->value << std::endl;

    return (0);
}

sp1->value == 3

get_deleter

Obtenha o agente de exclusão de um shared_ptr.

template <class Deleter, class T>
Deleter* get_deleter(
    const shared_ptr<T>& sp) noexcept;

Parâmetros

Deleter
O tipo do agente de exclusão.

T
O tipo controlado pelo ponteiro compartilhado.

sp
O ponteiro compartilhado.

Comentários

A função de modelo retorna um ponteiro para agente de exclusão do tipo Deleter que pertence ao sp do objeto de shared_ptr. Se sp não tiver nenhum agente de exclusão ou se o agente de exclusão não for do tipo Deleter, a função retornará 0.

Exemplo

// std__memory__get_deleter.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

struct base
{
    int value;
};

struct deleter
{
    void operator()(base *pb)
    {
        delete pb;
    }
};

int main()
{
    std::shared_ptr<base> sp0(new base);

    sp0->value = 3;
    std::cout << "get_deleter(sp0) != 0 == " << std::boolalpha
        << (std::get_deleter<deleter>(sp0) != 0) << std::endl;

    std::shared_ptr<base> sp1(new base, deleter());

    sp0->value = 3;
    std::cout << "get_deleter(sp1) != 0 == " << std::boolalpha
        << (std::get_deleter<deleter>(sp1) != 0) << std::endl;

    return (0);
}

get_deleter(sp0) != 0 == false
get_deleter(sp1) != 0 == true

get_pointer_safety

Retorna o tipo de segurança do ponteiro pressuposto por qualquer coletor de lixo.

pointer_safety get_pointer_safety() noexcept;

Comentários

A função retorna o tipo de segurança do ponteiro pressuposto por qualquer coletor de lixo automático.

get_temporary_buffer

Atribui o armazenamento temporário para uma sequência de elementos que não excede um número especificado de elementos.

template <class T>
pair<T *, ptrdiff_t> get_temporary_buffer(
    ptrdiff_t count);

Parâmetros

count
O número máximo de elementos solicitados para o qual a memória deve ser alocada.

Valor de retorno

Um pair cujo primeiro componente é um ponteiro para a memória que foi alocada e cujo segundo componente retorna o tamanho do buffer, indicando o maior número de elementos que ele pode armazenar.

Comentários

A função faz uma solicitação de memória e ela pode não ser bem-sucedida. Se nenhum é for alocado, a função retornará um par, com o segundo componente igual a zero e o primeiro componente igual ao ponteiro nulo.

Use essa função apenas para memória temporária.

Exemplo

// memory_get_temp_buf.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

using namespace std;

int main( )
{
    // Create an array of ints
    int intArray [] = { 10, 20, 30, 40, 100, 200, 300, 1000, 2000 };
    int count = sizeof ( intArray ) / sizeof ( int );
    cout << "The number of integers in the array is: "
        << count << "." << endl;

    pair<int *, ptrdiff_t> resultPair;
    resultPair = get_temporary_buffer<int>( count );

    cout << "The number of elements that the allocated memory\n"
        << "could store is given by: resultPair.second = "
        << resultPair.second << "." << endl;
}

The number of integers in the array is: 9.
The number of elements that the allocated memory
could store is given by: resultPair.second = 9.

make_shared

Cria e retorna um shared_ptr que aponta para os objetos alocados construídos de zero ou mais argumentos usando o alocador padrão. Aloca e constrói um objeto do tipo especificado e um shared_ptr para gerenciar a propriedade compartilhada do objeto e retorna o shared_ptr.

template <class T, class... Args>
shared_ptr<T> make_shared(
    Args&&... args);

Parâmetros

args
Zero ou mais argumentos de construtor. A função infere qual sobrecarga de construtor deve ser invocada com base nos argumentos fornecidos.

Comentários

Use make_shared como uma forma simples e mais eficiente de criar um objeto e um shared_ptr para gerenciar o acesso compartilhado para o objeto ao mesmo tempo. Semanticamente, essas duas instruções são equivalentes:

auto sp = std::shared_ptr<Example>(new Example(argument));
auto msp = std::make_shared<Example>(argument);

No entanto, a primeira instrução faz duas alocações e se a alocação do shared_ptr falhar após a alocação do objeto Example ter sido bem sucedida, o objeto Example sem nome será vazado. A instrução que usa make_shared é mais simples porque há apenas uma chamada de função envolvida. Ela é mais eficiente porque a biblioteca pode fazer uma única alocação do objeto e do ponteiro inteligente. Essa função é mais rápida e resulta em menos fragmentação de memória, e exclui a chance de uma exceção em uma alocação, e não na outra. O desempenho é melhorado pela melhor localidade para o código que faz referência ao objeto e atualiza as contagens de referência no ponteiro inteligente.

Considere o uso de make_unique se não precisar de acesso compartilhado ao objeto. Use allocate_shared se você precisar especificar um alocador personalizado para o objeto. Não será possível usar make_shared se o objeto exigir um agente de exclusão personalizado, pois não há como passar o agente de exclusão como um argumento.

O exemplo a seguir mostra como criar ponteiros compartilhados para um tipo invocando as sobrecargas do construtor específicas.

Exemplo

// stl_make_shared.cpp
// Compile by using: cl /W4 /EHsc stl_make_shared.cpp
#include <iostream>
#include <string>
#include <memory>
#include <vector>

class Song {
public:
    std::wstring title_;
    std::wstring artist_;

    Song(std::wstring title, std::wstring artist) : title_(title), artist_(artist) {}
    Song(std::wstring title) : title_(title), artist_(L"Unknown") {}
};

void CreateSharedPointers()
{
    // Okay, but less efficient to have separate allocations for
    // Song object and shared_ptr control block.
    auto song = new Song(L"Ode to Joy", L"Beethoven");
    std::shared_ptr<Song> sp0(song);

    // Use make_shared function when possible. Memory for control block
    // and Song object are allocated in the same call:
    auto sp1 = std::make_shared<Song>(L"Yesterday", L"The Beatles");
    auto sp2 = std::make_shared<Song>(L"Blackbird", L"The Beatles");

    // make_shared infers which constructor to use based on the arguments.
    auto sp3 = std::make_shared<Song>(L"Greensleeves");

    // The playlist vector makes copies of the shared_ptr pointers.
    std::vector<std::shared_ptr<Song>> playlist;
    playlist.push_back(sp0);
    playlist.push_back(sp1);
    playlist.push_back(sp2);
    playlist.push_back(sp3);
    playlist.push_back(sp1);
    playlist.push_back(sp2);
    for (auto&& sp : playlist)
    {
        std::wcout << L"Playing " << sp->title_ <<
            L" by " << sp->artist_ << L", use count: " <<
            sp.use_count() << std::endl;
    }
}

int main()
{
    CreateSharedPointers();
}

O exemplo produz essa saída:

Playing Ode to Joy by Beethoven, use count: 2
Playing Yesterday by The Beatles, use count: 3
Playing Blackbird by The Beatles, use count: 3
Playing Greensleeves by Unknown, use count: 2
Playing Yesterday by The Beatles, use count: 3
Playing Blackbird by The Beatles, use count: 3

make_unique

Cria e retorna um unique_ptr para um objeto do tipo especificado, que é construído usando os argumentos especificados.

// make_unique<T>
template <class T, class... Args>
unique_ptr<T> make_unique(Args&&... args);

// make_unique<T[]>
template <class T>
unique_ptr<T> make_unique(size_t size);

// make_unique<T[N]> disallowed
template <class T, class... Args>
/* unspecified */ make_unique(Args&&...) = delete;

Parâmetros

T
O tipo do objeto para o qual o unique_ptr apontará.

Args
Os tipos dos argumentos do construtor especificados por args.

args
Os argumentos a serem passados para o construtor do objeto do tipo T.

elements
Uma matriz de elementos do tipo T.

size
O número de elementos para os quais alocar espaço na nova matriz.

Comentários

A primeira sobrecarga é usada para objetos únicos. A segunda sobrecarga é invocada para matrizes. A terceira sobrecarga impede que você especifique um tamanho de matriz no argumento de tipo (make_unique<T[N]>); essa construção não tem suporte do padrão atual. Quando você usa make_unique para criar um unique_ptr para uma matriz, é necessário inicializar os elementos da matriz separadamente. Em vez de usar essa sobrecarga, talvez uma escolha melhor seja usar um std::vector.

Como make_unique é cuidadosamente implementado para a segurança de exceção, é recomendável usar make_unique em vez de chamar diretamente os construtores unique_ptr.

Exemplo

O exemplo a seguir mostra como usar make_unique. Para mais exemplos, consulte Como criar e usar instâncias unique_ptr.

class Animal
{
private:
    std::wstring genus;
    std::wstring species;
    int age;
    double weight;
public:
    Animal(const wstring&, const wstring&, int, double){/*...*/ }
    Animal(){}
};

void MakeAnimals()
{
    // Use the Animal default constructor.
    unique_ptr<Animal> p1 = make_unique<Animal>();

    // Use the constructor that matches these arguments
    auto p2 = make_unique<Animal>(L"Felis", L"Catus", 12, 16.5);

    // Create a unique_ptr to an array of 5 Animals
    unique_ptr<Animal[]> p3 = make_unique<Animal[]>(5);

    // Initialize the elements
    p3[0] = Animal(L"Rattus", L"norvegicus", 3, 2.1);
    p3[1] = Animal(L"Corynorhinus", L"townsendii", 4, 1.08);

    // auto p4 = p2; //C2280

    vector<unique_ptr<Animal>> vec;
    // vec.push_back(p2); //C2280
    // vector<unique_ptr<Animal>> vec2 = vec; // C2280

    // OK. p2 no longer points to anything
    vec.push_back(std::move(p2)); 

    // unique_ptr overloads operator bool
    wcout << boolalpha << (p2 == false) << endl; // Prints "true"

    // OK but now you have two pointers to the same memory location
    Animal* pAnimal = p2.get();

    // OK. p2 no longer points to anything
    Animal* p5 = p2.release();
}

Quando você vir o erro C2280 em conexão com um unique_ptr, provavelmente é porque você está tentando invocar o construtor de cópia, o que é uma função excluída.

owner_less

Permite comparações mistas baseadas em propriedade de ponteiros compartilhados e fracos. Retornará true se o parâmetro esquerdo for ordenado antes do parâmetro direito pela função membro owner_before.

template <class T>
    struct owner_less; // not defined

template <class T>
struct owner_less<shared_ptr<T>>
{
    bool operator()(
        const shared_ptr<T>& left,
        const shared_ptr<T>& right) const noexcept;

    bool operator()(
        const shared_ptr<T>& left,
        const weak_ptr<T>& right) const noexcept;

    bool operator()(
        const weak_ptr<T>& left,
        const shared_ptr<T>& right) const noexcept;
};

template <class T>
struct owner_less<weak_ptr<T>>
    bool operator()(
        const weak_ptr<T>& left,
        const weak_ptr<T>& right) const noexcept;

    bool operator()(
        const weak_ptr<T>& left,
        const shared_ptr<T>& right) const noexcept;

    bool operator()(
        const shared_ptr<T>& left,
        const weak_ptr<T>& right) const noexcept;
};

template<> struct owner_less<void>
{
    template<class T, class U>
    bool operator()(
        const shared_ptr<T>& left,
        const shared_ptr<U>& right) const noexcept;

    template<class T, class U>
    bool operator()(
        const shared_ptr<T>& left,
        const weak_ptr<U>& right) const noexcept;

    template<class T, class U>
    bool operator()(
        const weak_ptr<T>& left,
        const shared_ptr<U>& right) const noexcept;

    template<class T, class U>
    bool operator()(
        const weak_ptr<T>& left,
        const weak_ptr<U>& right) const noexcept;
};

Parâmetros

left
Um ponteiro compartilhado ou fraco.

right
Um ponteiro compartilhado ou fraco.

Comentários

As modelos de classe definem todos os operadores membro como left.owner_before(right) de retorno.

reinterpret_pointer_cast

Cria um novo shared_ptr a partir de um ponteiro compartilhado existente usando uma conversão.

template<class T, class U>
shared_ptr<T> reinterpret_pointer_cast(
    const shared_ptr<U>& ptr) noexcept;

template<class T, class U>
shared_ptr<T> reinterpret_pointer_cast(
    shared_ptr<U>&& ptr) noexcept;

Parâmetros

ptr
Uma referência a um shared_ptr<U>.

Comentários

Se ptr estiver vazio, o novo shared_ptr também estará vazio, do contrário, ele compartilhará a propriedade com ptr. O novo ponteiro compartilhado é o resultado da avaliação de reinterpret_cast<Y*>(ptr.get()), em que Y é typename std::shared_ptr<T>::element_type. O comportamento será indefinido se reinterpret_cast<T*>((U*)nullptr) não estiver bem formado.

A função de modelo que usa uma referência lvalue é nova no C++17. A função de modelo que usa uma referência rvalue é nova no C++ 20.

return_temporary_buffer

Desaloca a memória temporária que foi alocada usando a função de modelo get_temporary_buffer.

template <class T>
void return_temporary_buffer(
    T* buffer);

Parâmetros

buffer
Um ponteiro para a memória a ser desalocada.

Comentários

Use essa função apenas para memória temporária.

Exemplo

// memory_ret_temp_buf.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

using namespace std;

int main( )
{
    // Create an array of ints
    int intArray [] = { 10, 20, 30, 40, 100, 200, 300 };
    int count = sizeof ( intArray ) / sizeof ( int );
    cout << "The number of integers in the array is: "
         << count << "." << endl;

    pair<int *, ptrdiff_t> resultPair;
    resultPair = get_temporary_buffer<int>( count );

    cout << "The number of elements that the allocated memory\n"
         << " could store is given by: resultPair.second = "
         << resultPair.second << "." << endl;

    int* tempBuffer = resultPair.first;

    // Deallocates memory allocated with get_temporary_buffer
    return_temporary_buffer( tempBuffer );
}

The number of integers in the array is: 7.
The number of elements that the allocated memory
could store is given by: resultPair.second = 7.

static_pointer_cast

Conversão estática para shared_ptr.

template <class T, class Other>
shared_ptr<T> static_pointer_cast(
    const shared_ptr<Other>& sp) noexcept;

template <class T, class Other>
shared_ptr<T> static_pointer_cast(
    shared_ptr<Other>&& sp) noexcept;

Parâmetros

T
O tipo controlado pelo ponteiro compartilhado retornado.

Other
O tipo controlado pelo ponteiro compartilhado de argumento.

sp
O ponteiro compartilhado de argumento.

Comentários

A função de modelo retornará um objeto shared_ptr vazio se sp for um objeto shared_ptr vazio, do contrário, ele retornará um objeto shared_ptr<T> que possua o recurso que pertence a sp. A expressão static_cast<T*>(sp.get()) deve ser válida.

Exemplo

// std__memory__static_pointer_cast.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

struct base
{
    int value;
};

struct derived
    : public base
{
};

int main()
{
    std::shared_ptr<base> sp0(new derived);
    std::shared_ptr<derived> sp1 =
        std::static_pointer_cast<derived>(sp0);

    sp0->value = 3;
    std::cout << "sp1->value == " << sp1->value << std::endl;

    return (0);
}

sp1->value == 3

swap

Troca dois objetos shared_ptr, unique_ptr ou weak_ptr.

template <class T>
void swap(
    shared_ptr<T>& left,
    shared_ptr<T>& right) noexcept;

template <class T, class Deleter>
void swap(
    unique_ptr<T, Deleter>& left,
    unique_ptr<T, Deleter>& right) noexcept;

template <class T>
void swap(
    weak_ptr<T>& left,
    weak_ptr<T>& right) noexcept;

Parâmetros

T
O tipo controlado pelo ponteiro de argumento.

Deleter
O agente de exclusão do tipo de ponteiro exclusivo.

left
O ponteiro esquerdo.

right
O ponteiro direito.

Comentários

As funções de modelo chamam left.swap(right).

Exemplo

// std__memory__swap.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp1(new int(5));
    std::shared_ptr<int> sp2(new int(10));
    std::cout << "*sp1 == " << *sp1 << std::endl;

    sp1.swap(sp2);
    std::cout << "*sp1 == " << *sp1 << std::endl;

    swap(sp1, sp2);
    std::cout << "*sp1 == " << *sp1 << std::endl;
    std::cout << std::endl;

    std::weak_ptr<int> wp1(sp1);
    std::weak_ptr<int> wp2(sp2);
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;

    wp1.swap(wp2);
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;

    swap(wp1, wp2);
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;

    return (0);
}

*sp1 == 5
*sp1 == 10
*sp1 == 5

*wp1 == 5
*wp1 == 10
*wp1 == 5

undeclare_no_pointers

Informa um coletor de lixo que os caracteres no bloco de memória definido por um ponteiro de endereço básico e o tamanho de bloco agora podem conter ponteiros rastreáveis.

void undeclare_no_pointers(
    char* ptr,
    size_t size);

Parâmetros

ptr
Um ponteiro para o endereço de memória previamente marcado usando declare_no_pointers.

size
O número de bytes no intervalo de memória. Esse valor deve ser igual ao número usado na chamada declare_no_pointers.

Comentários

A função informa a qualquer coletor de lixo que o intervalo de endereços [ptr, ptr + size) agora pode conter ponteiros rastreáveis.

undeclare_reachable

Revoga uma declaração de acessibilidade para um local de memória especificado.

template <class T>
T *undeclare_reachable(
    T* ptr);

Parâmetros

ptr
Um ponteiro para o endereço de memória previamente marcado usando declare_reachable.

Comentários

Se ptr não for nullptr, a função informará a qualquer coletor de lixo que ptr não estará mais acessível. Ele retorna um ponteiro derivado com segurança que compara igual a ptr.

uninitialized_copy

Copia objetos de um intervalo de origem especificado em um intervalo de destino não inicializado.

template <class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_copy(
    InputIterator first,
    InputIterator last,
    ForwardIterator dest);

template <class ExecutionPolicy, class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_copy(
    ExecutionPolicy&& policy,
    InputIterator first,
    InputIterator last,
    ForwardIterator dest);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador de entrada que trata o primeiro elemento no intervalo de origem.

last
Um iterador de entrada que trata o último elemento no intervalo de origem.

dest
Um iterador de avanço que trata o primeiro elemento no intervalo de destino.

Valor de retorno

Um iterador de encaminhamento abordando a primeira posição além do intervalo de destino, a menos que o intervalo de origem esteja vazio.

Comentários

Esse algoritmo permite dissociar a alocação da memória da construção do objeto.

A função de modelo é executada efetivamente:

while (first != last)
{
    new (static_cast<void*>(&* dest++))
        typename iterator_traits<InputIterator>::value_type(*first++);
}
return dest;

a menos que o código lance uma exceção. Nesse caso, todos os objetos construídos são destruídos e a exceção é relançada.

A sobrecarga com uma política de execução é nova no C++17.

Exemplo

// memory_uninit_copy.cpp
// compile with: /EHsc /W3
#include <memory>
#include <iostream>

using namespace std;

class Integer
{
public:
    Integer(int x) : value(x) {}
    int get() { return value; }
private:
    int value;
};

int main()
{
    int Array[] = { 10, 20, 30, 40 };
    const int N = sizeof(Array) / sizeof(int);

    cout << "The initialized Array contains " << N << " elements: ";
    for (int i = 0; i < N; i++)
    {
        cout << " " << Array[i];
    }
    cout << endl;

    Integer* ArrayPtr = (Integer*)malloc(N * sizeof(int));
    Integer* LArrayPtr = uninitialized_copy(
        Array, Array + N, ArrayPtr);  // C4996

    cout << "Address of position after the last element in the array is: "
        << &Array[0] + N << endl;
    cout << "The iterator returned by uninitialized_copy addresses: "
        << (void*)LArrayPtr << endl;
    cout << "The address just beyond the last copied element is: "
        << (void*)(ArrayPtr + N) << endl;

    if ((&Array[0] + N) == (void*)LArrayPtr)
        cout << "The return value is an iterator "
        << "pointing just beyond the original array." << endl;
    else
        cout << "The return value is an iterator "
        << "not pointing just beyond the original array." << endl;

    if ((void*)LArrayPtr == (void*)(ArrayPtr + N))
        cout << "The return value is an iterator "
        << "pointing just beyond the copied array." << endl;
    else
        cout << "The return value is an iterator "
        << "not pointing just beyond the copied array." << endl;

    free(ArrayPtr);

    cout << "Note that the exact addresses returned will vary\n"
        << "with the memory allocation in individual computers."
        << endl;
}

uninitialized_copy_n

Cria uma cópia de um número especificado de elementos de um iterador de entrada. As cópias são colocadas em um iterador de avanço.

template <class InputIterator, class Size, class ForwardIterator>
ForwardIterator uninitialized_copy_n(
    InputIterator first,
    Size count,
    ForwardIterator dest);

template <class ExecutionPolicy, class InputIterator, class Size, class ForwardIterator>
ForwardIterator uninitialized_copy_n(
    ExecutionPolicy&& policy,
    InputIterator first,
    Size count,
    ForwardIterator dest);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador de entrada que faz referência ao objeto a ser copiado.

count
Um tipo de inteiro com sinal e sem sinal que especifica o número de vezes que o objeto deve ser copiado.

dest
Um iterador de avanço que faz referência ao local das novas cópias.

Valor de retorno

Um iterador de avanço que atende à primeira posição além do destino. Se o intervalo de origem estiver vazio, o iterador endereçará first.

Comentários

A função de modelo executa eficazmente o seguinte código:

    for (; 0 < count; --count)
        new (static_cast<void*>(&* dest++))
            typename iterator_traits<InputIterator>::value_type(*first++);
    return dest;

a menos que o código lance uma exceção. Nesse caso, todos os objetos construídos são destruídos e a exceção é relançada.

A sobrecarga com uma política de execução é nova no C++17.

uninitialized_default_construct

O padrão constrói objetos do value_type dos iteradores no intervalo especificado.

template <class ForwardIterator>
void uninitialized_default_construct(
    ForwardIterator first,
    ForwardIterator last);

template <class ExecutionPolicy, class ForwardIterator>
void uninitialized_default_construct(
    ExecutionPolicy&& policy,
    ForwardIterator first,
    ForwardIterator last);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador abordando o primeiro elemento no intervalo a ser construído.

last
Um iterador abordando um após o último elemento no intervalo a ser construído.

Comentários

A versão sem uma política de execução é efetivamente a mesma que:

for (; first != last; ++first)
    ::new (static_cast<void*>(addressof(*first)))
        typename iterator_traits<ForwardIterator>::value_type;

Se uma exceção for lançada, os objetos construídos anteriormente serão destruídos em ordem não especificada.

A versão com uma política de execução tem o mesmo resultado, mas a execução ocorre de acordo com o policy especificado.

Essas funções são novas no C++17.

uninitialized_default_construct_n

O padrão constrói um número especificado de objetos de value_type do iterador, começando no local especificado.

template <class ForwardIterator, class Size>
ForwardIterator uninitialized_default_construct_n(
    ForwardIterator first,
    Size count);

template <class ExecutionPolicy, class ForwardIterator, class Size>
ForwardIterator uninitialized_default_construct_n(
    ExecutionPolicy&& policy,
    ForwardIterator first,
    Size count);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador abordando o primeiro elemento no intervalo de destino a ser construído.

count
A contagem de elementos no intervalo de destino a ser construído.

Valor de retorno

Um iterador de encaminhamento abordando a primeira posição além do intervalo de destino, a menos que o intervalo de origem esteja vazio.

Comentários

A versão sem uma política de execução é efetivamente a mesma que:

for (; count>0; (void)++first, --count)
    ::new (static_cast<void*>(addressof(*first)))
        typename iterator_traits<ForwardIterator>::value_type;
return first;

Se uma exceção for lançada, os objetos construídos anteriormente serão destruídos em ordem não especificada.

A versão com uma política de execução tem o mesmo resultado, mas a execução ocorre de acordo com o policy especificado.

Essas funções são novas no C++17.

uninitialized_fill

Copia objetos de um valor especificado em um intervalo de destino não inicializado.

template <class ForwardIterator, class T>
void uninitialized_fill(
    ForwardIterator first,
    ForwardIterator last,
    const T& value);

template <class ExecutionPolicy, class ForwardIterator, class T>
void uninitialized_fill(
    ExecutionPolicy&& policy,
    ForwardIterator first,
    ForwardIterator last,
    const T& value);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador de encaminhamento abordando o primeiro elemento no intervalo de destino a ser inicializado.

last
Um iterador de encaminhamento abordando o último elemento no intervalo de destino a ser inicializado.

value
O valor a ser usado para inicializar o intervalo de destino.

Comentários

Esse algoritmo permite dissociar a alocação da memória da construção do objeto.

A função de modelo é executada efetivamente:

while (first != last)
    new (static_cast<void*>(&* first ++))
        typename iterator_traits<ForwardIterator>::value_type (value);

a menos que o código lance uma exceção. Nesse caso, todos os objetos construídos são destruídos e a exceção é relançada.

A sobrecarga com uma política de execução é nova no C++17.

Exemplo

// memory_uninit_fill.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

using namespace std;

class Integer
{
public:
    // No default constructor
    Integer( int x ) : value( x ) {}
    int get() { return value; }
private:
    int value;
};

int main()
{
    const int N = 10;
    Integer value ( 25 );
    Integer* Array = ( Integer* ) malloc( N * sizeof( int ) );
    uninitialized_fill( Array, Array + N, value );
    cout << "The initialized Array contains: ";
    for ( int i = 0; i < N; i++ )
        {
            cout << Array[ i ].get() << " ";
        }
    cout << endl;
}

The initialized Array contains: 25 25 25 25 25 25 25 25 25 25

uninitialized_fill_n

Copia objetos de um valor especificado no número especificado de elementos de um intervalo de destino não inicializado.

template <class ForwardIterator, class Size, class T>
ForwardIterator uninitialized_fill_n(
    ForwardIterator first,
    Size count,
    const T& value);

template <class ExecutionPolicy, class ForwardIterator, class Size, class T>
ForwardIterator uninitialized_fill_n(
    ExecutionPolicy&& policy,
    ForwardIterator first,
    Size count,
    const T& value);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador de encaminhamento abordando o primeiro elemento no intervalo de destino a ser inicializado.

count
O número de elementos a serem inicializados.

value
O valor a ser usado para inicializar o intervalo de destino.

Comentários

Esse algoritmo permite dissociar a alocação da memória da construção do objeto.

A função de modelo é executada efetivamente:

while (0 < count--)
    new (static_cast<void*>(&* first++))
        typename iterator_traits<ForwardIterator>::value_type(value);
return first;

a menos que o código lance uma exceção. Nesse caso, todos os objetos construídos são destruídos e a exceção é relançada.

A sobrecarga com uma política de execução é nova no C++17.

Exemplo

// memory_uninit_fill_n.cpp
// compile with: /EHsc /W3
#include <memory>
#include <iostream>

using namespace std;

class Integer
{
public:
    // No default constructor
    Integer( int x ) : value( x ) {}
    int get() { return value; }
private:
    int value;
};

int main()
{
    const int N = 10;
    Integer value( 60 );
    Integer* Array = ( Integer* ) malloc( N * sizeof( int ) );
    uninitialized_fill_n( Array, N, value );  // C4996
    cout << "The uninitialized Array contains: ";
    for ( int i = 0; i < N; i++ )
        cout << Array[ i ].get() <<  " ";
}

uninitialized_move

Move elementos de um intervalo de origem para uma área de memória de destino não inicializada.

template <class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_move(
    InputIterator first,
    InputIterator last,
    ForwardIterator dest);

template <class ExecutionPolicy, class InputIterator, class ForwardIterator>
ForwardIterator uninitialized_move(
    ExecutionPolicy&& policy,
    InputIterator first,
    InputIterator last,
    ForwardIterator dest);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador de entrada abordando o primeiro elemento no intervalo de origem a ser movido.

last
Um iterador de entrada abordando um após o último elemento no intervalo de origem a ser movido.

dest
O início do intervalo de destino.

Comentários

A versão sem uma política de execução é efetivamente a mesma que:

for (; first != last; (void)++dest, ++first)
    ::new (static_cast<void*>(addressof(*dest)))
        typename iterator_traits<ForwardIterator>::value_type(std::move(*first));
return dest;

Se uma exceção for lançada, alguns objetos no intervalo de origem podem ser deixados em um estado válido, mas não especificado. Objetos construídos anteriormente são destruídos em ordem não especificada.

A versão com uma política de execução tem o mesmo resultado, mas a execução ocorre de acordo com o policy especificado.

Essas funções são novas no C++17.

uninitialized_move_n

Move um número especificado de elementos de um intervalo de origem para uma área de memória de destino não inicializada.

template <class InputIterator, class Size, class ForwardIterator>
pair<InputIterator, ForwardIterator> uninitialized_move_n(
    InputIterator first,
    Size count,
    ForwardIterator dest);

template <class ExecutionPolicy, class InputIterator, class Size, class ForwardIterator>
pair<InputIterator, ForwardIterator> uninitialized_move_n(
    ExecutionPolicy&& policy,
    InputIterator first,
    Size count,
    ForwardIterator dest);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador de entrada abordando o primeiro elemento no intervalo de origem a ser movido.

count
A contagem de elementos no intervalo de origem a serem movidos.

dest
O início do intervalo de destino.

Comentários

A versão sem uma política de execução é efetivamente a mesma que:

for (; count > 0; ++dest, (void) ++first, --count)
    ::new (static_cast<void*>(addressof(*dest)))
        typename iterator_traits<ForwardIterator>::value_type(std::move(*first));
return {first, dest};

Se uma exceção for lançada, alguns objetos no intervalo de origem podem ser deixados em um estado válido, mas não especificado. Objetos construídos anteriormente são destruídos em ordem não especificada.

A versão com uma política de execução tem o mesmo resultado, mas a execução ocorre de acordo com o policy especificado.

Essas funções são novas no C++17.

uninitialized_value_construct

Constrói objetos do value_type dos iteradores por inicialização de valor, no intervalo especificado.

template <class ForwardIterator>
void uninitialized_value_construct(
    ForwardIterator first,
    ForwardIterator last);

template <class ExecutionPolicy, class ForwardIterator>
void uninitialized_value_construct(
    ExecutionPolicy&& policy,
    ForwardIterator first,
    ForwardIterator last);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador abordando o primeiro elemento no intervalo para construir valor.

last
Um iterador abordando o elemento seguinte ao último no intervalo de construção de valor.

Comentários

A versão sem uma política de execução é efetivamente a mesma que:

for (; first != last; ++first)
    ::new (static_cast<void*>(addressof(*first)))
        typename iterator_traits<ForwardIterator>::value_type();

Se uma exceção for lançada, os objetos construídos anteriormente serão destruídos em ordem não especificada.

A versão com uma política de execução tem o mesmo resultado, mas a execução ocorre de acordo com o policy especificado.

Se ocorrer uma falha de alocação de memória, uma exceção std::bad_alloc será lançada.

Essas funções são novas no C++17.

uninitialized_value_construct_n

Constrói um número especificado de objetos de value_type do iterador por inicialização de valor, começando no local especificado.

template <class ForwardIterator, class Size>
ForwardIterator uninitialized_value_construct_n(
    ForwardIterator first,
    Size count);

template <class ExecutionPolicy, class ForwardIterator, class Size>
ForwardIterator uninitialized_value_construct_n(
    ExecutionPolicy&& policy,
    ForwardIterator first,
    Size count);

Parâmetros

policy
A política de execução a ser usada.

first
Um iterador abordando o primeiro elemento no intervalo de destino a ser construído.

count
A contagem de elementos no intervalo de destino a ser construído.

Comentários

A versão sem uma política de execução é efetivamente a mesma que:

for (; count > 0; (void)++first, --count)
    ::new (static_cast<void*>(addressof(*first)))
        typename iterator_traits<ForwardIterator>::value_type();
return first;

Se uma exceção for lançada, os objetos construídos anteriormente serão destruídos em ordem não especificada.

A versão com uma política de execução tem o mesmo resultado, mas a execução ocorre de acordo com o policy especificado.

Se ocorrer uma falha de alocação de memória, uma exceção std::bad_alloc será lançada.

Essas funções são novas no C++17.

uses_allocator_v

Um modelo de variável auxiliar para acessar o valor do modelo de uses_allocator.

template <class T, class Alloc>
inline constexpr bool uses_allocator_v = uses_allocator<T, Alloc>::value;

Confira também

<memory>