`<memory>` 函式

發行項
08/04/2024

`addressof`

取得物件真正的位址。

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

參數

value
要取得真正位址的物件或函式。

傳回值

value 所參考物件或函式的實際位址，即使多載的 operator&() 存在。

備註

`align`

符合指定對齊規格所對齊之指定大小的記憶體，放入指定記憶體的第一個可能位址。

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

參數

alignment
嘗試的對齊界限。

size
對齊儲存體的大小 (位元組)。

ptr
要使用的可用連續儲存集區的開始位址。此參數也是輸出參數，如果對齊成功，則會設定為包含新的起始位址。如果 align() 失敗，則不會修改此參數。

space
align() 可用來建立對齊儲存體的總空間。這個參數也是輸出參數，在對齊儲存體和任何關聯的額外負荷減去之後，會包含儲存緩衝區中剩下的調整空間。

如果 align() 失敗，則不會修改此參數。

傳回值

NULL如果要求的對齊緩衝區無法放入可用空間，則為指標，否則為的新值ptr。

備註

修改的 ptr 和 space 參數可讓您在相同緩衝區上重複呼叫 align()，可能使用 alignment 和 size 的不同值。下列程式碼片段示範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`

建立 shared_ptr，指向透過使用指定的配置器為特定類型配置及建構的物件。傳回 shared_ptr。

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

參數

alloc
用來建立物件的配置器。

args
成為物件的零個或多個引數。

備註

此函式會建立 shared_ptr<T> 物件，這是 alloc 所配置和建構之 T(args...) 的指標。

`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`

常數轉型成 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;

參數

T
傳回之共用指標所控制的類型。

Other
引數共用指標所控制的類型。

sp
引數共用指標。

備註

如果const_cast<T*>(sp.get())傳回 Null 指標，則樣板函式會傳回空白shared_ptr對象，否則會傳回shared_ptr<T>擁有所sp擁有資源的物件。運算式 const_cast<T*>(sp.get()) 必須有效。

範例

// 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`

通知記憶體回收行程，指出基底位址指標和區塊大小所定義之記憶體區塊中的字元未包含任何可追蹤的指標。

void declare_no_pointers(
    char* ptr,
    size_t size);

參數

ptr
已不再包含可追蹤指標的第一個位元位址。

size
起始位置在 ptr 之未包含任何可追蹤指標的區塊大小。

備註

函式會通知任何垃圾收集行程，範圍 [ptr, ptr + size) 中的位址不再包含可追蹤的指標。（除非可連線，否則不得取值已配置記憶體的任何指標。

`declare_reachable`

告知記憶體回收，指示的位址是前往配置儲存體且可連接。

void declare_reachable(
    void* ptr);

參數

ptr
指向可存取、已配置之有效儲存區域的指標。

備註

如果 ptr 不是 Null，函式會通知任何現在可連線的垃圾收集行程 ptr ，也就是說，它會指向有效的已配置記憶體。

`default_delete`

刪除使用 operator new 配置的物件。適合搭配 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;
};

參數

ptr
要刪除的物件指標。

Other
要刪除的陣列項目類型。

備註

類別範本描述一個刪除程式，該刪除程式會刪除配置 operator new給的純量對象，適合與類別範本 unique_ptr搭配使用。它也具有明確的特製化 default_delete<T[]>。

`destroy_at`

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

與 location->~T() 相同。

`destroy`

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

與：

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

`destroy_n`

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

與：

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

`dynamic_pointer_cast`

動態轉型為 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;

參數

T
傳回之共用指標所控制的類型。

Other
引數共用指標所控制的類型。

sp
引數共用指標。

備註

如果dynamic_cast<T*>(sp.get())傳回 Null 指標，則樣板函式會傳回空白shared_ptr對象，否則會傳回shared_ptr<T>擁有所sp擁有資源的物件。運算式 dynamic_cast<T*>(sp.get()) 必須有效。

