| Home | Libraries | People | FAQ | More

## Class template node_handle

boost::container::node_handle

## Synopsis

    // In header: <boost/container/node_handle.hpp>

    template<typename NodeType, typename Value, typename Allocator,
             typename KeyMapped = void>
    class node_handle {
    public:
      // types
      typedef Value                    value_type;
      typedef keymapped_t::key_type    key_type;
      typedef keymapped_t::mapped_type mapped_type;
      typedef Allocator                allocator_type;
      typedef NodeType                 container_node_type;

      // construct/copy/destruct
      node_handle() noexcept;
      node_handle(node_pointer, const nallocator_type &) noexcept;
      template<typename KeyMapped2>
        node_handle(node_handle< NodeType, Value, Allocator, KeyMapped2 > &&,
                    unspecified = 0);
      node_handle(node_handle &&) noexcept;
      node_handle & operator=(node_handle &&);
      ~node_handle();

      // 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(ator_traits::propagate_on_container_swap::value||ator_traits::is_always_equal::value));

      // friend functions
      friend void swap(node_handle &, node_handle &) noexcept(BOOST_NOEXCEPT(x.swap(y))));
    };

## 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 al.

3.     template<typename KeyMapped2>
         node_handle(node_handle< NodeType, Value, Allocator, KeyMapped2 > && nh,
                     unspecified = 0);

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

   Requires: Either this->empty(), or ator_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 ator_traits::destroy, then deallocates m_ptr by calling ator_- traits::rebind_traits<container_node_type>::deallocate. Assigns nh.m_ptr to m_ptr. If this->empty() or ator_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 ator_traits::rebind_traits<container_node_type>::deallocate.

### `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(ator_traits::propagate_on_container_swap::value||ator_traits::is_always_equal::value));

   Requires: this->empty(), or nh.empty(), or ator_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 ator_traits::propagate_on_- container_swap is true calls swap(node_alloc(), nh.node_alloc()).

### `node_handle` friend functions

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

   Effects: x.swap(y).