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	//$Header$
2	//-------------------------------------------------------------------------------------------------
3	//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	//-------------------------------------------------------------------------------------------------
6	//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	//
16	//The above copyright notice and this permission notice shall be included in all
17	//copies or substantial portions of the Software.
18	//
19	//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	//-------------------------------------------------------------------------------------------------
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	#define ESRG_RAND_INT_H_VERSION ("$Header$")
92	#endif
93
94	//End of esrg_rand_int.h.