uniform distribution

group turbo_random_uniform

Functions

template<typename R = void, typename TagType, typename URBG>
std::enable_if_t<!std::is_same<R, void>::value, R> uniform(TagType tag, URBG &&urbg, R lo, R hi)

produces random values of type T uniformly distributed in a defined interval {lo, hi}.

The interval tag defines the type of interval which should be one of the following possible values:

  • turbo::IntervalOpenOpen

  • turbo::IntervalOpenClosed

  • turbo::IntervalClosedOpen

  • turbo::IntervalClosedClosed

where “open” refers to an exclusive value (excluded) from the output, while “closed” refers to an inclusive value (included) from the output.

In the absence of an explicit return type T, turbo::uniform() will deduce the return type based on the provided endpoint arguments {A lo, B hi}. Given these endpoints, one of {A, B} will be chosen as the return type, if a type can be implicitly converted into the other in a lossless way. The lack of any such implicit conversion between {A, B} will produce a compile-time error

See https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)

Example: 

cpp
      turbo::BitGen bitgen;

      // Produce a random float value between 0.0 and 1.0, inclusive
      auto x = turbo::uniform(turbo::IntervalClosedClosed, bitgen, 0.0f, 1.0f);

      // The most common interval of `turbo::IntervalClosedOpen` is available by
      // default:

      auto x = turbo::uniform(bitgen, 0.0f, 1.0f);

      // Return-types are typically inferred from the arguments, however callers
      // can optionally provide an explicit return-type to the template.

      auto x = turbo::uniform<float>(bitgen, 0, 1);

