Standard library header <memory>

From cppreference.com
< cpp‎ | header

This header is part of the dynamic memory management library.

Contents

[edit] 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)

[edit] 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
(function template)
copies an object to an uninitialized area of memory
(function template)
an iterator that allows standard algorithms to store results in uninitialized memory
(class template)
obtains uninitialized storage
(function template)
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 or const_cast to the type of the managed object
(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 managed pointer to an output stream
(function template)
specializes the std::swap algorithm
(function template)
specializes atomic operations
(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)

[edit] 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;
}


[edit] 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;
    };
}

[edit] 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);
    };
}

[edit] 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);
    };
}

[edit] 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);
    };
}

[edit] 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;
    };
}

[edit] 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;
    };
 
}

[edit] std::bad_weak_ptr

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

[edit] 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;
    };
}

[edit] 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

[edit] 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