QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE Namespace Reference

Namespaces
namespace	QDOC_CATCH_GENERATORS_TRAITS_NAMESPACE

Classes
struct	DistributionError
class	GeneratorHandler

Typedefs
template<typename T >
using	Histogram = std::unordered_map<T, std::size_t>

Functions
template<typename T >
std::remove_reference_t< T >	copy_value (T value)
	Forces \value to be copied in an expression context.
template<typename T >
Catch::Generators::GeneratorWrapper< T >	handler (Catch::Generators::GeneratorWrapper< T > &&generator)
	Returns a generator wrapping generator that ensures that changes its semantics so that the first call to get should be preceded by a call to next.
template<typename... MoveOnlyTypes>
auto	move_into_vector (MoveOnlyTypes... movables)
	Builds an std::vector by moving movables into it.
template<typename InputIt , typename GroupBy >
auto	make_histogram (InputIt begin, InputIt end, GroupBy &&group_by)
template<typename T >
std::ostream &	operator<< (std::ostream &os, const DistributionError< T > &error)
template<typename T , typename GroupBy , typename ProbabilityOf >
std::optional< DistributionError< T > >	respects_distribution (std::vector< T > &&sequence, GroupBy &&group_by, ProbabilityOf &&probability_of, double margin=33)
	Returns true when the given sequence approximately respects a given distribution.
double	percent_of (double amount, double total)
	Returns the percentage of \amount over total.
double	uniform_probability (std::size_t cardinality)
	Given the cardinality of a set, returns the percentage probability that applied to every element of the set generates a uniform distribution.
double	probability_to_percentage (double probability)
	Returns a percentage probability that is equal to probability.

Typedef Documentation

Histogram

template<typename T >

using QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::Histogram = std::unordered_map<T, std::size_t>

Definition at line 16 of file distribution.h.

Function Documentation

copy_value()

template<typename T >

std::remove_reference_t< T > QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::copy_value

(

T

value

)

Forces \value to be copied in an expression context.

This is used in contexts where inferences of a type that requires generality might identify a reference when ownership is required.

Note that the compiler might optmize the copy away. This is a non-issue as we are only interested in breaking lifetime dependencies.

Definition at line 24 of file copy_value.h.

handler()

template<typename T >

Catch::Generators::GeneratorWrapper< T > QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::handler ( Catch::Generators::GeneratorWrapper< T > && generator )

inline

Returns a generator wrapping generator that ensures that changes its semantics so that the first call to get should be preceded by a call to next.

Catch generators require that is valid to call get and obtain a valid value on a generator that was just created. That is, generators should be non-empty and their first value should be initialized on construction.

Normally, this is not a problem, and the next implementation of the generator can be simply called in the constructor. But when a generator depends on other generators, doing so will generally skip the first value that the generator produces, as the wrapping generator will need to advance the underlying generator, losing the value in the process. This is in particular, a problem, on generators that are finite or infinite and ordered.

To solve the issue, the original value can be saved before advancing the generator or some code can be duplicated or abstracted so that what a new element can be generated without advancing the underlying generator.

While this is acceptable, it can be error prone on more complex generators, generators that randomly access a collection of generators and so on.

To simplify this process, this generator changes the semantics of the wrapped generator such that the first value of the generator is produced after the first call to next and the generator is considered in an invalid state before the first advancement.

In this way, by wrapping all generators that a generator depends on, the implementation required for the first value is the same as the one required for all following values, with regards to the sequencing of next and get operations, simplifying the implementation of dependent generators.

Do note that, while the generator returned by this function implments the generator interface that Catch2 requires, it cannot be normally used as a generator as it fails to comply with the first value semantics that a generator requires. Indeed, it should only be used as an intermediate wrapper for the implementation of generators that depends on other generators.

Definition at line 93 of file generator_handler.h.

make_histogram()

template<typename InputIt , typename GroupBy >

auto QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::make_histogram	(	InputIt	begin,
		InputIt	end,
		GroupBy &&	group_by )

Definition at line 19 of file distribution.h.

move_into_vector()

template<typename... MoveOnlyTypes>

auto QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::move_into_vector ( MoveOnlyTypes... movables )

inline

Builds an std::vector by moving movables into it.

movables must be made of homogenous types.

This function is intended to allow the construction of an std::vector<T>, where T is a move only type, as an expression, to lighten the idiom.

For example, Catch's GeneratorWrapper<T> adapts a std::unique_ptr, which is move only, making it impossible to build a std::vector from them in place.

Then, everywhere this is needed, a more complex approach of generating the collection of objects, generating a vector of a suitable size and iterating the objects to move-emplace them in the vector is required.

This not only complicates the code but is incompatible with a GENERATE expression, making it extremely hard, noisy and error prone to use them together.

In those cases, then, a call to move_into_vector can be used as an expression to circumvent the problem.

Definition at line 52 of file move_into_vector.h.

operator<<()

template<typename T >

std::ostream & QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::operator<< ( std::ostream & os, const DistributionError< T > & error )

inline

Definition at line 41 of file distribution.h.

percent_of()

double QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::percent_of ( double amount, double total )

inline

Returns the percentage of \amount over total.

amount needs to be greater or equal to zero and total needs to be greater than zero.

Definition at line 18 of file percentages.h.

Referenced by QDOC_CATCH_GENERATORS_ROOT_NAMESPACE::uniformly_valued_oneof().

Here is the caller graph for this function:

probability_to_percentage()

double QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::probability_to_percentage ( double probability )

inline

Returns a percentage probability that is equal to probability.

probability must be in the range [0.0, 1.0]

Definition at line 42 of file percentages.h.

respects_distribution()

template<typename T , typename GroupBy , typename ProbabilityOf >

std::optional< DistributionError< T > > QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::respects_distribution	(	std::vector< T > &&	sequence,
		GroupBy &&	group_by,
		ProbabilityOf &&	probability_of,
		double	margin = 33 )

Returns true when the given sequence approximately respects a given distribution.

The sequence respects a given distribution when the count of each collection of values is a percentage of the total values that is near the percentage probability described by distribution.

The values in sequence are collected according to group_by. group_by, given an element of sequence, should return a value of some type that represent the category of the inspected value. Values that have the same category share their count.

The distribution that should be respected is given by probability_of. probability_of is a function that takes a category that was produced from a call to group_by and returns the expect probability, in percentage, of apperance for that category.

The given probability is then compared to the one found by counting the element of sequence under group_by, to ensure that it matches.

The margin of error for the comparison is given, in percentage points, by margin. The approximation uses an absolute comparison and scales the margin inversely based on the size of sequence, to account for the precision of the data set itself.

When the distribution is not respected, a DistributionError is returned enclosed in an optional value. The error allows reports which the first category for which the comparison failed, along with its expected probability and the one that was actually inferred from sequence.

Definition at line 90 of file distribution.h.

uniform_probability()

double QDOC_CATCH_GENERATORS_UTILITIES_ABSOLUTE_NAMESPACE::uniform_probability ( std::size_t cardinality )

inline

Given the cardinality of a set, returns the percentage probability that applied to every element of the set generates a uniform distribution.

Definition at line 30 of file percentages.h.