#include <muu/tagged_ptr.h>
template <typename T, size_t Align = impl::tptr_min_align<T>>
muu::tagged_ptr class

Specialized pointer capable of storing data in the unused bits of a pointer's value.

Template parameters
T The type being pointed to.
Align Minimum alignment of values stored in the tagged_ptr. Default is alignof(T), but you may override it if you know you will only be storing values with larger alignments.

Public types

using const_pointer = std::add_pointer_t<std::add_const_t<T>>
A pointer to element_type (const-qualified).
using element_type = T
The type being pointed to.
using pointer = std::add_pointer_t<T>
A pointer to element_type.
using tag_type = typename base::tag_type
An unsigned integer just large enough to store all the bits in the tag area.

Public static variables

static size_t alignment constexpr
The minimum alignment of values stored in this pointer.
static tag_type max_tag constexpr
The largest integral value that can be stored in the available tag bits.
static size_t tag_bit_count constexpr
The number of tag bits available.

Public static functions

static auto can_store_ptr(pointer value) -> bool noexcept
Checks if a raw pointer can be safely stored without clipping into the tag bits.
template <typename Tag>
static auto can_store_tag(const Tag& tag_value) -> bool constexpr noexcept
Checks if a tag value can be safely stored without clipping into the pointer bits.

Constructors, destructors, conversion operators

operator bool() const explicit constexpr noexcept
Returns true if the target pointer value is not nullptr.
operator pointer() const explicit noexcept
Returns the target pointer value.
tagged_ptr() defaulted constexpr noexcept
Constructs a null pointer with all tag bits initialized to zero.
tagged_ptr(std::nullptr_t) constexpr noexcept
Constructs a null pointer with all tag bits initialized to zero.
tagged_ptr(pointer value) explicit noexcept
Constructs a tagged pointer.
template <typename Tag>
tagged_ptr(pointer value, const Tag& tag_value) noexcept
Constructs a tagged pointer.
tagged_ptr(const tagged_ptr&) defaulted constexpr noexcept
Copy constructor.
~tagged_ptr() defaulted noexcept
Destructor.

Public functions

auto clear_ptr() -> tagged_ptr& constexpr noexcept
Sets the target pointer value to nullptr, leaving the tag bits unchanged.
auto clear_tag() -> tagged_ptr& constexpr noexcept
Sets the tag bits to zero, leaving the target pointer value unchanged.
auto get() const -> pointer noexcept
Returns the target pointer value.
template <typename... U>
auto operator()(U && ... args) const -> decltype(auto) noexcept(…)
Invokes the function call operator on the pointed function.
auto operator*() const -> element_type& noexcept
Returns a reference to the pointed object.
auto operator->() const -> pointer noexcept
Returns the target pointer value.
auto operator=(const tagged_ptr&) -> tagged_ptr& defaulted constexpr noexcept
Copy-assignment operator.
auto operator=(pointer rhs) -> tagged_ptr& noexcept
Sets the target pointer value, leaving the tag bits unchanged.
auto ptr() const -> pointer noexcept
Returns the target pointer value.
auto ptr(pointer value) -> tagged_ptr& noexcept
Sets the target pointer value, leaving the tag bits unchanged.
auto reset() -> tagged_ptr& constexpr noexcept
Sets the target pointer value and all tag bits to zero.
auto reset(pointer value) -> tagged_ptr& noexcept
Resets the target pointer value and sets the tag bits to zero.
template <typename Tag>
auto reset(pointer value, const Tag& tag_value) -> tagged_ptr& noexcept
Resets the target pointer value and tag.
template <typename Tag = tag_type>
auto tag() const -> Tag noexcept
Returns the tag bits as an integer, enum, or trivial object type.
template <typename Tag>
auto tag(const Tag& tag_value) -> tagged_ptr& noexcept
Sets the tag bits, leaving the target pointer value unchanged.
auto tag_bit(size_t tag_bit_index) const -> bool noexcept
Returns the value of one of the tag bits.
auto tag_bit(size_t tag_bit_index, bool val) -> tagged_ptr& noexcept
Sets the value of one of the tag bits.

Friends

