Website update

_layouts/cardlib.html

@@ -26,7 +26,7 @@ <h2>Card library</h2>
           <ul>
           <li><a href="http://github.com/lcrocker/ojcardlib">CardLib</a> on <a href="http://github.com">GitHub</a></li>
           <li><a href="/onejoker/cardlib/use.html">Using</a> CardLib</li>
-          <li>CardLib <a href="/onejoker/cardlib/downloads.html">downloads</a></li>
+          <li><a href="/onejoker/downloads/index.html">Downloads</a></li>
           <li>Other <a href="/onejoker/resources/index.html">resources</a></li>
           </ul>
           <p>Project maintained by <a href="http://github.com/lcrocker">Lee Daniel Crocker</a>

_layouts/index.html

@@ -27,10 +27,9 @@ <h2>Card game tools</h2>
           <ul>
           <li><a href="http://github.com/lcrocker/ojrandlib">RandLib</a> on <a href="http://github.com">GitHub</a></li>
           <li>RandLib <a href="/onejoker/randlib/index.html">documentation</a></li>
-          <li>RandLib <a href="/onejoker/randlib/downloads.html">downloads</a></li>
           <li><a href="http://github.com/lcrocker/ojcardlib">CardLib</a> on GitHub</li>
           <li>CardLib <a href="/onejoker/cardlib/index.html">documentation</a></li>
-          <li>CardLib <a href="/onejoker/cardlib/downloads.html">downloads</a></li>
+          <li><a href="/onejoker/downloads/index.html">Downloads</a></li>
           <li>Other <a href="/onejoker/resources/index.html">resources</a></li>
           </ul>
           <p>Project maintained by <a href="http://github.com/lcrocker">Lee Daniel Crocker</a>

_layouts/randlib.html

@@ -26,7 +26,8 @@ <h2>PRNG library</h2>
           <ul>
           <li><a href="http://github.com/lcrocker/ojrandlib">RandLib</a> on <a href="http://github.com">GitHub</a></li>
           <li><a href="/onejoker/randlib/use.html">Using</a> RandLib</li>
-          <li>CardLib <a href="/onejoker/randlib/downloads.html">downloads</a></li>
+          <li>RandLib <a href="/onejoker/randlib/devel.html">development</a></li>
+          <li><a href="/onejoker/downloads/index.html">Downloads</a></li>
           <li>Other <a href="/onejoker/resources/index.html">resources</a></li>
           </ul>
           <p>Project maintained by <a href="http://github.com/lcrocker">Lee Daniel Crocker</a>

downloads/index.textile

@@ -0,0 +1,12 @@
+---
+layout: index
+title: OneJoker Project Downloads
+---
+
+h1. OneJoker project downloads
+
+h2. RandLib
+
+h2. CardLib
+
+

randlib/capi.textile

