Namespaces
Variants
Views
Actions

node-handle

From cppreference.com
< cpp‎ | container
 
C++
 
Containers library
 


template</* unspecified */>
class /*node-handle*/;
 (since C++17)
(exposition only*)

A node handle is an object that accepts ownership of a single element from an associative containers and unordered associative containers. It may be used to transfer that ownership to another container with compatible nodes.

A node handle has two possible states:

  • It refers to an element extracted from a container, or
  • it is empty .

If a node handle is not empty, then it contains an allocator that is equal to the allocator of the previously extracted container.

For all map containers (std::map, std::multimap, std::unordered_map, and std::unordered_multimap) whose key_type is Key and mapped_type is T, the behavior of operations involving node handles is undefined if a user-defined specialization of std::pair exists for std::pair<Key, T> or std::pair<const Key, T>.

Contents

[edit] Nested types

Type Definition
key_type (map containers only) the key stored in the node[edit]
mapped_type (map containers only) the mapped part of the element stored in the node[edit]
value_type (set containers only) the element stored in the node[edit]
allocator_type the allocator to be used when destroying the element[edit]
container_node_type unspecified
(exposition-only member type*)
ator_traits std::allocator_traits<allocator_type>
(exposition-only member type*)

See AssociativeContainer and UnorderedAssociativeContainer for the actual definitions of the non-exposition-only nested types.

[edit] Data members

Member Description

typename ator_traits ::template
    rebind_traits<container_node_type >::pointer ptr_

a pointer to a container node containing the referred object[1]
(exposition-only member object*)
std::optional<allocator_type> alloc_ the allocator stored
(exposition-only member object*)
  1. ↑ The ownership of the pointed-to container node was already detached from the source container while extracting the element. Even if the lifetime of the source container has ended, the container node and the contained element are still accessible.

[edit] Member functions

node-handle ::node-handle

constexpr /*node-handle*/() noexcept;
 (1)
/*node-handle*/( /*node-handle*/&& other ) noexcept;
 (2) (constexpr since C++26)
1) The default constructor initializes the node handle to the empty state.
2) The move constructor takes ownership of the container element from other.
  • ptr_ is initialized with other.ptr_.
  • alloc_ is move constructed with other.alloc_.
  • Assigns nullptr to other.ptr_.
  • Assigns std::nullopt to other.ptr_.

Parameters

other - another node handle

Notes

There is no user-provided copy destructor. node-handle is not CopyConstructible.

Besides move construction and move assignment, a non-empty node-handle can only be created by calling the extract member functions of (unordered) associative containers.

node-handle ::operator=

/*node-handle*/& operator=( /*node-handle*/&& other );
 (constexpr since C++26)

The move assignment operator replaces state of *this with the state of other using move semantics.

  1. If ptr_ != nullptr is true, destroys the element referred to by *this by calling ator_traits ::destroy, then deallocates the storage for the referred element by calling ator_traits ::rebind_traits<container-node-type >::deallocate.
  2. Assigns other.ptr_ to ptr_ .
  3. If ator_traits ::propagate_on_container_move_assignment is true, move assigns other.alloc_ to alloc_ .
  4. Assigns nullptr to other.ptr_ and assigns std::nullopt to other.alloc_.

If the following values are all false, the behavior is undefined:

  • ator_traits ::propagate_on_container_move_assignment
  • !alloc_
  • alloc_ == other.alloc_

Parameters

other - another node handle

Return

*this

Exceptions

Throws nothing.

Notes

There is no user-provided copy assignment operator. node-handle is not CopyAssignable.

node-handle ::~node-handle

~/*node-handle*/();
 (constexpr since C++26)

If ptr_ != nullptr is true, destroys the element referred to by *this by calling ator_traits ::destroy, then deallocates the container element by calling ator_traits ::rebind_traits<container-node-type >::deallocate.

Otherwise, does nothing.

node-handle ::empty

bool empty() const noexcept;
 (constexpr since C++26)

Returns true if the node handle is empty, false otherwise.

Return value

ptr_ == nullptr

node-handle ::operator bool

explicit operator bool() const noexcept;
 (constexpr since C++26)

Converts to false if the node handle is empty, true otherwise.

Return value

ptr_ != nullptr

node-handle ::get_allocator

allocator_type get_allocator() const;
 (constexpr since C++26)

Returns a copy of the stored allocator.

If empty() is true, the behavior is undefined.

Return value

*alloc_

Exceptions

Throws nothing.

node-handle ::value (set containers only)

value_type& value() const;
 (constexpr since C++26)

Returns a reference to the element referred to by *this.

If empty() is true, the behavior is undefined.

Return value

As described above.

Exceptions

Throws nothing.

node-handle ::key (map containers only)

key_type& key() const;
 (constexpr since C++26)

Returns a non-const reference to the key_type member of the element referred to by *this.

If empty() is true, the behavior is undefined.

Return value

As described above.

Exceptions

Throws nothing.

Notes

This function makes it possible to modify the key of a node extracted from a map, and then re-insert it into the map, without ever copying or moving the element.

node-handle ::mapped (map containers only)

mapped_type& mapped() const;
 (constexpr since C++26)

Returns a reference to the mapped_type member of the element referred to by *this.

If empty() is true, the behavior is undefined.

Return value

As described above.

Exceptions

Throws nothing.

node-handle ::swap

void swap( /*node-handle*/& other ) noexcept(/* see below */);
 (constexpr since C++26)

Calls swap(ptr_ , nh.ptr_ ). If any of the following values is true, also calls swap(alloc_ , nh.alloc_ ):

  • ator_traits ::propagate_on_container_swap
  • !alloc_
  • !other.alloc_

If the following values are all false, the behavior is undefined:

  • ator_traits ::propagate_on_container_swap
  • !alloc_
  • !other.alloc_
  • alloc_ == other.alloc_

Exceptions

noexcept specification:  
noexcept(ator_traits::propagate_on_container_swap::value ||
         ator_traits::is_always_equal::value)

[edit] Non-member functions

std::swap(node-handle )

friend void swap(/*node-handle*/& lhs, /*node-handle*/& rhs)
    noexcept(noexcept(lhs.swap(rhs)));
 (constexpr since C++26)

Effectively executes x.swap(y).

This function is not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when node-handle is an associated class of the arguments.

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/node_handle&oldid=182614"