#ifndef WH_DICE_H_dca803e4_
#define WH_DICE_H_dca803e4_

#include "structs.h"

/*
 * APIs exported by dice.c.  These give the rest of the game convenient
 *  access to randomness.
 */

/*
 * Set and get the randomness seed.  This is useful for debugging, to
 *  reproduce a particular game exactly.
 */
extern unsigned long long int get_dice_seed(void);
extern void set_dice_seed(unsigned long long int);

/*
 * Three ways of getting random numbers.
 *
 * onein(N) returns true with probability 1/N, false with (N-1)/N.
 *
 * rnd(N) returns a random integer in [0..N).
 *
 * roll(dice) rolls dice based on a descriptive string, as in "d8" or
 *  "4d3+7" or "d10+d12-1".
 */
extern int onein(int);
extern int rnd(int);
extern int roll(const char *);

/*
 * Return a random value in the range [0..1) tick.
 */
extern TIME subtick(void);

/*
 * Return a random floating-point value in [0..1).
 */
extern double frnd(void);

/*
 * Support for choosing randomly from a list, with (not necessarily
 *  equal) relative probabilities.  To use this, create a RANDCHOICE
 *  array (typically but not necessarily static and initialized at
 *  compile time) and then, to make the choice, use RANDCHOOSE with the
 *  array name as argument.  The relprob values from the array must all
 *  be nonnegative, and their sum must not overflow an int; RANDCHOOSE
 *  (and rand_choose, see below) have undefined behaviour if any of
 *  those constraints are violated.  RANDCHOOSE() will panic if the
 *  probabilities' sum is zero.
 *
 * You can also call rand_choose() directly, mostly for cases where
 *  choosing the RANDCHOICE vector at compile time is inconvenient.
 *  The third argument is the value to return if all the relprob values
 *  add up to zero, or -1 to panic in that case.  Other negative values
 *  do not produce panics.
 */
typedef struct randchoice RANDCHOICE;
struct randchoice {
  int relprob;
  int choice;
  } ;
extern int rand_choose(const RANDCHOICE *, int, int);
#define RANDCHOOSE(array) rand_choose(&array[0],sizeof(array)/sizeof(array[0]),-1)

/*
 * Initialize randomness.  Called once at startup.
 */
extern void initrandom(void);

#endif