The machinery to handle u-rands, arbitrary precision random deviates. More...

#include <exrandom/u_rand.hpp>

Public Member Functions
	u_rand (digit_gen &D)

u_rand &	init ()

void	swap (u_rand &t)

int	sign () const

void	negate ()

unsigned	integer () const

void	set_integer (unsigned n)

size_t	ndigits () const

template<typename Generator >
uint_t	digit (Generator &g, size_t k)

uint_t	rawdigit (size_t k) const

uint_t &	rawdigit (size_t k)

template<typename Generator >
bool	less_than (Generator &g, u_rand &t)

template<typename Generator >
bool	less_than_half (Generator &g)

template<typename Generator >
bool	truncatep (Generator &g, size_t k)

template<typename Generator >
int	compare (Generator &g, long long u1, long long u2, long long v)

template<typename Generator >
bool	less_than (Generator &g, long long u0, long long c, long long v, i_rand< digit_gen > &h)

std::pair< long long, long long >	rawrational (size_t k) const

std::pair< long long, long long >	rational () const

template<typename Generator >
std::pair< long long, long long >	rational (Generator &g, size_t k)

template<typename RealType >
std::pair< RealType, RealType >	range () const

template<typename RealType >
RealType	midpoint ()

template<typename RealType , typename Generator >
RealType	midpoint (Generator &g, size_t k)

template<typename RealType , typename Generator >
RealType	value (Generator &g, std::float_round_style rnd, int &flag)

template<typename RealType , typename Generator >
RealType	value (Generator &g, int &flag)

template<typename RealType , typename Generator >
RealType	value (Generator &g)

std::string	print () const

template<typename Generator >
std::string	print_fixed (Generator &g, size_t k)

Static Public Attributes
static const uint_t	base

Friends
std::ostream &	operator<< (std::ostream &os, const u_rand &x)

Detailed Description

template<typename digit_gen>
class exrandom::u_rand< digit_gen >

The machinery to handle u-rands, arbitrary precision random deviates.

A u_rand is represented in base b as s (n + ∑_k=0^K−1 d_k b^−k−1 + b^−KU) where s = ±1, n and K are non-negative integers, and d_k ∈ [0,b).

Template Parameters

digit_gen the type of digit generator.

Examples: count_bits.cpp, hist_data.cpp, sample_exponential.cpp, sample_normal.cpp, sample_uniform.cpp, and tabulate_normals.cpp.

Definition at line 105 of file u_rand.hpp.

Constructor & Destructor Documentation

◆ u_rand()

template<typename digit_gen>

exrandom::u_rand< digit_gen >::u_rand ( digit_gen & D )

inline

The constructor.

Parameters

D	A reference to the digit generator to be used.

The initial state represents a random deviate uniform in (0,1)

Definition at line 114 of file u_rand.hpp.

Member Function Documentation

◆ init()

template<typename digit_gen>

u_rand& exrandom::u_rand< digit_gen >::init ( )

inline

Reset to the initial state.

Returns: the u_rand itself.

The returned result allows the idiom x.init().less_than(g, y) to be used.

Definition at line 123 of file u_rand.hpp.

◆ swap()

template<typename digit_gen>

void exrandom::u_rand< digit_gen >::swap ( u_rand< digit_gen > & t )

inline

Swap two u_rands.

Parameters

t	the u_rand to swap with.

The digit generator is not part of the swap.

Definition at line 134 of file u_rand.hpp.

◆ sign()

template<typename digit_gen>

int exrandom::u_rand< digit_gen >::sign ( ) const

inline

Returns: sign of the u_rand (either +1 or -1).

Definition at line 142 of file u_rand.hpp.

◆ negate()

template<typename digit_gen>

void exrandom::u_rand< digit_gen >::negate ( )

inline

Change the sign of the u_rand.

Definition at line 146 of file u_rand.hpp.

◆ integer()

template<typename digit_gen>

unsigned exrandom::u_rand< digit_gen >::integer ( ) const

inline

Returns: unsigned integer part of the u_rand.

Definition at line 150 of file u_rand.hpp.

◆ set_integer()

template<typename digit_gen>

void exrandom::u_rand< digit_gen >::set_integer ( unsigned n )

inline

Set the integer part of the u_rand.

Parameters

n	the new value of the (unsigned) integer part.

Definition at line 155 of file u_rand.hpp.

◆ ndigits()

template<typename digit_gen>

size_t exrandom::u_rand< digit_gen >::ndigits ( ) const

inline

Returns: the number of digits in the fraction.