範例

// 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`

從 shared_ptr取得刪除程式。

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

參數

Deleter
刪除者的類型。

T
共用指標所控制的類型。

sp
共用指標。

備註

樣板函式會傳回屬於 shared_ptr 物件 sp之型Deleter別的刪除器的指標。如果沒有 sp 刪除程式，或它的刪除程式不是型 Deleter別，則函式會傳回 0。

範例

// 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`

傳回任何記憶體回收行程所假設之指標安全的類型。

pointer_safety get_pointer_safety() noexcept;

備註

函式會傳回任何自動垃圾收集行程所假設的指標安全性類型。

`get_temporary_buffer`

為一連串未超過指定項目數目的專案配置暫存盤。

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

參數

計數
所要求的元素數目上限，將針對這些元素配置記憶體。

傳回值

一個 pair，其第一個元件是指向所配置記憶體的指標，第二個元件提供緩衝區的大小，指出它所能儲存的元素數目上限。

備註

此函式會提出記憶體要求，但可能不會成功。如果未配置任何緩衝區，此函式就會傳回一個配對，其中第二個元件等於零，而第一個元件等於 Null 指標。

只將此函式用於暫存的記憶體。

範例

// 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`

建立並傳回 shared_ptr，它會指向使用預設配置器從零個或多個引數建構的配置物件。配置並建構指定類別的物件和 shared_ptr 來管理共用的物件擁有權，並傳回 shared_ptr。

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

參數

args
零或多個建構函式引數。函式會根據所提供的引數推斷要叫用的建構函式多載。

備註

使用 make_shared 做為建立物件和 shared_ptr 的一個簡單且更有效率的方式，並藉以同時管理物件的共用存取權。語意上來說，這兩個陳述式是相等的：

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

但是，第一個陳述式會產生兩個配置，而若 shared_ptr 物件配置成功之後，Example 配置失敗，則未命名的 Example 物件會遭到洩露。使用 make_shared 的陳述式比較簡單，因為這樣只會使用一個函式呼叫。這樣會更有效率，因為程式庫可以讓物件和智慧型指標進行單一配置。此函式既更快，又會導致記憶體分散較少，而且沒有一個配置發生例外狀況，但不可能發生另一個配置。改善參考物件的程式碼位置，並更新智慧型指標中的參考計數，便能夠提升效能。

如果您不需要對物件進行共享存取，請考慮使用 make_unique 。如果您需要指定物件的自訂設定器，請使用 allocate_shared 。如果您的物件需要自定義刪除器，您無法使用 make_shared ，因為無法將刪除程式當做自變數傳遞。

下列範例示範如何透過叫用特定的建構函式多載來建立共用的類型指標。

範例

// 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();
}

