...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::container::node_handle
// In header: <boost/container/node_handle.hpp> template<typename NodeAllocator, typename KeyMapped = void> class node_handle { public: // types typedef priv_value_t value_type; typedef keymapped_t::key_type key_type; typedef keymapped_t::mapped_type mapped_type; typedef nator_traits::template portable_rebind_alloc< value_type >::type allocator_type; typedef priv_node_t container_node_type; // construct/copy/destruct node_handle() noexcept; node_handle(node_pointer, const nallocator_type &) noexcept; template<typename KeyMapped2> node_handle(node_handle< NodeAllocator, KeyMapped2 > &&, typename dtl::enable_if_c<((unsigned) dtl::is_same< KeyMapped, void >::value+(unsigned) dtl::is_same< KeyMapped2, void >::value)==1u >::type * = 0) noexcept; node_handle(node_handle &&) noexcept; node_handle & operator=(node_handle &&) noexcept; ~node_handle(); // friend functions friend void swap(node_handle &, node_handle &) noexcept(noexcept(x.swap(y)))); // public member functions value_type & value() const noexcept; key_type & key() const noexcept; mapped_type & mapped() const noexcept; allocator_type get_allocator() const; explicit operator bool() const noexcept; bool empty() const noexcept; void swap(node_handle &) noexcept(nator_traits::propagate_on_container_swap::value||nator_traits::is_always_equal::value)); node_pointer release() noexcept; node_pointer get() const noexcept; nallocator_type & node_alloc() noexcept; const nallocator_type & node_alloc() const noexcept; };
A node_handle is an object that accepts ownership of a single element from an associative container. It may be used to transfer that ownership to another container with compatible nodes. Containers with compatible nodes have the same node handle type. Elements may be transferred in either direction between container types in the same row:.
Container types with compatible nodes
map<K, T, C1, A> <-> map<K, T, C2, A>
map<K, T, C1, A> <-> multimap<K, T, C2, A>
set<K, C1, A> <-> set<K, C2, A>
set<K, C1, A> <-> multiset<K, C2, A>
If a node handle is not empty, then it contains an allocator that is equal to the allocator of the container when the element was extracted. If a node handle is empty, it contains no allocator.
node_handle
public
construct/copy/destructnode_handle() noexcept;
Effects: Initializes m_ptr to nullptr.
Postcondition: this->empty()
node_handle(node_pointer p, const nallocator_type & al) noexcept;
Effects: Constructs a node_handle
object initializing internal pointer with p. If p != nullptr copy constructs internal allocator from al.
template<typename KeyMapped2> node_handle(node_handle< NodeAllocator, KeyMapped2 > && nh, typename dtl::enable_if_c<((unsigned) dtl::is_same< KeyMapped, void >::value+(unsigned) dtl::is_same< KeyMapped2, void >::value)==1u >::type * = 0) noexcept;
Effects: Constructs a node_handle
object initializing internal pointer with a related nh's internal pointer and assigns nullptr to the later. If nh's internal pointer was not nullptr, move constructs internal allocator with nh's internal allocator and destroy nh's internal allocator.
Postcondition: nh.empty()
Note: Two node_handle
's are related if only one of KeyMapped template parameter of a node handle is void.
node_handle(node_handle && nh) noexcept;
Effects: Constructs a node_handle
object initializing internal pointer with nh's internal pointer and assigns nullptr to the later. If nh's internal pointer was not nullptr, move constructs internal allocator with nh's internal allocator and destroy nh's internal allocator.
Postcondition: nh.empty()
node_handle & operator=(node_handle && nh) noexcept;
Requires: Either this->empty(), or nator_traits::propagate_on_container_move_assignment is true, or node_alloc() == nh.node_alloc().
Effects: If m_ptr != nullptr, destroys the value_type subobject in the container_node_type object pointed to by m_ptr by calling nator_traits::destroy, then deallocates m_ptr by calling nator_traits::deallocate. Assigns nh.m_ptr to m_ptr. If this->empty() or nator_traits::propagate_on_container_move_assignment is true, move assigns nh.node_alloc() to node_alloc(). Assigns nullptr to nh.m_ptr and assigns nullopt to nh.node_alloc().
Returns: *this.
Throws: Nothing.
~node_handle();
Effects: If !this->empty(), destroys the value_type subobject in the container_node_type object pointed to by c by calling allocator_traits<impl_defined>::destroy, then deallocates m_ptr by calling nator_traits::rebind_traits<container_node_type>::deallocate.
node_handle
friend functionsfriend void swap(node_handle & x, node_handle & y) noexcept(noexcept(x.swap(y))));
Effects: x.swap(y).
node_handle
public member functionsvalue_type & value() const noexcept;
Requires: empty() == false.
Returns: A reference to the value_type subobject in the container_node_type object pointed to by m_ptr
Throws: Nothing.
key_type & key() const noexcept;
Requires: empty() == false.
Returns: A non-const reference to the key_type member of the value_type subobject in the container_node_type object pointed to by m_ptr.
Throws: Nothing.
Requires: Modifying the key through the returned reference is permitted.
mapped_type & mapped() const noexcept;
Requires: empty() == false.
Returns: A reference to the mapped_type member of the value_type subobject in the container_node_type object pointed to by m_ptr
Throws: Nothing.
allocator_type get_allocator() const;
Requires: empty() == false.
Returns: A copy of the internally hold allocator.
Throws: Nothing.
explicit operator bool() const noexcept;
Returns: m_ptr != nullptr.
bool empty() const noexcept;
Returns: m_ptr == nullptr.
void swap(node_handle & nh) noexcept(nator_traits::propagate_on_container_swap::value||nator_traits::is_always_equal::value));
Requires: this->empty(), or nh.empty(), or nator_traits::propagate_on_container_swap is true, or node_alloc() == nh.node_alloc().
Effects: Calls swap(m_ptr, nh.m_ptr). If this->empty(), or nh.empty(), or nator_traits::propagate_on_- container_swap is true calls swap(node_alloc(), nh.node_alloc()).
node_pointer release() noexcept;
Effects: If this->empty() returns nullptr, otherwise returns m_ptr resets m_ptr to nullptr and destroys the internal allocator.
Postcondition: this->empty()
Note: Non-standard extensions
node_pointer get() const noexcept;
Effects: Returns m_ptr.
Note: Non-standard extensions
nallocator_type & node_alloc() noexcept;
Effects: Returns a reference to the internal node allocator.
Note: Non-standard extensions
const nallocator_type & node_alloc() const noexcept;
Effects: Returns a reference to the internal node allocator.
Note: Non-standard extensions