diff options
author | Hanna Mendes Levitin <hanna@anomaly-3.local> | 2010-12-01 03:37:07 -0600 |
---|---|---|
committer | Hanna Mendes Levitin <hanna@anomaly-3.local> | 2010-12-01 03:37:07 -0600 |
commit | a0549b4a15a7093f990fffa4bc1d2d52ec1c16e2 (patch) | |
tree | 9c6383570be6d045db4d8942ca3137fc3cb5b8a0 /docs/source/lang/api/random.rst | |
parent | 3b7f16dba295da3a0071564ac284c25dc56e6b18 (diff) | |
download | librambutan-a0549b4a15a7093f990fffa4bc1d2d52ec1c16e2.tar.gz librambutan-a0549b4a15a7093f990fffa4bc1d2d52ec1c16e2.zip |
docs, now with style
Diffstat (limited to 'docs/source/lang/api/random.rst')
-rw-r--r-- | docs/source/lang/api/random.rst | 73 |
1 files changed, 73 insertions, 0 deletions
diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst new file mode 100644 index 0000000..f2a9762 --- /dev/null +++ b/docs/source/lang/api/random.rst @@ -0,0 +1,73 @@ +.. highlight:: cpp + +.. _lang-random: + +random() +======== + +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. + +Library Documentation +--------------------- + +.. cpp:function:: random(long max) + + Same as a call to ``random(0, max)``. + +.. cpp:function:: random(long min, long max) + + Generate a pseudo-random number with given lower and upper bounds. + + *Parameters* + + - ``min`` - Lower bound on the returned value, inclusive + - ``max`` - Upper bound on the returned value, exclusive + + *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 pseudorandom +sequences that repeat exactly. This can be accomplished by calling +``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() { + pinMode(0, INPUT_ANALOG); + randomSeed(analogRead(0)); + } + + void loop() { + randNumber = random(300); + SerialUSB.println(randNumber); + + delay(50); + } + +See Also +-------- + +- :ref:`randomSeed() <lang-randomseed>` + +.. include:: cc-attribution.txt |