std::uses_a...ruction_args(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

💖 NAME 💖

std::uses_allocator_construction_args — std::uses_allocator_construction_args. Yes bestie, that’s the NAME twice, no cap 😭. This is the std::uses_a...ruction_args(3) page from the C++ Standard Libary (their spelling, not mine 🫶), and it’s giving allocator propagation main-character energy.

🦋 SYNOPSIS 🦋

Defined in header <memory> 💖

First, the T is not a specialization of std::pair era:

  • (1) (since C++20)
template< class T, class Alloc, class... Args >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    Args&&... args ) noexcept;

Now the T is a specialization of std::pair era, aka the pair-pilled overloads 👑:

  • (2) (since C++20)
template< class T, class Alloc, class Tuple1, class Tuple2 >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    std::piecewise_construct_t, Tuple1&& x, Tuple2&& y ) noexcept;
  • (3) (since C++20)
template< class T, class Alloc >
constexpr auto uses_allocator_construction_args( const Alloc& alloc ) noexcept;
  • (4) (since C++20)
template< class T, class Alloc, class U, class V >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    U&& u, V&& v ) noexcept;
  • (5) (since C++23)
template< class T, class Alloc, class U, class V >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    std::pair<U, V>& pr ) noexcept;
  • (6) (since C++20)
template< class T, class Alloc, class U, class V >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    const std::pair<U, V>& pr ) noexcept;
  • (7) (since C++20)
template< class T, class Alloc, class U, class V >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    std::pair<U, V>&& pr ) noexcept;
  • (8) (since C++23)
template< class T, class Alloc, class U, class V >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    const std::pair<U, V>&& pr ) noexcept;
  • (9) (since C++20)
template< class T, class Alloc, class NonPair >
constexpr auto uses_allocator_construction_args( const Alloc& alloc,
    NonPair&& non_pair ) noexcept;

Prepares the argument list needed to create an object of the given type T by means of uses-allocator construction ✨.

How the overloads behave 💅

(1) This overload participates in overload resolution only if T is not a specialization of std::pair. Returns std::tuple determined as follows:

  • If std::uses_allocator_v<T, Alloc> is false and std::is_constructible_v<T, Args...> is true, returns std::forward_as_tuple(std::forward<Args>(args)...).
  • Otherwise, if std::uses_allocator_v<T, Alloc> is true and std::is_constructible_v<T, std::allocator_arg_t, const Alloc&, Args...> is true, returns std::tuple<std::allocator_arg_t, const Alloc&, Args&&...>(std::allocator_arg, alloc, std::forward<Args>(args)...).
  • Otherwise, if std::uses_allocator_v<T, Alloc> is true and std::is_constructible_v<T, Args..., const Alloc&> is true, returns std::forward_as_tuple(std::forward<Args>(args)..., alloc).
  • Otherwise, the program is ill-formed.

(2) This overload participates in overload resolution only if T is a specialization of std::pair. For T that is std::pair<T1, T2>, equivalent to:

return std::make_tuple(std::piecewise_construct,
    std::apply([&alloc](auto&&... args1)
        {
            return std::uses_allocator_construction_args<T1>(alloc,
                       std::forward<decltype(args1)>(args1)...);
        }, std::forward<Tuple1>(x)
    ),
    std::apply([&alloc](auto&&... args2)
        {
            return std::uses_allocator_construction_args<T2>(alloc,
                       std::forward<decltype(args2)>(args2)...);
        }, std::forward<Tuple2>(y)
    )
);

(3) This overload participates in overload resolution only if T is a specialization of std::pair. Equivalent to:

return std::uses_allocator_construction_args<T>(alloc,
    std::piecewise_construct, std::tuple<>{}, std::tuple<>{}
);

(4) This overload participates in overload resolution only if T is a specialization of std::pair. Equivalent to:

