[4.2] [stdlib] Add notes about future changes to high-level random algorithms

stdlib/public/core/Bool.swift

@@ -102,6 +102,12 @@ public struct Bool {
   ///         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 @@ public struct Bool {
   ///         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.

stdlib/public/core/Collection.swift

@@ -1038,14 +1038,19 @@ extension Collection {
   ///     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 @@ extension Collection {
   ///     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()

stdlib/public/core/CollectionAlgorithms.swift

@@ -387,10 +387,10 @@ extension Sequence {
   /// 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 @@ extension Sequence {
   /// - 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 @@ extension Sequence {
   ///     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 @@ extension MutableCollection where Self : RandomAccessCollection {
   ///   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 @@ extension MutableCollection where Self : RandomAccessCollection {
 
   /// 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

stdlib/public/core/FloatingPoint.swift.gyb

@@ -2416,9 +2416,15 @@ where Self.RawSignificand : FixedWidthInteger {
   ///
   /// 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 @@ where Self.RawSignificand : FixedWidthInteger {
   /// 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':

stdlib/public/core/Integers.swift.gyb

@@ -2628,6 +2628,12 @@ extension FixedWidthInteger {
   ///     // 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 @@ extension FixedWidthInteger {
   ///     // 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':