summaryrefslogtreecommitdiff
path: root/src/common/random.h
diff options
context:
space:
mode:
authorHaru <haru@dotalux.com>2016-03-13 21:12:42 +0100
committerHaru <haru@dotalux.com>2016-07-12 20:58:39 +0200
commitbdfa016ce40fb7382206775d656ba5f751ac3b49 (patch)
treec258f115f30c6c401832390b9f2f3e71454042e2 /src/common/random.h
parent7214eb1ef48352911a84ada089bbebdb0d5678f2 (diff)
downloadhercules-bdfa016ce40fb7382206775d656ba5f751ac3b49.tar.gz
hercules-bdfa016ce40fb7382206775d656ba5f751ac3b49.tar.bz2
hercules-bdfa016ce40fb7382206775d656ba5f751ac3b49.tar.xz
hercules-bdfa016ce40fb7382206775d656ba5f751ac3b49.zip
Various changes to the random interface
Mostly stylistic changes. Cleaned up documentation. Signed-off-by: Haru <haru@dotalux.com>
Diffstat (limited to 'src/common/random.h')
-rw-r--r--src/common/random.h68
1 files changed, 61 insertions, 7 deletions
diff --git a/src/common/random.h b/src/common/random.h
index 41bdb4083..1b249ef19 100644
--- a/src/common/random.h
+++ b/src/common/random.h
@@ -23,25 +23,79 @@
#include "common/hercules.h"
+/** @file
+ * The random number generator interface.
+ */
+
+/// Random interface.
struct rnd_interface {
+ /**
+ * Interface initialization.
+ *
+ * During initialization, the RNG is seeded with a random seed.
+ */
void (*init) (void);
+
+ /// Interface finalization.
void (*final) (void);
- void (*seed) (uint32);
+ /**
+ * Re-seeds the random number generator.
+ *
+ * @param seed The new seed.
+ */
+ void (*seed) (uint32 seed);
+
+ /**
+ * Generates a random number in the interval [0, SINT32_MAX].
+ */
+ int32 (*random) (void);
+
+ /**
+ * Generates a random number in the interval [0, dice_faces).
+ *
+ * @remark
+ * interval is open ended, so dice_faces is excluded (unless it's 0)
+ */
+ uint32 (*roll) (uint32 dice_faces);
- int32 (*random) (void);// [0, SINT32_MAX]
- uint32 (*roll) (uint32 dice_faces);// [0, dice_faces)
- int32 (*value) (int32 min, int32 max);// [min, max]
- double (*uniform) (void);// [0.0, 1.0)
- double (*uniform53) (void);// [0.0, 1.0)
+ /**
+ * Generates a random number in the interval [min, max].
+ *
+ * @retval min if range is invalid.
+ */
+ int32 (*value) (int32 min, int32 max);
+
+ /**
+ * Generates a random number in the interval [0.0, 1.0)
+ *
+ * @remark
+ * interval is open ended, so 1.0 is excluded
+ */
+ double (*uniform) (void);
+
+ /**
+ * Generates a random number in the interval [0.0, 1.0) with 53-bit resolution.
+ *
+ * 53 bits is the maximum precision of a double.
+ *
+ * @remark
+ * interval is open ended, so 1.0 is excluded
+ */
+ double (*uniform53) (void);
};
+/**
+ * Utlity macro to call the frequently used rnd_interface#random().
+ *
+ * @related rnd_interface.
+ */
#define rnd() rnd->random()
#ifdef HERCULES_CORE
void rnd_defaults(void);
#endif // HERCULES_CORE
-HPShared struct rnd_interface *rnd;
+HPShared struct rnd_interface *rnd; ///< Pointer to the random interface.
#endif /* COMMON_RANDOM_H */