shared_source/c_datd/esrg_rand_int.h

//$Header$
//-------------------------------------------------------------------------------------------------
//This file is part of "David T. Ashley's Shared Source Code", a set of shared components
//integrated into many of David T. Ashley's projects.
//-------------------------------------------------------------------------------------------------
//This source code and any program in which it is compiled/used is provided under the MIT License,
//reproduced below.
//-------------------------------------------------------------------------------------------------
//Permission is hereby granted, free of charge, to any person obtaining a copy of
//this software and associated documentation files(the "Software"), to deal in the
//Software without restriction, including without limitation the rights to use,
//copy, modify, merge, publish, distribute, sublicense, and / or sell copies of the
//Software, and to permit persons to whom the Software is furnished to do so,
//subject to the following conditions :
//
//The above copyright notice and this permission notice shall be included in all
//copies or substantial portions of the Software.
//
//THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
//AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
//SOFTWARE.
//-------------------------------------------------------------------------------------------------
#ifndef ESRG_RAND_INT_H_INCLUDED
   #define ESRG_RAND_INT_H_INCLUDED

   #ifdef MODULE_ESRG_RAND_INT
      #define DECMOD_ESRG_RAND_INT
   #else
      #define DECMOD_ESRG_RAND_INT extern
   #endif

   //This module is grouped as a collection of algorithms.
   //At present, there is only one algorithm, but this may
   //change.
   //**************************************************************************
   //**************************************************************************
   //**********  Algorithm 01:  Power Residue 16807  **************************
   //**************************************************************************
   //**************************************************************************
   //This is the state vector.  This is conceptually private, and the
   //caller should not tamper with it or peek into it.
   struct ESRG_RAND_INT_Alg01RngState
      {
      unsigned rn_seed_whole;
         //The current whole random number.  This is the random
         //number that will be served up when the first algorithm
         //is used directly or when a random integer over a large
         //range is required.
      unsigned rn_seed_fractional;
         //The current seed in use for requests for bits or
         //small portions of bits.
      unsigned bit_buffer;
         //A buffer maintained to doll out bits and small random
         //numbers.  This buffer is emptied from the right.
      unsigned n_bb_valid;
         //The number of valid bits in the bit buffer.  When there
         //are no more valid bits, the bit buffer must be 
         //restocked.
      };
   
   //Initializes the random number generation structure.  If 
   //(init_val == -1), then the state will be randomized using the system
   //clock and other system randomness.  This means that the random 
   //sequence generated won't be predictable (it will vary from usage
   //to usage of this module).  If init_val is positive, the positive
   //value will be used to initialize the state.  The mapping from 
   //init_val is guaranteed to be deterministic (the same value always
   //leads to the same sequences), but uniqueness is not guaranteed:
   //different values of init_val may lead to the same sequences.
   DECMOD_ESRG_RAND_INT
   void ESRG_RAND_INT_Alg01_Init(struct ESRG_RAND_INT_Alg01RngState *state,
                                 int    init_val);

   //Returns a single random bit.
   DECMOD_ESRG_RAND_INT
   unsigned int ESRG_RAND_INT_Alg01_RandomBit(
                                 struct ESRG_RAND_INT_Alg01RngState *state
                                 );
   //Returns a single random byte.
   DECMOD_ESRG_RAND_INT
   unsigned int ESRG_RAND_INT_Alg01_RandomByte(
                                 struct ESRG_RAND_INT_Alg01RngState *state
                                 );

   DECMOD_ESRG_RAND_INT const char *ESRG_RAND_INT_cvcinfo(void);
   DECMOD_ESRG_RAND_INT const char *ESRG_RAND_INT_hvcinfo(void);
   #define ESRG_RAND_INT_H_VERSION ("$Header$")
#endif