@@ -0,0 +1,113 @@
+---
+layout: randlib
+title: "RandLib C API"
+---
+
+h1. Using the library in your C code
+
+h2. Quickstart
+
+All of the functions of the RandLib C API begin with @ojr_@. There are two ways to interact with the library. You can create @ojr_generator@ objects with a specific algorithm and pass a pointer to your generator to all the functions, or you can just call the functions with NULL as the generator argument and get the library's "default" generator. Here's a simple example of using the C API to print 10 random numbers in the range 0...99, using the Mersenne Twister algorithm.
+
+{% highlight cpp %}
+ojr_generator *g = ojr_open("mt19937");
+ojr_system_seed(g);
+
+for (int i = 0; i < 10; ++i) {
+    printf("%d ", ojr_rand(g, 100));
+}
+printf("\n");
+ojr_close(g);
+{% endhighlight %}
+
+We first create a new generator object with @ojr_open()@, which returns a pointer to the newly created generator. This allocates memory for the generator's internal structures, so we have to call @ojr_close()@ to free those up later. We then seed the generator with a call to @ojr_system_seed()@, which uses whatever randomness is available from your operating system to seed the generator (this is done automatically if you use the "default" generator). Finally, @ojr_rand()@ fetches a random integer in the range 0 to the given limit - 1, each with equal probability.
+
+That's all you need for basic use, for example, writing a simple card game. There are many other functions available for more complex needs, detailed below.
+
+h2. Basic generator functions
+
+h3. @ojr_generator *ojr_open(char *algorithm)@
+
+Creates a new generator using the algorithm named by the single argument. If you pass NULL, a reasonable default algorithm will be chosen. See the @ojr_algorithm_*@ functions below for how to get information on the available algorithms. The generator objects returned by this function are totally independent of each other, regardless of algorithm. In particular, if you create two generators with the same algorithm and same seed, they will independently produce the same stream of random numbers (this can be handy for writing test programs, for example).
+
+h3. @ojr_close(ojr_generator *g)@
+
+Closes and frees all allocated resources of the given generator. Using the pointer after this will produce undefined results. If you fail to close a generator created by @ojr_open()@, it will be closed when the library is unloaded, and produce a warning message. When the library is unloaded is dependent on the OS, so it is best to avoid this memory leak.
+
+h3. @ojr_system_seed(ojr_generator *g)@
+
+Seeds the given generator with random values derived from whatever entropy is available from your operating system. The size of the seed will be chosen to suit the algorithm. If you need to save the value of a system-generated seed for reproduction later, you will have to instead call @ojr_get_system_entropy()@ with appropriate arguments followed by @ojr_array_seed()@ (see below).
+
+h3. @ojr_int_seed(ojr_generator *g, int val)@
+
+Seeds the generator with the integer value @val@.
+
+h3. @ojr_array_seed(ojr_generator *g, uint32_t *seed, int count)@
+
+Seeds the generator with the given array of the 32-bit unsigned ints. This allows you to produce many more random sequences than are possible with a single integer seed, while still allowing reproducibility.
+
+h3. @ojr_reseed(ojr_generator *g, uint32_t *seed, int count)@
+
+Applies a new seed to an existing generator to change its state "on the fly" without re-initializing. This function should not be needed by most applications. It could be used, for example, to occasionally add extra system entropy to a generator to make it more cryptographically secure. This eliminates reproducibility.
+
+h3. @ojr_discard(ojr_generator *g, int count)@
+
+Advances the generator @count@ steps wihout producing actual output. This is roughly equivalent to calling @ojr_next32(g)@ (see below) @count@ times, though it is a bit faster due to reduced function call overhead. Some generator algorithms benefit from discarding some number of values after initialization before using their output.
+
+h2. Producing output
+
+Now that you've created and generator and seeded it, you can use it to produce random numbers in various ways.
+
+h3. @uint32_t ojr_next32(ojr_generator *g)@
+
+Produces a random 32-bit unsigned integer. All of the algorithms included in ojrandlib are natively 32-bit generators, so the most basic way to get random values is to get them as 32-bit unsigned integers. All of the other producer functions are based on this one.
+
+h3. @uint16_t ojr_next16(ojr_generator *g)@
+
+Produce a 16-bit random unsigned integer.
+
+h3. @uint64_t ojr_next64(ojr_generator *g)@
+
+Produce a 64-bit random unsigned integer.
+
+h3. @int ojr_rand(ojr_generator *g, int limit)@
+
+Produces a random integer in the range 0...(limit-1). This is the most useful function for randomly choosing from among a small set of alternatives, for example, selecting a random card from a deck of cards. The numbers are guaranteed to be balanced. That is, if you ask for numbers from 0 to 2, you will get 0, 1, and 2 with exactly equal probability. The maximum limit for this function is 32768.
+
+h3. @double ojr_next_double(ojr_generator *g)@
+
+Produces a random double value uniformly distributed in the half-open interval [0.0, 1.0). That is, it may produce the value 0.0, but will never produce 1.0, and will produce every representable value in between with equal probability.
+
+h3. @double ojr_next_signed_double(ojr_generator *g)@
+
+Produces a random double value uniformly distributed in the open interval (-1.0, 1.0). That is, it will never produce the values -1.0 or 1.0, and will produce every representable value in between with equal probability.
+
+h3. @double ojr_next_gaussian(ojr_generator *g)@
+
+Produces a random double value normally distributed about a mean of 0.0 with a standard deviation of 1.0.
+
+h2. Non-generator functions
+
+These functions do not take a generator object argument because they provide information or services independent of any particular generator.
+
+h3. @ojr_get_system_entropy(uint32_t *seed, int count)@
+
+Fills the given array (which must have room for @count@ 32-bit unsinged integers) with random bits from whatever source of randomness your OS provides. On Linux-like systems, this will be @/dev/urandom@. On Windows, @CryptGenRandom()@ from the cryptography library will be used. If neither of these is available, the system time and process ID will be used. You should only use this function manually if you need both a good quality seed for a generator and need to save it for reproducibility later. Otherwise, simply using @ojr_system_seed()@ on the generator is much simpler.
+
+h3. @ojr_algorithm_count()@
+
+Returns the number of algorithms available in the system.
+
+h3. @char *ojr_algorithm_name(int a)@
+
+Returns the name of the algorithm at the given index. Algorithms are identified by an integer from 1 to the number available. So, to list all the available algorithms by name, one could use code like the following:
+
+{% highlight cpp %}
+int i, n = ojr_algorithm_count();
+
+for (i = 1; i <= n; ++i) {
+    printf("%s\n", ojr_algorithm_name(i));
+}
+{% endhighlight %}
+
+Passing a value of 0 will return the name of the "default" algorithm, which is the one that will be used when you call @ojr_open(NULL)@.