return std::uses_allocator_construction_args<T>(alloc,
    std::piecewise_construct,
    std::forward_as_tuple(std::forward<U>(u)),
    std::forward_as_tuple(std::forward<V>(v))
);

(5,6) This overload participates in overload resolution only if T is a specialization of std::pair. Equivalent to:

return std::uses_allocator_construction_args<T>(alloc,
    std::piecewise_construct,
    std::forward_as_tuple(pr.first),
    std::forward_as_tuple(pr.second)
);

(7,8) This overload participates in overload resolution only if T is a specialization of std::pair. Equivalent to:

return std::uses_allocator_construction_args<T>(alloc,
    std::piecewise_construct,
    std::forward_as_tuple(std::get<0>(std::move(pr))),
    std::forward_as_tuple(std::get<1>(std::move(pr)))
);

(9) This overload participates in overload resolution only if T is a specialization of std::pair, and given the exposition-only function template:

template<class A, class B>
void /*deduce-as-pair*/(const std::pair<A, B>&);

then /*deduce-as-pair*/(non_pair) is ill-formed when considered as an unevaluated operand.

Let the exposition-only class pair-constructor be defined as:

class /*pair-constructor*/
{
    const Alloc& alloc_; // exposition only
    NonPair&     u_;     // exposition only

    constexpr reconstruct(const std::remove_cv<T>& p) const // exposition only
    {
        return std::make_obj_using_allocator<std::remove_cv<T>>(alloc_, p);
    }

    constexpr reconstruct(std::remove_cv<T>&& p) const // exposition only
    {
        return std::make_obj_using_allocator<std::remove_cv<T>>(alloc_, std::move(p));
    }

public:
    constexpr operator std::remove_cv<T>() const
    {
        return reconstruct(std::forward<NonPair>(u_));
    }
};

This overload is equivalent to return std::make_tuple(pair_construction);, where pair_construction is a value of type pair-constructor whose alloc_ and u_ members are alloc and non_pair respectively.

🌸 PARAMETERS 🌸

  • alloc — the allocator to use.
  • args — the arguments to pass to T’s constructor.
  • x — tuple of arguments to pass to the constructors of T’s first data member.
  • y — tuple of arguments to pass to the constructors of T’s second data member.
  • u — single argument to pass to the constructor of T’s first data member.
  • v — single argument to pass to the constructor of T’s second data member.
  • pr — a pair whose first data member will be passed to the constructor of T’s first data member and second data member will be passed to the constructor of T’s second data member.
  • non_pair — single argument to convert to a std::pair for further construction.

🎀 RETURN VALUE 🎀

std::tuple of arguments suitable for passing to the constructor of T.

💜 NOTES 💜

The overloads (2-9) provide allocator propagation into std::pair, which supports neither leading-allocator nor trailing-allocator calling conventions (unlike, e.g. std::tuple, which uses leading-allocator convention). Ngl, std::pair is lowkey built different here 😭.

When used in uses-allocator construction, the conversion function of pair-constructor converts the provided argument to std::pair at first, and then constructs the result from that std::pair by uses-allocator construction.

🦋 EXAMPLE 🦋

This section is incomplete Reason: no example

🔥 DEFECT REPORTS 🔥

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

  • LWG 3525 — applied to C++20; behavior as published: no overload could handle non-pair types convertible to pair; correct behavior: reconstructing overload added.

⭐ SEE ALSO ⭐

  • uses_allocator (C++11) — checks if the specified type supports uses-allocator construction (class template).
  • make_obj_using_allocator (C++20) — creates an object of the given type by means of uses-allocator construction (function template).
  • uninitialized_construct_using_allocator (C++20) — creates an object of the given type at specified memory location by means of uses-allocator construction (function template).

🧚 CATEGORY 🧚

  • Todo no example

That’s the whole page, bestie 💋 — source: http://cppreference.com, version/date: 2024.06.10, and the manpage is std::uses_a...ruction_args(3). Mwah 🫶

📦 where this page comes from