該範例會產生以下輸出：

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`

建立並將傳回 unique_ptr 至指定型別的對象，這個物件是使用指定的自變數所建構的。

// 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;

參數

T
unique_ptr 指向的物件類型。

Args
args 所指定的建構函式引數類型。

args
要傳遞給 T 類型物件之建構函式的引數。

elements
T 類型的元素陣列。

size
在新陣列中要為其配置空間的元素數目。

備註

第一個多載用於單一物件。第二個多載會針對陣列叫用。第三個多載可防止您在類型自變數中指定數位大小;make_unique<T[N]>目前的標準不支援此建構。當您使用 make_unique 來建立陣列的 unique_ptr，必須將陣列元素個別初始化。與其使用此多載，也許更好的選擇是使用 std::vector。

為了例外狀況安全，make_unique 實作很謹慎，因此建議您使用 make_unique，而不是直接呼叫 unique_ptr 建構函式。

範例

下列範例示範如何使用 make_unique。如需更多範例，請參閱如何：建立和使用 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();
}

當您看到與 unique_ptr 有關的錯誤 C2280 時，通常都是因為您嘗試叫用它的複製建構函式，這是一個被刪除的函式。

`owner_less`

允許按擁有權混合比較共用指標和弱式指標。如果成員函式 owner_before 將 left 參數排序在 right 參數之前，便會傳回 true。

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;
};

參數

left
共用指標或弱式指標。

right
共用指標或弱式指標。

備註

類別範本會將所有成員運算子定義為傳 left.owner_before(right)回。

`reinterpret_pointer_cast`

使用轉換從現有的共享指標建立新的 shared_ptr 。

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;

參數

ptr
的 shared_ptr<U>參考。

備註

如果 ptr 是空的，則新的 shared_ptr 也是空的，否則它會與 ptr共用擁有權。新的共享指標是評估 reinterpret_cast<Y*>(ptr.get())的結果，其中 Y 是 typename std::shared_ptr<T>::element_type。如果 reinterpret_cast<T*>((U*)nullptr) 格式不正確，則行為未定義。

採用左值參考的範本函式在 C++17 中是新的。採用右值參考的範本函式在 C++20 中是新的。

`return_temporary_buffer`

將使用 get_temporary_buffer 樣板函式配置的暫存記憶體取消配置。

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

參數

buffer
指向要配置之記憶體的指標。

備註

只將此函式用於暫存的記憶體。

範例

// 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`

靜態轉型至 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;

參數

T
傳回之共用指標所控制的類型。

Other
引數共用指標所控制的類型。

sp
引數共用指標。

備註

如果 sp 是空的物件，則樣板函式會傳回空白shared_ptrshared_ptr對象，否則會傳回shared_ptr<T>擁有所sp擁有之資源的物件。運算式 static_cast<T*>(sp.get()) 必須有效。

範例

// 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`

交換兩個 shared_ptr、 unique_ptr或 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;

參數

T
引數指標所控制的類型。

Deleter
唯一指標類型的刪除器。

left
左指標。

right
右指標。

備註

範本函式呼叫 left.swap(right)。

範例

// 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`

通知記憶體回收行程，基底位址指標和區塊大小定義的記憶體區塊中的字元現在可能會包含可追蹤的指標。

void undeclare_no_pointers(
    char* ptr,
    size_t size);

參數

ptr
先前使用 declare_no_pointers標記之內存位址的指標。

size
記憶體範圍內的位元組數目。這個值必須等於呼叫中使用的 declare_no_pointers 數位。

備註

函式會通知任何垃圾收集行程，位址 [ptr, ptr + size) 範圍現在可能包含可追蹤的指標。

`undeclare_reachable`

撤銷指定記憶體位置的可觸達性宣告。

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

參數

ptr
先前使用 declare_reachable標記之內存位址的指標。

備註

如果 ptr 不是 nullptr，函式會通知無法再連線的任何垃圾收集行程 ptr 。它會傳回與相等 ptr之安全衍生的指標。

`uninitialized_copy`

從指定的來源範圍將物件複製到未初始化的目的範圍內。

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);

參數

policy
要使用的執行原則。

first
輸入迭代器，為來源範圍中的第一個項目定址。

last
輸入迭代器，為來源範圍中的最後一個項目定址。

dest
正向迭代器，為目的範圍中的第一個項目定址。

傳回值

正向反覆運算器，尋址目標範圍以外的第一個位置，除非來源範圍是空的。

備註

這個演算法允許記憶體配置與物件建構分開處理。

樣板函式有效地執行：

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

除非程式碼擲回例外狀況。在這種情況下，會終結所有建構的物件，並重新擲回例外狀況。

執行原則的多載在 C++17 中是新的。

範例

// 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`

從輸入迭代器建立所指定項目數的複本。複本會放在正向迭代器中。

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);

參數

policy
要使用的執行原則。

first
輸入迭代器，參考要複製的物件。

count
帶正負號或不帶正負號的整數類型，指定複製物件的次數。

dest
正向迭代器，參考放置新複本的位置。

傳回值