randlib/cppapi.textile

@@ -0,0 +1,113 @@
+---
+layout: randlib
+title: "RandLib C++ API"
+---
+
+h1. Using the library in your C++ code
+
+h2. Quickstart
+
+All of the functions of the RandLib C API begin with @ojr_@. There are two ways to interact with the library. You can create @ojr_generator@ objects with a specific algorithm and pass a pointer to your generator to all the functions, or you can just call the functions with NULL as the generator argument and get the library's "default" generator. Here's a simple example of using the C API to print 10 random numbers in the range 0...99, using the Mersenne Twister algorithm.
+
+{% highlight cpp %}
+ojr_generator *g = ojr_open("mt19937");
+ojr_system_seed(g);
+
+for (int i = 0; i < 10; ++i) {
+    printf("%d ", ojr_rand(g, 100));
+}
+printf("\n");
+ojr_close(g);
+{% endhighlight %}
+
+We first create a new generator object with @ojr_open()@, which returns a pointer to the newly created generator. This allocates memory for the generator's internal structures, so we have to call @ojr_close()@ to free those up later. We then seed the generator with a call to @ojr_system_seed()@, which uses whatever randomness is available from your operating system to seed the generator (this is done automatically if you use the "default" generator). Finally, @ojr_rand()@ fetches a random integer in the range 0 to the given limit - 1, each with equal probability.
+
+That's all you need for basic use, for example, writing a simple card game. There are many other functions available for more complex needs, detailed below.
+
+h2. Basic generator functions
+
+h3. @ojr_generator *ojr_open(char *algorithm)@
+
+Creates a new generator using the algorithm named by the single argument. If you pass NULL, a reasonable default algorithm will be chosen. See the @ojr_algorithm_*@ functions below for how to get information on the available algorithms. The generator objects returned by this function are totally independent of each other, regardless of algorithm. In particular, if you create two generators with the same algorithm and same seed, they will independently produce the same stream of random numbers (this can be handy for writing test programs, for example).
+
+h3. @ojr_close(ojr_generator *g)@
+
+Closes and frees all allocated resources of the given generator. Using the pointer after this will produce undefined results. If you fail to close a generator created by @ojr_open()@, it will be closed when the library is unloaded, and produce a warning message. When the library is unloaded is dependent on the OS, so it is best to avoid this memory leak.
+
+h3. @ojr_system_seed(ojr_generator *g)@
+
+Seeds the given generator with random values derived from whatever entropy is available from your operating system. The size of the seed will be chosen to suit the algorithm. If you need to save the value of a system-generated seed for reproduction later, you will have to instead call @ojr_get_system_entropy()@ with appropriate arguments followed by @ojr_array_seed()@ (see below).
+
+h3. @ojr_int_seed(ojr_generator *g, int val)@
+
+Seeds the generator with the integer value @val@.
+
+h3. @ojr_array_seed(ojr_generator *g, uint32_t *seed, int count)@
+
+Seeds the generator with the given array of the 32-bit unsigned ints. This allows you to produce many more random sequences than are possible with a single integer seed, while still allowing reproducibility.
+
+h3. @ojr_reseed(ojr_generator *g, uint32_t *seed, int count)@
+
+Applies a new seed to an existing generator to change its state "on the fly" without re-initializing. This function should not be needed by most applications. It could be used, for example, to occasionally add extra system entropy to a generator to make it more cryptographically secure. This eliminates reproducibility.
+
+h3. @ojr_discard(ojr_generator *g, int count)@
+
+Advances the generator @count@ steps wihout producing actual output. This is roughly equivalent to calling @ojr_next32(g)@ (see below) @count@ times, though it is a bit faster due to reduced function call overhead. Some generator algorithms benefit from discarding some number of values after initialization before using their output.
+
+h2. Producing output
+
+Now that you've created and generator and seeded it, you can use it to produce random numbers in various ways.
+
+h3. @uint32_t ojr_next32(ojr_generator *g)@
+
+Produces a random 32-bit unsigned integer. All of the algorithms included in ojrandlib are natively 32-bit generators, so the most basic way to get random values is to get them as 32-bit unsigned integers. All of the other producer functions are based on this one.
+
+h3. @uint16_t ojr_next16(ojr_generator *g)@
+
+Produce a 16-bit random unsigned integer.
+
+h3. @uint64_t ojr_next64(ojr_generator *g)@
+
+Produce a 64-bit random unsigned integer.
+
+h3. @int ojr_rand(ojr_generator *g, int limit)@
+
+Produces a random integer in the range 0...(limit-1). This is the most useful function for randomly choosing from among a small set of alternatives, for example, selecting a random card from a deck of cards. The numbers are guaranteed to be balanced. That is, if you ask for numbers from 0 to 2, you will get 0, 1, and 2 with exactly equal probability. The maximum limit for this function is 32768.
+
+h3. @double ojr_next_double(ojr_generator *g)@
+
+Produces a random double value uniformly distributed in the half-open interval [0.0, 1.0). That is, it may produce the value 0.0, but will never produce 1.0, and will produce every representable value in between with equal probability.
+
+h3. @double ojr_next_signed_double(ojr_generator *g)@
+
+Produces a random double value uniformly distributed in the open interval (-1.0, 1.0). That is, it will never produce the values -1.0 or 1.0, and will produce every representable value in between with equal probability.
+
+h3. @double ojr_next_gaussian(ojr_generator *g)@
+
+Produces a random double value normally distributed about a mean of 0.0 with a standard deviation of 1.0.
+
+h2. Non-generator functions
+
+These functions do not take a generator object argument because they provide information or services independent of any particular generator.
+
+h3. @ojr_get_system_entropy(uint32_t *seed, int count)@
+
+Fills the given array (which must have room for @count@ 32-bit unsinged integers) with random bits from whatever source of randomness your OS provides. On Linux-like systems, this will be @/dev/urandom@. On Windows, @CryptGenRandom()@ from the cryptography library will be used. If neither of these is available, the system time and process ID will be used. You should only use this function manually if you need both a good quality seed for a generator and need to save it for reproducibility later. Otherwise, simply using @ojr_system_seed()@ on the generator is much simpler.
+
+h3. @ojr_algorithm_count()@
+
+Returns the number of algorithms available in the system.
+
+h3. @char *ojr_algorithm_name(int a)@
+
+Returns the name of the algorithm at the given index. Algorithms are identified by an integer from 1 to the number available. So, to list all the available algorithms by name, one could use code like the following:
+
+{% highlight cpp %}
+int i, n = ojr_algorithm_count();
+
+for (i = 1; i <= n; ++i) {
+    printf("%s\n", ojr_algorithm_name(i));
+}
+{% endhighlight %}
+
+Passing a value of 0 will return the name of the "default" algorithm, which is the one that will be used when you call @ojr_open(NULL)@.