Utilities for generating pseudorandom numbers. More...

Typedefs
typedef void	AERRandGen
	Opaque type for a self-managed pseudorandom number generator. More...

Functions
uint64_t	AERRandUInt (void)
	Get a pseudorandom unsigned integer on the interval [0, 2^64) using the automatically-seeded global generator. More...

uint64_t	AERRandUIntRange (uint64_t min, uint64_t max)
	Get a pseudorandom unsigned integer on the interval [min, max) using the automatically-seeded global generator. More...

int64_t	AERRandInt (void)
	Get a pseudorandom signed integer on the interval [-2^63, 2^63) using the automatically-seeded global generator. More...

int64_t	AERRandIntRange (int64_t min, int64_t max)
	Get a pseudorandom signed integer on the interval [min, max) using the automatically-seeded global generator. More...

float	AERRandFloat (void)
	Get a pseudorandom floating-point value on the interval [0.0f, 1.0f) using the automatically-seeded global generator. More...

float	AERRandFloatRange (float min, float max)
	Get a pseudorandom floating-point value on the interval [min, max) using the automatically-seeded global generator. More...

double	AERRandDouble (void)
	Get a pseudorandom double floating-point value on the interval [0.0, 1.0) using the automatically-seeded global generator. More...

double	AERRandDoubleRange (double min, double max)
	Get a pseudorandom double floating-point value on the interval [min, max) using the automatically-seeded global generator. More...

bool	AERRandBool (void)
	Get a pseudorandom boolean using the automatically-seeded global generator. More...

void	AERRandShuffle (size_t elemSize, size_t bufSize, void *elemBuf)
	Shuffle an array of arbitrary elements using the automatically-seeded global generator. More...

AERRandGen *	AERRandGenNew (uint64_t seed)
	Allocate and initialize a new self-managed pseudorandom number generator. More...

void	AERRandGenFree (AERRandGen *gen)
	Free a self-managed pseudorandom number generator allocated using AERRandGenNew. More...

void	AERRandGenSeed (AERRandGen *gen, uint64_t seed)
	Re-seed a self-managed pseudorandom number generator. More...

uint64_t	AERRandGenUInt (AERRandGen *gen)
	Get a pseudorandom unsigned integer on the interval [0, 2^64) using a self-managed generator. More...

uint64_t	AERRandGenUIntRange (AERRandGen *gen, uint64_t min, uint64_t max)
	Get a pseudorandom unsigned integer on the interval [min, max) using a self-managed generator. More...

int64_t	AERRandGenInt (AERRandGen *gen)
	Get a pseudorandom signed integer on the interval [-2^63, 2^63) using a self-managed generator. More...

int64_t	AERRandGenIntRange (AERRandGen *gen, int64_t min, int64_t max)
	Get a pseudorandom signed integer on the interval [min, max) using a self-managed generator. More...

float	AERRandGenFloat (AERRandGen *gen)
	Get a pseudorandom floating-point value on the interval [0.0f, 1.0f) using a self-managed generator. More...

float	AERRandGenFloatRange (AERRandGen *gen, float min, float max)
	Get a pseudorandom floating-point value on the interval [min, max) using a self-managed generator. More...

double	AERRandGenDouble (AERRandGen *gen)
	Get a pseudorandom double floating-point value on the interval [0.0, 1.0) using a self-managed generator. More...

double	AERRandGenDoubleRange (AERRandGen *gen, double min, double max)
	Get a pseudorandom double floating-point value on the interval [min, max) using a self-managed generator. More...

bool	AERRandGenBool (AERRandGen *gen)
	Get a pseudorandom boolean using a self-managed generator. More...

void	AERRandGenShuffle (AERRandGen gen, size_t elemSize, size_t bufSize, void elemBuf)
	Shuffle an array of arbitrary elements using a self-managed generator. More...

Detailed Description

Utilities for generating pseudorandom numbers.

Since: 1.0.0

Copyright: 2021 the libaermre authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Typedef Documentation

◆ AERRandGen

typedef void AERRandGen

Opaque type for a self-managed pseudorandom number generator.

Use this with the functions prefixed with AERRandGen...

Since: 1.0.0

Function Documentation

◆ AERRandBool()

bool AERRandBool ( void )

Get a pseudorandom boolean using the automatically-seeded global generator.

Returns: Pseudorandom boolean.

Since: 1.0.0

See also: AERRandGenBool

◆ AERRandDouble()

double AERRandDouble ( void )

Get a pseudorandom double floating-point value on the interval [0.0, 1.0) using the automatically-seeded global generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Returns: Pseudorandom double floating-point value.

Since: 1.0.0

See also: AERRandGenDouble

◆ AERRandDoubleRange()

double AERRandDoubleRange	(	double	min,
		double	max
	)

Get a pseudorandom double floating-point value on the interval [min, max) using the automatically-seeded global generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Parameters

