diff options
Diffstat (limited to 'docs/source/lang/random.rst')
| -rw-r--r-- | docs/source/lang/random.rst | 90 |
1 files changed, 34 insertions, 56 deletions
diff --git a/docs/source/lang/random.rst b/docs/source/lang/random.rst index 51bee67..f2a9762 100644 --- a/docs/source/lang/random.rst +++ b/docs/source/lang/random.rst @@ -1,95 +1,73 @@ +.. highlight:: cpp + .. _lang-random: random() ======== -Description ------------ - -The random function generates pseudo-random numbers. - - - -Syntax ------- - -random(max) -random(min, max) - - - -Parameters ----------- - -min - lower bound of the random value, inclusive *(optional)* - +The ``random()`` function generates pseudo-random numbers. +.. TODO keep tracking Sphinx/Breathe's ability to reference overloaded +.. functions so we can use doxygenfunction instead of manually +.. documenting this. -max - upper bound of the random value, exclusive +Library Documentation +--------------------- +.. cpp:function:: random(long max) + Same as a call to ``random(0, max)``. -Returns -------- - -a random number between min and max-1 (*long*) +.. cpp:function:: random(long min, long max) + Generate a pseudo-random number with given lower and upper bounds. + *Parameters* -Note: ------ + - ``min`` - Lower bound on the returned value, inclusive + - ``max`` - Upper bound on the returned value, exclusive -If it is important for a sequence of values generated by random() -to differ, on subsequent executions of a sketch, use randomSeed() -to initialize the random number generator with a fairly random -input, such as analogRead() on an unconnected pin. + *Returns*: A pseudo-random number in the range [min, max). +Discussion +---------- +If it is important for a sequence of values generated by +:ref:`random() <lang-random>` to differ, on subsequent executions of a +sketch, use :ref:`randomSeed() <lang-randomseed>` to initialize the +random number generator with a fairly random input, such as +:ref:`analogRead() <lang-analogread>` on an unconnected pin. -Conversely, it can occasionally be useful to use pseudo-random +Conversely, it can occasionally be useful to use pseudorandom sequences that repeat exactly. This can be accomplished by calling -randomSeed() with a fixed number, before starting the random +``randomSeed()`` with a fixed number, before starting the random sequence. - - Example ------- -:: +The following sketch initializes the random seed based on an :ref:`ADC +<adc>` reading of pin 0. If this pin is unconnected, the Sketch +should print different values to the :ref:`serial monitor +<ide-serial-monitor>` each time it is run:: long randNumber; - void setup(){ - Serial.begin(9600); - - // if analog input pin 0 is unconnected, random analog - // noise will cause the call to randomSeed() to generate - // different seed numbers each time the sketch runs. - // randomSeed() will then shuffle the random function. + void setup() { + pinMode(0, INPUT_ANALOG); randomSeed(analogRead(0)); } void loop() { - // print a random number from 0 to 299 randNumber = random(300); - Serial.println(randNumber); - - // print a random number from 10 to 19 - randNumber = random(10, 20); - Serial.println(randNumber); + SerialUSB.println(randNumber); delay(50); } - - -See also +See Also -------- - -- `randomSeed <http://arduino.cc/en/Reference/RandomSeed>`_\ () - - +- :ref:`randomSeed() <lang-randomseed>` .. include:: cc-attribution.txt |