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, hallucination.cpp, qled1.cpp, reorder.cpp, and speed4.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);
    }

Generated on Fri Apr 22 06:56:36 2011 for SFB by doxygen 1.5.9