Definition at line 159 of file u_rand.hpp.

◆ digit()

template<typename digit_gen>

template<typename Generator >

uint_t exrandom::u_rand< digit_gen >::digit	(	Generator &	g,
		size_t	k
	)

inline

The k'th digit generating it if necessary.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine used to generate the digit.
k	which digit of the fraction to return (counting from 0).

Returns: the value of the digit.

Definition at line 169 of file u_rand.hpp.

◆ rawdigit() [1/2]

template<typename digit_gen>

uint_t exrandom::u_rand< digit_gen >::rawdigit ( size_t k ) const

inline

The k'th digit (which must already have been generated).

Parameters

k	which digit of the fraction to return (counting from 0).

Returns: the value of the digit.

Definition at line 179 of file u_rand.hpp.

◆ rawdigit() [2/2]

template<typename digit_gen>

uint_t& exrandom::u_rand< digit_gen >::rawdigit ( size_t k )

inline

A reference to the k'th digit (which must already be generated).

Parameters

k	which digit of the fraction to return (counting from 0).

Returns: a reference to the k'th digit.

Definition at line 186 of file u_rand.hpp.

◆ less_than() [1/2]

template<typename digit_gen>

template<typename Generator >

bool exrandom::u_rand< digit_gen >::less_than	(	Generator &	g,
		u_rand< digit_gen > &	t
	)

inline

Test *this < t.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine used to generate the digit.
t	the u_rand to compare with.

Returns: *this < t.

Definition at line 196 of file u_rand.hpp.

◆ less_than_half()

template<typename digit_gen>

template<typename Generator >

bool exrandom::u_rand< digit_gen >::less_than_half ( Generator & g )

inline

Test *this < 1/2.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine used to generate the digit.

Returns: *this < 1/2.

Definition at line 213 of file u_rand.hpp.

◆ truncatep()

template<typename digit_gen>

template<typename Generator >

bool exrandom::u_rand< digit_gen >::truncatep	(	Generator &	g,
		size_t	k
	)

inline

Determine how the result should be rounded.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine used to generate the digit.
k	which rounding digit.

Returns: true if the result can be truncated towards zero.

Look at the kth (and subsequent) digits to determine whether the (k-1)th digit should retained (i.e., the result rounded towards zero) or incremented (i.e., the result should rounded away from zero). If k = 0, then the (k-1)th digit affects the integer part of the result. If base is even only one digit is tested.

Definition at line 233 of file u_rand.hpp.

◆ compare()

template<typename digit_gen>

template<typename Generator >

int exrandom::u_rand< digit_gen >::compare	(	Generator &	g,
		long long	u1,
		long long	u2,
		long long	v
	)

inline

Compare *this with u1/v and u2/v.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
u1	the numerator of the first fraction.
u2	the numerator of the second fraction.
v	the denominator of the fractions.

Returns: -1 if *this < u1/v, +1 if frac(*this) > u2/v, and 0 otherwise.

This function requires v > 0, u2 > u1.

Definition at line 254 of file u_rand.hpp.

◆ less_than() [2/2]

template<typename digit_gen>

template<typename Generator >

bool exrandom::u_rand< digit_gen >::less_than	(	Generator &	g,
		long long	u0,
		long long	c,
		long long	v,
		i_rand< digit_gen > &	h
	)

inline

Compare *this with a i_rand.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
u0	the offset in the numerator.
c	the multiplier for the i_rand.
v	the denominator of the fraction.
h	the i_rand.

Returns: *this < u/v, where u = u0 + h * c.

This function requires v > 0, c > 0.

Definition at line 281 of file u_rand.hpp.

◆ rawrational()

template<typename digit_gen>

std::pair<long long, long long> exrandom::u_rand< digit_gen >::rawrational ( size_t k ) const

inline

The lower end of the range as a rational.

Parameters

k	the number of digits to include from the fractional part of the number.

Returns: the lower end of the range represented by the u_rand with a given number of (already generated) digits in the fraction as a rational (a std::pair of the numerator and denominator).

The fraction is not in lowest terms. Thus the upper end can be found by adding 1 to the numerator. Overflow is possible in this routine and no attempt is made to detect this.

This function requires that base ≤ 2⁸ (in an attempt to avoid overflow).

Definition at line 306 of file u_rand.hpp.

◆ rational() [1/2]

template<typename digit_gen>

std::pair<long long, long long> exrandom::u_rand< digit_gen >::rational ( ) const

inline

The lower end of the range as a rational.

