Class template node

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

```
node_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 al.
```
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.
```
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);
```
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.
```
~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

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

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

Effects: x.swap(y).