Merge pull request #16707 from natecook1000/nc-fixes-84-1 (#16711)

Author: natecook1000

docs/Random.md

@@ -0,0 +1,16 @@
+# Random APIs
+
+More documentation to come.
+
+## Platform-Specific Default Random
+
+The implementation of the default random generator varies by platform. The implementation
+on each platform must be thread-safe and automatically seeded, and should be
+cryptographically secure to the extent possible. Currently supported platforms have the
+following implementation details:
+
+- Apple platforms use `arc4random_buf(3)`.
+- Linux, FreeBSD, and other UNIX-like platforms use `getrandom(2)` when available;
+otherwise, they read from `/dev/urandom`.
+- Fuchsia platforms use `getentropy(3)`.
+- Windows platforms use `BCryptGenRandom`.

stdlib/public/core/AnyHashable.swift

@@ -287,11 +287,17 @@ extension AnyHashable : Equatable {
 }
 
 extension AnyHashable : Hashable {
+  /// The hash value.
   @inlinable // FIXME(sil-serialize-all)
   public var hashValue: Int {
     return _box._hashValue
   }
 
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     _box._hash(into: &hasher)

stdlib/public/core/Arrays.swift.gyb

@@ -2263,6 +2263,11 @@ extension ${Self} : Equatable where Element : Equatable {
 }
 
 extension ${Self}: Hashable where Element: Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     hasher.combine(count) // discriminator

stdlib/public/core/Bool.swift

@@ -87,23 +87,48 @@ public struct Bool {
     self = value
   }
 
-  /// Returns a random Boolean value
+  /// Returns a random Boolean value, using the given generator as a source for
+  /// randomness.
   ///
-  /// - Parameter generator: The random number generator to use when getting a
-  ///   random Boolean.
-  /// - Returns: A random Boolean value.
+  /// This method returns `true` and `false` with equal probability. Use this
+  /// method to generate a random Boolean value when you are using a custom
+  /// random number generator.
+  ///
+  ///     let flippedHeads = Boolean.random(using: &myGenerator)
+  ///     if flippedHeads {
+  ///         print("Heads, you win!")
+  ///     } else {
+  ///         print("Maybe another try?")
+  ///     }
+  ///
+  /// - Parameter generator: The random number generator to use when creating
+  ///   the new random value.
+  /// - Returns: Either `true` or `false`, randomly chosen with equal
+  ///   probability.
   @inlinable
   public static func random<T: RandomNumberGenerator>(
     using generator: inout T
   ) -> Bool {
     return (generator.next() >> 17) & 1 == 0
   }
 
-  /// Returns a random Boolean value
+  /// Returns a random Boolean value.
   ///
-  /// - Returns: A random Boolean value.
+  /// This method returns `true` and `false` with equal probability.
   ///
-  /// This uses the standard library's default random number generator.
+  ///     let flippedHeads = Boolean.random()
+  ///     if flippedHeads {
+  ///         print("Heads, you win!")
+  ///     } else {
+  ///         print("Maybe another try?")
+  ///     }
+  ///
+  /// `Bool.random()` uses the default random generator, `Random.default`. The
+  /// call in the example above is equivalent to
+  /// `Bool.random(using: &Random.default)`.
+  ///
+  /// - Returns: Either `true` or `false`, randomly chosen with equal
+  ///   probability.
   @inlinable
   public static func random() -> Bool {
     return Bool.random(using: &Random.default)
@@ -167,6 +192,11 @@ public // COMPILER_INTRINSIC
 func _getBool(_ v: Builtin.Int1) -> Bool { return Bool(v) }
 
 extension Bool : Equatable, Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     hasher.combine((self ? 1 : 0) as UInt8)

stdlib/public/core/CTypes.swift

@@ -174,6 +174,11 @@ extension OpaquePointer: Equatable {
 }
 
 extension OpaquePointer: Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     hasher.combine(Int(Builtin.ptrtoint_Word(_rawValue)))

stdlib/public/core/Character.swift

@@ -478,6 +478,11 @@ extension Character : Comparable {
 
 extension Character: Hashable {
   // not @inlinable (performance)
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @effects(releasenone)
   public func hash(into hasher: inout Hasher) {
     // FIXME(performance): constructing a temporary string is extremely

stdlib/public/core/ClosedRange.swift

@@ -168,6 +168,11 @@ extension ClosedRange.Index : Comparable {
 
 extension ClosedRange.Index: Hashable
 where Bound: Strideable, Bound.Stride: SignedInteger, Bound: Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     switch self {

stdlib/public/core/Codable.swift.gyb

@@ -45,6 +45,10 @@ public protocol Decodable {
 }
 
 /// A type that can convert itself into and out of an external representation.
+///
+/// `Codable` is a type alias for the `Encodable` and `Decodable` protocols.
+/// When you use `Codable` as a type or a generic constraint, it matches
+/// any type that conforms to both protocols.
 public typealias Codable = Encodable & Decodable
 
 //===----------------------------------------------------------------------===//
@@ -1095,6 +1099,11 @@ public struct CodingUserInfoKey : RawRepresentable, Equatable, Hashable {
     return self.rawValue.hashValue
   }
 
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     hasher.combine(self.rawValue)

stdlib/public/core/Collection.swift

@@ -812,7 +812,7 @@ public protocol Collection: Sequence where SubSequence: Collection {
   ///
   ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
   ///     let randomName = names.randomElement(using: &myGenerator)!
-  ///     // randomName == "Amani" (maybe)
+  ///     // randomName == "Amani"
   ///
   /// - Parameter generator: The random number generator to use when choosing
   ///   a random element.
@@ -1038,13 +1038,13 @@ extension Collection {
   /// Returns a random element of the collection, using the given generator as
   /// a source for randomness.
   ///
-  /// You use this method to select a random element from a collection when you
-  /// are using a custom random number generator. For example, call
-  /// `randomElement(using:)` to select a random element from an array of names.
+  /// Call `randomElement(using:)` to select a random element from an array or
+  /// another collection when you are using a custom random number generator.
+  /// This example picks a name at random from an array:
   ///
   ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
   ///     let randomName = names.randomElement(using: &myGenerator)!
-  ///     // randomName == "Amani" (maybe)
+  ///     // randomName == "Amani"
   ///
   /// - Parameter generator: The random number generator to use when choosing
   ///   a random element.
@@ -1065,12 +1065,12 @@ extension Collection {
 
   /// Returns a random element of the collection.
   ///
-  /// For example, call `randomElement()` to select a random element from an
-  /// array of names.
+  /// Call `randomElement()` to select a random element from an array or
+  /// another collection. This example picks a name at random from an array:
   ///
   ///     let names = ["Zoey", "Chloe", "Amani", "Amaia"]
   ///     let randomName = names.randomElement()!
-  ///     // randomName == "Amani" (perhaps)
+  ///     // randomName == "Amani"
   ///
   /// This method uses the default random generator, `Random.default`. The call
   /// to `names.randomElement()` above is equivalent to calling

stdlib/public/core/Dictionary.swift

@@ -1449,6 +1449,11 @@ extension Dictionary: Equatable where Value: Equatable {
 }
 
 extension Dictionary: Hashable where Value: Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     var commutativeHash = 0

stdlib/public/core/DropWhile.swift

@@ -183,11 +183,17 @@ extension LazyDropWhileCollection.Index: Equatable, Comparable {
 }
 
 extension LazyDropWhileCollection.Index: Hashable where Base.Index: Hashable {
+  /// The hash value.
   @inlinable // FIXME(sil-serialize-all)
   public var hashValue: Int {
     return base.hashValue
   }
 
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     hasher.combine(base)

stdlib/public/core/Flatten.swift

@@ -229,6 +229,11 @@ extension FlattenCollection.Index : Comparable {
 
 extension FlattenCollection.Index : Hashable
   where Base.Index : Hashable, Base.Element.Index : Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     hasher.combine(_outer)

stdlib/public/core/FloatingPointTypes.swift.gyb

@@ -1521,6 +1521,11 @@ extension ${Self} : _ExpressibleByBuiltinFloatLiteral {
 % end
 
 extension ${Self} : Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     var v = self

stdlib/public/core/Hashable.swift

@@ -40,9 +40,9 @@
 /// from the `Equatable` protocol, so you must also satisfy that protocol's
 /// requirements.
 ///
-/// A custom type's `Hashable` and `Equatable` requirements are automatically
-/// synthesized by the compiler when you declare `Hashable` conformance in the
-/// type's original declaration and your type meets these criteria:
+/// The compiler automatically synthesizes your custom type's `Hashable` and
+/// requirements when you declare `Hashable` conformance in the type's original
+/// declaration and your type meets these criteria:
 ///
 /// - For a `struct`, all its stored properties must conform to `Hashable`.
 /// - For an `enum`, all its associated values must conform to `Hashable`. (An
@@ -51,10 +51,14 @@
 ///
 /// To customize your type's `Hashable` conformance, to adopt `Hashable` in a
 /// type that doesn't meet the criteria listed above, or to extend an existing
-/// type to conform to `Hashable`, implement the `hash(into:)` function in your
-/// custom type. To ensure that your type meets the semantic requirements of the
-/// `Hashable` and `Equatable` protocols, it's a good idea to also customize
-/// your type's `Equatable` conformance to match the `hash(into:)` definition.
+/// type to conform to `Hashable`, implement the `hash(into:)` method in your
+/// custom type.
+///
+/// In your `hash(into:)` implementation, call `combine(_:)` on the provided
+/// `Hasher` instance with the essential components of your type. To ensure
+/// that your type meets the semantic requirements of the `Hashable` and
+/// `Equatable` protocols, it's a good idea to also customize your type's
+/// `Equatable` conformance to match.
 ///
 /// As an example, consider a `GridPoint` type that describes a location in a
 /// grid of buttons. Here's the initial declaration of the `GridPoint` type:
@@ -67,8 +71,8 @@
 ///
 /// You'd like to create a set of the grid points where a user has already
 /// tapped. Because the `GridPoint` type is not hashable yet, it can't be used
-/// as the `Element` type for a set. To add `Hashable` conformance, provide an
-/// `==` operator function and a `hash(into:)` method.
+/// in a set. To add `Hashable` conformance, provide an `==` operator function
+/// and implement the `hash(into:)` method.
 ///
 ///     extension GridPoint: Hashable {
 ///         static func == (lhs: GridPoint, rhs: GridPoint) -> Bool {
@@ -81,12 +85,9 @@
 ///         }
 ///     }
 ///
-/// The `hash(into:)` method in this example feeds the properties `x` and `y`
-/// to the supplied hasher; these are the same properties compared by the
-/// implementation of the `==` operator function.
-///
-/// (Because `x` and `y` are both `Hashable` themselves, you could've also let
-/// the compiler synthesize these implementations for you.)
+/// The `hash(into:)` method in this example feeds the grid point's `x` and `y`
+/// properties into the provided hasher. These properties are the same ones
+/// used to test for equality in the `==` operator function.
 ///
 /// Now that `GridPoint` conforms to the `Hashable` protocol, you can create a
 /// set of previously tapped grid points.
@@ -107,16 +108,19 @@ public protocol Hashable : Equatable {
   /// your program. Do not save hash values to use during a future execution.
   var hashValue: Int { get }
 
-  /// Hash the essential components of this value into the hash function
-  /// represented by `hasher`, by feeding them into it using its `combine`
-  /// methods.
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// Implement this method to conform to the `Hashable` protocol. The
+  /// components used for hashing must be the same as the components compared
+  /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
+  /// with each of these components.
   ///
-  /// Essential components are precisely those that are compared in the type's
-  /// implementation of `Equatable`.
+  /// - Important: Never call `finalize()` on `hasher`. Doing so may become a
+  ///   compile-time error in the future.
   ///
-  /// Note that `hash(into:)` doesn't own the hasher passed into it, so it must
-  /// not call `finalize()` on it. Doing so may become a compile-time error in
-  /// the future.
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   func hash(into hasher: inout Hasher)
 }
 

stdlib/public/core/Hasher.swift

@@ -226,7 +226,7 @@ internal struct _BufferingHasher<Core: _HasherCore> {
   }
 }
 
-/// Represents the universal hash function used by `Set` and `Dictionary`.
+/// The universal hash function used by `Set` and `Dictionary`.
 ///
 /// `Hasher` can be used to map an arbitrary sequence of bytes to an integer
 /// hash value. You can feed data to the hasher using a series of calls to

stdlib/public/core/Integers.swift.gyb

@@ -3879,6 +3879,11 @@ ${assignmentOperatorComment(x.operator, True)}
 %# end of concrete type: ${Self}
 
 extension ${Self} : Hashable {
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   public func hash(into hasher: inout Hasher) {
     // FIXME(hasher): To correctly bridge `Set`s/`Dictionary`s containing

stdlib/public/core/KeyPath.swift

@@ -46,11 +46,17 @@ public class AnyKeyPath: Hashable, _AppendKeyPath {
   @usableFromInline // FIXME(sil-serialize-all)
   internal final var _kvcKeyPathStringPtr: UnsafePointer<CChar>?
 
+  /// The hash value.
   @inlinable // FIXME(sil-serialize-all)
   final public var hashValue: Int {
     return _hashValue(for: self)
   }
 
+  /// Hashes the essential components of this value by feeding them into the
+  /// given hasher.
+  ///
+  /// - Parameter hasher: The hasher to use when combining the components
+  ///   of this instance.
   @inlinable // FIXME(sil-serialize-all)
   final public func hash(into hasher: inout Hasher) {
     return withBuffer {