Returns: the lower end of the range represented by the u_rand as a rational (a std::pair of the numerator and denominator).

The fraction is not in lowest terms. Thus the upper end can be found by adding 1 to the numerator. Overflow is possible in this routine and no attempt is made to detect this.

This function requires that base ≤ 2⁸ (in an attempt to avoid overflow).

Definition at line 329 of file u_rand.hpp.

◆ rational() [2/2]

template<typename digit_gen>

template<typename Generator >

std::pair<long long, long long> exrandom::u_rand< digit_gen >::rational	(	Generator &	g,
		size_t	k
	)

inline

The lower end of the range as a rational.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
k	the number of digits to include from the fractional part of the number.

Returns: the lower end of the range represented by the u_rand with a given number of digits in the fraction as a rational (a std::pair of the numerator and denominator).

The fraction is not in lowest terms. Thus the upper end can be found by adding 1 to the numerator. Overflow is possible in this routine and no attempt is made to detect this.

This function requires that base ≤ 2⁸ (in an attempt to avoid overflow).

Definition at line 350 of file u_rand.hpp.

◆ range()

template<typename digit_gen>

template<typename RealType >

std::pair<RealType, RealType> exrandom::u_rand< digit_gen >::range ( ) const

inline

The range.

Template Parameters

RealType the floating point type for the ends of the range.

Returns: the range represented by the u_rand as a std::pair.

The calculations of the end points are done using ordinary floating point arithmetic. The results will be reasonably close to the true end points.

Definition at line 364 of file u_rand.hpp.

◆ midpoint() [1/2]

template<typename digit_gen>

template<typename RealType >

RealType exrandom::u_rand< digit_gen >::midpoint ( )

inline

The midpoint of the range.

Template Parameters

RealType the floating point type for the result.

Returns: the midpoint of the current range.

The calculation of the midpoint is done using ordinary floating point arithmetic. The result will be reasonably close to the true midpoint.

Definition at line 387 of file u_rand.hpp.

◆ midpoint() [2/2]

template<typename digit_gen>

template<typename RealType , typename Generator >

RealType exrandom::u_rand< digit_gen >::midpoint	(	Generator &	g,
		size_t	k
	)

inline

The midpoint of the range.

Template Parameters

RealType	the floating point type for the result.
Generator	the type of g.

Parameters

g	the random generator engine.
k	make sure there are at least k digits in the fraction.

Returns: the midpoint of the resulting range.

The calculation of the midpoint is done using ordinary floating point arithmetic. The result will be reasonably close to the true midpoint.

Definition at line 404 of file u_rand.hpp.

◆ value() [1/3]

template<typename digit_gen>

template<typename RealType , typename Generator >

RealType exrandom::u_rand< digit_gen >::value	(	Generator &	g,
		std::float_round_style	rnd,
		int &	flag
	)

inline

Return the value of the u_rand with specified rounding as a floating point number of type RealType and, if necessary, creating additional digits of the number. Also return inexact flag to indicate whether the rounded result is greater or less than the true result.

Template Parameters

RealType	the floating point type to convert to.
Generator	the type of g.

Parameters

	g	the random generator engine.
	rnd	the rounding mode; by default this is the rounding mode for RealType.
[out]	flag	the inexact flag, +1 (resp. -1) if rounded result is greater (resp. less) than the true result.

Returns: the value of the u_rand rounded to a RealType.

This function is only implemented if the base is a power of two for conventional floating point types (which have radix = 2). If the floating point radix is not two (e.g., radix = 10), then the base needs to match the radix and be even. The meaning for the inexact flag is the same as in the MPFR library.

Possible values for rnd are

std::round_indeterminate, taken to mean round away from zero
std::round_toward_zero
std::round_to_nearest, this is the default for float, double, etc.
std::round_toward_infinity
std::round_toward_neg_infinity

The conversions have been tested for

float, double, long double
mpfr::mpreal
boost's mpfr_float, mpf_float, cpp_dec_float, and float128

RealType needs to support the following operations:

std::numeric_limits<RealType> must include min(), radix, digits, min_exponent, max_exponent, has_denorm, round_style
std::numeric_limits<RealType>::is_integer is false
basic arithmetic: negation, addition
ldexp(const RealType&, int) if radix is 2; multiplication otherwise

Special treatment is included for

mpfr::mpreal (std::numeric_limits has digits() and round_style() instead of digits and round_style)

Definition at line 454 of file u_rand.hpp.

◆ value() [2/3]

template<typename digit_gen>

template<typename RealType , typename Generator >

