std::ranges...rate_random(3)

🌸 NAME 🌸

okay so this is the C++ Standard Libary manual (yes, spelling exactly like that, respect the typo 💅), and the main character is std::ranges::generate_random - std::ranges::generate_random. That's the whole name, periodt. 🫶

---

✨ SYNOPSIS ✨

here's the exact synopsis, bestie — don't let the formatting jump-scare you:

          Defined in header <random>
          Call signature
          template< class R, class G >

              requires ranges::output_range<R, std::invoke_result_t<G&>> &&
       (since
                       std::uniform_random_bit_generator<std::remove_cvref_t<G>>
       (1) C++26)
          constexpr ranges::borrowed_iterator_t<R>

              generate_random( R&& r, G&& g );
          template< class G, std::output_iterator<std::invoke_result_t<G&>> O,

                    std::sentinel_for<O> S >
       (since
              requires
       std::uniform_random_bit_generator<std::remove_cvref_t<G>>   (2) C++26)
          constexpr O

              generate_random( O first, S last, G&& g );
          template< class R, class G, class D >

              requires ranges::output_range<R, std::invoke_result_t<D&, G&>> &&
                       std::invocable<D&, G&> &&
       (3) (since
                       std::uniform_random_bit_generator<std::remove_cvref_t<G>>
       C++26)
          constexpr ranges::borrowed_iterator_t<R>

              generate_random( R&& r, G&& g, D&& d );
          template< class G, class D,
          std::output_iterator<std::invoke_result_t<D&, G&>> O,

                    std::sentinel_for<O> S >
       (since
              requires std::invocable<D&, G&> &&
       (4) C++26)
                       std::uniform_random_bit_generator<std::remove_cvref_t<G>>
          constexpr O

              generate_random( O first, S last, G&& g, D&& d );

---

💖 DESCRIPTION 💖

Attempts to generate random numbers with the generate_random member function of the random number generator or the distribution, which is expected to be more efficient. Falls back to element-wise generation if no generate_random member function is available.

Let fallback operation be calling ranges::generate(std::forward<R>(r), std::ref(g)) or ranges::generate(std::forward<R>(r), [&d, &g] { return std::invoke(d, g); }) for (1) or (3) respectively.

• (1) — Calls g.generate_random(std::forward<R>(r)) if this expression is well-formed. Otherwise, let I be std::invoke_result_t<G&>. If R models sized_range, fills r with ranges::size(r) values of I by performing an unspecified number of invocations of the form g() or g.generate_random(s), if such an expression is well-formed for a value N and an object s of type std::span<I, N>. Otherwise, performs the fallback operation.
• (3) — Calls d.generate_random(std::forward<R>(r), g) if this expression is well-formed. Otherwise, let I be std::invoke_result_t<D&, G&>. If R models sized_range, fills r with ranges::size(r) values of type I by performing an unspecified number of invocations of the form std::invoke(d, g) or d.generate_random(s, g), if such an expression is well-formed for a value N and an object s of type std::span<I, N>. Otherwise, performs the fallback operation.
• (2,4) — Equivalent to (1,3) respectively, where r is obtained from ranges::subrange<O, S>(std::move(first), last).

⚠️ If the effects of (1) or (3) are not equivalent to those of the corresponding fallback operation, the behavior is undefined. That's undefined behavior, bestie — not cute, not slay, do not collect $200. 💀

The value of N can differ between invocations. Implementations may select smaller values for shorter ranges.

The function-like entities described on this page are niebloids, that is:

• Explicit template argument lists cannot be specified when calling any of them.
• None of them are visible to argument-dependent lookup.
• When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.

In practice, they may be implemented as function objects, or with special compiler extensions.

---

🦋 PARAMETERS 🦋

• first, last — iterator-sentinel pair that denotes the range to which random numbers are written
• r — range to which random numbers are written
• g — uniform random bit generator
• d — random number distribution object

---

🌈 NOTES 🌈

At the time of the standardization of std::ranges::generate_random, there is no random number generator or distribution in the standard library that provides a generate_random member function.

std::ranges::generate_random can be more efficient when used with a user-defined random number generator that wraps an underlying vectorized API.

feature-test macro tea ☕:

• __cpp_lib_ranges_generate_random — value 202403L — standard C++26 — feature std::ranges::generate_random

---

🍓 EXAMPLE 🍓

        // Run this code

        #include <algorithm>
        #include <iomanip>
        #include <iostream>
        #include <random>

        int main()
        {
            std::default_random_engine eng;
            std::default_random_engine::result_type rs[16]{};
            std::ranges::generate_random(rs, eng);

            std::cout << std::left;
            for (int i{}; auto n : rs)
                std::cout << std::setw(11) << n << (++i % 4 ? ' ' : '\n');
        }

✨ Possible output ✨

        16807       282475249   1622650073  984943658
        1144108930  470211272   101027544   1457850878
        1458777923  2007237709  823564440   1115438165
        1784484492  74243042    114807987   1137522503

---

👑 SEE ALSO 👑

• ranges::generate — saves the result of a function in a range (C++20) (niebloid)
• uniform_random_bit_generator — specifies that a type qualifies as a uniform random bit generator (C++20) (concept)

---

source/version: http://cppreference.com, date: 2024.06.10, page tag: std::ranges...rate_random(3) — mwah 💋✨