JKLRand Class Reference

#include <JKLRand.h>

Public Member Functions
	JKLRand ()
	JKLRand (const JInt32 seed)
JInt32	UniformInt32 () const
JUInt32	UniformUInt32 () const
long	UniformLong (const long lim1, const long lim2) const
unsigned long	UniformULong (const unsigned long lim1, const unsigned long lim2) const
double	UniformClosedProb () const
double	UniformSemiOpenProb () const
double	UniformProb () const
double	UniformDouble (const double lim1, const double lim2) const
JInt32	GetSeed () const
void	SetSeed (const JInt32 newSeed)
JInt32	SetSeedByAbsoluteTime ()

Detailed Description

A random-number generator class based on the JKLRand generator function.  A
class is a natural way to maintain the seed and has no special implications
in a multi-threaded or re-entrant environment.  Further, the absence of
virtual methods (except for the destructor, as discussed below) means that
there is virtually performance penalty in using a class method as opposed to
a function call.  (Well, technically there may be a performance penalty for
de-referencing the seed when this would otherwise not be necessary.  If this
is a problem, you should probably be hand-coding in assembly anyway.)

It can be quite useful to subclass JKLRand, for example to add methods to
generate non-uniformly distributed variables.  Accordingly, JKLRand has a
virtual destructor even though it does nothing.  Users are unlikely to
create thousands of separate generators, so the performance penalty involved
should not be a problem (assuming that the compiler does not simply optimize
away the destructor calls in the first place).

Design and Performance:

Because random numbers are often generated inside tight inner loops, more
attention than usual should be paid to performance in their generation.  This
is doubly true for JKLRand; since this class uses the fastest implementation
that is likely to be available, it will be the generator of choice.

Implementation:

The JKLRand class uses the JKLRandInt function to generate its values.  The
price of speed is that this function has all the usual defects of simple
linear congruential generators.  See the notes in jRand.cpp, and make sure you
understand how to use it properly.



Notes:

    Could also provide PeekRand... functions which return the next value
    but do not update the seed.

Constructor & Destructor Documentation

JKLRand() [1/2]

JKLRand::JKLRand

(

)

The default constructor generates an initial seed based on time() in exactly the same manner as the SetSeedByAbsoluteTime method. Failure (see the SetSeedByAbsoluteTime documentation) can be tested for with GetSeed().

JKLRand() [2/2]

JKLRand::JKLRand

(

const JInt32

seed

)

Member Function Documentation

GetSeed()

JInt32 JKLRand::GetSeed ( ) const

inline

Sets the random number seed to the given value.

SetSeed()

void JKLRand::SetSeed ( const JInt32  newSeed )

inline

Sets the random number seed to the given value.

SetSeedByAbsoluteTime()

JInt32 JKLRand::SetSeedByAbsoluteTime ( )

inline

Sets the generator seed to time(nullptr), returning the new seed for convenience in testing for failure (see below).

According to ANSI it is possible for time() to fail, which sets the seed to -1. This error can be tested for with GetSeed as well as the return value. For all but the most extreme portability this can probably be ignored, since virtually all systems provide a realtime clock and on such systems it is unlikely that time() can fail.

UniformClosedProb()

double JKLRand::UniformClosedProb ( ) const

inline

Returns a random double in the range [0.0, 1.0]. (For the non-mathematically inclined this means that 0.0 and 1.0 are possible return values.)

This version is provided for maximum speed when coding a tight inner loop; in numerical work the extra test in UniformSemiOpenProb could conceivably affect performance.

UniformDouble()

double JKLRand::UniformDouble	(	const double	lim1,
		const double	lim2
	)		const

Returns a floating-point value between lim1 and lim2 inclusive. The limits may be in either order.

UniformInt32()

JInt32 JKLRand::UniformInt32 ( ) const

inline

Returns a random 32-bit integer in the range [0, 2^32-1], converted to a signed quantity.

UniformLong()

long JKLRand::UniformLong	(	const long	lim1,
		const long	lim2
	)		const

Returns an integer value between lim1 and lim2 inclusive. The limits may be in either order.

UniformProb()

double JKLRand::UniformProb ( ) const

inline

The default random floating point number method, UniformProb simply calls UniformSemiOpenProb(). This is the standard uniform deviate function because people often carelessly write code which assumes 1.0 will not be returned. If you need maximum performance, I assume you will pay attention to the proper method to call.

UniformSemiOpenProb()

double JKLRand::UniformSemiOpenProb ( ) const

inline

Returns a random double in the range [0.0, 1.0). (For the non-mathematically inclined this means that 0.0 is a possible return value but 1.0 is not.)

This is the standard uniform deviate function because people often write code which assumes 1.0 will not be returned.

UniformUInt32()

JUInt32 JKLRand::UniformUInt32 ( ) const

inline

Returns a random 32-bit integer in the range [0, 2^32-1]. This alternative to UniformInt32 is provided so that it is as easy as possible to avoid 'comparison between signed and unsigned' warnings.

UniformULong()

unsigned long JKLRand::UniformULong	(	const unsigned long	lim1,
		const unsigned long	lim2
	)		const

Returns an integer value between lim1 and lim2 inclusive. The limits may be in either order.

---

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

• libjcore/code/JKLRand.h
• libjcore/code/JKLRand.cpp