Merge pull request #11670 from natecook1000/nc-rev-77-2

Author: swift-ci

stdlib/public/core/Character.swift

@@ -25,29 +25,29 @@
 ///     // Prints "Length: 8"
 ///
 /// Because each character in a string can be made up of one or more Unicode
-/// code points, the number of characters in a string may not match the length
-/// of the Unicode code point representation or the length of the string in a
-/// particular binary representation.
+/// scalar values, the number of characters in a string may not match the
+/// length of the Unicode scalar value representation or the length of the
+/// string in a particular binary representation.
 ///
-///     print("Unicode code point count: \(greeting.unicodeScalars.count)")
-///     // Prints "Unicode code point count: 15"
+///     print("Unicode scalar value count: \(greeting.unicodeScalars.count)")
+///     // Prints "Unicode scalar value count: 15"
 ///
 ///     print("UTF-8 representation count: \(greeting.utf8.count)")
 ///     // Prints "UTF-8 representation count: 18"
 ///
-/// Every `Character` instance is composed of one or more Unicode code points
+/// Every `Character` instance is composed of one or more Unicode scalar values
 /// that are grouped together as an *extended grapheme cluster*. The way these
-/// code points are grouped is defined by a canonical, localized, or otherwise
-/// tailored Unicode segmentation algorithm.
+/// scalar values are grouped is defined by a canonical, localized, or
+/// otherwise tailored Unicode segmentation algorithm.
 ///
 /// For example, a country's Unicode flag character is made up of two regional
-/// indicator code points that correspond to that country's ISO 3166-1 alpha-2
-/// code. The alpha-2 code for The United States is "US", so its flag
-/// character is made up of the Unicode code points `"\u{1F1FA}"` (REGIONAL
+/// indicator scalar values that correspond to that country's ISO 3166-1
+/// alpha-2 code. The alpha-2 code for The United States is "US", so its flag
+/// character is made up of the Unicode scalar values `"\u{1F1FA}"` (REGIONAL
 /// INDICATOR SYMBOL LETTER U) and `"\u{1F1F8}"` (REGIONAL INDICATOR SYMBOL
-/// LETTER S). When placed next to each other in a Swift string literal, these
-/// two code points are combined into a single grapheme cluster, represented
-/// by a `Character` instance in Swift.
+/// LETTER S). When placed next to each other in a string literal, these two
+/// scalar values are combined into a single grapheme cluster, represented by
+/// a `Character` instance in Swift.
 ///
 ///     let usFlag: Character = "\u{1F1FA}\u{1F1F8}"
 ///     print(usFlag)

stdlib/public/core/CompilerProtocols.swift

@@ -363,15 +363,15 @@ public protocol _ExpressibleByBuiltinExtendedGraphemeClusterLiteral
 /// A type that can be initialized with a string literal containing a single
 /// extended grapheme cluster.
 ///
-/// An *extended grapheme cluster* is a group of one or more Unicode code
-/// points that approximates a single user-perceived character.  Many
+/// An *extended grapheme cluster* is a group of one or more Unicode scalar
+/// values that approximates a single user-perceived character.  Many
 /// individual characters, such as "é", "김", and "🇮🇳", can be made up of
-/// multiple Unicode code points. These code points are combined by Unicode's
-/// boundary algorithms into extended grapheme clusters.
+/// multiple Unicode scalar values. These code points are combined by
+/// Unicode's boundary algorithms into extended grapheme clusters.
 ///
 /// The `String`, `StaticString`, and `Character` types conform to the
-/// `ExpressibleByExtendedGraphemeClusterLiteral` protocol. You can initialize a
-/// variable or constant of any of these types using a string literal that
+/// `ExpressibleByExtendedGraphemeClusterLiteral` protocol. You can initialize
+/// a variable or constant of any of these types using a string literal that
 /// holds a single character.
 ///
 ///     let snowflake: Character = "❄︎"
@@ -505,8 +505,8 @@ extension ExpressibleByStringLiteral
 ///   initialize a type that conforms to `ExpressibleByArrayLiteral` simply by
 ///   assigning an existing array.
 ///
-///         let anotherSet: Set = employeesArray
-///         // error: cannot convert value of type '[String]' to specified type 'Set'
+///       let anotherSet: Set = employeesArray
+///       // error: cannot convert value of type '[String]' to specified type 'Set'
 ///
 /// Type Inference of Array Literals
 /// ================================

stdlib/public/core/Dump.swift

