std::launder

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) is_within_lifetime (C++26) initializer_list (C++11) source_location (C++20) Three-way comparison three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20)   bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17) to_chars_result (C++17) from_chars_result (C++17)

 

Defined in header <new>
template <class T> constexpr T* launder(T* p) noexcept;		(since C++17) (until C++20)
template <class T> [[nodiscard]] constexpr T* launder(T* p) noexcept;		(since C++20)

Obtains a pointer to the object located at the address represented by p.

Formally, given

• the pointer p represents the address A of a byte in memory
• an object X is located at the address A
• X is within its lifetime
• the type of X is the same as T, ignoring cv-qualifiers at every level
• every byte that would be reachable through the result is reachable through p (bytes are reachable through a pointer that points to an object Y if those bytes are within the storage of an object Z that is pointer-interconvertible with Y, or within the immediately enclosing array of which Z is an element)

Then std::launder(p) returns a value of type T* that points to the object X. Otherwise, the behavior is undefined.

The program is ill-formed if T is a function type or (possibly cv-qualified) void.

std::launder may be used in a core constant expression if the value of its argument may be used in a core constant expression

Notes

Typical uses of std::launder include:

• Obtaining a pointer to an object created in the storage of an existing object of the same type, where pointers to the old object cannot be reused because the object has const or reference data members, or because either object is a base class subobject;
• Obtaining a pointer to an object created by placement new from a pointer to an object providing storage for that object.

Example

Run this code

#include <new>
#include <cstddef>
#include <cassert>
 
struct X {
  const int n; // note: X has a const member
  int m;
};
 
struct Y {
  int z;
};
 
struct A { 
    virtual int transmogrify();
};
 
struct B : A {
    int transmogrify() override { new(this) A; return 2; }
};
 
int A::transmogrify() { new(this) B; return 1; }
 
static_assert(sizeof(B) == sizeof(A));
 
int main()
{
  X *p = new X{3, 4};
  const int a = p->n;
  X* np = new (p) X{5, 6};    // p does not point to new object because X::n is const; np does
  const int b = p->n; // undefined behavior
  const int c = p->m; // undefined behavior (even though m is non-const, p can't be used)
  const int d = std::launder(p)->n; // OK, std::launder(p) points to new object
  const int e = np->n; // OK
 
  alignas(Y) std::byte s[sizeof(Y)];
  Y* q = new(&s) Y{2};
  const int f = reinterpret_cast<Y*>(&s)->z; // Class member access is undefined behavior:
                                             // reinterpret_cast<Y*>(&s) has value "pointer to s"
                                             // and does not point to a Y object 
  const int g = q->z; // OK
  const int h = std::launder(reinterpret_cast<Y*>(&s))->z; // OK
 
  A i;
  int n = i.transmogrify();
  // int m = i.transmogrify(); // undefined behavior
  int m = std::launder(&i)->transmogrify(); // OK
  assert(m + n == 3);
}