W3cubDocs

/C++

Standard library header <memory>

This header is part of the dynamic memory management library.

Classes

Smart pointers categories
(C++11)
smart pointer with unique object ownership semantics
(class template)
(C++11)
smart pointer with shared object ownership semantics
(class template)
(C++11)
weak reference to an object managed by std::shared_ptr
(class template)
(until C++17)
smart pointer with strict object ownership semantics
(class template)
Smart pointers helper classes
(C++11)
provides mixed-type owner-based ordering of shared and weak pointers
(class template)
allows an object to create a shared_ptr referring to itself
(class template)
(C++11)
exception thrown when accessing a weak_ptr which refers to already destroyed object
(class)
default deleter for unique_ptr
(class template)
Allocators
the default allocator
(class template)
provides information about allocator types
(class template)
tag type used to select allocator-aware constructor overloads
(class)
an object of type std::allocator_arg_t used to select allocator-aware constructors
(constant)
checks if the specified type supports uses-allocator construction
(class template)
Other
lists pointer safety models
(class)
provides information about pointer-like types
(class template)
hash support for std::shared_ptr
(class template specialization)
hash support for std::unique_ptr
(class template specialization)
Forward declaration
Defined in header <functional>
(C++11)
hash function object
(class template)

Constants

an object of type std::allocator_arg_t used to select allocator-aware constructors
(constant)

Functions

Uninitialized storage
copies a range of objects to an uninitialized area of memory
(function template)
copies a number of objects to an uninitialized area of memory
(function template)
copies an object to an uninitialized area of memory, defined by a range
(function template)
copies an object to an uninitialized area of memory, defined by a start and a count
(function template)
(deprecated in C++17)
an iterator that allows standard algorithms to store results in uninitialized memory
(class template)
(deprecated in C++17)
obtains uninitialized storage
(function template)
(deprecated in C++17)
frees uninitialized storage
(function template)
Garbage collector support
declares that an object can not be recycled
(function)
declares that an object can be recycled
(function template)
declares that a memory area does not contain traceable pointers
(function)
cancels the effect of std::declare_no_pointers
(function)
returns the current pointer safety model
(function)
Miscellaneous
(C++11)
obtains actual address of an object, even if the & operator is overloaded
(function template)
(C++11)
aligns a pointer in a buffer
(function)
Smart pointer non-member operations
(C++14)
creates a unique pointer that manages a new object
(function template)
creates a shared pointer that manages a new object
(function template)
creates a shared pointer that manages a new object allocated using an allocator
(function template)
applies static_cast, dynamic_cast, const_cast, or reinterpret_cast to the stored pointer
(function template)
returns the deleter of specified type, if owned
(function template)
compares with another shared_ptr or with nullptr
(function template)
outputs the value of the stored pointer to an output stream
(function template)
specializes the std::swap algorithm
(function template)
specializes atomic operations for std::shared_ptr
(function template)
compares to another unique_ptr or with nullptr
(function template)
specializes the std::swap algorithm
(function template)
specializes the std::swap algorithm
(function template)
Allocator non-member operations
compares two allocator instances
(public member function of std::allocator)
compares two scoped_allocator_adaptor instances
(public member function of std::scoped_allocator_adaptor)

Synopsis

namespace std {
    // pointer traits
    template <class Ptr> struct pointer_traits;
    template <class T> struct pointer_traits<T*>;
 
    // pointer safety
    enum class pointer_safety { relaxed, preferred, strict };
    void declare_reachable(void *p);
    template <class T> T *undeclare_reachable(T *p);
    void declare_no_pointers(char *p, size_t n);
    void undeclare_no_pointers(char *p, size_t n);
    pointer_safety get_pointer_safety() noexcept;
 
    // pointer alignment function
    void *align(std::size_t alignment, std::size_t size,
                void *&ptr, std::size_t& space);
 
    // allocator argument tag
    struct allocator_arg_t { };
    constexpr allocator_arg_t allocator_arg = allocator_arg_t();
 
    // uses_allocator
    template <class T, class Alloc> struct uses_allocator;
 
