std::sample(3)

💖 NAME 💖

okay so bestie, this is std::sample — and yes, the name is literally std::sample. the manual page is std::sample(3) from the C++ Standard Library, and it is giving random-sampling main character energy. no cap. ✨

---

✨ Synopsis ✨

Defined in header <algorithm>

template< class PopulationIt, class SampleIt, class Distance, class URBG >
SampleIterator sample( PopulationIt first, PopulationIt last,
                       SampleIt out, Distance n, URBG&& g );

(since C++17), bestie. 🫶

So what does it do? It selects n elements from the sequence [first, last) (without replacement) such that each possible sample has equal probability of appearance, and writes those selected elements into the output iterator out. Random numbers are generated using the random number generator g.

If n is greater than the number of elements in the sequence, it selects all elements in the sequence. slay.

The algorithm is stable (preserves the relative order of the selected elements) only if PopulationIt meets the requirements of LegacyForwardIterator. so like, stability is not automatic, bestie.

Also: if the value type of first (until C++20) or *first (since C++20) is not writable to out, the program is ill-formed. not a vibe check you want to fail 😭

If any of the following conditions is satisfied, the behavior is undefined — and UB is not a cute look:

• out is in [first, last).
• PopulationIt does not meet the requirements of LegacyInputIterator.
• SampleIt does not meet the requirements of LegacyOutputIterator.
• All following conditions are satisfied:
  • PopulationIt does not meet the requirements of LegacyForwardIterator. (until C++23)
  • PopulationIt does not model forward_iterator. (since C++23)
  • SampleIt does not meet the requirements of LegacyRandomAccessIterator.
• Given the type T as std::remove_reference_t<URBG>, any of the following conditions is satisfied:
  • T does not meet the requirements of UniformRandomBitGenerator.
  • The return type of T is not convertible to Distance. (until C++20)

---

🌸 Parameters 🌸

• first, last — pair of iterators forming the range from which to make the sampling (the population).
• out — the output iterator where the samples are written.
• n — number of samples to make.
• g — the random number generator used as the source of randomness.

---

🎀 Type requirements 🎀

• Distance must be an integer type.

---

🦋 Return value 🦋

Returns a copy of out after the last sample that was output, that is, end of the sample range. so it hands you back the end of the sample range, periodt. 💅

---

⭐ Complexity ⭐

Linear in std::distance(first, last). lowkey tidy. ✨

---

💅 Possible implementation 💅

See the implementations in libstdc++, libc++ and MSVC STL. the page is just pointing you at the real ones, iykyk.

---

🍓 Notes 🍓

This function may implement selection sampling or reservoir sampling. literally either vibe.

Feature-test macro table, translated into bestie bullets because tables are not the moment:

• Feature-test macro: __cpp_lib_sample
• Value: 201603L
• Std: (C++17)
• Feature: std::sample

---

🌈 Example 🌈

the page marks this // Run this code, so here it is exactly:

#include <algorithm>
#include <iostream>
#include <iterator>
#include <random>
#include <string>

int main()
{
    std::string in {"ABCDEFGHIJK"}, out;
    std::sample(in.begin(), in.end(), std::back_inserter(out), 4,
                std::mt19937 {std::random_device{}()});
    std::cout << "Four random letters out of " << in << " : " << out << '\n';
}

Possible output: Four random letters out of ABCDEFGHIJK: EFGK

random, so your letters may absolutely serve a different look. 🎀

---

👑 See also 👑

• random_shuffle — randomly re-orders elements in a range (until C++17) (function template)
• shuffle — randomly re-orders elements in a range (C++11) (function template)
• ranges::sample — selects N random elements from a sequence (C++20) (niebloid)

---

mwah 💋 that's the whole page, bestie. footer sign-off: source/version http://cppreference.com, date 2024.06.10, page std::sample(3). periodt. 🫶