RealType exrandom::u_rand< digit_gen >::value	(	Generator &	g,
		int &	flag
	)

inline

Return the value of the u_rand rounded to nearest floating point number of type RealType and, if necessary, creating additional digits of the number. Also return inexact flag to indicate whether the rounded result is greater or less than the true result.

Template Parameters

RealType	the floating point type to convert to.
Generator	the type of g.

Parameters

	g	the random generator engine.
[out]	flag	the inexact flag, +1 (resp. -1) if rounded result is greater (resp. less) than the true result.

Returns: the value of the u_rand rounded to a RealType.

This function is only implemented if the base is a power of two for conventional floating point types (which have radix = 2). If the floating point radix is not two (e.g., radix = 10), then the base needs to match the radix and be even. The meaning for the inexact flag is the same as in the MPFR library.

Definition at line 575 of file u_rand.hpp.

◆ value() [3/3]

template<typename digit_gen>

template<typename RealType , typename Generator >

RealType exrandom::u_rand< digit_gen >::value ( Generator & g )

inline

Return the value of the u_rand rounded to nearest floating point number of type RealType and, if necessary, creating additional digits of the number.

Template Parameters

RealType	the floating point type to convert to.
Generator	the type of g.

Parameters

g	the random generator engine.

Returns: the value of the u_rand rounded to a RealType.

This function is only implemented if the base is a power of two for conventional floating point types (which have radix = 2). If the floating point radix is not two (e.g., radix = 10), then the base needs to match the radix and be even.

Definition at line 594 of file u_rand.hpp.

◆ print()

template<typename digit_gen>

std::string exrandom::u_rand< digit_gen >::print ( ) const

inline

Print a u_rand in u-rand format.

Returns: the printed representation of the current number.

This prints the number to the existing precision followed by an ellipsis "…" to indicate the digits which haven't been generated yet. This function is only implemented if the base is less than 16 or a power of 16. The representation uses the base of the u_rand or hexadecimal if base > 16.

Definition at line 610 of file u_rand.hpp.

◆ print_fixed()

template<typename digit_gen>

template<typename Generator >

std::string exrandom::u_rand< digit_gen >::print_fixed	(	Generator &	g,
		size_t	k
	)

inline

Print a u_rand in rounded fixed point format.

Template Parameters

Generator the type of g.

Parameters

g	the random generator engine.
k

Returns: the printed fixed point representation rounded to k digits.

This prints the number with k digits in the fraction and (+) (resp. (−)) to indicate that the true result is further from (resp. closer to) zero. This function is only implemented if the base is less than 16 or a power of 16. The representation uses the base of the u_rand or hexadecimal if base > 16.

Definition at line 628 of file u_rand.hpp.

Friends And Related Function Documentation

◆ operator<<

template<typename digit_gen>

std::ostream& operator<<	(	std::ostream &	os,
		const u_rand< digit_gen > &	x
	)

friend

Print a u_rand in u-rand format.

Parameters

os	an output stream.
x	a u_rand.

Returns: os.

This prints the number to the existing precision followed by an ellipsis "..." to indicate the digits which haven't been generated yet. This function is only implemented if the base is less than 16 or a power of

The representation uses the base of the u_rand or hexadecimal if base > 16.

Definition at line 658 of file u_rand.hpp.

Member Data Documentation

◆ base

template<typename digit_gen>

const uint_t exrandom::u_rand< digit_gen >::base

static

The base of the digit generator.

Definition at line 664 of file u_rand.hpp.

The documentation for this class was generated from the following file:

u_rand.hpp

Public Member Functions

Static Public Attributes

Friends

Detailed Description

template<typename digit_gen> class exrandom::u_rand< digit_gen >

Constructor & Destructor Documentation

◆ u_rand()

Member Function Documentation

◆ init()

◆ swap()

◆ sign()

◆ negate()

◆ integer()

◆ set_integer()

◆ ndigits()

◆ digit()

◆ rawdigit() [1/2]

◆ rawdigit() [2/2]

◆ less_than() [1/2]

◆ less_than_half()

◆ truncatep()

◆ compare()

◆ less_than() [2/2]

◆ rawrational()

◆ rational() [1/2]

◆ rational() [2/2]

◆ range()

◆ midpoint() [1/2]

◆ midpoint() [2/2]

◆ value() [1/3]

◆ value() [2/3]

◆ value() [3/3]

◆ print()

◆ print_fixed()

Friends And Related Function Documentation

◆ operator<<

Member Data Documentation

◆ base

template<typename digit_gen>
class exrandom::u_rand< digit_gen >