cgul_shuffle.h File Reference

Fisher-Yates Shuffle. More...

#include "cgul_common.h"
#include "cgul_exception.h"
#include "cgul_int.h"

Include dependency graph for cgul_shuffle.h:

This graph shows which files directly or indirectly include this file:

Functions
CGUL_EXPORT void	cgul_shuffle (cgul_exception_t *cex, void *v, size_t v_count, size_t element_size, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_pointers (cgul_exception_t *cex, void **v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_schar (cgul_exception_t *cex, signed char *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_uchar (cgul_exception_t *cex, unsigned char *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_short (cgul_exception_t *cex, short int *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_ushort (cgul_exception_t *cex, unsigned short int *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_int (cgul_exception_t *cex, int *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_uint (cgul_exception_t *cex, unsigned int *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_long (cgul_exception_t *cex, long int *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_ulong (cgul_exception_t *cex, unsigned long int *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_int8 (cgul_exception_t *cex, cgul_int8_t *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_uint8 (cgul_exception_t *cex, cgul_uint8_t *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_int16 (cgul_exception_t *cex, cgul_int16_t *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_uint16 (cgul_exception_t *cex, cgul_uint16_t *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_int32 (cgul_exception_t *cex, cgul_int32_t *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)
CGUL_EXPORT void	cgul_shuffle_uint32 (cgul_exception_t *cex, cgul_uint32_t *v, size_t v_count, cgul_shuffle__next_in_range_t next_in_range, void *prng)

Variables
CGUL_BEGIN_C typedef cgul_uint32_t(*	cgul_shuffle__next_in_range_t )(cgul_exception_t *cex, void *prng, cgul_uint32_t range_max)

Detailed Description

Shuffle an array.

Author

Paul Serice

Function Documentation

cgul_shuffle()

CGUL_EXPORT void cgul_shuffle	(	cgul_exception_t *	cex,
		void *	v,
		size_t	v_count,
		size_t	element_size,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count arbitrary elements of size element_size (in bytes). If v holds integers or pointers, one of the other shuffle functions tailored to the specific type will perform better. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG object prng unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32 - 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	element_size	size of each element in v (in bytes)
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_pointers()

CGUL_EXPORT void cgul_shuffle_pointers	(	cgul_exception_t *	cex,
		void **	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count void* elements. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_schar()

CGUL_EXPORT void cgul_shuffle_schar	(	cgul_exception_t *	cex,
		signed char *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type signed char. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_uchar()

CGUL_EXPORT void cgul_shuffle_uchar	(	cgul_exception_t *	cex,
		unsigned char *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type unsigned char. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_short()

CGUL_EXPORT void cgul_shuffle_short	(	cgul_exception_t *	cex,
		short int *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type short. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_ushort()

CGUL_EXPORT void cgul_shuffle_ushort	(	cgul_exception_t *	cex,
		unsigned short int *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type unsigned short. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_int()

CGUL_EXPORT void cgul_shuffle_int	(	cgul_exception_t *	cex,
		int *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type int. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_uint()

CGUL_EXPORT void cgul_shuffle_uint	(	cgul_exception_t *	cex,
		unsigned int *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type unsigned int. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_long()

CGUL_EXPORT void cgul_shuffle_long	(	cgul_exception_t *	cex,
		long int *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type long. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_ulong()

CGUL_EXPORT void cgul_shuffle_ulong	(	cgul_exception_t *	cex,
		unsigned long int *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type unsigned long. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_int8()

CGUL_EXPORT void cgul_shuffle_int8	(	cgul_exception_t *	cex,
		cgul_int8_t *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type cgul_int8_t. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_uint8()

CGUL_EXPORT void cgul_shuffle_uint8	(	cgul_exception_t *	cex,
		cgul_uint8_t *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type cgul_uint8_t. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_int16()

CGUL_EXPORT void cgul_shuffle_int16	(	cgul_exception_t *	cex,
		cgul_int16_t *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type cgul_int16_t. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_uint16()

CGUL_EXPORT void cgul_shuffle_uint16	(	cgul_exception_t *	cex,
		cgul_uint16_t *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type cgul_uint16_t. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_int32()

CGUL_EXPORT void cgul_shuffle_int32	(	cgul_exception_t *	cex,
		cgul_int32_t *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type cgul_int32_t. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

cgul_shuffle_uint32()

CGUL_EXPORT void cgul_shuffle_uint32	(	cgul_exception_t *	cex,
		cgul_uint32_t *	v,
		size_t	v_count,
		cgul_shuffle__next_in_range_t	next_in_range,
		void *	prng
	)

Perform an in-place Fisher-Yates shuffle on the array v having v_count elements of type cgul_uint32_t. The quality of the shuffle depends entirely on the quality of the random numbers returned by the next_in_range callback which is passed the PRNG prng object unmodified. Because this function assumes a 32-bit PRNG, v_count can indicate no more than (2^32

• 1) elements. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	v	array of elements to shuffle
[in]	v_count	number of elements in v
[in]	next_in_range	PRNG callback
[in]	prng	PRNG

Variable Documentation

cgul_shuffle__next_in_range_t

CGUL_BEGIN_C typedef cgul_uint32_t(* cgul_shuffle__next_in_range_t) (cgul_exception_t *cex, void *prng, cgul_uint32_t range_max)

This type definition defines the interface to a pseudo-random number generator (PRNG) which the shuffle functions use to generate pseudo-random numbers that are used to shuffle an array. The quality of the shuffle depends entirely upon the quality of the pseudo-random numbers returned.

Functions that implement this interface will be passed the same PRNG prng that is passed into the shuffle function. The return value should be a pseudo-random integer in the half-open interval [0, range_max). If an error occurs when this function is called, the client should propagate the error via cex.

Note that this interface closely resembles the signature of the cgul_random_*__next_in_range() functions. So closely in fact, that it is usually not necessary to write a special callback to implement this function. Instead, this interface can be satisfied by casting cgul_random_*__next_in_range() to have cgul_shuffle__next_in_range_t function type and pass in your PRNG object as prng.

Parameters

[in,out]	cex	c-style exception
[in]	prng	PRNG
[in]	range_max	maximum, non-negative range for pseudo-random numbers

Returns

pseudo-random integer in the half-open interval [0, range_max)