Parameters:

  • tag – defines the type of interval, which should be one of the following possible values:

    • turbo::IntervalOpenOpen

    • turbo::IntervalOpenClosed

    • turbo::IntervalClosedOpen

    • turbo::IntervalClosedClosed

  • urbg – a uniform random bit generator

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename TagType>
std::enable_if_t<!std::is_same<R, void>::value && is_random_tag<TagType>::value, R> uniform(TagType tag, R lo, R hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses the default engine, which is a thread-local instance of turbo::BitGen

See also

turbo::uniform(tag, urbg, lo, hi)

See also

get_tls_bit_gen()

See also

set_tls_bit_gen()

Note

This function is thread-safe.

Parameters:

  • tag – defines the type of interval, which should be one of the following possible values:

    • turbo::IntervalOpenOpen

    • turbo::IntervalOpenClosed

    • turbo::IntervalClosedOpen

    • turbo::IntervalClosedClosed

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename TagType>
std::enable_if_t<!std::is_same<R, void>::value && is_random_tag<TagType>::value, R> fast_uniform(TagType tag, R lo, R hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses the default engine, which is a thread-local instance of turbo::InsecureBitGen

See also

turbo::uniform(tag, urbg, lo, hi)

See also

get_tls_fast_bit_gen()

See also

set_tls_fast_bit_gen()

Note

This function is thread-safe.

Parameters:

  • tag – defines the type of interval, which should be one of the following possible values:

    • turbo::IntervalOpenOpen

    • turbo::IntervalOpenClosed

    • turbo::IntervalClosedOpen

    • turbo::IntervalClosedClosed

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename URBG>
std::enable_if_t<!std::is_same<R, void>::value && !is_random_tag<URBG>::value, R> uniform(URBG &&urbg, R lo, R hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses the default tag turbo::IntervalClosedOpen of [lo, hi), and returns values of type T

See also

turbo::uniform(tag, urbg, lo, hi)

Template Parameters:

R – the return type

Parameters:

  • urbg – a uniform random bit generator

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void>
std::enable_if_t<!std::is_same<R, void>::value, R> uniform(R lo, R hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses the default tag turbo::IntervalClosedOpen of [lo, hi), and defaults engine, which is a thread-local instance of turbo::BitGen.

See also

turbo::uniform(tag, urbg, lo, hi)

See also

get_tls_bit_gen()

See also

set_tls_bit_gen()

Note

This function is thread-safe.

Template Parameters:

R – the return type

Parameters:

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void>
std::enable_if_t<!std::is_same<R, void>::value, R> fast_uniform(R lo, R hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses the default tag turbo::IntervalClosedOpen of [lo, hi), and defaults engine, which is a thread-local instance of turbo::InsecureBitGen.

See also

turbo::uniform(tag, urbg, lo, hi)

See also

get_tls_fast_bit_gen()

See also

set_tls_fast_bit_gen()

Note

This function is thread-safe.

Template Parameters:

R – the return type

Parameters:

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename TagType, typename URBG, typename A, typename B>
std::enable_if_t<std::is_same<R, void>::value && is_random_tag<TagType>::value && !is_random_tag<URBG>::value, random_internal::uniform_inferred_return_t<A, B>> uniform(TagType tag, URBG &&urbg, A lo, B hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses different (but compatible) lo, hi types.

Note that a compile-error will result if the return type cannot be deduced correctly from the passed types. The return type is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way. Example: 

cpp
      turbo::BitGen bitgen;
      // Produce a random uint32_t and size_t type value.
      int32_t lo = 0;
      size_t hi = 100;
      // at this way,`R` is `void` it self. will be deduced from the passed types.
      // `R` is `size` type. it is a using the mist suitable type of `lo` and `hi`.
      // simple to say, `R` is the most big type of `lo` and `hi`.but it is not always true.
      // shuch under the precondition that `lo` and `hi` can be implicitly converted into the other in a lossless way.
      // simple to say, type A and type B should be the same type or the same series type, eg signed and unsigned.
      // like `int8_t` and `int16_t` can be so int8_t can be promoted to int16_t.
      auto x = turbo::uniform(turbo::IntervalClosedClosed, bitgen, lo, hi);

Note

make sure that A and B can be implicitly converted into the other in a lossless way. eg they are all signed or unsigned, or all the same type. Intuitive representation with code: 

std::is_same<A, B>::value ||
std::is_signed<A>::value == std::is_signed<B>::value ||
std::is_unsigned<A>::value == std::is_unsigned<B>::value ||
std::is_float_point<A>::value == std::is_float_point<B>::value

Template Parameters:

R – the return type which is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way.

Parameters:

  • tag – defines the type of interval, which should be one of the following possible values:

  • urbg – a uniform random bit generator

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename TagType, typename A, typename B>
std::enable_if_t<std::is_same<R, void>::value && is_random_tag<TagType>::value, random_internal::uniform_inferred_return_t<A, B>> uniform(TagType tag, A lo, B hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses different (but compatible) lo, hi types.

uses the default engine, which is a thread-local instance of turbo::BitGen.

See also

turbo::uniform(tag, urbg, lo, hi)

Template Parameters:

R – the return type which is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way.

Parameters:

  • tag – defines the type of interval.

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename TagType, typename A, typename B>
std::enable_if_t<std::is_same<R, void>::value && is_random_tag<TagType>::value, random_internal::uniform_inferred_return_t<A, B>> fast_uniform(TagType tag, A lo, B hi)

similar to turbo::uniform(tag, urbg, lo, hi), but uses different (but compatible) lo, hi types.

uses the default engine, which is a thread-local instance of turbo::InsecureBitGen.

See also

turbo::uniform(tag, urbg, lo, hi)

Template Parameters:

R – the return type which is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way.

Parameters:

  • tag – defines the type of interval.

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename URBG, typename A, typename B>
std::enable_if_t<std::is_same<R, void>::value && !is_random_tag<URBG>::value, random_internal::uniform_inferred_return_t<A, B>> uniform(URBG &&urbg, A lo, B hi)

similar to turbo::uniform(tag, urbg, lo, hi), using default tag turbo::IntervalClosedOpen of [lo, hi).

See also

turbo::uniform(tag, urbg, lo, hi)

Template Parameters:

R – the return type which is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way.

Parameters:

  • urbg – a uniform random bit generator

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename A, typename B>
std::enable_if_t<std::is_same<R, void>::value, random_internal::uniform_inferred_return_t<A, B>> uniform(A lo, B hi)

similar to turbo::uniform(tag, urbg, lo, hi), using default tag turbo::IntervalClosedOpen of [lo, hi).

uses the default engine, which is a thread-local instance of turbo::BitGen.

See also

turbo::uniform(tag, urbg, lo, hi)

See also

get_tls_bit_gen()

See also

set_tls_bit_gen()

Note

This function is thread-safe.

Template Parameters:

R – the return type which is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way.

Parameters:

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R = void, typename A, typename B>
std::enable_if_t<std::is_same<R, void>::value, random_internal::uniform_inferred_return_t<A, B>> fast_uniform(A lo, B hi)

similar to turbo::uniform(tag, urbg, lo, hi), using default tag turbo::IntervalClosedOpen of [lo, hi).

uses the default engine, which is a thread-local instance of turbo::InsecureBitGen.

See also

turbo::uniform(tag, urbg, lo, hi)

See also

get_tls_fast_bit_gen()

See also

set_tls_fast_bit_gen()

Note

This function is thread-safe.

Template Parameters:

R – the return type which is deduced from the passed types, and is the type of lo or hi which can be implicitly converted into the other in a lossless way.

Parameters:

  • lo – the lower bound of the interval

  • hi – the upper bound of the interval

Returns:

a random value of type T uniformly distributed in a defined interval {lo, hi}

template<typename R, typename URBG>
std::enable_if_t<!std::is_signed<R>::value && !is_random_tag<URBG>::value, R> uniform(URBG &&urbg)

similar to turbo::uniform(tag, urbg, lo, hi), using std::numeric_limits<T>::min() and std::numeric_limits<T>::max() as the interval.

using default tag turbo::IntervalClosedOpen of [lo, hi).

Note

T must be unsigned.

Parameters:

urbg – a uniform random bit generator

Template Parameters:

T – the return type which is deduced from the passed types.

Returns:

a random value of type T uniformly distributed in a defined interval [lo, hi)

template<typename R>
std::enable_if_t<!std::is_signed<R>::value, R> uniform()

similar to turbo::uniform(urbs), using default engine, which is a thread-local instance of turbo::BitGen.

Note

R must be unsigned.

Template Parameters:

R – the return type which is deduced from the passed types.

Returns:

a random value of type R uniformly distributed in a defined interval [lo, hi)

template<typename R>
std::enable_if_t<!std::is_signed<R>::value, R> fast_uniform()

similar to turbo::uniform(urbs), using default engine, which is a thread-local instance of turbo::InsecureBitGen.

Note

R must be unsigned.

Template Parameters:

R – the return type which is deduced from the passed types.

Returns:

a random value of type R uniformly distributed in a defined interval [lo, hi)

template<typename T, typename URBG = BitGen>
class FixedUniform
#include <uniform.h>

a tool kit class for using uniform distribution, to generate random values of type T uniformly distributed in a defined interval {lo, hi}.

Template Parameters:

  • T – the return type which is deduced from the passed types.

  • URBG – the uniform random bit generator.

template<typename R, typename T, typename URBG = BitGen>
class FixedUniformRanges
#include <uniform.h>

a tool kit class for using uniform distribution, to generate random values of type T uniformly distributed in a defined interval list.

the interval list is a vector of pair of {lo, hi}. Example: 

cpp
      turbo::BitGen bitgen;
      // Produce a random uint32_t and size_t type value.
      std::vector<std::pair<uint32_t, uint32_t>> ranges = {{0, 10}, {20, 30}, {40, 50}};
      turbo::FixedUniformRanges<int32_t, int32_t> fixed_uniform_ranges(ranges);
      auto x = fixed_uniform_ranges();

Note

T and R must be same type or the same series type, eg signed and unsigned.

Template Parameters:

  • R – the return type which is passed to the template.

  • T – the return type which is passed to the template.

  • URBG – the uniform random bit generator.