aboutsummaryrefslogtreecommitdiffstats
path: root/source/lang/random.rst
diff options
context:
space:
mode:
Diffstat (limited to 'source/lang/random.rst')
-rw-r--r--source/lang/random.rst90
1 files changed, 34 insertions, 56 deletions
diff --git a/source/lang/random.rst b/source/lang/random.rst
index 51bee67..f2a9762 100644
--- a/source/lang/random.rst
+++ b/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