diff options
| -rw-r--r-- | docs/crandom_api.md | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/docs/crandom_api.md b/docs/crandom_api.md new file mode 100644 index 00000000..59389d5e --- /dev/null +++ b/docs/crandom_api.md @@ -0,0 +1,61 @@ +# Introduction + +UNDER CONSTRUCTION! + +This describes the API of module **crandom**. + +## Types + +| crandom | Type definition | Used to represent... | +|:----------------------|:-------------------------------------------|:-------------------------------------| +| `crand_rng32_t` | `struct {uint64_t state[2];}` | The crandom type | +| `crand_uniform_i32_t` | `struct {int32_t offset; uint32_t range;}` | The crandom element type | +| `crand_uniform_f32_t` | `struct {float offset, range;}` | crandom iterator | +| `crand_rng64_t` | `struct {uint64_t state[4];}` | | +| `crand_uniform_i64_t` | `struct {int64_t offset; uint64_t range;}` | | +| `crand_uniform_f64_t` | `struct {double offset, range;}` | | +| `crand_normal_f64_t` | `struct {double mean, stddev, next; bool has_next;}` | | + +## Header file + +All cstr definitions and prototypes may be included in your C source file by including a single header file. +```c +#include "stc/crandom.h" +``` + +## Methods + +### Construction + +Interfaces to create 32-bits random numbers: +```c +crand_rng32_t crand_rng32_with_seq(uint64_t seed, uint64_t seq); +crand_rng32_t crand_rng32_init(uint64_t seed); + +uint32_t crand_i32(crand_rng32_t* rng); /* int random number generator, range [0, 2^32) */ +float crand_f32(crand_rng32_t* rng); + +crand_uniform_i32_t crand_uniform_i32_init(int32_t low, int32_t high); /* int generator in range [low, high] */ +int32_t crand_uniform_i32(crand_rng32_t* rng, crand_uniform_i32_t* dist); + +uint32_t crand_unbiased_i32(crand_rng32_t* rng, crand_uniform_i32_t* dist); /* https://github.com/lemire/fastrange */ +crand_uniform_f32_t crand_uniform_f32_init(float low, float high); /* float random number in range [low, high). Note: 23 bit resolution. */ +float crand_uniform_f32(crand_rng32_t* rng, crand_uniform_f32_t* dist); +``` +Interfaces to create 64-bits random numbers: +```c +crand_rng64_t crand_rng64_with_seq(uint64_t seed, uint64_t seq); /* engine initializers */ +crand_rng64_t crand_rng64_init(uint64_t seed); + +uint64_t crand_i64(crand_rng64_t* rng); /* int generator, range [0, 2^64). PRNG copyright Tyge Løvset, NORCE Research, 2020 */ +double crand_f64(crand_rng64_t* rng); /* double random number in range [low, high). 52 bit resolution. */ + +crand_uniform_i64_t crand_uniform_i64_init(int64_t low, int64_t high); /* int generator in range [low, high] */ +int64_t crand_uniform_i64(crand_rng64_t* rng, crand_uniform_i64_t* dist); + +crand_uniform_f64_t crand_uniform_f64_init(double low, double high); +double crand_uniform_f64(crand_rng64_t* rng, crand_uniform_f64_t* dist); + +crand_normal_f64_t crand_normal_f64_init(double mean, double stddev); +double crand_normal_f64(crand_rng64_t* rng, crand_normal_f64_t* dist); +``` |