Merge pull request #14777 from cwakamo/introducing-CustomPlaygroundDisplayConvertible-4.1
[4.1] [SE-0198] Introduced CustomPlaygroundDisplayConvertible and deprecated PlaygroundQuickLook/CustomPlaygroundQuickLookable
diff --git a/stdlib/public/core/Arrays.swift.gyb b/stdlib/public/core/Arrays.swift.gyb
index ed9fa54..bc7b604 100644
--- a/stdlib/public/core/Arrays.swift.gyb
+++ b/stdlib/public/core/Arrays.swift.gyb
@@ -491,8 +491,20 @@
}
extension ${Self}: RandomAccessCollection, MutableCollection {
+ /// The index type for arrays, `Int`.
+ %if Self == 'ArraySlice':
+ ///
+ /// `ArraySlice` instances are not always indexed from zero. Use `startIndex`
+ /// and `endIndex` as the bounds for any element access, instead of `0` and
+ /// `count`.
+ %end
public typealias Index = Int
+
+ /// The type that represents the indices that are valid for subscripting an
+ /// array, in ascending order.
public typealias Indices = CountableRange<Int>
+
+ /// The type that allows iteration over an array's elements.
public typealias Iterator = IndexingIterator<${Self}>
%if Self == 'ArraySlice':
@@ -541,6 +553,11 @@
%end
}
+ /// Returns the position immediately after the given index.
+ ///
+ /// - Parameter i: A valid index of the collection. `i` must be less than
+ /// `endIndex`.
+ /// - Returns: The index immediately after `i`.
@_inlineable
public func index(after i: Int) -> Int {
// NOTE: this is a manual specialization of index movement for a Strideable
@@ -551,6 +568,10 @@
return i + 1
}
+ /// Replaces the given index with its successor.
+ ///
+ /// - Parameter i: A valid index of the collection. `i` must be less than
+ /// `endIndex`.
@_inlineable
public func formIndex(after i: inout Int) {
// NOTE: this is a manual specialization of index movement for a Strideable
@@ -561,6 +582,11 @@
i += 1
}
+ /// Returns the position immediately before the given index.
+ ///
+ /// - Parameter i: A valid index of the collection. `i` must be greater than
+ /// `startIndex`.
+ /// - Returns: The index immediately before `i`.
@_inlineable
public func index(before i: Int) -> Int {
// NOTE: this is a manual specialization of index movement for a Strideable
@@ -571,6 +597,10 @@
return i - 1
}
+ /// Replaces the given index with its predecessor.
+ ///
+ /// - Parameter i: A valid index of the collection. `i` must be greater than
+ /// `startIndex`.
@_inlineable
public func formIndex(before i: inout Int) {
// NOTE: this is a manual specialization of index movement for a Strideable
@@ -2184,7 +2214,15 @@
% for (Self, a_Self) in arrayTypes:
extension ${Self} : Equatable where Element : Equatable {
- /// Returns `true` if these arrays contain the same elements.
+ /// Returns a Boolean value indicating whether two arrays contain the same
+ /// elements in the same order.
+ ///
+ /// You can use the equal-to operator (`==`) to compare any two arrays
+ /// that store the same, `Equatable`-conforming element type.
+ ///
+ /// - Parameters:
+ /// - lhs: An array to compare.
+ /// - rhs: Another array to compare.
@_inlineable
public static func ==(lhs: ${Self}<Element>, rhs: ${Self}<Element>) -> Bool {
let lhsCount = lhs.count
@@ -2227,7 +2265,15 @@
return true
}
- /// Returns `true` if the arrays do not contain the same elements.
+ /// Returns a Boolean value indicating whether two arrays are not equal.
+ ///
+ /// Two arrays are equal if they contain the same elements in the same order.
+ /// You can use the not-equal-to operator (`!=`) to compare any two arrays
+ /// that store the same, `Equatable`-conforming element type.
+ ///
+ /// - Parameters:
+ /// - lhs: An array to compare.
+ /// - rhs: Another array to compare.
@_inlineable
public static func !=(lhs: ${Self}<Element>, rhs: ${Self}<Element>) -> Bool {
return !(lhs == rhs)
diff --git a/stdlib/public/core/ClosedRange.swift b/stdlib/public/core/ClosedRange.swift
index b2212d6..da4de91 100644
--- a/stdlib/public/core/ClosedRange.swift
+++ b/stdlib/public/core/ClosedRange.swift
@@ -103,25 +103,28 @@
/// A `CountableClosedRange` instance contains both its lower bound and its
/// upper bound.
///
-/// print(throughFive.contains(3)) // Prints "true"
-/// print(throughFive.contains(10)) // Prints "false"
-/// print(throughFive.contains(5)) // Prints "true"
+/// throughFive.contains(3)
+/// // true
+/// throughFive.contains(10)
+/// // false
+/// throughFive.contains(5)
+/// // true
///
/// Because a closed range includes its upper bound, a closed range whose lower
-/// bound is equal to the upper bound contains one element. Therefore, a
+/// bound is equal to the upper bound contains that value. Therefore, a
/// `CountableClosedRange` instance cannot represent an empty range.
///
/// let zeroInclusive = 0...0
-/// print(zeroInclusive.isEmpty)
-/// // Prints "false"
-/// print(zeroInclusive.count)
-/// // Prints "1"
+/// zeroInclusive.contains(0)
+/// // true
+/// zeroInclusive.isEmpty
+/// // false
///
/// You can use a `for`-`in` loop or any sequence or collection method with a
/// countable range. The elements of the range are the consecutive values from
/// its lower bound up to, and including, its upper bound.
///
-/// for n in throughFive.suffix(3) {
+/// for n in 3...5 {
/// print(n)
/// }
/// // Prints "3"
diff --git a/stdlib/public/core/Collection.swift b/stdlib/public/core/Collection.swift
index e46b498..9cf0177 100644
--- a/stdlib/public/core/Collection.swift
+++ b/stdlib/public/core/Collection.swift
@@ -69,11 +69,11 @@
/// }
/// }
///
-/// The `CollectionOfTwo` type uses the default iterator type,
-/// `IndexingIterator`, because it doesn't define its own `makeIterator()`
-/// method or `Iterator` associated type. This example shows how a
-/// `CollectionOfTwo` instance can be created holding the values of a point,
-/// and then iterated over using a `for`-`in` loop.
+/// Because `CollectionOfTwo` doesn't define its own `makeIterator()`
+/// method or `Iterator` associated type, it uses the default iterator type,
+/// `IndexingIterator`. This example shows how a `CollectionOfTwo` instance
+/// can be created holding the values of a point, and then iterated over
+/// using a `for`-`in` loop.
///
/// let point = CollectionOfTwo(15.0, 20.0)
/// for element in point {
@@ -426,22 +426,35 @@
/// Accesses a contiguous subrange of the collection's elements.
///
- /// The accessed slice uses the same indices for the same elements as the
- /// original collection uses. Always use the slice's `startIndex` property
- /// instead of assuming that its indices start at a particular value.
- ///
- /// This example demonstrates getting a slice of an array of strings, finding
- /// the index of one of the strings in the slice, and then using that index
- /// in the original array.
+ /// For example, using a `PartialRangeFrom` range expression with an array
+ /// accesses the subrange from the start of the range expression until the
+ /// end of the array.
///
/// let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
- /// let streetsSlice = streets[2 ..< streets.endIndex]
+ /// let streetsSlice = streets[2...]
/// print(streetsSlice)
- /// // Prints "["Channing", "Douglas", "Evarts"]"
+ /// // ["Channing", "Douglas", "Evarts"]
///
- /// let index = streetsSlice.index(of: "Evarts") // 4
- /// print(streets[index!])
- /// // Prints "Evarts"
+ /// The accessed slice uses the same indices for the same elements as the
+ /// original collection. This example searches `streetsSlice` for one of the
+ /// strings in the slice, and then uses that index in the original array.
+ ///
+ /// let index = streetsSlice.index(of: "Evarts")! // 4
+ /// print(streets[index])
+ /// // "Evarts"
+ ///
+ /// Always use the slice's `startIndex` property instead of assuming that its
+ /// indices start at a particular value. Attempting to access an element by
+ /// using an index outside the bounds of the slice may result in a runtime
+ /// error, even if that index is valid for the original collection.
+ ///
+ /// print(streetsSlice.startIndex)
+ /// // 2
+ /// print(streetsSlice[2])
+ /// // "Channing"
+ ///
+ /// print(streetsSlice[0])
+ /// // error: Index out of bounds
///
/// - Parameter bounds: A range of the collection's indices. The bounds of
/// the range must be valid indices of the collection.
@@ -1044,7 +1057,7 @@
/// Accesses a contiguous subrange of the collection's elements.
///
/// The accessed slice uses the same indices for the same elements as the
- /// original collection uses. Always use the slice's `startIndex` property
+ /// original collection. Always use the slice's `startIndex` property
/// instead of assuming that its indices start at a particular value.
///
/// This example demonstrates getting a slice of an array of strings, finding
diff --git a/stdlib/public/core/Integers.swift.gyb b/stdlib/public/core/Integers.swift.gyb
index 018bb36..813fff6 100644
--- a/stdlib/public/core/Integers.swift.gyb
+++ b/stdlib/public/core/Integers.swift.gyb
@@ -809,8 +809,8 @@
def overflowOperationComment(operator):
comments = {
'+': """\
- /// Returns the sum of this value and the given value along with a flag
- /// indicating whether overflow occurred in the operation.
+ /// Returns the sum of this value and the given value, along with a Boolean
+ /// value indicating whether overflow occurred in the operation.
///
/// - Parameter rhs: The value to add to this value.
/// - Returns: A tuple containing the result of the addition along with a
@@ -821,32 +821,34 @@
/// and `rhs`.
""",
'-': """\
- /// Returns the difference of this value and the given value along with a
- /// flag indicating whether overflow occurred in the operation.
+ /// Returns the difference obtained by subtracting the given value from this
+ /// value, along with a Boolean value indicating whether overflow occurred in
+ /// the operation.
///
/// - Parameter rhs: The value to subtract from this value.
/// - Returns: A tuple containing the result of the subtraction along with a
- /// flag indicating whether overflow occurred. If the `overflow` component
- /// is `false`, the `partialValue` component contains the entire
- /// difference. If the `overflow` component is `true`, an overflow
- /// occurred and the `partialValue` component contains the truncated
- /// result of `rhs` subtracted from this value.
+ /// Boolean value indicating whether overflow occurred. If the `overflow`
+ /// component is `false`, the `partialValue` component contains the entire
+ /// difference. If the `overflow` component is `true`, an overflow occurred
+ /// and the `partialValue` component contains the truncated result of `rhs`
+ /// subtracted from this value.
""",
'*': """\
- /// Returns the product of this value and the given value along with a flag
- /// indicating whether overflow occurred in the operation.
+ /// Returns the product of this value and the given value, along with a
+ /// Boolean value indicating whether overflow occurred in the operation.
///
/// - Parameter rhs: The value to multiply by this value.
/// - Returns: A tuple containing the result of the multiplication along with
/// a Boolean value indicating whether overflow occurred. If the `overflow`
/// component is `false`, the `partialValue` component contains the entire
- /// product. If the `overflow` component is `true`, an overflow
- /// occurred and the `partialValue` component contains the truncated
- /// product of this value and `rhs`.
+ /// product. If the `overflow` component is `true`, an overflow occurred and
+ /// the `partialValue` component contains the truncated product of this
+ /// value and `rhs`.
""",
'/': """\
- /// Returns the quotient of dividing this value by the given value along with
- /// a flag indicating whether overflow occurred in the operation.
+ /// Returns the quotient obtained by dividing this value by the given value,
+ /// along with a Boolean value indicating whether overflow occurred in the
+ /// operation.
///
/// Dividing by zero is not an error when using this method. For a value `x`,
/// the result of `x.dividedReportingOverflow(by: 0)` is `(x, true)`.
@@ -856,22 +858,24 @@
/// Boolean value indicating whether overflow occurred. If the `overflow`
/// component is `false`, the `partialValue` component contains the entire
/// quotient. If the `overflow` component is `true`, an overflow occurred
- /// and the `partialValue` component contains the truncated quotient.
+ /// and the `partialValue` component contains either the truncated quotient
+ /// or, if the quotient is undefined, the dividend.
""",
'%': """\
- // FIXME(integers): the comment is for division instead of remainder
- /// Returns the remainder of dividing this value by the given value along
- /// with a flag indicating whether overflow occurred in the operation.
+ /// Returns the remainder after dividing this value by the given value, along
+ /// with a Boolean value indicating whether overflow occurred during division.
///
/// Dividing by zero is not an error when using this method. For a value `x`,
- /// the result of `x.dividedReportingOverflow(by: 0)` is `(x, true)`.
+ /// the result of `x.remainderReportingOverflow(dividingBy: 0)` is
+ /// `(x, true)`.
///
/// - Parameter rhs: The value to divide this value by.
- /// - Returns: A tuple containing the result of the division along with a
+ /// - Returns: A tuple containing the result of the operation along with a
/// Boolean value indicating whether overflow occurred. If the `overflow`
/// component is `false`, the `partialValue` component contains the entire
- /// quotient. If the `overflow` component is `true`, an overflow occurred
- /// and the `partialValue` component contains the truncated quotient.
+ /// remainder. If the `overflow` component is `true`, an overflow occurred
+ /// during division and the `partialValue` component contains either the
+ /// entire remainder or, if the remainder is undefined, the dividend.
""",
}
return comments[operator]
@@ -896,15 +900,15 @@
/// - Returns: The sum of this value and `rhs`.
""",
'-': """\
- /// Returns the difference of this value and the given value without checking
- /// for arithmetic overflow.
+ /// Returns the difference obtained by subtracting the given value from this
+ /// value without checking for arithmetic overflow.
///
/// If an arithmetic overflow occurs, the behavior is undefined. Use this
/// function only to avoid the cost of overflow checking when you are sure
/// that the operation won't overflow.
///
/// - Parameter rhs: The value to subtract from this value.
- /// - Returns: The difference of this value and `rhs`.
+ /// - Returns: The result of subtracting `rhs` from this value.
""",
'*': """\
/// Returns the product of this value and the given value without checking
@@ -915,18 +919,18 @@
/// that the operation won't overflow.
///
/// - Parameter rhs: The value to multiply by this value.
- /// - Returns: The difference of this value and `rhs`.
+ /// - Returns: The product of this value and `rhs`.
""",
'/': """\
- /// Returns the quotient of dividing this value by the given value without
- /// checking for arithmetic overflow.
+ /// Returns the quotient obtained by dividing this value by the given value
+ /// without checking for arithmetic overflow.
///
/// If an arithmetic overflow occurs, the behavior is undefined. Use this
/// function only to avoid the cost of overflow checking when you are sure
/// that the operation won't overflow.
///
/// - Parameter rhs: The value to divide this value by.
- /// - Returns: The quotient of dividing this value by `rhs`.
+ /// - Returns: The result of dividing this value by `rhs`.
""",
}
return comments[operator]
@@ -1576,12 +1580,18 @@
}
extension BinaryInteger {
+ /// Creates a new value equal to zero.
@_inlineable // FIXME(sil-serialize-all)
@_transparent
public init() {
self = 0
}
+ /// Returns `-1` if this value is negative and `1` if it's positive;
+ /// otherwise, `0`.
+ ///
+ /// - Returns: The sign of this number, expressed as an integer of the same
+ /// type.
@_inlineable // FIXME(sil-serialize-all)
@_transparent
public func signum() -> Self {
@@ -1729,6 +1739,7 @@
return other - self
}
+ // FIXME(ABI): using Int as the parameter type is wrong.
/// Returns a value that is offset the specified distance from this value.
///
/// Use the `advanced(by:)` method in generic code to offset a value by a
@@ -1740,7 +1751,6 @@
///
/// - Parameter n: The distance to advance this value.
/// - Returns: A value that is offset from this value by `n`.
- // FIXME(ABI): using Int as the parameter type is wrong.
@_inlineable // FIXME(sil-serialize-all)
@_transparent
public func advanced(by n: Int) -> Int {
@@ -2055,7 +2065,7 @@
/// `-(2 ** (bitWidth - 1))` through `(2 ** (bitWidth - 1)) - 1`. For example,
/// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
/// the range `-128...127`.
- static var bitWidth : Int { get }
+ static var bitWidth: Int { get }
/// The maximum representable integer in this type.
///
@@ -2083,10 +2093,10 @@
///
/// Use this method to calculate the full result of a product that would
/// otherwise overflow. Unlike traditional truncating multiplication, the
- /// `multipliedFullWidth(by:)` method returns a tuple
- /// containing both the `high` and `low` parts of the product of this value and
- /// `other`. The following example uses this method to multiply two `UInt8`
- /// values that normally overflow when multiplied:
+ /// `multipliedFullWidth(by:)` method returns a tuple containing both the
+ /// `high` and `low` parts of the product of this value and `other`. The
+ /// following example uses this method to multiply two `UInt8` values that
+ /// normally overflow when multiplied:
///
/// let x: UInt8 = 100
/// let y: UInt8 = 20
@@ -2107,20 +2117,18 @@
/// - Returns: A tuple containing the high and low parts of the result of
/// multiplying this value and `other`.
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.
+ /// Returns a tuple containing the quotient and remainder obtained by dividing
+ /// the given value by this value.
///
/// The resulting quotient must be representable within the bounds of the
- /// type. If the quotient of dividing `dividend` by this value is too large
- /// to represent in the type, a runtime error may occur.
+ /// type. If the quotient is too large to represent in the type, a runtime
+ /// error may occur.
///
/// - Parameter dividend: A tuple containing the high and low parts of a
- /// double-width integer. The `high` component of the value carries the
- /// sign, if the type is signed.
- /// - Returns: A tuple containing the quotient and remainder of `dividend`
- /// divided by this value.
+ /// double-width integer.
+ /// - Returns: A tuple containing the quotient and remainder obtained by
+ /// dividing `dividend` by this value.
func dividingFullWidth(_ dividend: (high: Self, low: Self.Magnitude))
-> (quotient: Self, remainder: Self)
@@ -2521,11 +2529,8 @@
% for x in binaryArithmetic['Numeric'] + binaryArithmetic["BinaryInteger"][:1]:
% callLabel = x.firstArg + ': ' if not x.firstArg == '_' else ''
-// FIXME(integers): pending optimizer work on handling the case where the
-// boolean value is wrapped into a two-case enum and then immediately
-// unwrapped. <rdar://problem/29004429>
-// Uncomment this block and remove the corresponding one from the concrete
-// types once the optimizer is ready.
+// FIXME(integers): uncomment this block and remove the corresponding one from
+// the concrete types
#if false
${assignmentOperatorComment(x.operator, True)}
@_transparent
@@ -2936,6 +2941,7 @@
: FixedWidthInteger, ${Unsigned}Integer,
_ExpressibleByBuiltinIntegerLiteral {
+ /// A type that represents an integer literal.
public typealias IntegerLiteralType = ${Self}
@@ -3051,9 +3057,6 @@
return Bool(Builtin.cmp_${u}lt_Int${bits}(lhs._value, rhs._value))
}
-// FIXME(integers): pending optimizer work on handling the case where the
-// boolean value is wrapped into a two-case enum and then immediately
-// unwrapped. <rdar://problem/29004429>
// See corresponding definitions in the FixedWidthInteger extension.
% for x in binaryArithmetic['Numeric'] + binaryArithmetic["BinaryInteger"][:1]:
${assignmentOperatorComment(x.operator, True)}
@@ -3085,7 +3088,6 @@
lhs = ${Self}(result)
}
% end
-// end of FIXME(integers)
% for x in chain(*binaryArithmetic.values()):
diff --git a/stdlib/public/core/Range.swift.gyb b/stdlib/public/core/Range.swift.gyb
index dc8cefb..5b79e5f 100644
--- a/stdlib/public/core/Range.swift.gyb
+++ b/stdlib/public/core/Range.swift.gyb
@@ -777,7 +777,7 @@
}
}
-/// A partial half-open interval up to, and including, an upper bound.
+/// A partial interval up to, and including, an upper bound.
///
/// You create `PartialRangeThrough` instances by using the prefix closed range
/// operator (prefix `...`).
@@ -875,9 +875,12 @@
/// You can use a countable partial range to quickly check if a value is
/// contained in a particular range of values. For example:
///
-/// atLeastFive.contains(4) // false
-/// atLeastFive.contains(5) // true
-/// atLeastFive.contains(6) // true
+/// atLeastFive.contains(4)
+/// // false
+/// atLeastFive.contains(5)
+/// // true
+/// atLeastFive.contains(6)
+/// // true
///
/// You can use a countable partial range of a collection's indices to
/// represent the range from the partial range's lower bound up to the end of
@@ -893,7 +896,7 @@
/// a countable range.
///
/// Using a Partial Range as a Sequence
-/// ===================================
+/// -----------------------------------
///
/// You can iterate over a countable partial range using a `for`-`in` loop, or
/// call any sequence method that doesn't require that the sequence is finite.
@@ -990,8 +993,8 @@
/// Returns a half-open range that contains its lower bound but not its upper
/// bound.
///
- /// Use the half-open range operator (`..<`) to create a range of any type that
- /// conforms to the `Comparable` protocol. This example creates a
+ /// Use the half-open range operator (`..<`) to create a range of any type
+ /// that conforms to the `Comparable` protocol. This example creates a
/// `Range<Double>` from zero up to, but not including, 5.0.
///
/// let lessThanFive = 0.0..<5.0
@@ -1207,17 +1210,94 @@
}
}
-// FIXME: replace this with a computed var named `...` when the language makes
-// that possible.
+/// A range expression that represents the entire range of a collection.
+///
+/// You can use the unbounded range operator (`...`) to create a slice of a
+/// collection that contains all of the collection's elements. Slicing with an
+/// unbounded range is essentially a conversion of a collection instance into
+/// its slice type.
+///
+/// For example, the following code declares `levenshteinDistance(_:_:)`, a
+/// function that calculates the number of changes required to convert one
+/// string into another. `levenshteinDistance(_:_:)` uses `Substring`, a
+/// string's slice type, for its parameters.
+///
+/// func levenshteinDistance(_ s1: Substring, _ s2: Substring) -> Int {
+/// if s1.isEmpty { return s2.count }
+/// if s2.isEmpty { return s1.count }
+///
+/// let cost = s1.first == s2.first ? 0 : 1
+///
+/// return min(
+/// levenshteinDistance(s1.dropFirst(), s2) + 1,
+/// levenshteinDistance(s1, s2.dropFirst()) + 1,
+/// levenshteinDistance(s1.dropFirst(), s2.dropFirst()) + cost)
+/// }
+///
+/// To call `levenshteinDistance(_:_:)` with two strings, use an unbounded
+/// range in each string's subscript to convert it to a `Substring`.
+///
+/// let word1 = "grizzly"
+/// let word2 = "grisly"
+/// let distance = levenshteinDistance(word1[...], word2[...])
+/// // distance == 2
public enum UnboundedRange_ {
+ // FIXME: replace this with a computed var named `...` when the language makes
+ // that possible.
+
+ /// Creates an unbounded range expression.
+ ///
+ /// The unbounded range operator (`...`) is valid only within a collection's
+ /// subscript.
@_inlineable // FIXME(sil-serialize-all)
public static postfix func ... (_: UnboundedRange_) -> () {
fatalError("uncallable")
}
}
+
+/// The type of an unbounded range operator.
public typealias UnboundedRange = (UnboundedRange_)->()
extension Collection {
+ /// Accesses the contiguous subrange of the collection's elements specified
+ /// by a range expression.
+ ///
+ /// The range expression is converted to a concrete subrange relative to this
+ /// collection. For example, using a `PartialRangeFrom` range expression
+ /// with an array accesses the subrange from the start of the range
+ /// expression until the end of the array.
+ ///
+ /// let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
+ /// let streetsSlice = streets[2...]
+ /// print(streetsSlice)
+ /// // ["Channing", "Douglas", "Evarts"]
+ ///
+ /// The accessed slice uses the same indices for the same elements as the
+ /// original collection uses. This example searches `streetsSlice` for one
+ /// of the strings in the slice, and then uses that index in the original
+ /// array.
+ ///
+ /// let index = streetsSlice.index(of: "Evarts") // 4
+ /// print(streets[index!])
+ /// // "Evarts"
+ ///
+ /// Always use the slice's `startIndex` property instead of assuming that its
+ /// indices start at a particular value. Attempting to access an element by
+ /// using an index outside the bounds of the slice's indices may result in a
+ /// runtime error, even if that index is valid for the original collection.
+ ///
+ /// print(streetsSlice.startIndex)
+ /// // 2
+ /// print(streetsSlice[2])
+ /// // "Channing"
+ ///
+ /// print(streetsSlice[0])
+ /// // error: Index out of bounds
+ ///
+ /// - Parameter bounds: A range of the collection's indices. The bounds of
+ /// the range must be valid indices of the collection.
+ ///
+ /// - Complexity: O(1)
@_inlineable
public subscript<R: RangeExpression>(r: R)
-> SubSequence where R.Bound == Index {
diff --git a/stdlib/public/core/SequenceAlgorithms.swift.gyb b/stdlib/public/core/SequenceAlgorithms.swift.gyb
index 5add15f..fb2a7fd 100644
--- a/stdlib/public/core/SequenceAlgorithms.swift.gyb
+++ b/stdlib/public/core/SequenceAlgorithms.swift.gyb
@@ -741,7 +741,7 @@
/// let mapped: [Int?] = possibleNumbers.map { str in Int(str) }
/// // [1, 2, nil, nil, 5]
///
- /// let flatMapped: [Int] = possibleNumbers.compactMap { str in Int(str) }
+ /// let compactMapped: [Int] = possibleNumbers.compactMap { str in Int(str) }
/// // [1, 2, 5]
///
/// - Parameter transform: A closure that accepts an element of this
diff --git a/stdlib/public/core/String.swift b/stdlib/public/core/String.swift
index 84c015b..a1fe657 100644
--- a/stdlib/public/core/String.swift
+++ b/stdlib/public/core/String.swift
@@ -1240,6 +1240,10 @@
}
extension String : CustomStringConvertible {
+ /// The value of this string.
+ ///
+ /// Using this property directly is discouraged. Instead, use simple
+ /// assignment to create a new constant or variable equal to this string.
@_inlineable // FIXME(sil-serialize-all)
public var description: String {
return self
diff --git a/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb b/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
index 47b11eb..887271c 100644
--- a/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
+++ b/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
@@ -441,6 +441,34 @@
}
extension Collection {
+ /// Returns an array containing the non-`nil` strings resulting from the given
+ /// transformation on each element of this sequence.
+ ///
+ /// Use this method to receive an array of non-optional strings when your
+ /// transformation produces a `String?`.
+ ///
+ /// In this example, note the difference in the result of using `map` and
+ /// `compactMap` with a transformation that returns a `String?` value.
+ ///
+ /// let errorLookup = [400: "Bad request",
+ /// 403: "Forbidden",
+ /// 404: "Not found"]
+ ///
+ /// let errorCodes = [400, 407, 404]
+ ///
+ /// let mapped: [String?] = errorCodes.map { code in errorLookup[code] }
+ /// // ["Bad request", nil, "Not found"]
+ ///
+ /// let compactMapped: [String] = errorCodes.compactMap { code in errorLookup[code] }
+ /// // ["Bad request", "Not found"]
+ ///
+ /// - Parameter transform: A closure that accepts an element of this
+ /// sequence as its argument and returns a `String?`.
+ /// - Returns: An array of the non-`nil` results of calling `transform`
+ /// with each element of the sequence.
+ ///
+ /// - Complexity: O(*m* + *n*), where *m* is the length of this sequence
+ /// and *n* is the length of the result.
@_inlineable // FIXME(sil-serialize-all)
public func compactMap(
_ transform: (Element) throws -> String?