    // allocator traits
    template <class Alloc> struct allocator_traits;
 
    // the default allocator:
    template <class T> class allocator;
    template <> class allocator<void>;
    template <class T, class U>
        bool operator==(const allocator<T>&, const allocator<U>&) noexcept;
    template <class T, class U>
        bool operator!=(const allocator<T>&, const allocator<U>&) noexcept;
 
    // raw storage iterator:
    template <class OutputIterator, class T> class raw_storage_iterator;
 
    // temporary buffers:
    template <class T>
        pair<T*,ptrdiff_t> get_temporary_buffer(ptrdiff_t n) noexcept;
    template <class T>
        void return_temporary_buffer(T* p);
 
    // specialized algorithms:
    template <class T> T* addressof(T& r) noexcept;
    template <class InputIterator, class ForwardIterator>
        ForwardIterator uninitialized_copy(InputIterator first, InputIterator last,
                                           ForwardIterator result);
    template <class InputIterator, class Size, class ForwardIterator>
        ForwardIterator uninitialized_copy_n(InputIterator first, Size n,
                                             ForwardIterator result);
    template <class ForwardIterator, class T>
        void uninitialized_fill(ForwardIterator first, ForwardIterator last,
                                const T& x);
    template <class ForwardIterator, class Size, class T>
        ForwardIterator uninitialized_fill_n(ForwardIterator first, Size n, const T& x);
    // class template unique_ptr:
    template <class T> class default_delete;
    template <class T> class default_delete<T[]>;
    template <class T, class D = default_delete<T>> class unique_ptr;
    template <class T, class D> class unique_ptr<T[], D>;
 
