Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit c5994560ca.
PrevUpHomeNext

Class template node_handle

boost::container::node_handle

Synopsis

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

Description

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

  1. node_handle() noexcept;

    Effects: Initializes m_ptr to nullptr.

    Postcondition: this->empty()

  2. 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.

  3. 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.

  4. 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()

  5. 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.

  6. ~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 functions

  1. friend void swap(node_handle & x, node_handle & y) noexcept(noexcept(x.swap(y))));

    Effects: x.swap(y).

node_handle public member functions

  1. value_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.

  2. 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.

  3. 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.

  4. allocator_type get_allocator() const;

    Requires: empty() == false.

    Returns: A copy of the internally hold allocator.

    Throws: Nothing.

  5. explicit operator bool() const noexcept;

    Returns: m_ptr != nullptr.

  6. bool empty() const noexcept;

    Returns: m_ptr == nullptr.

  7. 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()).

  8. 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

  9. node_pointer get() const noexcept;

    Effects: Returns m_ptr.

    Note: Non-standard extensions

  10. nallocator_type & node_alloc() noexcept;

    Effects: Returns a reference to the internal node allocator.

    Note: Non-standard extensions

  11. const nallocator_type & node_alloc() const noexcept;

    Effects: Returns a reference to the internal node allocator.

    Note: Non-standard extensions


PrevUpHomeNext