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

```
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 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 functions

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

Effects: x.swap(y).

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

Boost C++ Libraries