Merge pull request #19166 from natecook1000/nc42-random-notes
[4.2] [stdlib] Add notes about future changes to high-level random algorithms
diff --git a/stdlib/public/core/Bool.swift b/stdlib/public/core/Bool.swift
index 50c7217..23f4607 100644
--- a/stdlib/public/core/Bool.swift
+++ b/stdlib/public/core/Bool.swift
@@ -102,6 +102,12 @@
/// print("Maybe another try?")
/// }
///
+ /// - Note: The algorithm used to create random values may change in a future
+ /// version of Swift. If you're passing a generator that results in the
+ /// same sequence of Boolean values each time you run your program, that
+ /// sequence may change when your program is compiled using a different
+ /// version of Swift.
+ ///
/// - Parameter generator: The random number generator to use when creating
/// the new random value.
/// - Returns: Either `true` or `false`, randomly chosen with equal
@@ -124,9 +130,8 @@
/// print("Maybe another try?")
/// }
///
- /// `Bool.random()` uses the default random generator,
- /// `SystemRandomNumberGenerator`. To supply a non-default generator, call the
- /// equivalent method that takes one as an argument.
+ /// This method is equivalent to calling `Bool.random(using:)`, passing in
+ /// the system's default random generator.
///
/// - Returns: Either `true` or `false`, randomly chosen with equal
/// probability.
diff --git a/stdlib/public/core/Collection.swift b/stdlib/public/core/Collection.swift
index 28d8e16..d94b5ed 100644
--- a/stdlib/public/core/Collection.swift
+++ b/stdlib/public/core/Collection.swift
@@ -1038,14 +1038,19 @@
/// let randomName = names.randomElement(using: &myGenerator)!
/// // randomName == "Amani"
///
- /// - Parameter generator: The random number generator to use when choosing
- /// a random element.
+ /// - Parameter generator: The random number generator to use when choosing a
+ /// random element.
/// - Returns: A random element from the collection. If the collection is
/// empty, the method returns `nil`.
///
/// - Complexity: O(1) if the collection conforms to
- /// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length of
- /// the collection.
+ /// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length
+ /// of the collection.
+ /// - Note: The algorithm used to select a random element may change in a
+ /// future version of Swift. If you're passing a generator that results in
+ /// the same sequence of elements each time you run your program, that
+ /// sequence may change when your program is compiled using a different
+ /// version of Swift.
@inlinable
public func randomElement<T: RandomNumberGenerator>(
using generator: inout T
@@ -1068,15 +1073,15 @@
/// let randomName = names.randomElement()!
/// // randomName == "Amani"
///
- /// This method is equivalent to calling the version that takes a generator,
- /// passing in the system's default random generator.
+ /// This method is equivalent to calling `randomElement(using:)`, passing in
+ /// the system's default random generator.
///
/// - Returns: A random element from the collection. If the collection is
/// empty, the method returns `nil`.
///
/// - Complexity: O(1) if the collection conforms to
- /// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length of
- /// the collection.
+ /// `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length
+ /// of the collection.
@inlinable
public func randomElement() -> Element? {
var g = SystemRandomNumberGenerator()
diff --git a/stdlib/public/core/CollectionAlgorithms.swift b/stdlib/public/core/CollectionAlgorithms.swift
index 83fa7e3..23ab598 100644
--- a/stdlib/public/core/CollectionAlgorithms.swift
+++ b/stdlib/public/core/CollectionAlgorithms.swift
@@ -387,10 +387,10 @@
/// Returns the elements of the sequence, shuffled using the given generator
/// as a source for randomness.
///
- /// You use this method to randomize the elements of a sequence when you
- /// are using a custom random number generator. For example, you can shuffle
- /// the numbers between `0` and `9` by calling the `shuffled(using:)` method
- /// on that range:
+ /// You use this method to randomize the elements of a sequence when you are
+ /// using a custom random number generator. For example, you can shuffle the
+ /// numbers between `0` and `9` by calling the `shuffled(using:)` method on
+ /// that range:
///
/// let numbers = 0...9
/// let shuffledNumbers = numbers.shuffled(using: &myGenerator)
@@ -401,6 +401,11 @@
/// - Returns: An array of this sequence's elements in a shuffled order.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
+ /// - Note: The algorithm used to shuffle a sequence may change in a future
+ /// version of Swift. If you're passing a generator that results in the
+ /// same shuffled order each time you run your program, that sequence may
+ /// change when your program is compiled using a different version of
+ /// Swift.
@inlinable
public func shuffled<T: RandomNumberGenerator>(
using generator: inout T
@@ -419,8 +424,8 @@
/// let shuffledNumbers = numbers.shuffled()
/// // shuffledNumbers == [1, 7, 6, 2, 8, 9, 4, 3, 5, 0]
///
- /// This method is equivalent to calling the version that takes a generator,
- /// passing in the system's default random generator.
+ /// This method is equivalent to calling `shuffled(using:)`, passing in the
+ /// system's default random generator.
///
/// - Returns: A shuffled array of this sequence's elements.
///
@@ -448,6 +453,11 @@
/// the collection.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
+ /// - Note: The algorithm used to shuffle a collection may change in a future
+ /// version of Swift. If you're passing a generator that results in the
+ /// same shuffled order each time you run your program, that sequence may
+ /// change when your program is compiled using a different version of
+ /// Swift.
@inlinable
public mutating func shuffle<T: RandomNumberGenerator>(
using generator: inout T
@@ -469,15 +479,14 @@
/// Shuffles the collection in place.
///
- /// Use the `shuffle()` method to randomly reorder the elements of an
- /// array.
+ /// Use the `shuffle()` method to randomly reorder the elements of an array.
///
/// var names = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"]
/// names.shuffle(using: myGenerator)
/// // names == ["Luis", "Camila", "Luciana", "Sofía", "Alejandro", "Diego"]
///
- /// This method is equivalent to calling the version that takes a generator,
- /// passing in the system's default random generator.
+ /// This method is equivalent to calling `shuffle(using:)`, passing in the
+ /// system's default random generator.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
diff --git a/stdlib/public/core/FloatingPoint.swift.gyb b/stdlib/public/core/FloatingPoint.swift.gyb
index ef66414..5af1455 100644
--- a/stdlib/public/core/FloatingPoint.swift.gyb
+++ b/stdlib/public/core/FloatingPoint.swift.gyb
@@ -2416,9 +2416,15 @@
///
/// The `random(in:using:)` static method chooses a random value from a
/// continuous uniform distribution in `range`, and then converts that value
- /// to the nearest representable value in this type. Depending on the size and
- /// span of `range`, some concrete values may be represented more frequently
- /// than others.
+ /// to the nearest representable value in this type. Depending on the size
+ /// and span of `range`, some concrete values may be represented more
+ /// frequently than others.
+ ///
+ /// - Note: The algorithm used to create random values may change in a future
+ /// version of Swift. If you're passing a generator that results in the
+ /// same sequence of floating-point values each time you run your program,
+ /// that sequence may change when your program is compiled using a
+ /// different version of Swift.
///
/// - Parameters:
/// - range: The range in which to create a random value.
@@ -2502,8 +2508,8 @@
/// of `range`, some concrete values may be represented more frequently than
/// others.
///
- /// This method is equivalent to calling the version that takes a generator,
- /// passing in the system's default random generator.
+ /// This method is equivalent to calling `random(in:using:)`, passing in the
+ /// system's default random generator.
///
/// - Parameter range: The range in which to create a random value.
% if Range == 'Range':
diff --git a/stdlib/public/core/Integers.swift.gyb b/stdlib/public/core/Integers.swift.gyb
index d582ff0..2fac0b3 100644
--- a/stdlib/public/core/Integers.swift.gyb
+++ b/stdlib/public/core/Integers.swift.gyb
@@ -2628,6 +2628,12 @@
/// // Prints "44"
/// // Prints "21"
///
+ /// - Note: The algorithm used to create random values may change in a future
+ /// version of Swift. If you're passing a generator that results in the
+ /// same sequence of integer values each time you run your program, that
+ /// sequence may change when your program is compiled using a different
+ /// version of Swift.
+ ///
/// - Parameters:
/// - range: The range in which to create a random value.
% if Range == 'Range':
@@ -2689,8 +2695,8 @@
/// // Prints "64"
/// // Prints "5"
///
- /// This method is equivalent to calling the version that takes a generator,
- /// passing in the system's default random generator.
+ /// This method is equivalent to calling `random(in:using:)`, passing in the
+ /// system's default random generator.
///
/// - Parameter range: The range in which to create a random value.
% if Range == 'Range':