//End of esrg_rand_int.h.
1	dashley	56	//$Header$
2	dashley	25	//-------------------------------------------------------------------------------------------------
3	dashley	56	//This file is part of "David T. Ashley's Shared Source Code", a set of shared components
4			//integrated into many of David T. Ashley's projects.
5	dashley	25	//-------------------------------------------------------------------------------------------------
6	dashley	56	//This source code and any program in which it is compiled/used is provided under the MIT License,
7			//reproduced below.
8			//-------------------------------------------------------------------------------------------------
9			//Permission is hereby granted, free of charge, to any person obtaining a copy of
10			//this software and associated documentation files(the "Software"), to deal in the
11			//Software without restriction, including without limitation the rights to use,
12			//copy, modify, merge, publish, distribute, sublicense, and / or sell copies of the
13			//Software, and to permit persons to whom the Software is furnished to do so,
14			//subject to the following conditions :
15	dashley	25	//
16	dashley	56	//The above copyright notice and this permission notice shall be included in all
17			//copies or substantial portions of the Software.
18	dashley	25	//
19	dashley	56	//THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20			//IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21			//FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
22			//AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23			//LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24			//OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25			//SOFTWARE.
26	dashley	25	//-------------------------------------------------------------------------------------------------
27			#ifndef ESRG_RAND_INT_H_INCLUDED
28			#define ESRG_RAND_INT_H_INCLUDED
29
30			#ifdef MODULE_ESRG_RAND_INT
31			#define DECMOD_ESRG_RAND_INT
32			#else
33			#define DECMOD_ESRG_RAND_INT extern
34			#endif
35
36			//This module is grouped as a collection of algorithms.
37			//At present, there is only one algorithm, but this may
38			//change.
39			//**************************************************************************
40			//**************************************************************************
41			//******** Algorithm 01: Power Residue 16807 ************************
42			//**************************************************************************
43			//**************************************************************************
44			//This is the state vector. This is conceptually private, and the
45			//caller should not tamper with it or peek into it.
46			struct ESRG_RAND_INT_Alg01RngState
47			{
48			unsigned rn_seed_whole;
49			//The current whole random number. This is the random
50			//number that will be served up when the first algorithm
51			//is used directly or when a random integer over a large
52			//range is required.
53			unsigned rn_seed_fractional;
54			//The current seed in use for requests for bits or
55			//small portions of bits.
56			unsigned bit_buffer;
57			//A buffer maintained to doll out bits and small random
58			//numbers. This buffer is emptied from the right.
59			unsigned n_bb_valid;
60			//The number of valid bits in the bit buffer. When there
61			//are no more valid bits, the bit buffer must be
62			//restocked.
63			};
64
65			//Initializes the random number generation structure. If
66			//(init_val == -1), then the state will be randomized using the system
67			//clock and other system randomness. This means that the random
68			//sequence generated won't be predictable (it will vary from usage
69			//to usage of this module). If init_val is positive, the positive
70			//value will be used to initialize the state. The mapping from
71			//init_val is guaranteed to be deterministic (the same value always
72			//leads to the same sequences), but uniqueness is not guaranteed:
73			//different values of init_val may lead to the same sequences.
74			DECMOD_ESRG_RAND_INT
75			void ESRG_RAND_INT_Alg01_Init(struct ESRG_RAND_INT_Alg01RngState *state,
76			int init_val);
77
78			//Returns a single random bit.
79			DECMOD_ESRG_RAND_INT
80			unsigned int ESRG_RAND_INT_Alg01_RandomBit(
81			struct ESRG_RAND_INT_Alg01RngState *state
82			);
83			//Returns a single random byte.
84			DECMOD_ESRG_RAND_INT
85			unsigned int ESRG_RAND_INT_Alg01_RandomByte(
86			struct ESRG_RAND_INT_Alg01RngState *state
87			);
88
89			DECMOD_ESRG_RAND_INT const char *ESRG_RAND_INT_cvcinfo(void);
90			DECMOD_ESRG_RAND_INT const char *ESRG_RAND_INT_hvcinfo(void);
91	dashley	56	#define ESRG_RAND_INT_H_VERSION ("$Header$")
92	dashley	25	#endif
93
94	dashley	56	//End of esrg_rand_int.h.