    template <class T1, class D1, class T2, class D2>
        bool operator==(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
    template <class T1, class D1, class T2, class D2>
        bool operator!=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
    template <class T1, class D1, class T2, class D2>
        bool operator<(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
    template <class T1, class D1, class T2, class D2>
        bool operator<=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
    template <class T1, class D1, class T2, class D2>
        bool operator>(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
    template <class T1, class D1, class T2, class D2>
        bool operator>=(const unique_ptr<T1, D1>& x, const unique_ptr<T2, D2>& y);
 
    template <class T, class D>
        bool operator==(const unique_ptr<T, D>& x, nullptr_t) noexcept;
    template <class T, class D>
        bool operator==(nullptr_t, const unique_ptr<T, D>& y) noexcept;
    template <class T, class D>
        bool operator!=(const unique_ptr<T, D>& x, nullptr_t) noexcept;
    template <class T, class D>
        bool operator!=(nullptr_t, const unique_ptr<T, D>& y) noexcept;
 
    template <class T, class D>
        bool operator<(const unique_ptr<T, D>& x, nullptr_t);
    template <class T, class D>
        bool operator<(nullptr_t, const unique_ptr<T, D>& y);
    template <class T, class D>
        bool operator<=(const unique_ptr<T, D>& x, nullptr_t);
    template <class T, class D>
        bool operator<=(nullptr_t, const unique_ptr<T, D>& y);
    template <class T, class D>
        bool operator>(const unique_ptr<T, D>& x, nullptr_t);
    template <class T, class D>
        bool operator>(nullptr_t, const unique_ptr<T, D>& y);
    template <class T, class D>
        bool operator>=(const unique_ptr<T, D>& x, nullptr_t);
    template <class T, class D>
        bool operator>=(nullptr_t, const unique_ptr<T, D>& y);
 
    // class bad_weak_ptr:
    class bad_weak_ptr;
 
    // class template shared_ptr:
    template<class T> class shared_ptr;
 
    // shared_ptr comparisons:
    template<class T, class U>
        bool operator==(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
    template<class T, class U>
        bool operator!=(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
    template<class T, class U>
        bool operator<(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
    template<class T, class U>
        bool operator>(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
    template<class T, class U>
        bool operator<=(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
    template<class T, class U>
        bool operator>=(shared_ptr<T> const& a, shared_ptr<U> const& b) noexcept;
 
    template <class T>
        bool operator==(const shared_ptr<T>& x, nullptr_t) noexcept;
    template <class T>
        bool operator==(nullptr_t, const shared_ptr<T>& y) noexcept;
    template <class T>
        bool operator!=(const shared_ptr<T>& x, nullptr_t) noexcept;
    template <class T>
        bool operator!=(nullptr_t, const shared_ptr<T>& y) noexcept;
    template <class T>
        bool operator<(const shared_ptr<T>& x, nullptr_t) noexcept;
    template <class T>
        bool operator<(nullptr_t, const shared_ptr<T>& y) noexcept;
    template <class T>
        bool operator<=(const shared_ptr<T>& x, nullptr_t) noexcept;
    template <class T>
        bool operator<=(nullptr_t, const shared_ptr<T>& y) noexcept;
    template <class T>
        bool operator>(const shared_ptr<T>& x, nullptr_t) noexcept;
    template <class T>
    bool operator>(nullptr_t, const shared_ptr<T>& y) noexcept;
    template <class T>
        bool operator>=(const shared_ptr<T>& x, nullptr_t) noexcept;
    template <class T>
        bool operator>=(nullptr_t, const shared_ptr<T>& y) noexcept;
 
    // shared_ptr specialized algorithms:
    template<class T> void swap(shared_ptr<T>& a, shared_ptr<T>& b) noexcept;
 
    // shared_ptr casts:
    template<class T, class U>
        shared_ptr<T> static_pointer_cast(shared_ptr<U> const& r) noexcept;
    template<class T, class U>
        shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const& r) noexcept;
    template<class T, class U>
        shared_ptr<T> const_pointer_cast(shared_ptr<U> const& r) noexcept;
 
    // shared_ptr get_deleter:
    template<class D, class T> D* get_deleter(shared_ptr<T> const& p) noexcept;
 
    // shared_ptr I/O:
    template<class E, class T, class Y>
        basic_ostream<E, T>& operator<< (basic_ostream<E, T>& os, shared_ptr<Y> const& p);
 
    // class template weak_ptr:
    template<class T> class weak_ptr;
 
    // weak_ptr specialized algorithms:
    template<class T> void swap(weak_ptr<T>& a, weak_ptr<T>& b) noexcept;
 
    // class template owner_less:
    template<class T> class owner_less;
 
    // class template enable_shared_from_this:
    template<class T> class enable_shared_from_this;
 
    // shared_ptr atomic access:
    template<class T>
        bool atomic_is_lock_free(const shared_ptr<T>* p);
    template<class T>
        shared_ptr<T> atomic_load(const shared_ptr<T>* p);
    template<class T>
        shared_ptr<T> atomic_load_explicit(const shared_ptr<T>* p, memory_order mo);
    template<class T>
        void atomic_store(shared_ptr<T>* p, shared_ptr<T> r);
    template<class T>
        void atomic_store_explicit(shared_ptr<T>* p, shared_ptr<T> r, memory_order mo);
    template<class T>
        shared_ptr<T> atomic_exchange(shared_ptr<T>* p, shared_ptr<T> r);
    template<class T>
        shared_ptr<T> atomic_exchange_explicit(shared_ptr<T>* p, shared_ptr<T> r,
                                                memory_order mo);
    template<class T>
        bool atomic_compare_exchange_weak(
            shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T>  w);
    template<class T>
        bool atomic_compare_exchange_strong(
            shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T>  w);
    template<class T>
        bool atomic_compare_exchange_weak_explicit(
            shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w,
            memory_order success, memory_order failure);
    template<class T>
        bool atomic_compare_exchange_strong_explicit(
            shared_ptr<T>* p, shared_ptr<T>* v, shared_ptr<T> w,
            memory_order success, memory_order failure);
 
    //  hash support
    template <class T> struct hash;
    template <class T, class D> struct hash<unique_ptr<T, D> >;
    template <class T> struct hash<shared_ptr<T> >;
 
    // auto_ptr (deprecated)
    template <class X> class auto_ptr;
}

std::pointer_traits

namespace std {
    template <class Ptr> struct pointer_traits {
        typedef Ptr         pointer;
        typedef /*depends*/ element_type;
        typedef /*depends*/ difference_type;
 
        template <class U> using rebind = /*depends*/;
 
        static pointer pointer_to(element_type& r);
    };
    template <class T> struct pointer_traits<T*> {
        typedef T*          pointer;
        typedef T           element_type;
        typedef ptrdiff_t   difference_type;
 
        template <class U> using rebind = U*;
 
        static pointer pointer_to(element_type& r) noexcept;
    };
}

std::allocator_traits

namespace std {
    template <class Alloc> struct allocator_traits {
        typedef Alloc allocator_type;
 
        typedef typename Alloc::value_type value_type;
 
        typedef /*depends*/ pointer;
        typedef /*depends*/ const_pointer;
        typedef /*depends*/ void_pointer;
        typedef /*depends*/ const_void_pointer;
 
        typedef /*depends*/ difference_type;
        typedef /*depends*/ size_type;
 
        typedef /*depends*/ propagate_on_container_copy_assignment;
        typedef /*depends*/ propagate_on_container_move_assignment;
        typedef /*depends*/ propagate_on_container_swap;
        typedef /*depends*/ is_always_equal;
 
        template <class T> using rebind_alloc = /*depends*/ ;
        template <class T> using rebind_traits = allocator_traits<rebind_alloc<T> >;
 
        static pointer allocate(Alloc& a, size_type n);
        static pointer allocate(Alloc& a, size_type n, const_void_pointer hint);
 
        static void deallocate(Alloc& a, pointer p, size_type n);
 
        template <class T, class... Args>
            static void construct(Alloc& a, T* p, Args&&... args);
 
        template <class T>
            static void destroy(Alloc& a, T* p);
 
        static size_type max_size(const Alloc& a) noexcept;
 
        static Alloc select_on_container_copy_construction(const Alloc& rhs);
    };
}

std::allocator

namespace std {
    template <class T> class allocator;
    // specialize for void:
    template <> class allocator<void> {
    public:
        typedef void*           pointer;
        typedef const void*     const_pointer;
        // reference-to-void members are impossible.
        typedef void            value_type;
        template <class U> struct rebind { typedef allocator<U> other; };
    };
    template <class T> class allocator {
    public:
        typedef size_t          size_type;
        typedef ptrdiff_t       difference_type;
        typedef T*              pointer;
        typedef const T*        const_pointer;
        typedef T&              reference;
        typedef const T&        const_reference;
        typedef T               value_type;
        template <class U> struct rebind { typedef allocator<U> other; };
        typedef true_type       propagate_on_container_move_assignment;
        typedef true_type       is_always_equal;
 
        allocator() noexcept;
        allocator(const allocator&) noexcept;
        template <class U> allocator(const allocator<U>&) noexcept;
        ~allocator();
 
        pointer address(reference x) const noexcept;
        const_pointer address(const_reference x) const noexcept;
 
        pointer allocate(
            size_type, allocator<void>::const_pointer hint = 0);
        void deallocate(pointer p, size_type n);
        size_type max_size() const noexcept;
 
        template<class U, class... Args>
            void construct(U* p, Args&&... args);
        template <class U>
            void destroy(U* p);
    };
}

std::raw_storage_iterator

namespace std {
    template <class OutputIterator, class T>
    class raw_storage_iterator
        : public iterator<output_iterator_tag,void,void,void,void> {
    public:
        explicit raw_storage_iterator(OutputIterator x);
 
        raw_storage_iterator&    operator*();
        raw_storage_iterator&    operator=(const T& element);
        raw_storage_iterator&    operator++();
        raw_storage_iterator    operator++(int);
    };
}

std::default_delete

namespace std {
    template <class T> struct default_delete {
        constexpr default_delete() noexcept = default;
        template <class U> default_delete(const default_delete<U>&) noexcept;
        void operator()(T*) const;
    };
 
    template <class T> struct default_delete<T[]> {
        constexpr default_delete() noexcept = default;
        template <class U> default_delete(const default_delete<U[]>&) noexcept;
        template <class U> void operator()(U* ptr) const;
    };
}

std::unique_ptr

namespace std {
    //  unique_ptr for single objects
    template <class T, class D = default_delete<T>> class unique_ptr {
    public:
        typedef /*depends*/ pointer;
        typedef T element_type;
        typedef D deleter_type;
 
        // 20.8.1.2.1, constructors
        constexpr unique_ptr() noexcept;
        explicit unique_ptr(pointer p) noexcept;
        unique_ptr(pointer p, /*depends*/ d1) noexcept;
        unique_ptr(pointer p, /*depends*/ d2) noexcept;
        unique_ptr(unique_ptr&& u) noexcept;
        constexpr unique_ptr(nullptr_t) noexcept
            : unique_ptr() { }
        template <class U, class E>
            unique_ptr(unique_ptr<U, E>&& u) noexcept;
 
        // 20.8.1.2.2, destructor
        ~unique_ptr();
 
        // 20.8.1.2.3, assignment
        unique_ptr& operator=(unique_ptr&& u) noexcept;
        template <class U, class E> unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
        unique_ptr& operator=(nullptr_t) noexcept;
 
        // 20.8.1.2.4, observers
        add_lvalue_reference_t<T> operator*() const;
        pointer operator->() const noexcept;
        pointer get() const noexcept;
        deleter_type& get_deleter() noexcept;
        const deleter_type& get_deleter() const noexcept;
        explicit operator bool() const noexcept;
 
        // 20.8.1.2.5 modifiers
        pointer release() noexcept;
        void reset(pointer p = pointer()) noexcept;
        void swap(unique_ptr& u) noexcept;
 
        // disable copy from lvalue
        unique_ptr(const unique_ptr&) = delete;
        unique_ptr& operator=(const unique_ptr&) = delete;
    };
 
    // unique_ptr for array objects with a runtime length
    template <class T, class D> class unique_ptr<T[], D> {
    public:
        typedef see below pointer;
        typedef T element_type;
        typedef D deleter_type;
 
        // 20.8.1.3.1, constructors
        constexpr unique_ptr() noexcept;
        template <class U> explicit unique_ptr(U p) noexcept;
        template <class U> unique_ptr(U p, see below d) noexcept;
        template <class U> unique_ptr(U p, see below d) noexcept;
        unique_ptr(unique_ptr&& u) noexcept;
        template <class U, class E>
            unique_ptr(unique_ptr<U, E>&& u) noexcept;
        constexpr unique_ptr(nullptr_t) noexcept : unique_ptr() { }
 
        // destructor
        ~unique_ptr();
 
        // assignment
        unique_ptr& operator=(unique_ptr&& u) noexcept;
        template <class U, class E>
            unique_ptr& operator=(unique_ptr<U, E>&& u) noexcept;
        unique_ptr& operator=(nullptr_t) noexcept;
 
        // 20.8.1.3.3, observers
        T& operator[](size_t i) const;
        pointer get() const noexcept;
        deleter_type& get_deleter() noexcept;
        const deleter_type& get_deleter() const noexcept;
        explicit operator bool() const noexcept;
 
        // 20.8.1.3.4 modifiers
        pointer release() noexcept;
        template <class U> void reset(U p) noexcept;
        void reset(nullptr_t = nullptr) noexcept;
        void swap(unique_ptr& u) noexcept;
 
        // disable copy from lvalue
        unique_ptr(const unique_ptr&) = delete;
        unique_ptr& operator=(const unique_ptr&) = delete;
    };
 
}

std::bad_weak_ptr

namespace std {
    class bad_weak_ptr: public std::exception {
    public:
        bad_weak_ptr() noexcept;
    };
} // namespace std

std::shared_ptr

namespace std {
    template<class T> class shared_ptr {
    public:
        typedef T element_type;
 
        // 20.8.2.2.1, constructors:
        constexpr shared_ptr() noexcept;
        template<class Y> explicit shared_ptr(Y* p);
        template<class Y, class D> shared_ptr(Y* p, D d);
        template<class Y, class D, class A> shared_ptr(Y* p, D d, A a);
        template <class D> shared_ptr(nullptr_t p, D d);
        template <class D, class A> shared_ptr(nullptr_t p, D d, A a);
        template<class Y> shared_ptr(const shared_ptr<Y>& r, T* p) noexcept;
        shared_ptr(const shared_ptr& r) noexcept;
        template<class Y> shared_ptr(const shared_ptr<Y>& r) noexcept;
        shared_ptr(shared_ptr&& r) noexcept;
        template<class Y> shared_ptr(shared_ptr<Y>&& r) noexcept;
        template<class Y> explicit shared_ptr(const weak_ptr<Y>& r);
        template <class Y, class D> shared_ptr(unique_ptr<Y, D>&& r);
        constexpr shared_ptr(nullptr_t) noexcept : shared_ptr() { }
 
        // 20.8.2.2.2, destructor:
        ~shared_ptr();
 
        // 20.8.2.2.3, assignment:
        shared_ptr& operator=(const shared_ptr& r) noexcept;
        template<class Y> shared_ptr& operator=(const shared_ptr<Y>& r) noexcept;
        shared_ptr& operator=(shared_ptr&& r) noexcept;
        template<class Y> shared_ptr& operator=(shared_ptr<Y>&& r) noexcept;
        template <class Y, class D> shared_ptr& operator=(unique_ptr<Y, D>&& r);
 
        // 20.8.2.2.4, modifiers:
        void swap(shared_ptr& r) noexcept;
        void reset() noexcept;
        template<class Y> void reset(Y* p);
        template<class Y, class D> void reset(Y* p, D d);
        template<class Y, class D, class A> void reset(Y* p, D d, A a);
 
        // 20.8.2.2.5, observers:
        T* get() const noexcept;
        T& operator*() const noexcept;
        T* operator->() const noexcept;
        long use_count() const noexcept;
        bool unique() const noexcept;
        explicit operator bool() const noexcept;
        template<class U> bool owner_before(shared_ptr<U> const& b) const;
        template<class U> bool owner_before(weak_ptr<U> const& b) const;
    };
}

std::weak_ptr

namespace std {
    template<class T> class weak_ptr {
    public:
        typedef T element_type;
 
        // 20.8.2.3.1, constructors
        constexpr weak_ptr() noexcept;
        template<class Y> weak_ptr(shared_ptr<Y> const& r) noexcept;
        weak_ptr(weak_ptr const& r) noexcept;
        template<class Y> weak_ptr(weak_ptr<Y> const& r) noexcept;
        weak_ptr(weak_ptr&& r) noexcept;
        template<class Y> weak_ptr(weak_ptr<Y>&& r) noexcept;
 
        // 20.8.2.3.2, destructor
        ~weak_ptr();
 
        // 20.8.2.3.3, assignment
        weak_ptr& operator=(weak_ptr const& r) noexcept;
        template<class Y> weak_ptr& operator=(weak_ptr<Y> const& r) noexcept;
        template<class Y> weak_ptr& operator=(shared_ptr<Y> const& r) noexcept;
        weak_ptr& operator=(weak_ptr&& r) noexcept;
        template<class Y> weak_ptr& operator=(weak_ptr<Y>&& r) noexcept;
 
        // 20.8.2.3.4, modifiers
        void swap(weak_ptr& r) noexcept;
        void reset() noexcept;
 
        // 20.8.2.3.5, observers
        long use_count() const noexcept;
        bool expired() const noexcept;
        shared_ptr<T> lock() const noexcept;
        template<class U> bool owner_before(shared_ptr<U> const& b) const;
        template<class U> bool owner_before(weak_ptr<U> const& b) const;
    };
} // namespace std

std::enable_shared_from_this

namespace std {
    template<class T> class enable_shared_from_this {
    protected:
        constexpr enable_shared_from_this() noexcept;
        enable_shared_from_this(enable_shared_from_this const&) noexcept;
        enable_shared_from_this& operator=(enable_shared_from_this const&) noexcept;
        ~enable_shared_from_this();
    public:
        shared_ptr<T> shared_from_this();
        shared_ptr<T const> shared_from_this() const;
    };
} // namespace std

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/header/memory