auto operator!=(tagged_ptr lhs, const_pointer rhs) -> bool noexcept
Returns true if a tagged_ptr and raw pointer do not refer to the same address.
auto operator!=(const_pointer lhs, tagged_ptr rhs) -> bool noexcept
Returns true if a tagged_ptr and raw pointer do not refer to the same address.
auto operator!=(tagged_ptr lhs, tagged_ptr rhs) -> bool constexpr noexcept
Returns true if two tagged_ptrs are not equal (including their tag bits).
auto operator==(tagged_ptr lhs, const_pointer rhs) -> bool noexcept
Returns true if a tagged_ptr and raw pointer refer to the same address.
auto operator==(const_pointer lhs, tagged_ptr rhs) -> bool noexcept
Returns true if a tagged_ptr and raw pointer refer to the same address.
auto operator==(tagged_ptr lhs, tagged_ptr rhs) -> bool constexpr noexcept
Returns true if two tagged_ptrs are equal (including their tag bits).

Function documentation

template <typename T, size_t Align>
static bool muu::tagged_ptr::can_store_ptr(pointer value) noexcept

Checks if a raw pointer can be safely stored without clipping into the tag bits.

Returns True if the given raw pointer is sufficiently aligned and does not already contain any tag bits.

template <typename T, size_t Align>
template <typename Tag>
static bool muu::tagged_ptr::can_store_tag(const Tag& tag_value) constexpr noexcept

Checks if a tag value can be safely stored without clipping into the pointer bits.

Returns True if the given tag value is of a compatible type (trivial, integer/enum/POD, small enough, etc.) and would not collide with any bits in the pointer region.

template <typename T, size_t Align>
muu::tagged_ptr::tagged_ptr(pointer value) explicit noexcept

Constructs a tagged pointer.

Parameters
value The initial address of the pointer's target.

Tag bits are initialized to zero.

template <typename T, size_t Align>
template <typename Tag>
muu::tagged_ptr::tagged_ptr(pointer value, const Tag& tag_value) noexcept

Constructs a tagged pointer.

Template parameters
Tag An integer, enum, or a trivial object type small enough to fit.
Parameters
value The initial address of the pointer's target.
tag_value The initial value of the pointer's tag bits.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::clear_ptr() constexpr noexcept

Sets the target pointer value to nullptr, leaving the tag bits unchanged.

Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::clear_tag() constexpr noexcept

Sets the tag bits to zero, leaving the target pointer value unchanged.

Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
pointer muu::tagged_ptr::get() const noexcept

Returns the target pointer value.

template <typename T, size_t Align>
template <typename... U>
decltype(auto) muu::tagged_ptr::operator()(U && ... args) const noexcept(…)

Invokes the function call operator on the pointed function.

Template parameters
U Argument types.
Parameters
args The arguments to pass to the pointed function.
Returns The return value of the function call.

template <typename T, size_t Align>
element_type& muu::tagged_ptr::operator*() const noexcept

Returns a reference to the pointed object.

template <typename T, size_t Align>
pointer muu::tagged_ptr::operator->() const noexcept

Returns the target pointer value.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::operator=(pointer rhs) noexcept

Sets the target pointer value, leaving the tag bits unchanged.

Parameters
rhs The new target pointer value.
Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::ptr(pointer value) noexcept

Sets the target pointer value, leaving the tag bits unchanged.

Parameters
value The new target pointer value.
Returns A reference to a tagged_ptr.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::reset() constexpr noexcept

Sets the target pointer value and all tag bits to zero.

Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::reset(pointer value) noexcept

Resets the target pointer value and sets the tag bits to zero.

Parameters
value The new target pointer value.
Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
template <typename Tag>
tagged_ptr& muu::tagged_ptr::reset(pointer value, const Tag& tag_value) noexcept

Resets the target pointer value and tag.

Template parameters
Tag An integer, enum, or a trivial object type small enough to fit.
Parameters
value The new target pointer value.
tag_value The new tag.
Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
template <typename Tag>
tagged_ptr& muu::tagged_ptr::tag(const Tag& tag_value) noexcept

Sets the tag bits, leaving the target pointer value unchanged.

Template parameters
Tag An integer, enum, or a trivial object type small enough to fit.
Parameters
tag_value The new value to set for the pointer's tag bits.
Returns A reference to the tagged_ptr.

template <typename T, size_t Align>
tagged_ptr& muu::tagged_ptr::tag_bit(size_t tag_bit_index, bool val) noexcept

Sets the value of one of the tag bits.

Parameters
tag_bit_index Zero-based index of the tag bit.
val The bit state to set.
Returns A reference to the tagged_ptr.