正向迭代器，定址目的之外的第一個位置。如果來源範圍是空的，反覆運算器會尋址 first。

備註

範本函式會有效地執行下列程式代碼：

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

除非程式碼擲回例外狀況。在這種情況下，會終結所有建構的物件，並重新擲回例外狀況。

執行原則的多載在 C++17 中是新的。

`uninitialized_default_construct`

預設會建構指定範圍中反覆運算器的物件 value_type 。

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);

參數

policy
要使用的執行原則。

first
反覆運算器，尋址要建構之範圍中的第一個專案。

last
反覆運算器，尋址範圍中最後一個要建構的專案。

備註

沒有執行原則的版本實際上與：

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

如果擲回例外狀況，先前建構的物件會以未指定的順序終結。

具有執行原則的版本具有相同的結果，但會根據指定的 policy執行。

這些函式是 C++17 中的新功能。

`uninitialized_default_construct_n`

默認值會從指定的位置開始，建構反覆運算器的 value_type指定物件數目。

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);

參數

policy
要使用的執行原則。

first
反覆運算器，尋址目的地範圍中要建構的第一個專案。

count
要建構之目的範圍中的項目計數。

傳回值

正向反覆運算器，尋址目標範圍以外的第一個位置，除非來源範圍是空的。

備註

沒有執行原則的版本實際上與：

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

如果擲回例外狀況，先前建構的物件會以未指定的順序終結。

具有執行原則的版本具有相同的結果，但會根據指定的 policy執行。

這些函式是 C++17 中的新功能。

`uninitialized_fill`

將所指定值的物件複製到未初始化的目的範圍內。

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);

參數

policy
要使用的執行原則。

first
正向反覆運算器，尋址目的地範圍中要初始化的第一個專案。

last
正向反覆運算器，尋址目的地範圍中要初始化的最後一個專案。

value
用來初始化目的範圍的值。

備註

這個演算法允許記憶體配置與物件建構分開處理。

樣板函式有效地執行：

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

除非程式碼擲回例外狀況。在這種情況下，會終結所有建構的物件，並重新擲回例外狀況。

執行原則的多載在 C++17 中是新的。

範例

// 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`

將指定值的物件複製到未初始化目的範圍的指定項目數目。

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);

參數

policy
要使用的執行原則。

first
正向反覆運算器，尋址目的地範圍中要初始化的第一個專案。

count
要初始化的項目數目。

value
要用來初始化目的範圍的值。

備註

這個演算法允許記憶體配置與物件建構分開處理。

樣板函式有效地執行：

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

除非程式碼擲回例外狀況。在這種情況下，會終結所有建構的物件，並重新擲回例外狀況。

執行原則的多載在 C++17 中是新的。

範例

// 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`

將專案從來源範圍移至未初始化的目的地記憶體區域。

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);

參數

policy
要使用的執行原則。

first
輸入反覆運算器，尋址來源範圍中要移動的第一個專案。

last
輸入反覆運算器，尋址來源範圍中要移動的最後一個專案。

dest
目的範圍的開頭。

備註

沒有執行原則的版本實際上與：

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

如果擲回例外狀況，來源範圍中的某些物件可能會保持有效但未指定的狀態。先前建構的物件會以未指定的順序終結。

具有執行原則的版本具有相同的結果，但會根據指定的 policy執行。

這些函式是 C++17 中的新功能。

`uninitialized_move_n`

將指定的項目數目從來源範圍移至未初始化的目的地記憶體區域。

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);

參數

policy
要使用的執行原則。

first
輸入反覆運算器，尋址來源範圍中要移動的第一個專案。

count
要移動之來源範圍中的項目計數。

dest
目的範圍的開頭。

備註

沒有執行原則的版本實際上與：

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};

如果擲回例外狀況，來源範圍中的某些物件可能會保持有效但未指定的狀態。先前建構的物件會以未指定的順序終結。