[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom double floating-point value or 0.0 if unsuccessful.

Exceptions

AER_BAD_VAL if argument min is greater than or equal to argument max.

Since: 1.0.0

See also: AERRandGenDoubleRange

◆ AERRandFloat()

float AERRandFloat ( void )

Get a pseudorandom floating-point value on the interval [0.0f, 1.0f) using the automatically-seeded global generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Returns: Pseudorandom floating-point value.

Since: 1.0.0

See also: AERRandGenFloat

◆ AERRandFloatRange()

float AERRandFloatRange	(	float	min,
		float	max
	)

Get a pseudorandom floating-point value on the interval [min, max) using the automatically-seeded global generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Parameters

[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom floating-point value or 0.0f if unsuccessful.

Exceptions

AER_BAD_VAL if argument min is greater than or equal to argument max.

Since: 1.0.0

See also: AERRandGenFloatRange

◆ AERRandGenBool()

bool AERRandGenBool ( AERRandGen * gen )

Get a pseudorandom boolean using a self-managed generator.

Parameters

[in] gen Generator of interest.

Returns: Pseudorandom boolean or false if unsuccessful.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

See also: AERRandBool

◆ AERRandGenDouble()

double AERRandGenDouble ( AERRandGen * gen )

Get a pseudorandom double floating-point value on the interval [0.0, 1.0) using a self-managed generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Parameters

[in] gen Generator of interest.

Returns: Pseudorandom double floating-point value or 0.0 if unsuccessful.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

See also: AERRandDouble

◆ AERRandGenDoubleRange()

double AERRandGenDoubleRange	(	AERRandGen *	gen,
		double	min,
		double	max
	)

Get a pseudorandom double floating-point value on the interval [min, max) using a self-managed generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Parameters

[in]	gen	Generator of interest.
[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom double floating-point value or 0.0 if unsuccessful.

Exceptions

AER_NULL_ARG	if argument `gen` is `NULL`.
AER_BAD_VAL	if argument `min` is greater than or equal to argument `max`.

Since: 1.0.0

See also: AERRandDoubleRange

◆ AERRandGenFloat()

float AERRandGenFloat ( AERRandGen * gen )

Get a pseudorandom floating-point value on the interval [0.0f, 1.0f) using a self-managed generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Parameters

[in] gen Generator of interest.

Returns: Pseudorandom floating-point value or 0.0f if unsuccessful.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

See also: AERRandFloat

◆ AERRandGenFloatRange()

float AERRandGenFloatRange	(	AERRandGen *	gen,
		float	min,
		float	max
	)

Get a pseudorandom floating-point value on the interval [min, max) using a self-managed generator.

Bug:: This function uses a method of obtaining floats from integers that is now known to introduce slight distribution-related bias (see Generating Random Floating-Point Numbers by Dividing Integers: a Case Study by Frédéric Goualard). This is unlikely to cause issues in the vast majority of usecases, but it should be kept in mind.

Parameters

[in]	gen	Generator of interest.
[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom floating-point value or 0.0f if unsuccessful.

Exceptions

AER_NULL_ARG	if argument `gen` is `NULL`.
AER_BAD_VAL	if argument `min` is greater than or equal to argument `max`.

Since: 1.0.0

See also: AERRandFloatRange

◆ AERRandGenFree()

void AERRandGenFree ( AERRandGen * gen )

Free a self-managed pseudorandom number generator allocated using AERRandGenNew.

Parameters

[in] gen Generator of interest.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

See also: AERRandGenNew

◆ AERRandGenInt()

int64_t AERRandGenInt ( AERRandGen * gen )

Get a pseudorandom signed integer on the interval [-2^63, 2^63) using a self-managed generator.

Parameters

[in] gen Generator of interest.

Returns: Pseudorandom signed integer or 0 if unsuccessful.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

See also: AERRandInt

◆ AERRandGenIntRange()

int64_t AERRandGenIntRange	(	AERRandGen *	gen,
		int64_t	min,
		int64_t	max
	)

Get a pseudorandom signed integer on the interval [min, max) using a self-managed generator.

This function has been carefully designed to avoid introducing any distribution-related bias. For faster but potentially biased generation, use modulo.

Parameters

[in]	gen	Generator of interest.
[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom signed integer or 0 if unsuccessful.

Exceptions

AER_NULL_ARG	if argument `gen` is `NULL`.
AER_BAD_VAL	if argument `min` is greater than or equal to argument `max`.

Since: 1.0.0

See also: AERRandIntRange

◆ AERRandGenNew()

AERRandGen * AERRandGenNew ( uint64_t seed )

Allocate and initialize a new self-managed pseudorandom number generator.

When no longer needed, free this generator using AERRandGenFree.

Parameters

[in] seed Initial generator seed.

Returns: Newly allocated generator.

Since: 1.0.0

See also: AERRandGenFree

◆ AERRandGenSeed()

void AERRandGenSeed	(	AERRandGen *	gen,
		uint64_t	seed
	)

Re-seed a self-managed pseudorandom number generator.

Parameters

[in]	gen	Generator of interest.
[in]	seed	New generator seed.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

◆ AERRandGenShuffle()

void AERRandGenShuffle	(	AERRandGen *	gen,
		size_t	elemSize,
		size_t	bufSize,
		void *	elemBuf
	)

Shuffle an array of arbitrary elements using a self-managed generator.

Parameters

[in]	gen	Generator of interest.
[in]	elemSize	Size of each buffer element in bytes.
[in]	bufSize	Size of buffer in elements.
[in,out]	elemBuf	Buffer of elements to shuffle.

Exceptions

AER_BAD_VAL	if argument `elemSize` is `0`.
AER_NULL_ARG	if either argument `gen` or `elemBuf` is `NULL`.

Since: 1.4.0

See also: AERRandShuffle

◆ AERRandGenUInt()

uint64_t AERRandGenUInt ( AERRandGen * gen )

Get a pseudorandom unsigned integer on the interval [0, 2^64) using a self-managed generator.

Parameters

[in] gen Generator of interest.

Returns: Pseudorandom unsigned integer or 0 if unsuccessful.

Exceptions

AER_NULL_ARG if argument gen is NULL.

Since: 1.0.0

See also: AERRandUInt

◆ AERRandGenUIntRange()

uint64_t AERRandGenUIntRange	(	AERRandGen *	gen,
		uint64_t	min,
		uint64_t	max
	)

Get a pseudorandom unsigned integer on the interval [min, max) using a self-managed generator.

This function has been carefully designed to avoid introducing any distribution-related bias. For faster but potentially biased generation, use modulo.

Parameters

[in]	gen	Generator of interest.
[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom unsigned integer or 0 if unsuccessful.

Exceptions

AER_NULL_ARG	if argument `gen` is `NULL`.
AER_BAD_VAL	if argument `min` is greater than or equal to argument `max`.

Since: 1.0.0

See also: AERRandUIntRange

◆ AERRandInt()

int64_t AERRandInt ( void )

Get a pseudorandom signed integer on the interval [-2^63, 2^63) using the automatically-seeded global generator.

Returns: Pseudorandom signed integer.

Since: 1.0.0

See also: AERRandGenInt

◆ AERRandIntRange()

int64_t AERRandIntRange	(	int64_t	min,
		int64_t	max
	)

Get a pseudorandom signed integer on the interval [min, max) using the automatically-seeded global generator.

This function has been carefully designed to avoid introducing any distribution-related bias. For faster but potentially biased generation, use modulo.

Parameters

[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom signed integer or 0 if unsuccessful.

Exceptions

AER_BAD_VAL if argument min is greater than or equal to argument max.

Since: 1.0.0

See also: AERRandGenIntRange

◆ AERRandShuffle()

void AERRandShuffle	(	size_t	elemSize,
		size_t	bufSize,
		void *	elemBuf
	)

Shuffle an array of arbitrary elements using the automatically-seeded global generator.

Parameters

[in]	elemSize	Size of each buffer element in bytes.
[in]	bufSize	Size of buffer in elements.
[in,out]	elemBuf	Buffer of elements to shuffle.

Exceptions

AER_BAD_VAL	if argument `elemSize` is `0`.
AER_NULL_ARG	if argument `elemBuf` is `NULL`.

Since: 1.4.0

See also: AERRandGenShuffle

◆ AERRandUInt()

uint64_t AERRandUInt ( void )

Get a pseudorandom unsigned integer on the interval [0, 2^64) using the automatically-seeded global generator.

Returns: Pseudorandom unsigned integer.

Since: 1.0.0

See also: AERRandGenUInt

◆ AERRandUIntRange()

uint64_t AERRandUIntRange	(	uint64_t	min,
		uint64_t	max
	)

Get a pseudorandom unsigned integer on the interval [min, max) using the automatically-seeded global generator.

This function has been carefully designed to avoid introducing any distribution-related bias. For faster but potentially biased generation, use modulo.

Parameters

[in]	min	Minimum possible value (inclusive).
[in]	max	Maximum possible value (exclusive).

Returns: Pseudorandom unsigned integer or 0 if unsuccessful.

Exceptions

AER_BAD_VAL if argument min is greater than or equal to argument max.

Since: 1.0.0

See also: AERRandGenUIntRange

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ AERRandGen

Function Documentation

◆ AERRandBool()

◆ AERRandDouble()

◆ AERRandDoubleRange()

◆ AERRandFloat()

◆ AERRandFloatRange()

◆ AERRandGenBool()

◆ AERRandGenDouble()

◆ AERRandGenDoubleRange()

◆ AERRandGenFloat()

◆ AERRandGenFloatRange()

◆ AERRandGenFree()

◆ AERRandGenInt()

◆ AERRandGenIntRange()

◆ AERRandGenNew()

◆ AERRandGenSeed()

◆ AERRandGenShuffle()

◆ AERRandGenUInt()

◆ AERRandGenUIntRange()

◆ AERRandInt()

◆ AERRandIntRange()

◆ AERRandShuffle()

◆ AERRandUInt()

◆ AERRandUIntRange()