Node:Description, Next:, Up:Usage

Interface Description

The interface has changed dramatically in version 2.0. As more and more generator types were added to this package, a new generic interface was needed. While still plain Ansi C, the architecture is now object-oriented.

All generators are identified by a textual description. This description is either of the form "type(parameter1,parameter2, ...)" or is a shortcut name for a common PRNG as defined in src/prng_def.h.

Calling prng_new with such a description as the only argument will allocate a new generator object, initialize it, and return its handle (struct prng *).

All further calls need this handle as the first argument. They are best explained by example:

#include <prng.h>   /* make sure that the compiler can find this file. */

   struct prng *g;
   prng_num seed, n, M;
   double next, *array;
   int count;

   g = prng_new("eicg(2147483647,111,1,0)");

   if (g == NULL) /* always check whether prng_new has been successful */
      fprintf(stderr,"Initialisation of generator failed.\n");
      exit (-1);

   printf("Short name: %s\n",prng_short_name(g));
                                  /* definition as in call to prng_new */
   printf("Expanded name: %s\n",prng_long_name(g));
                                  /* Shortcuts expanded                */

   next = prng_get_next(g);       /* get next number 0 <= next < 1     */
   prng_get_array(g,array,count); /* fill array with count numbers     */
   prng_reset(g);                 /* reset the generator */
   prng_free(g);                  /* deallocate the generator object   */


These functions work with all generators. For certain generators, the following functions are available, too:

if (prng_is_congruential(g))
   n = prng_get_next_int(g);       /* return next *unscaled* number    */
   M = prng_get_modulus(g);        /* return the modulus of the prng   */

if (prng_can_seed(g))
   prng_seed(g,seed);              /* reseed the generator             */

if (prng_can_fast_sub(g))
   puts(prng_get_sub_def(g,20,0)); /* Get subsequence definition       */

if (prng_can_fast_con(g))
   puts(prng_get_con_def(g,20,1)); /* Get block definition             */

prng_new performs only a rudimentary check on the parameters. The user is responsible for enforcing all restrictions on the parameters, such as checking that the modulus of an [E]ICG is prime, or that LCG and ICG are maximum period generators.

Most of these functions are implemented as macros, so be careful with autoincrements (++) in parameters.