具有執行原則的版本具有相同的結果，但會根據指定的 policy執行。

這些函式是 C++17 中的新功能。

`uninitialized_value_construct`

在指定的範圍內，依值初始化來建構反覆運算器 value_type 的物件。

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);

參數

policy
要使用的執行原則。

first
反覆運算器，尋址範圍中要建構值的第一個專案。

last
反覆運算器，尋址範圍中最後一個專案的尋址物件為 value construct。

備註

沒有執行原則的版本實際上與：

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

如果擲回例外狀況，先前建構的物件會以未指定的順序終結。

具有執行原則的版本具有相同的結果，但會根據指定的 policy執行。

如果發生記憶體配置失敗， std::bad_alloc 則會擲回例外狀況。

這些函式是 C++17 中的新功能。

`uninitialized_value_construct_n`

從指定位置開始，依值初始化建構反覆運算器的 value_type 指定數目物件。

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);

參數

policy
要使用的執行原則。

first
反覆運算器，尋址目的地範圍中要建構的第一個專案。

count
要建構之目的範圍中的項目計數。

備註

沒有執行原則的版本實際上與：

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

如果擲回例外狀況，先前建構的物件會以未指定的順序終結。

具有執行原則的版本具有相同的結果，但會根據指定的 policy執行。

如果發生記憶體配置失敗， std::bad_alloc 則會擲回例外狀況。

這些函式是 C++17 中的新功能。

`uses_allocator_v`

用來存取範本值的 uses_allocator 協助程式變數範本。

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

另請參閱

<memory>

共用方式為

<memory> 函式

addressof

參數

傳回值

備註

align

參數

傳回值

備註

allocate_shared

參數

備註

atomic_compare_exchange_strong

atomic_compare_exchange_weak

atomic_compare_exchange_strong_explicit

atomic_compare_exchange_weak_explicit

atomic_exchange

atomic_exchange_explicit

atomic_is_lock_free

atomic_load

atomic_load_explicit

atomic_store

atomic_store_explicit

const_pointer_cast

參數

備註

範例

declare_no_pointers

參數

備註

declare_reachable

參數

備註

default_delete

參數

備註

destroy_at

destroy

destroy_n

dynamic_pointer_cast

參數

備註

範例

get_deleter

參數

備註

範例

get_pointer_safety

備註

get_temporary_buffer

參數

傳回值

備註

範例

make_shared

參數

備註

範例

make_unique

參數

備註

範例

owner_less

參數

備註

reinterpret_pointer_cast

參數

備註

return_temporary_buffer

參數

備註

範例

static_pointer_cast

參數

備註

範例

swap

參數

備註

`<memory>` 函式

`addressof`

`align`

`allocate_shared`

`atomic_compare_exchange_strong`

`atomic_compare_exchange_weak`

`atomic_compare_exchange_strong_explicit`

`atomic_compare_exchange_weak_explicit`

`atomic_exchange`

`atomic_exchange_explicit`

`atomic_is_lock_free`

`atomic_load`

`atomic_load_explicit`

`atomic_store`

`atomic_store_explicit`

`const_pointer_cast`

`declare_no_pointers`

`declare_reachable`

`default_delete`

`destroy_at`

`destroy`

`destroy_n`

`dynamic_pointer_cast`

`get_deleter`

`get_pointer_safety`

`get_temporary_buffer`

`make_shared`

`make_unique`

`owner_less`

`reinterpret_pointer_cast`

`return_temporary_buffer`

`static_pointer_cast`

`swap`

`undeclare_no_pointers`

`undeclare_reachable`

`uninitialized_copy`

`uninitialized_copy_n`

`uninitialized_default_construct`

`uninitialized_default_construct_n`

`uninitialized_fill`

`uninitialized_fill_n`

`uninitialized_move`

`uninitialized_move_n`

`uninitialized_value_construct`

`uninitialized_value_construct_n`

`uses_allocator_v`