Documentation update for Random class
Examples added
Closes https://github.com/dart-lang/sdk/pull/47986
https://github.com/dart-lang/sdk/pull/47986
GitOrigin-RevId: ecb3a428e3974d0505e8846626bd897359612117
Change-Id: I3c3a406482be6cb55bb01aba4f78c74ae2d7648f
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/225120
Reviewed-by: Lasse Nielsen <lrn@google.com>
Commit-Queue: Lasse Nielsen <lrn@google.com>
diff --git a/sdk/lib/math/random.dart b/sdk/lib/math/random.dart
index fd75e12..35fdd14 100644
--- a/sdk/lib/math/random.dart
+++ b/sdk/lib/math/random.dart
@@ -10,6 +10,24 @@
/// not suitable for cryptographic purposes.
///
/// Use the [Random.secure]() constructor for cryptographic purposes.
+///
+/// To create a non-negative random integer uniformly distributed in the range
+/// from 0, inclusive, to max, exclusive, use [nextInt(int max)].
+/// ```dart
+/// var intValue = Random().nextInt(10); // Value is >= 0 and < 10.
+/// intValue = Random().nextInt(100) + 50; // Value is >= 50 and < 150.
+/// ```
+/// To create a non-negative random floating point value uniformly distributed
+/// in the range from 0.0, inclusive, to 1.0, exclusive, use [nextDouble].
+/// ```dart
+/// var doubleValue = Random().nextDouble(); // Value is >= 0.0 and < 1.0.
+/// doubleValue = Random().nextDouble() * 256; // Value is >= 0.0 and < 256.0.
+/// ```
+/// To create a random Boolean value, use [nextBool].
+/// ```dart
+/// var boolValue = Random().nextBool(); // true or false, with equal chance.
+/// ```
+///
abstract class Random {
/// Creates a random number generator.
///
@@ -29,12 +47,29 @@
///
/// Implementation note: The default implementation supports [max] values
/// between 1 and (1<<32) inclusive.
+ ///
+ /// Example:
+ /// ```dart
+ /// var intValue = Random().nextInt(10); // Value is >= 0 and < 10.
+ /// intValue = Random().nextInt(100) + 50; // Value is >= 50 and < 150.
+ /// ```
int nextInt(int max);
/// Generates a non-negative random floating point value uniformly distributed
/// in the range from 0.0, inclusive, to 1.0, exclusive.
+ ///
+ /// Example:
+ /// ```dart
+ /// var doubleValue = Random().nextDouble(); // Value is >= 0.0 and < 1.0.
+ /// doubleValue = Random().nextDouble() * 256; // Value is >= 0.0 and < 256.0.
+ /// ```
double nextDouble();
/// Generates a random boolean value.
+ ///
+ /// Example:
+ /// ```dart
+ /// var boolValue = Random().nextBool(); // true or false, with equal chance.
+ /// ```
bool nextBool();
}
