# SFBRandom.h File Reference

Arduino-compatible random number API for the SFB. More...

`#include "random.h"`

Include dependency graph for SFBRandom.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Functions
void | randomSeed (u32 seed)
| Reseed the pseudo-random number generator (PRNG).
long | random (u32 max)
| Get a non-negative pseudo-random number that is less than max.
long | random (int min, int max)
| Get a pseudo-random number that is greater than or equal to min but less than max.
u32 | randomBits (u32 n)
| Get a pseudo-random number containing n random bits, for n from 0 to 32 inclusive.

## Detailed Description

Arduino-compatible random number API for the SFB.

Author:
  David H. Ackley.

Date:
  (C) 2009 All rights reserved.

Code License:
  The GNU Lesser General Public License

License Note:
  All code samples shown in documentation are placed into the public domain.

## Function Documentation

long random | ( | int | min,
|  | int | max |
| ) |  |  |

Get a pseudo-random number that is greater than or equal to min but less than max.

For best efficiency (as well as code sanity), min should be less than or equal to max. However, if min is greater than max, that is not an error; instead it is treated as if the two arguments are swapped. Beyond here we assume min is no larger than max.

Parameters:

  | min | Minimum value. Returned values will always be greater than or equal to min
  | max | Minimum limit. Returned values will always be less than max (unless max equals min, in which case the returned value will always be that value.)

Returns:
  min if max==min, else a pseudo-random number from min to max-1.

Side Effects:
  The internal PRNG state is updated.

Example:

        void setup() { }
        void loop() {
          println(random(0,2));   // Prints 0 or 1 equally likely
          println(random(3,3));   // Prints 3
          println(random(-2,2));  // Prints -2, -1, 0, or 1 equally likely (note max value 2 is excluded!)
          println(random(-2,3));  // Prints -2, -1, 0, 1, or 2 equally likely
          println(random(-7,-10));// Prints -10, -9 or -8 equally likely (note max value -7 is excluded!)
          println();              // Prints a blank line
          delay(1000);
        }

long random | ( | u32 | max | ) |

Get a non-negative pseudo-random number that is less than max.

Parameters:

  | max | Size limit. Returned values will always be less than max if possible. Should be greater than or equal to 1, but passing 0 does not produce an error.

Returns:
  0 if max is 0 or 1, otherwise returns a pseudo-random number in the range of 0 through max-1, inclusive.

Side Effects:
  The internal PRNG state is updated.

Example:

        void setup() { }
        void loop() {
          println(random(2));   // Prints 0 or 1 equally likely
          println(random(3));   // Prints 0, 1, or 2 equally likely
          println(random(6));   // Prints 0, 1, 2, 3, 4, or 5 equally likely
          println();            // Prints a blank line
          delay(1000);
        }

Examples:
  alarm3.cpp, and hallucination.cpp.

u32 randomBits | ( | u32 | n | ) |

Get a pseudo-random number containing n random bits, for n from 0 to 32 inclusive.

The returned number will be in the range of 0 to (1<<n)-1.

Parameters:

  | n | Number of random bits desired. Minimum value n==0 is legal but somewhat pointless as the returned value will always be 0; any n>32 is treated as if n==32.

Returns:
  0 if n==0, otherwise a pseudo-random number from 0 to (1<<n)-1.

Side Effects:
  The internal PRNG state is updated.

Example:

        void setup() { }
        void loop() {
          println(randomBits(1), DEC);   // Prints 0 or 1 equally likely
          println(randomBits(3), DEC);   // Prints 0, 1, 2, 3, 4, 5, 6, or 7 equally likely
          println(randomBits(32), DEC);  // Prints any value from 0 to 4294967295 equally likely
          println(randomBits(99), DEC);  //     ditto
          println((int) randomBits(32)); // Prints any value from -2147483648 to 2147483647 equally likely
          println();                     // Prints a blank line
          delay(1000);
        }

void randomSeed | ( | u32 | seed | ) |

Reseed the pseudo-random number generator (PRNG).

The provided seed determines the entire sequence of numbers that will be produced by subsequent calls to random(u32), random(int,int), and/or randomBits(u32).

Note that during initialization the core software automatically seeds the PRNG with a seed that changes from one reboot to another, so, if this function is not called, the sequence of pseudo random numbers seen by the program will change from one reboot to the next. It is only necessary to call this function if you wish to ensure a repeatable sequence of random numbers for some reason -- such as debugging.

Parameters:

  | seed | Value with which to seed the PRNG.

Side Effects:
  The internal PRNG is initialized

Compare this code:

        void setup() {
          randomSeed(12);         // Set the PRNG to a known seed, once
        }
        void loop() {
          println(random(100));   // Print some decimal from 0..99
          println(random(-20,20));// Print some decimal from -20..19
          println(randomBits(16),HEX); // Print some hex from 0..FFFF
          println();            // Prints a blank line
          delay(1000);
        }

to this code:

        void setup() { }
        void loop() {
          randomSeed(12);         // RESETS the PRNG to given seed, for a demo
                                  // Note that calling randomSeed in the loop()
                                  // function (or repeatedly) is usually a BUG!

          println(random(100));   // Always prints 9 (in this specific sketch)
          println(random(-20,20));// Always prints 11 (in this specific sketch)
          println(randomBits(16),HEX); // Always prints 1EC8 (in this specific sketch)
          println();            // Prints a blank line
          delay(1000);
        }