@@ -10,7 +10,21 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Dumps an object's contents using its mirror to the specified output stream.
+/// Dumps the given object's contents using its mirror to the specified output
+/// stream.
+///
+/// - Parameters:
+///   - value: The value to output to the `target` stream.
+///   - target: The stream to use for writing the contents of `value`.
+///   - name: A label to use when writing the contents of `value`. When `nil`
+///     is passed, the label is omitted. The default is `nil`.
+///   - indent: The number of spaces to use as an indent for each line of the
+///     output. The default is `0`.
+///   - maxDepth: The maximum depth to descend when writing the contents of a
+///     value that has nested components. The default is `Int.max`.
+///   - maxItems: The maximum number of elements for which to write the full
+///     contents. The default is `Int.max`.
+/// - Returns: The instance passed as `value`.
 @discardableResult
 @_semantics("optimize.sil.specialize.generic.never")
 public func dump<T, TargetStream : TextOutputStream>(
@@ -36,7 +50,19 @@ public func dump<T, TargetStream : TextOutputStream>(
   return value
 }
 
-/// Dumps an object's contents using its mirror to standard output.
+/// Dumps the given object's contents using its mirror to standard output.
+///
+/// - Parameters:
+///   - value: The value to output to the `target` stream.
+///   - name: A label to use when writing the contents of `value`. When `nil`
+///     is passed, the label is omitted. The default is `nil`.
+///   - indent: The number of spaces to use as an indent for each line of the
+///     output. The default is `0`.
+///   - maxDepth: The maximum depth to descend when writing the contents of a
+///     value that has nested components. The default is `Int.max`.
+///   - maxItems: The maximum number of elements for which to write the full
+///     contents. The default is `Int.max`.
+/// - Returns: The instance passed as `value`.
 @discardableResult
 @_semantics("optimize.sil.specialize.generic.never")
 public func dump<T>(

stdlib/public/core/Integers.swift.gyb

@@ -88,7 +88,7 @@ extension ExpressibleByIntegerLiteral
 }
 
 //===----------------------------------------------------------------------===//
-//===--- Documentation Helpers --------------------------------------------===//
+//===--- Operator Documentation -------------------------------------------===//
 //===----------------------------------------------------------------------===//
 
 %{
@@ -1587,6 +1587,20 @@ extension BinaryInteger {
     return it.next() ?? 0
   }
 
+  /// Returns the quotient and remainder of this value divided by the given
+  /// value.
+  ///
+  /// Use this method to calculate the quotient and remainder of a division at
+  /// the same time.
+  ///
+  ///     let x = 1_000_000
+  ///     let (q, r) = x.quotientAndRemainder(dividingBy: 933)
+  ///     // q == 1071
+  ///     // r == 757
+  ///
+  /// - Parameter rhs: The value to divide this value by.
+  /// - Returns: A tuple containing the quotient and remainder of this value
+  ///   divided by `rhs`.
   public func quotientAndRemainder(dividingBy rhs: Self)
     -> (quotient: Self, remainder: Self) {
     return (self / rhs, self % rhs)
@@ -2007,8 +2021,8 @@ ${overflowOperationComment(x.operator)}
   /// - Parameter other: The value to multiply this value by.
   /// - Returns: A tuple containing the high and low parts of the result of
   ///   multiplying this value and `other`.
-  // FIXME(integers): figure out how to return DoubleWidth<Self>
   func multipliedFullWidth(by other: Self) -> (high: Self, low: Self.Magnitude)
+  // FIXME(integers): figure out how to return DoubleWidth<Self>
 
   /// Returns a tuple containing the quotient and remainder of dividing the
   /// given value by this value.
@@ -2113,6 +2127,11 @@ extension FixedWidthInteger {
   @_inlineable
   public var bitWidth: Int { return Self.bitWidth }
 
+  /// Creates an integer from its little-endian representation, changing the
+  /// byte order if necessary.
+  ///
+  /// - Parameter value: A value to use as the little-endian representation of
+  ///   the new integer.
   public init(littleEndian value: Self) {
 #if _endian(little)
     self = value
@@ -2121,6 +2140,11 @@ extension FixedWidthInteger {
 #endif
   }
 
+  /// Creates an integer from its big-endian representation, changing the byte
+  /// order if necessary.
+  ///
+  /// - Parameter value: A value to use as the big-endian representation of the
+  ///   new integer.
   public init(bigEndian value: Self) {
 #if _endian(big)
     self = value
@@ -2129,6 +2153,11 @@ extension FixedWidthInteger {
 #endif
   }
 
+  /// The little-endian representation of this integer.
+  ///
+  /// If necessary, the byte order of this value is reversed from the typical
+  /// byte order of this integer type. On a little-endian platform, for any
+  /// integer `x`, `x == x.littleEndian`.
   public var littleEndian: Self {
 #if _endian(little)
     return self
@@ -2137,6 +2166,11 @@ extension FixedWidthInteger {
 #endif
   }
 
+  /// The big-endian representation of this integer.
+  ///
+  /// If necessary, the byte order of this value is reversed from the typical
+  /// byte order of this integer type. On a big-endian platform, for any
+  /// integer `x`, `x == x.bigEndian`.
   public var bigEndian: Self {
 #if _endian(big)
     return self
@@ -2552,6 +2586,25 @@ extension UnsignedInteger {
 }
 
 extension UnsignedInteger where Self : FixedWidthInteger {
+  /// Creates a new instance from the given integer.
+  ///
+  /// Use this initializer to convert from another integer type when you know
+  /// the value is within the bounds of this type. Passing a value that can't
+  /// be represented in this type results in a runtime error.
+  ///
+  /// In the following example, the constant `y` is successfully created from
+  /// `x`, an `Int` instance with a value of `100`. Because the `Int8` type
+  /// can represent `127` at maximum, the attempt to create `z` with a value
+  /// of `1000` results in a runtime error.
+  ///
+  ///     let x = 100
+  ///     let y = Int8(x)
+  ///     // y == 100
+  ///     let z = Int8(x * 10)
+  ///     // Error: Not enough bits to represent the given value
+  ///
+  /// - Parameter source: A value to convert to this type of integer. The value
+  ///   passed as `source` must be representable in this type.
   @_semantics("optimize.sil.specialize.generic.partial.never")
   @inline(__always)
   public init<T : BinaryInteger>(_ source: T) {
@@ -2646,6 +2699,25 @@ extension SignedInteger {
 }
 
 extension SignedInteger where Self : FixedWidthInteger {
+  /// Creates a new instance from the given integer.
+  ///
+  /// Use this initializer to convert from another integer type when you know
+  /// the value is within the bounds of this type. Passing a value that can't
+  /// be represented in this type results in a runtime error.
+  ///
+  /// In the following example, the constant `y` is successfully created from
+  /// `x`, an `Int` instance with a value of `100`. Because the `Int8` type
+  /// can represent `127` at maximum, the attempt to create `z` with a value
+  /// of `1000` results in a runtime error.
+  ///
+  ///     let x = 100
+  ///     let y = Int8(x)
+  ///     // y == 100
+  ///     let z = Int8(x * 10)
+  ///     // Error: Not enough bits to represent the given value
+  ///
+  /// - Parameter source: A value to convert to this type of integer. The value
+  ///   passed as `source` must be representable in this type.
   @_semantics("optimize.sil.specialize.generic.partial.never")
   @inline(__always)
   public init<T : BinaryInteger>(_ source: T) {
@@ -3154,9 +3226,9 @@ ${assignmentOperatorComment(x.operator, True)}
   /// - Parameter other: The value to multiply this value by.
   /// - Returns: A tuple containing the high and low parts of the result of
   ///   multiplying this value and `other`.
-  // FIXME(integers): tests
   public func multipliedFullWidth(by other: ${Self})
-  -> (high: ${Self}, low: ${Self}.Magnitude) {
+    -> (high: ${Self}, low: ${Self}.Magnitude) {
+    // FIXME(integers): tests
 %   # 128 bit types are not provided by the 32-bit LLVM
 %   if word_bits == 32 and bits == 64:
     // FIXME(integers): implement
@@ -3186,10 +3258,10 @@ ${assignmentOperatorComment(x.operator, True)}
   ///   sign, if the type is signed.
   /// - Returns: A tuple containing the quotient and remainder of `dividend`
   ///   divided by this value.
-  // FIXME(integers): tests
   public func dividingFullWidth(
     _ dividend: (high: ${Self}, low: ${Self}.Magnitude)
   ) -> (quotient: ${Self}, remainder: ${Self}) {
+    // FIXME(integers): tests
 %   # 128 bit types are not provided by the 32-bit LLVM
 %   #if word_bits == 32 and bits == 64:
 %   if bits == 64:

stdlib/public/core/Optional.swift

@@ -179,7 +179,7 @@ public enum Optional<Wrapped> : ExpressibleByNilLiteral {
   ///     let possibleNumber: Int? = Int("42")
   ///     let nonOverflowingSquare = possibleNumber.flatMap { x -> Int? in
   ///         let (result, overflowed) = x.multipliedReportingOverflow(by: x)
-  ///         return overflowed == .overflow ? nil : result
+  ///         return overflowed ? nil : result
   ///     }
   ///     print(nonOverflowingSquare)
   ///     // Prints "Optional(1764)"

stdlib/public/core/Range.swift.gyb

@@ -10,11 +10,14 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A type which can be used to slice a collection. A `RangeExpression` can
-/// convert itself to a `Range<Bound>` of indices within a given collection;
-/// the collection can then slice itself with that `Range`.
+/// A type that can be used to slice a collection.
+///
+/// A type that conforms to `RangeExpression` can convert itself to a
+/// `Range<Bound>` of indices within a given collection.
 public protocol RangeExpression {
+  /// The type for which the expression describes a range.
   associatedtype Bound: Comparable
+
   /// Returns the range of indices within the given collection described by
   /// this range expression.
   ///
@@ -61,6 +64,12 @@ public protocol RangeExpression {
     to collection: C
   ) -> Range<Bound> where C.Index == Bound
 
+  /// Returns a Boolean value indicating whether the given element is contained
+  /// within the range expression.
+  ///
+  /// - Parameter element: The element to check for containment.
+  /// - Returns: `true` if `element` is contained in the range expression;
+  ///   otherwise, `false`.
   func contains(_ element: Bound) -> Bool
 }
 

stdlib/public/core/StaticString.swift

@@ -219,7 +219,7 @@ public struct StaticString
   }
 
   /// Creates an instance initialized to a single character that is made up of
-  /// one or more Unicode code points.
+  /// one or more Unicode scalar values.
   ///
   /// Do not call this initializer directly. It may be used by the compiler
   /// when you initialize a static string using an extended grapheme cluster.

stdlib/public/core/String.swift

@@ -363,7 +363,7 @@ extension String {
 ///
 ///     let banner = """
 ///               __,
-///              (          o   /) _/_
+///              (           o  /) _/_
 ///               `.  , , , ,  //  /
 ///             (___)(_(_/_(_ //_ (__
 ///                          /)
@@ -393,9 +393,9 @@ extension String {
 ///     print(cafe1 == cafe2)
 ///     // Prints "true"
 ///
-/// The Unicode code point `"\u{301}"` modifies the preceding character to
+/// The Unicode scalar value `"\u{301}"` modifies the preceding character to
 /// include an accent, so `"e\u{301}"` has the same canonical representation
-/// as the single Unicode code point `"é"`.
+/// as the single Unicode scalar value `"é"`.
 ///
 /// Basic string operations are not sensitive to locale settings, ensuring that
 /// string comparisons and other operations always have a single, stable
@@ -407,10 +407,10 @@ extension String {
 ///
 /// A string is a collection of *extended grapheme clusters*, which approximate
 /// human-readable characters. Many individual characters, such as "é", "김",
-/// and "🇮🇳", can be made up of multiple Unicode code points. These code points
-/// are combined by Unicode's boundary algorithms into extended grapheme
-/// clusters, represented by the Swift `Character` type. Each element of a
-/// string is represented by a `Character` instance.
+/// and "🇮🇳", can be made up of multiple Unicode scalar values. These scalar
+/// values are combined by Unicode's boundary algorithms into extended
+/// grapheme clusters, represented by the Swift `Character` type. Each element
+/// of a string is represented by a `Character` instance.
 ///
 /// For example, to retrieve the first word of a longer string, you can search
 /// for a space and then create a substring from a prefix of the string up to
@@ -468,9 +468,9 @@ extension String {
 ///
 /// The `unicodeScalars` view's elements comprise each Unicode scalar value in
 /// the `cafe` string. In particular, because `cafe` was declared using the
-/// decomposed form of the `"é"` character, `unicodeScalars` contains the code
-/// points for both the letter `"e"` (101) and the accent character `"´"`
-/// (769).
+/// decomposed form of the `"é"` character, `unicodeScalars` contains the
+/// scalar values for both the letter `"e"` (101) and the accent character
+/// `"´"` (769).
 ///
 /// UTF-16 View
 /// -----------

stdlib/public/core/StringCharacterView.swift

@@ -29,10 +29,10 @@ extension String {
   ///
   /// In Swift, every string provides a view of its contents as characters. In
   /// this view, many individual characters---for example, "é", "김", and
-  /// "🇮🇳"---can be made up of multiple Unicode code points. These code points
-  /// are combined by Unicode's boundary algorithms into *extended grapheme
-  /// clusters*, represented by the `Character` type. Each element of a
-  /// `CharacterView` collection is a `Character` instance.
+  /// "🇮🇳"---can be made up of multiple Unicode scalar values. These scalar
+  /// values are combined by Unicode's boundary algorithms into *extended
+  /// grapheme clusters*, represented by the `Character` type. Each element of
+  /// a `CharacterView` collection is a `Character` instance.
   ///
   ///     let flowers = "Flowers 💐"
   ///     for c in flowers.characters {