Merge pull request #4078 from rudkx/fix-27639935
Add a fixit for attempting member lookup on Any.
diff --git a/docs/SIL.rst b/docs/SIL.rst
index 6d227d2..02b5426 100644
--- a/docs/SIL.rst
+++ b/docs/SIL.rst
@@ -1538,15 +1538,16 @@
Class instances and other *heap object references* are pointers at the
implementation level, but unlike SIL addresses, they are first class values and
-can be ``capture``-d and alias. Swift, however, is memory-safe and statically
+can be ``capture``-d and aliased. Swift, however, is memory-safe and statically
typed, so aliasing of classes is constrained by the type system as follows:
* A ``Builtin.NativeObject`` may alias any native Swift heap object,
including a Swift class instance, a box allocated by ``alloc_box``,
or a thick function's closure context.
It may not alias natively Objective-C class instances.
-* A ``Builtin.UnknownObject`` may alias any class instance, whether Swift or
- Objective-C, but may not alias non-class-instance heap objects.
+* A ``Builtin.UnknownObject`` or ``Builtin.BridgeObject`` may alias
+ any class instance, whether Swift or Objective-C, but may not alias
+ non-class-instance heap objects.
* Two values of the same class type ``$C`` may alias. Two values of related
class type ``$B`` and ``$D``, where there is a subclass relationship between
``$B`` and ``$D``, may alias. Two values of unrelated class types may not
@@ -1560,6 +1561,15 @@
potentially alias concrete instances of the generic type, such as
``$C<Int>``, because ``Int`` is a potential substitution for ``T``.
+A violation of the above aliasing rules only results in undefined
+behavior if the aliasing references are dereferenced within Swift code.
+For example,
+``_SwiftNativeNS[Array|Dictionary|String]`` classes alias with
+``NS[Array|Dictionary|String]`` classes even though they are not
+statically related. Since Swift never directly accesses stored
+properties on the Foundation classes, this aliasing does not pose a
+danger.
+
Typed Access TBAA
~~~~~~~~~~~~~~~~~
@@ -1571,15 +1581,86 @@
typed projection operation (e.x. ``ref_element_addr``,
``tuple_element_addr``).
-It is undefined behavior to perform a typed access to an address or reference if
-the stored object or referent is not an allocated object of the relevant type.
+With limited exceptions, it is undefined behavior to perform a typed access to
+an address or reference addressed memory is not bound to the relevant type.
-This allows the optimizer to assume that two addresses cannot alias if there
-does not exist a substitution of archetypes that could cause one of the types to
-be the type of a subobject of the other. Additionally, this applies to the types
-of the values from which the addresses were derived, ignoring "blessed"
-alias-introducing operations such as ``pointer_to_address``, the ``bitcast``
-intrinsic, and the ``inttoptr`` intrinsic.
+This allows the optimizer to assume that two addresses cannot alias if
+there does not exist a substitution of archetypes that could cause one
+of the types to be the type of a subobject of the other. Additionally,
+this applies to the types of the values from which the addresses were
+derived via a typed projection.
+
+Consider the following SIL::
+
+ struct Element {
+ var i: Int
+ }
+ struct S1 {
+ var elt: Element
+ }
+ struct S2 {
+ var elt: Element
+ }
+ %adr1 = struct_element_addr %ptr1 : $*S1, #S.elt
+ %adr2 = struct_element_addr %ptr2 : $*S2, #S.elt
+
+The optimizer may assume that ``%adr1`` does not alias with ``%adr2``
+because the values that the addresses are derived from (``%ptr1`` and
+``%ptr2``) have unrelated types. However, in the following example,
+the optimizer cannot assume that ``%adr1`` does not alias with
+``%adr2`` because ``%adr2`` is derived from a cast, and any subsequent
+typed operations on the address will refer to the common ``Element`` type::
+
+ %adr1 = struct_element_addr %ptr1 : $*S1, #S.elt
+ %adr2 = pointer_to_address %ptr2 : $Builtin.RawPointer to $*Element
+
+Exceptions to typed access TBAA rules are only allowed for blessed
+alias-introducing operations. This permits limited type-punning. The only
+current exception is the non-struct ``pointer_to_address`` variant. The
+optimizer must be able to defensively determine that none of the *roots* of an
+address are alias-introducing operations. An address root is the operation that
+produces the address prior to applying any typed projections, indexing, or
+casts. The following are valid address roots:
+
+* Object allocation that generates an address, such as ``alloc_stack``
+ and ``alloc_box``.
+
+* Address-type function arguments. These are crucially *not* considered
+ alias-introducing operations. It is illegal for the SIL optimizer to
+ form a new function argument from an arbitrary address-type
+ value. Doing so would require the optimizer to guarantee that the
+ new argument is both has a non-alias-introducing address root and
+ can be properly represented by the calling convention (address types
+ do not have a fixed representation).
+
+* A strict cast from an untyped pointer, ``pointer_to_address [strict]``. It is
+ illegal for ``pointer_to_address [strict]`` to derive its address from an
+ alias-introducing operation's value. A type punned address may only be
+ produced from an opaque pointer via a non-strict ``pointer_to_address`` at the
+ point of conversion.
+
+Address-to-address casts, via ``unchecked_addr_cast``, transparently
+forward their source's address root, just like typed projections.
+
+Address-type basic block arguments can be conservatively considered
+aliasing-introducing operations; they are uncommon enough not to
+matter and may eventually be prohibited altogether.
+
+Although some pointer producing intrinsics exist, they do not need to be
+considered alias-introducing exceptions to TBAA rules. ``Builtin.inttoptr``
+produces a ``Builtin.RawPointer`` which is not interesting because by definition
+it may alias with everything. Similarly, the LLVM builtins ``Builtin.bitcast``
+and ``Builtin.trunc|sext|zextBitCast`` cannot produce typed pointers. These
+pointer values must be converted to an address via ``pointer_to_address`` before
+typed access can occur. Whether the ``pointer_to_address`` is strict determines
+whether aliasing may occur.
+
+Memory may be rebound to an unrelated type. Addresses to unrelated types may
+alias as long as typed access only occurs while memory is bound to the relevant
+type. Consequently, the optimizer cannot outright assume that addresses accessed
+as unrelated types are nonaliasing. For example, pointer comparison cannot be
+eliminated simply because the two addresses derived from those pointers are
+accessed as unrelated types at different program points.
Value Dependence
----------------
diff --git a/docs/Testing.rst b/docs/Testing.rst
index aadea8e..75f3474 100644
--- a/docs/Testing.rst
+++ b/docs/Testing.rst
@@ -273,7 +273,7 @@
``armv7``, ``armv7k``, ``arm64``).
* ``%target-os``: the target operating system (``macosx``, ``darwin``,
- ``linux``, ``freebsd``).
+ ``linux``, ``freebsd``, ``windows-cygnus``, ``windows-gnu``).
* ``%target-object-format``: the platform's object format (``elf``, ``macho``,
``coff``).
diff --git a/include/swift/AST/DiagnosticsParse.def b/include/swift/AST/DiagnosticsParse.def
index eaea22d..405f42e 100644
--- a/include/swift/AST/DiagnosticsParse.def
+++ b/include/swift/AST/DiagnosticsParse.def
@@ -1106,8 +1106,6 @@
"expected ')' to complete '#selector' expression", ())
// Type-of expressions.
-ERROR(expr_typeof_expected_lparen,PointsToFirstBadToken,
- "expected '(' following 'type'", ())
ERROR(expr_typeof_expected_label_of,PointsToFirstBadToken,
"expected argument label 'of:' within 'type(...)'", ())
ERROR(expr_typeof_expected_expr,PointsToFirstBadToken,
diff --git a/include/swift/AST/DiagnosticsSema.def b/include/swift/AST/DiagnosticsSema.def
index 1ded128..ae0d379 100644
--- a/include/swift/AST/DiagnosticsSema.def
+++ b/include/swift/AST/DiagnosticsSema.def
@@ -72,6 +72,9 @@
ERROR(could_not_find_type_member,none,
"type %0 has no member %1", (Type, DeclName))
+ERROR(could_not_find_enum_case,none,
+ "enum type %0 has no case %1; did you mean %2", (Type, DeclName, DeclName))
+
NOTE(did_you_mean_raw_type,none,
"did you mean to specify a raw type on the enum declaration?", ())
@@ -595,8 +598,10 @@
"protocol %0 can only be used as a generic constraint because it has "
"Self or associated type requirements", (Identifier))
-ERROR(no_decl_in_module,none,
- "no such decl in module", ())
+ERROR(decl_does_not_exist_in_module,none,
+ "%select{**MODULE**|type|struct|class|enum|protocol|variable|function}0 "
+ "%1 does not exist in module %2",
+ (/*ImportKind*/ unsigned, Identifier, Identifier))
ERROR(imported_decl_is_wrong_kind,none,
"%0 was imported as '%1', but is a "
"%select{**MODULE**|type|struct|class|enum|protocol|variable|function}2",
@@ -2458,8 +2463,6 @@
"type annotation missing in pattern", ())
ERROR(refutable_pattern_requires_initializer,none,
"pattern matching requires an initializer value to match against", ())
-ERROR(invalid_pattern,none,
- "invalid pattern", ())
WARNING(var_pattern_didnt_bind_variables,none,
"'%0' pattern has no effect; sub-pattern didn't bind any variables",
(StringRef))
diff --git a/lib/ClangImporter/ImportDecl.cpp b/lib/ClangImporter/ImportDecl.cpp
index de55096..bddfaa7 100644
--- a/lib/ClangImporter/ImportDecl.cpp
+++ b/lib/ClangImporter/ImportDecl.cpp
@@ -6087,7 +6087,7 @@
Decl *
VisitObjCCompatibleAliasDecl(const clang::ObjCCompatibleAliasDecl *decl) {
- // Import Objective-C’s @compatibility_alias as typealias.
+ // Import Objective-C's @compatibility_alias as typealias.
EffectiveClangContext effectiveContext(decl->getDeclContext()->getRedeclContext());
auto dc = Impl.importDeclContextOf(decl, effectiveContext);
if (!dc) return nullptr;
diff --git a/lib/Driver/Driver.cpp b/lib/Driver/Driver.cpp
index 294b0b1..14a443a 100644
--- a/lib/Driver/Driver.cpp
+++ b/lib/Driver/Driver.cpp
@@ -1316,7 +1316,8 @@
if (OI.shouldLink() && !AllLinkerInputs.empty()) {
auto *LinkAction = new LinkJobAction(AllLinkerInputs, OI.LinkAction);
- if (TC.getTriple().getObjectFormat() == llvm::Triple::ELF) {
+ if (TC.getTriple().getObjectFormat() == llvm::Triple::ELF ||
+ TC.getTriple().isOSCygMing()) {
// On ELF platforms there's no built in autolinking mechanism, so we
// pull the info we need from the .o files directly and pass them as an
// argument input file to the linker.
diff --git a/lib/IDE/CodeCompletion.cpp b/lib/IDE/CodeCompletion.cpp
index f91d4f6..18a2dc4 100644
--- a/lib/IDE/CodeCompletion.cpp
+++ b/lib/IDE/CodeCompletion.cpp
@@ -3019,12 +3019,6 @@
optionSetType, conformances);
}
- bool isOptionSet(Type Ty) {
- return Ty &&
- Ty->getNominalOrBoundGenericNominal() &&
- isOptionSetDecl(Ty->getNominalOrBoundGenericNominal());
- }
-
void getTupleExprCompletions(TupleType *ExprType) {
unsigned Index = 0;
for (auto TupleElt : ExprType->getElements()) {
diff --git a/lib/Sema/CSDiag.cpp b/lib/Sema/CSDiag.cpp
index 4b95ca6b..ea63bec 100644
--- a/lib/Sema/CSDiag.cpp
+++ b/lib/Sema/CSDiag.cpp
@@ -1948,7 +1948,7 @@
/// the exact expression kind).
bool diagnoseGeneralMemberFailure(Constraint *constraint);
- /// Diagnose the lookup of an static member or enum element as instance member.
+ /// Diagnose the lookup of a static member or enum element as instance member.
void diagnoseTypeMemberOnInstanceLookup(Type baseObjTy,
Expr *baseExpr,
DeclName memberName,
@@ -2448,6 +2448,32 @@
return;
}
+/// When a user refers a enum case with a wrong member name, we try to find a enum
+/// element whose name differs from the wrong name only in convention; meaning their
+/// lower case counterparts are identical.
+/// - DeclName is valid when such a correct case is found; invalid otherwise.
+static DeclName
+findCorrectEnumCaseName(MetatypeType *MetaTy, LookupResult &Result,
+ DeclName memberName) {
+ if (!memberName.isSimpleName())
+ return DeclName();
+ if (!MetaTy->getInstanceType()->is<EnumType>())
+ return DeclName();
+ std::vector<DeclName> candidates;
+ for (auto &correction : Result) {
+ DeclName correctName = correction.Decl->getFullName();
+ if (!correctName.isSimpleName())
+ continue;
+ if (!isa<EnumElementDecl>(correction.Decl))
+ continue;
+ if (correctName.getBaseName().str().
+ compare_lower(memberName.getBaseName().str()) == 0)
+ candidates.push_back(correctName);
+ }
+ if (candidates.size() == 1)
+ return candidates.front();
+ return DeclName();
+}
/// Given a result of name lookup that had no viable results, diagnose the
/// unviable ones.
@@ -2473,10 +2499,17 @@
diagnose(loc, diag::type_not_subscriptable, baseObjTy)
.highlight(baseRange);
} else if (auto MTT = baseObjTy->getAs<MetatypeType>()) {
+ tryTypoCorrection();
+ if (DeclName rightName = findCorrectEnumCaseName(MTT, correctionResults,
+ memberName)) {
+ diagnose(loc, diag::could_not_find_enum_case, MTT->getInstanceType(),
+ memberName, rightName).fixItReplace(nameLoc.getBaseNameLoc(),
+ rightName.getBaseName().str());
+ return;
+ }
diagnose(loc, diag::could_not_find_type_member,
MTT->getInstanceType(), memberName)
.highlight(baseRange).highlight(nameLoc.getSourceRange());
- tryTypoCorrection();
} else {
diagnose(loc, diag::could_not_find_value_member,
baseObjTy, memberName)
diff --git a/lib/Sema/NameBinding.cpp b/lib/Sema/NameBinding.cpp
index 3866786..a69ce26 100644
--- a/lib/Sema/NameBinding.cpp
+++ b/lib/Sema/NameBinding.cpp
@@ -227,7 +227,10 @@
/*resolver*/nullptr, &SF);
if (decls.empty()) {
- diagnose(ID, diag::no_decl_in_module)
+ diagnose(ID, diag::decl_does_not_exist_in_module,
+ static_cast<unsigned>(ID->getImportKind()),
+ declPath.front().first,
+ ID->getModulePath().front().first)
.highlight(SourceRange(declPath.front().second,
declPath.back().second));
return;
diff --git a/stdlib/private/StdlibUnittest/CMakeLists.txt b/stdlib/private/StdlibUnittest/CMakeLists.txt
index 2eb32e9..e18d39f 100644
--- a/stdlib/private/StdlibUnittest/CMakeLists.txt
+++ b/stdlib/private/StdlibUnittest/CMakeLists.txt
@@ -15,6 +15,7 @@
# filename.
StdlibUnittest.swift.gyb
+ CheckStrideable.swift.gyb
InspectValue.cpp
InspectValue.swift
InterceptTraps.cpp
diff --git a/stdlib/private/StdlibUnittest/CheckStrideable.swift.gyb b/stdlib/private/StdlibUnittest/CheckStrideable.swift.gyb
new file mode 100644
index 0000000..fbbe590
--- /dev/null
+++ b/stdlib/private/StdlibUnittest/CheckStrideable.swift.gyb
@@ -0,0 +1,32 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+%{
+from gyb_stdlib_unittest_support import TRACE, stackTrace, trace
+}%
+
+public func checkStrideable<S : Strideable>(
+ instances: [S],
+ distances: [S.Stride],
+ distanceOracle: (Int, Int) -> S.Stride,
+ ${TRACE}
+) {
+ for i in instances.indices {
+ let first = instances[i]
+ for j in instances.indices {
+ let second = instances[j]
+ expectEqual(distanceOracle(i, j), first.distance(to: second))
+ expectEqual(second, first.advanced(by: distanceOracle(i, j)))
+ }
+ }
+}
+
diff --git a/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb b/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb
index ba3731d..05d87c1 100644
--- a/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb
+++ b/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb
@@ -150,6 +150,14 @@
expectEqualTest(expected.2, actual.2, ${trace}, showFrame: false) {$0 == $1}
}
+public func expectEqual<T : Equatable, U : Equatable, V : Equatable, W : Equatable>(
+ _ expected: (T, U, V, W), _ actual: (T, U, V, W), ${TRACE}) {
+ expectEqualTest(expected.0, actual.0, ${trace}, showFrame: false) {$0 == $1}
+ expectEqualTest(expected.1, actual.1, ${trace}, showFrame: false) {$0 == $1}
+ expectEqualTest(expected.2, actual.2, ${trace}, showFrame: false) {$0 == $1}
+ expectEqualTest(expected.3, actual.3, ${trace}, showFrame: false) {$0 == $1}
+}
+
public func expectationFailure(
_ reason: String,
trace message: String,
diff --git a/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift b/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift
index 2cc4380..4337546 100644
--- a/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift
+++ b/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift
@@ -82,6 +82,7 @@
rangeLength: Int)
extension NSArray {
+ @nonobjc // FIXME: there should be no need in this attribute.
public func available_getObjects(
_ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>?, range: NSRange
) {
@@ -101,6 +102,7 @@
)
extension NSDictionary {
+ @nonobjc // FIXME: there should be no need in this attribute.
public func available_getObjects(
_ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>?,
andKeys keys: AutoreleasingUnsafeMutablePointer<AnyObject?>?
diff --git a/stdlib/public/Platform/Platform.swift b/stdlib/public/Platform/Platform.swift
index 7c830d6..a3284be 100644
--- a/stdlib/public/Platform/Platform.swift
+++ b/stdlib/public/Platform/Platform.swift
@@ -124,13 +124,15 @@
}
public func dprintf(_ fd: Int, _ format: UnsafePointer<Int8>, _ args: CVarArg...) -> Int32 {
- let va_args = getVaList(args)
- return vdprintf(Int32(fd), format, va_args)
+ return withVaList(args) { va_args in
+ vdprintf(Int32(fd), format, va_args)
+ }
}
public func snprintf(ptr: UnsafeMutablePointer<Int8>, _ len: Int, _ format: UnsafePointer<Int8>, _ args: CVarArg...) -> Int32 {
- let va_args = getVaList(args)
- return vsnprintf(ptr, len, format, va_args)
+ return withVaList(args) { va_args in
+ return vsnprintf(ptr, len, format, va_args)
+ }
}
#endif
diff --git a/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift b/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift
index cb79880..607199e 100644
--- a/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift
+++ b/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift
@@ -21,7 +21,7 @@
}
public func distance(to other: String.UTF16View.Index) -> Int {
- return other._offset.distance(to: _offset)
+ return _offset.distance(to: other._offset)
}
public func advanced(by n: Int) -> String.UTF16View.Index {
diff --git a/stdlib/public/SDK/Foundation/Foundation.swift b/stdlib/public/SDK/Foundation/Foundation.swift
index d06016a..bfd1ffe 100644
--- a/stdlib/public/SDK/Foundation/Foundation.swift
+++ b/stdlib/public/SDK/Foundation/Foundation.swift
@@ -501,7 +501,7 @@
@_semantics("convertToObjectiveC")
public func _bridgeToObjectiveC() -> NSArray {
- return unsafeBitCast(self._buffer._asCocoaArray() as AnyObject, to: NSArray.self)
+ return unsafeBitCast(self._bridgeToObjectiveCImpl(), to: NSArray.self)
}
public static func _forceBridgeFromObjectiveC(
diff --git a/stdlib/public/SDK/os/os.swift b/stdlib/public/SDK/os/os.swift
index 7ba4a55..cc396f8 100644
--- a/stdlib/public/SDK/os/os.swift
+++ b/stdlib/public/SDK/os/os.swift
@@ -27,8 +27,9 @@
// Since dladdr is in libc, it is safe to unsafeBitCast
// the cstring argument type.
let str = unsafeBitCast(buf.baseAddress!, to: UnsafePointer<Int8>.self)
- let valist = getVaList(args)
- _swift_os_log(dso, log, type, str, valist)
+ withVaList(args) { valist in
+ _swift_os_log(dso, log, type, str, valist)
+ }
}
}
diff --git a/stdlib/public/core/Algorithm.swift b/stdlib/public/core/Algorithm.swift
index 7958b2f..b207029 100644
--- a/stdlib/public/core/Algorithm.swift
+++ b/stdlib/public/core/Algorithm.swift
@@ -10,9 +10,12 @@
//
//===----------------------------------------------------------------------===//
-/// Returns the lesser of `x` and `y`.
+/// Returns the lesser of two comparable values.
///
-/// If `x == y`, returns `x`.
+/// - Parameters:
+/// - x: A value to compare.
+/// - y: Another value to compare.
+/// - Returns: The lesser of `x` and `y`. If `x` is equal to `y`, returns `x`.
public func min<T : Comparable>(_ x: T, _ y: T) -> T {
// In case `x == y` we pick `x`.
// This preserves any pre-existing order in case `T` has identity,
@@ -23,7 +26,13 @@
/// Returns the least argument passed.
///
-/// If there are multiple equal least arguments, returns the first one.
+/// - Parameters:
+/// - x: A value to compare.
+/// - y: Another value to compare.
+/// - z: A third value to compare.
+/// - rest: Zero or more additional values.
+/// - Returns: The least of all the arguments. If there are multiple equal
+/// least arguments, the result is the first one.
public func min<T : Comparable>(_ x: T, _ y: T, _ z: T, _ rest: T...) -> T {
var minValue = min(min(x, y), z)
// In case `value == minValue`, we pick `minValue`. See min(_:_:).
@@ -33,9 +42,12 @@
return minValue
}
-/// Returns the greater of `x` and `y`.
+/// Returns the greater of two comparable values.
///
-/// If `x == y`, returns `y`.
+/// - Parameters:
+/// - x: A value to compare.
+/// - y: Another value to compare.
+/// - Returns: The greater of `x` and `y`. If `x` is equal to `y`, returns `y`.
public func max<T : Comparable>(_ x: T, _ y: T) -> T {
// In case `x == y`, we pick `y`. See min(_:_:).
return y >= x ? y : x
@@ -43,7 +55,13 @@
/// Returns the greatest argument passed.
///
-/// If there are multiple equal greatest arguments, returns the last one.
+/// - Parameters:
+/// - x: A value to compare.
+/// - y: Another value to compare.
+/// - z: A third value to compare.
+/// - rest: Zero or more additional values.
+/// - Returns: The greatest of all the arguments. If there are multiple equal
+/// greatest arguments, the result is the last one.
public func max<T : Comparable>(_ x: T, _ y: T, _ z: T, _ rest: T...) -> T {
var maxValue = max(max(x, y), z)
// In case `value == maxValue`, we pick `value`. See min(_:_:).
@@ -53,18 +71,20 @@
return maxValue
}
-/// The iterator for `EnumeratedSequence`. `EnumeratedIterator`
-/// wraps a `Base` iterator and yields successive `Int` values,
-/// starting at zero, along with the elements of the underlying
-/// `Base`:
+/// The iterator for `EnumeratedSequence`.
+///
+/// An instance of `EnumeratedIterator` wraps a base iterator and yields
+/// successive `Int` values, starting at zero, along with the elements of the
+/// underlying base iterator. The following example enumerates the elements of
+/// an array:
///
/// var iterator = ["foo", "bar"].enumerated().makeIterator()
/// iterator.next() // (0, "foo")
/// iterator.next() // (1, "bar")
/// iterator.next() // nil
///
-/// - Note: Idiomatic usage is to call `enumerate` instead of
-/// constructing an `EnumerateIterator` directly.
+/// To create an instance of `EnumeratedIterator`, call
+/// `enumerated().makeIterator()` on a sequence or collection.
public struct EnumeratedIterator<
Base : IteratorProtocol
> : IteratorProtocol, Sequence {
@@ -91,14 +111,22 @@
}
}
-/// The type of the `enumerated()` property.
+/// An enumeration of the elements of a sequence or collection.
///
-/// `EnumeratedSequence` is a sequence of pairs (*n*, *x*), where *n*s
-/// are consecutive `Int`s starting at zero, and *x*s are the elements
-/// of a `Base` `Sequence`:
+/// `EnumeratedSequence` is a sequence of pairs (*n*, *x*), where *n*s are
+/// consecutive `Int` values starting at zero, and *x*s are the elements of a
+/// base sequence.
+///
+/// To create an instance of `EnumeratedSequence`, call `enumerated()` on a
+/// sequence or collection. The following example enumerates the elements of
+/// an array.
///
/// var s = ["foo", "bar"].enumerated()
-/// Array(s) // [(0, "foo"), (1, "bar")]
+/// for (n, x) in s {
+/// print("\(n): \(x)")
+/// }
+/// // Prints "0: foo"
+/// // Prints "1: bar"
public struct EnumeratedSequence<Base : Sequence> : Sequence {
internal var _base: Base
@@ -108,8 +136,6 @@
}
/// Returns an iterator over the elements of this sequence.
- ///
- /// - Complexity: O(1).
public func makeIterator() -> EnumeratedIterator<Base.Iterator> {
return EnumeratedIterator(_base: _base.makeIterator())
}
diff --git a/stdlib/public/core/AnyHashable.swift b/stdlib/public/core/AnyHashable.swift
index db4d43d..e81988c 100644
--- a/stdlib/public/core/AnyHashable.swift
+++ b/stdlib/public/core/AnyHashable.swift
@@ -87,14 +87,14 @@
/// A type-erased hashable value.
///
-/// Forwards equality comparisons and hashing operations to an
-/// underlying hashable value, hiding its specific type.
+/// The `AnyHashable` type forwards equality comparisons and hashing operations
+/// to an underlying hashable value, hiding its specific underlying type.
///
-/// You can store mixed-type keys in `Dictionary` and other
-/// collections that require `Hashable` by wrapping mixed-type keys in
+/// You can store mixed-type keys in dictionaries and other collections that
+/// require `Hashable` conformance by wrapping mixed-type keys in
/// `AnyHashable` instances:
///
-/// let descriptions: [AnyHashable : Any] = [
+/// let descriptions: [AnyHashable: Any] = [
/// AnyHashable("😄"): "emoji",
/// AnyHashable(42): "an Int",
/// AnyHashable(Int8(43)): "an Int8",
@@ -107,17 +107,24 @@
public struct AnyHashable {
internal var _box: _AnyHashableBox
- /// Creates an opaque hashable value that wraps `base`.
+ /// Creates a type-erased hashable value that wraps the given instance.
///
- /// Example:
+ /// The following example creates two type-erased hashable values: `x` wraps
+ /// an `Int` with the value 42, while `y` wraps a `UInt8` with the same
+ /// numeric value. Because the underlying types of `x` and `y` are
+ /// different, the two variables do not compare as equal despite having
+ /// equal underlying values.
///
/// let x = AnyHashable(Int(42))
/// let y = AnyHashable(UInt8(42))
///
- /// print(x == y) // Prints "false" because `Int` and `UInt8`
- /// // are different types.
+ /// print(x == y)
+ /// // Prints "false" because `Int` and `UInt8` are different types
///
- /// print(x == AnyHashable(Int(42))) // Prints "true".
+ /// print(x == AnyHashable(Int(42)))
+ /// // Prints "true"
+ ///
+ /// - Parameter base: A hashable value to wrap.
public init<H : Hashable>(_ base: H) {
if let customRepresentation =
(base as? _HasCustomAnyHashableRepresentation)?._toCustomAnyHashable() {
@@ -135,11 +142,16 @@
self._box = _ConcreteHashableBox(base)
}
- /// The value wrapped in this `AnyHashable` instance.
+ /// The value wrapped by this instance.
///
- /// let anyMessage = AnyHashable("Hello")
- /// let unwrappedMessage: Any = anyMessage.base
- /// print(unwrappedMessage) // prints "hello"
+ /// The `base` property can be cast back to its original type using one of
+ /// the casting operators (`as?`, `as!`, or `as`).
+ ///
+ /// let anyMessage = AnyHashable("Hello world!")
+ /// if let unwrappedMessage = anyMessage.base as? String {
+ /// print(unwrappedMessage)
+ /// }
+ /// // Prints "Hello world!"
public var base: Any {
return _box._base
}
@@ -155,6 +167,31 @@
}
extension AnyHashable : Equatable {
+ /// Returns a Boolean value indicating whether two type-erased hashable
+ /// instances wrap the same type and value.
+ ///
+ /// Two instances of `AnyHashable` compare as equal if and only if the
+ /// underlying types have the same conformance to the `Equatable` protocol
+ /// and the underlying values compare as equal.
+ ///
+ /// The following example creates two type-erased hashable values: `x` wraps
+ /// an `Int` with the value 42, while `y` wraps a `UInt8` with the same
+ /// numeric value. Because the underlying types of `x` and `y` are
+ /// different, the two variables do not compare as equal despite having
+ /// equal underlying values.
+ ///
+ /// let x = AnyHashable(Int(42))
+ /// let y = AnyHashable(UInt8(42))
+ ///
+ /// print(x == y)
+ /// // Prints "false" because `Int` and `UInt8` are different types
+ ///
+ /// print(x == AnyHashable(Int(42)))
+ /// // Prints "true"
+ ///
+ /// - Parameters:
+ /// - lhs: A type-erased hashable value.
+ /// - rhs: Another type-erased hashable value.
public static func == (lhs: AnyHashable, rhs: AnyHashable) -> Bool {
return lhs._box._isEqual(to: rhs._box)
}
diff --git a/stdlib/public/core/ArrayBuffer.swift b/stdlib/public/core/ArrayBuffer.swift
index 82b31e8..cd65004 100644
--- a/stdlib/public/core/ArrayBuffer.swift
+++ b/stdlib/public/core/ArrayBuffer.swift
@@ -83,7 +83,7 @@
extension _ArrayBuffer {
/// Adopt the storage of `source`.
- public init(_ source: NativeBuffer, shiftedToStartIndex: Int) {
+ public init(_buffer source: NativeBuffer, shiftedToStartIndex: Int) {
_sanityCheck(shiftedToStartIndex == 0, "shiftedToStartIndex must be 0")
_storage = _ArrayBridgeStorage(native: source._storage)
}
@@ -232,7 +232,7 @@
let boundsCount = bounds.count
if boundsCount == 0 {
return _SliceBuffer(
- _ContiguousArrayBuffer<Element>(),
+ _buffer: _ContiguousArrayBuffer<Element>(),
shiftedToStartIndex: bounds.lowerBound)
}
@@ -262,7 +262,8 @@
.assumingMemoryBound(to: AnyObject.self),
range: _SwiftNSRange(location: bounds.lowerBound, length: boundsCount))
- return _SliceBuffer(result, shiftedToStartIndex: bounds.lowerBound)
+ return _SliceBuffer(
+ _buffer: result, shiftedToStartIndex: bounds.lowerBound)
}
set {
fatalError("not implemented")
diff --git a/stdlib/public/core/ArrayBufferProtocol.swift b/stdlib/public/core/ArrayBufferProtocol.swift
index 5cd21fd..08db658 100644
--- a/stdlib/public/core/ArrayBufferProtocol.swift
+++ b/stdlib/public/core/ArrayBufferProtocol.swift
@@ -24,7 +24,7 @@
init()
/// Adopt the entire buffer, presenting it at the provided `startIndex`.
- init(_ buffer: _ContiguousArrayBuffer<Element>, shiftedToStartIndex: Int)
+ init(_buffer: _ContiguousArrayBuffer<Element>, shiftedToStartIndex: Int)
/// Copy the elements in `bounds` from this buffer into uninitialized
/// memory starting at `target`. Return a pointer "past the end" of the
diff --git a/stdlib/public/core/Arrays.swift.gyb b/stdlib/public/core/Arrays.swift.gyb
index 9dc60fb..ed975cd 100644
--- a/stdlib/public/core/Arrays.swift.gyb
+++ b/stdlib/public/core/Arrays.swift.gyb
@@ -99,7 +99,7 @@
///
/// You can call any method on the slices that you might have called on the
/// `absences` array. To learn which half had more absences, use the
-/// `reduce(_:)` method to calculate each sum.
+/// `reduce(_:_:)` method to calculate each sum.
///
/// let firstHalfSum = firstHalf.reduce(0, +)
/// let secondHalfSum = secondHalf.reduce(0, +)
@@ -168,16 +168,15 @@
/// An ordered, random-access collection.
///
/// Arrays are one of the most commonly used data types in an app. You use
-/// arrays to organize your app's data. Specifically, you use the `Array`
-/// type to hold elements of a single type, the array's `Element` type. An
-/// array's elements can be anything from an integer to a string to a
-/// class.
+/// arrays to organize your app's data. Specifically, you use the `Array` type
+/// to hold elements of a single type, the array's `Element` type. An array's
+/// elements can be anything from an integer to a string to a class.
///
-/// Swift makes it easy to create arrays in your code using an array
-/// literal: simply surround a comma-separated list of values with square
-/// brackets. Without any other information, Swift creates an array that
-/// includes the specified values, automatically inferring the array's
-/// `Element` type. For example:
+/// Swift makes it easy to create arrays in your code using an array literal:
+/// simply surround a comma separated list of values with square brackets.
+/// Without any other information, Swift creates an array that includes the
+/// specified values, automatically inferring the array's `Element` type. For
+/// example:
///
/// // An array of 'Int' elements
/// let oddNumbers = [1, 3, 5, 7, 9, 11, 13, 15]
@@ -194,8 +193,8 @@
/// // The full type name is also allowed
/// var emptyFloats: Array<Float> = Array()
///
-/// If you need an array that is preinitialized with a fixed number of
-/// default values, use the `Array(repeating:count:)` initializer.
+/// If you need an array that is preinitialized with a fixed number of default
+/// values, use the `Array(repeating:count:)` initializer.
///
/// var digitCounts = Array(repeating: 0, count: 10)
/// print(digitCounts)
@@ -204,8 +203,8 @@
/// Accessing Array Values
/// ======================
///
-/// When you need to perform an operation on all of an array's elements, use
-/// a `for`-`in` loop to iterate through the array's contents.
+/// When you need to perform an operation on all of an array's elements, use a
+/// `for`-`in` loop to iterate through the array's contents.
///
/// for street in streets {
/// print("I don't live on \(street).")
@@ -238,10 +237,10 @@
/// // Prints "nil, nil"
///
/// You can access individual array elements through a subscript. The first
-/// element of a nonempty array is always at index zero. You can
-/// subscript an array with any integer from zero up to, but not including,
-/// the count of the array. Using a negative number or an index equal to or
-/// greater than `count` triggers a runtime error. For example:
+/// element of a nonempty array is always at index zero. You can subscript an
+/// array with any integer from zero up to, but not including, the count of
+/// the array. Using a negative number or an index equal to or greater than
+/// `count` triggers a runtime error. For example:
///
/// print(oddNumbers[0], oddNumbers[3], separator: ", ")
/// // Prints "1, 7"
@@ -255,52 +254,47 @@
/// Adding and Removing Elements
/// ============================
///
-/// Suppose you need to store a list of the names of students that are
-/// signed up for a class you're teaching. During the registration period,
-/// you need to add and remove names as students add and drop the class.
+/// Suppose you need to store a list of the names of students that are signed
+/// up for a class you're teaching. During the registration period, you need
+/// to add and remove names as students add and drop the class.
///
/// var students = ["Ben", "Ivy", "Jordell"]
///
-/// More students are signing up. Add single elements to the end of an array
-/// by using the `append(_:)` method. Add multiple elements at once by passing
-/// another array or a sequence of any kind to the `append(contentsOf:)`
-/// method.
+/// To add single elements to the end of an array, use the `append(_:)` method.
+/// Add multiple elements at once by passing another array or a sequence of
+/// any kind to the `append(contentsOf:)` method.
///
/// students.append("Maxime")
/// students.append(contentsOf: ["Shakia", "William"])
+/// // ["Ben", "Ivy", "Jordell", "Maxime", "Shakia", "William"]
///
-/// print(students)
-/// // Prints "["Ben", "Ivy", "Jordell", "Maxime", "Shakia", "William"]"
-///
-/// Another last-minute addition! Add new elements into the middle of the
-/// array by using the `insert(_:at:)` method for single elements and
-/// by using `insert(contentsOf:at:)` to insert multiple elements from another
+/// You can add new elements in the middle of an array by using the
+/// `insert(_:at:)` method for single elements and by using
+/// `insert(contentsOf:at:)` to insert multiple elements from another
/// collection or array literal. The elements at that index and later are
/// shifted back to make room.
///
-/// // Welcome, Liam!
/// students.insert("Liam", at: 3)
+/// // ["Ben", "Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]
///
-/// A couple of students can't take your class after all. Use the
-/// `removeLast()` and `remove(at:)` methods to remove their names
-/// from the array.
+/// To remove elements from an array, use the `remove(at:)`,
+/// `removeSubrange(_:)`, and `removeLast()` methods.
///
/// // Ben's family is moving to another state
/// students.remove(at: 0)
+/// // ["Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]
///
/// // William is signing up for a different class
/// students.removeLast()
+/// // ["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]
///
-/// print(students)
-/// // Prints "["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]"
-///
-/// On the first day, you learn that Maxime really prefers to go by Max.
-/// Replace an existing element with a new value by assigning to the
+/// You can replace an existing element with a new value by assigning to the
/// subscript.
///
/// if let i = students.index(of: "Maxime") {
/// students[i] = "Max"
/// }
+/// // ["Ivy", "Jordell", "Liam", "Max", "Shakia"]
///
/// Growing the Size of an Array
/// ----------------------------
@@ -308,21 +302,20 @@
/// Every array reserves a specific amount of memory to hold its contents. When
/// you add elements to an array and that array begins to exceed its reserved
/// capacity, the array allocates a larger region of memory and copies its
-/// elements into the new storage. The new storage is a multiple of the
-/// old storage's size. This exponential growth strategy means that appending
-/// an element happens in constant time, averaging the performance of many
-/// append operations. Append operations that trigger reallocation have a
-/// performance cost, but they occur less and less often as the array grows
-/// larger.
+/// elements into the new storage. The new storage is a multiple of the old
+/// storage's size. This exponential growth strategy means that appending an
+/// element happens in constant time, averaging the performance of many append
+/// operations. Append operations that trigger reallocation have a performance
+/// cost, but they occur less and less often as the array grows larger.
///
-/// If you know approximately how many elements you will need to store, use
-/// the `reserveCapacity(_:)` method before appending to the array to avoid
-/// intermediate reallocations. Use the `capacity` and `count` properties
-/// to determine how many more elements the array can store without
-/// allocating larger storage.
+/// If you know approximately how many elements you will need to store, use the
+/// `reserveCapacity(_:)` method before appending to the array to avoid
+/// intermediate reallocations. Use the `capacity` and `count` properties to
+/// determine how many more elements the array can store without allocating
+/// larger storage.
///
-/// For arrays of most `Element` types, this storage is a contiguous block
-/// of memory. For arrays with an `Element` type that is a class or `@objc`
+/// For arrays of most `Element` types, this storage is a contiguous block of
+/// memory. For arrays with an `Element` type that is a class or `@objc`
/// protocol type, this storage can be a contiguous block of memory or an
/// instance of `NSArray`. Because any arbitrary subclass of `NSArray` can
/// become an `Array`, there are no guarantees about representation or
@@ -331,10 +324,10 @@
/// Modifying Copies of Arrays
/// ==========================
///
-/// Each array has an independent value that includes the values of all of
-/// its elements. For simple types such as integers and other structures,
-/// this means that when you change a value in one array, the value of that
-/// element does not change in any copies of the array. For example:
+/// Each array has an independent value that includes the values of all of its
+/// elements. For simple types such as integers and other structures, this
+/// means that when you change a value in one array, the value of that element
+/// does not change in any copies of the array. For example:
///
/// var numbers = [1, 2, 3, 4, 5]
/// var numbersCopy = numbers
@@ -344,13 +337,13 @@
/// print(numbersCopy)
/// // Prints "[1, 2, 3, 4, 5]"
///
-/// If the elements in an array are instances of a class, the semantics are
-/// the same, though they might appear different at first. In this case,
-/// the values stored in the array are references to objects that live
-/// outside the array. If you change a reference to an object in one array,
-/// only that array has a reference to the new object. However, if two
-/// arrays contain references to the same object, you can observe changes
-/// to that object's properties from both arrays. For example:
+/// If the elements in an array are instances of a class, the semantics are the
+/// same, though they might appear different at first. In this case, the
+/// values stored in the array are references to objects that live outside the
+/// array. If you change a reference to an object in one array, only that
+/// array has a reference to the new object. However, if two arrays contain
+/// references to the same object, you can observe changes to that object's
+/// properties from both arrays. For example:
///
/// // An integer type with reference semantics
/// class IntegerReference {
@@ -374,21 +367,21 @@
///
/// Arrays, like all variable-size collections in the standard library, use
/// copy-on-write optimization. Multiple copies of an array share the same
-/// storage until you modify one of the copies. When that happens, the
-/// array being modified replaces its storage with a uniquely owned copy of
-/// itself, which is then modified in place. Optimizations are sometimes
-/// applied that can reduce the amount of copying.
+/// storage until you modify one of the copies. When that happens, the array
+/// being modified replaces its storage with a uniquely owned copy of itself,
+/// which is then modified in place. Optimizations are sometimes applied that
+/// can reduce the amount of copying.
///
-/// This means that if an array is sharing storage with other copies, the
-/// first mutating operation on that array incurs the cost of copying the
-/// array. An array that is the sole owner of its storage can perform
-/// mutating operations in place.
+/// This means that if an array is sharing storage with other copies, the first
+/// mutating operation on that array incurs the cost of copying the array. An
+/// array that is the sole owner of its storage can perform mutating
+/// operations in place.
///
/// In the example below, a `numbers` array is created along with two copies
/// that share the same storage. When the original `numbers` array is
/// modified, it makes a unique copy of its storage before making the
-/// modification. Further modifications to `numbers` are made in place,
-/// while the two copies continue to share the original storage.
+/// modification. Further modifications to `numbers` are made in place, while
+/// the two copies continue to share the original storage.
///
/// var numbers = [1, 2, 3, 4, 5]
/// var firstCopy = numbers
@@ -412,11 +405,11 @@
/// Foundation type.
///
/// The following example shows how you can bridge an `Array` instance to
-/// `NSArray` to use the `write(to:atomically:)` method. In this
-/// example, the `colors` array can be bridged to `NSArray` because its
-/// `String` elements bridge to `NSString`. The compiler prevents bridging
-/// the `moreColors` array, on the other hand, because its `Element` type
-/// is `Optional<String>`, which does *not* bridge to a Foundation type.
+/// `NSArray` to use the `write(to:atomically:)` method. In this example, the
+/// `colors` array can be bridged to `NSArray` because its `String` elements
+/// bridge to `NSString`. The compiler prevents bridging the `moreColors`
+/// array, on the other hand, because its `Element` type is
+/// `Optional<String>`, which does *not* bridge to a Foundation type.
///
/// let colors = ["periwinkle", "rose", "moss"]
/// let moreColors: [String?] = ["ochre", "pine"]
@@ -429,17 +422,17 @@
/// // error: cannot convert value of type '[String?]' to type 'NSArray'
///
/// Bridging from `Array` to `NSArray` takes O(1) time and O(1) space if the
-/// array's elements are already instances of a class or an `@objc`
-/// protocol; otherwise, it takes O(n) time and space.
+/// array's elements are already instances of a class or an `@objc` protocol;
+/// otherwise, it takes O(n) time and space.
///
/// Bridging from `NSArray` to `Array` first calls the `copy(with:)`
/// (`- copyWithZone:` in Objective-C) method on the array to get an immutable
/// copy and then performs additional Swift bookkeeping work that takes O(1)
-/// time. For instances of `NSArray` that are already immutable,
-/// `copy(with:)` usually returns the same array in O(1) time; otherwise,
-/// the copying performance is unspecified. The instances of `NSArray` and
-/// `Array` share storage using the same copy-on-write optimization that is
-/// used when two instances of `Array` share storage.
+/// time. For instances of `NSArray` that are already immutable, `copy(with:)`
+/// usually returns the same array in O(1) time; otherwise, the copying
+/// performance is unspecified. The instances of `NSArray` and `Array` share
+/// storage using the same copy-on-write optimization that is used when two
+/// instances of `Array` share storage.
///
/// - Note: The `ContiguousArray` and `ArraySlice` types are not bridged;
/// instances of those types always have a contiguous block of memory as
@@ -563,9 +556,6 @@
/// If `n` is negative, this is the same value as the result of `-n` calls
/// to `index(before:)`.
///
- /// - Precondition:
- /// - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
- /// - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
/// - Complexity: O(1)
public func index(_ i: Int, offsetBy n: Int) -> Int {
// NOTE: this is a manual specialization of index movement for a Strideable
@@ -660,7 +650,9 @@
/// Accesses the element at the specified position.
///
- /// For example:
+ /// The following example uses indexed subscripting to update an array's
+ /// second element. After assigning the new value (`"Butler"`) at a specific
+ /// position, that value is immediately available at that same position.
///
/// var streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
/// streets[1] = "Butler"
@@ -794,7 +786,8 @@
buffer._copyContents(
subRange: Range(buffer.indices),
initializing: newBuffer.firstElementAddress)
- buffer = _Buffer(newBuffer, shiftedToStartIndex: buffer.startIndex)
+ buffer = _Buffer(
+ _buffer: newBuffer, shiftedToStartIndex: buffer.startIndex)
}
@_semantics("array.make_mutable")
@@ -893,8 +886,8 @@
/// Initialization from an existing buffer does not have "array.init"
/// semantics because the caller may retain an alias to buffer.
public // @testable
- init(_buffer: _ContiguousArrayBuffer<Element>) {
- self.init(_buffer: _Buffer(_buffer, shiftedToStartIndex: 0))
+ init(_buffer buffer: _ContiguousArrayBuffer<Element>) {
+ self.init(_buffer: _Buffer(_buffer: buffer, shiftedToStartIndex: 0))
}
%end
@@ -1039,7 +1032,7 @@
self = ${Self}(
_buffer: _Buffer(
- s._copyToContiguousArray()._buffer,
+ _buffer: s._copyToContiguousArray()._buffer,
shiftedToStartIndex: 0))
}
@@ -1073,7 +1066,7 @@
) -> _Buffer {
let newBuffer = _ContiguousArrayBuffer<Element>(
uninitializedCount: 0, minimumCapacity: minimumCapacity)
- return _Buffer(newBuffer, shiftedToStartIndex: 0)
+ return _Buffer(_buffer: newBuffer, shiftedToStartIndex: 0)
}
/// Construct a ${Self} of `count` uninitialized elements.
@@ -1126,7 +1119,8 @@
storage, to: _ContiguousArrayStorage<Element>.self))
return (
- Array(_buffer: _Buffer(innerBuffer, shiftedToStartIndex: 0)),
+ Array(
+ _buffer: _Buffer(_buffer: innerBuffer, shiftedToStartIndex: 0)),
innerBuffer.firstElementAddress)
}
@@ -1211,7 +1205,8 @@
_buffer._copyContents(
subRange: Range(_buffer.indices),
initializing: newBuffer.firstElementAddress)
- _buffer = _Buffer(newBuffer, shiftedToStartIndex: _buffer.startIndex)
+ _buffer = _Buffer(
+ _buffer: newBuffer, shiftedToStartIndex: _buffer.startIndex)
}
_sanityCheck(capacity >= minimumCapacity)
}
@@ -1258,13 +1253,25 @@
/// Adds a new element at the end of the array.
///
+ /// Use this method to append a single element to the end of a mutable array.
+ ///
+ /// var numbers = [1, 2, 3, 4, 5]
+ /// numbers.append(100)
+ /// print(numbers)
+ /// // Prints "[1, 2, 3, 4, 5, 100]"
+ ///
+ /// Because arrays increase their allocated capacity using an exponential
+ /// strategy, appending a single element to an array is an O(1) operation
+ /// when averaged over many calls to the `append(_:)` method. When an array
+ /// has additional capacity and is not sharing its storage with another
+ /// instance, appending an element is O(1). When an array needs to
+ /// reallocate storage before appending or its storage is shared with
+ /// another copy, appending is O(*n*), where *n* is the length of the array.
+ ///
/// - Parameter newElement: The element to append to the array.
///
- /// - Complexity: Appending an element to the array averages to O(1) over
- /// many additions. When the array needs to reallocate storage before
- /// appending or its storage is shared with another copy, appending an
- /// element is O(*n*), where *n* is the length of the array. If the array
- /// uses a bridged `NSArray` instance as its storage, the efficiency is
+ /// - Complexity: Amortized O(1) over many additions. If the array uses a
+ /// bridged `NSArray` instance as its storage, the efficiency is
/// unspecified.
public mutating func append(_ newElement: Element) {
_makeUniqueAndReserveCapacityIfNotUnique()
@@ -1275,8 +1282,8 @@
/// Adds the elements of a sequence to the end of the array.
///
- /// Use this method to append the elements of a sequence to the end of a
- /// collection. This example appends the elements of a `Range<Int>` instance
+ /// Use this method to append the elements of a sequence to the end of an
+ /// array. This example appends the elements of a `Range<Int>` instance
/// to an array of integers.
///
/// var numbers = [1, 2, 3, 4, 5]
@@ -1307,7 +1314,7 @@
/// Adds the elements of a collection to the end of the array.
///
/// Use this method to append the elements of a collection to the end of this
- /// collection. This example appends the elements of a `Range<Int>` instance
+ /// array. This example appends the elements of a `Range<Int>` instance
/// to an array of integers.
///
/// var numbers = [1, 2, 3, 4, 5]
@@ -1341,7 +1348,13 @@
%if Self == 'ArraySlice':
/// Removes and returns the last element of the array.
///
- /// The array must not be empty.
+ /// The array must not be empty. This example removes the last number from an
+ /// array of `Double` values.
+ ///
+ /// var measurements: [Double] = [1.1, 1.5, 2.9, 1.2, 1.5, 1.3, 1.2]
+ /// let removed = measurements.removeLast()
+ /// print(measurements)
+ /// // Prints "[1.1, 1.5, 2.9, 1.2, 1.5, 1.3]"
///
/// - Returns: The element that was removed.
public mutating func _customRemoveLast() -> Element? {
@@ -1923,7 +1936,7 @@
let tailEnd = source.endIndex
source._copyContents(subRange: tailStart..<tailEnd, initializing: newEnd)
}
- source = _Buffer(dest, shiftedToStartIndex: source.startIndex)
+ source = _Buffer(_buffer: dest, shiftedToStartIndex: source.startIndex)
}
internal struct _InitializePointer<T> : _PointerFunction {
@@ -2081,6 +2094,11 @@
#if _runtime(_ObjC)
extension Array {
+ public // @SPI(Foundation)
+ func _bridgeToObjectiveCImpl() -> AnyObject {
+ return _buffer._asCocoaArray()
+ }
+
/// Tries to downcast the source `NSArray` as our native buffer type.
/// If it succeeds, creates a new `Array` around it and returns that.
/// Returns `nil` otherwise.
@@ -2144,7 +2162,7 @@
init(_startIndex: Int) {
self.init(
_buffer: _Buffer(
- ContiguousArray()._buffer,
+ _buffer: ContiguousArray()._buffer,
shiftedToStartIndex: _startIndex))
}
}
diff --git a/stdlib/public/core/Assert.swift b/stdlib/public/core/Assert.swift
index efc9ad8..7b007ad 100644
--- a/stdlib/public/core/Assert.swift
+++ b/stdlib/public/core/Assert.swift
@@ -10,23 +10,33 @@
//
//===----------------------------------------------------------------------===//
-/// Traditional C-style assert with an optional message.
+/// Performs a traditional C-style assert with an optional message.
///
-/// Use this function for internal sanity checks that are active
-/// during testing but do not impact performance of shipping code.
-/// To check for invalid usage in Release builds; see `precondition`.
+/// Use this function for internal sanity checks that are active during testing
+/// but do not impact performance of shipping code. To check for invalid usage
+/// in Release builds, see `precondition(_:_:file:line:)`.
///
-/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-/// configuration): if `condition` evaluates to false, stop program
+/// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
+/// configuration): If `condition` evaluates to `false`, stop program
/// execution in a debuggable state after printing `message`.
///
-/// * In -O builds (the default for Xcode's Release configuration),
+/// * In `-O` builds (the default for Xcode's Release configuration),
/// `condition` is not evaluated, and there are no effects.
///
-/// * In -Ounchecked builds, `condition` is not evaluated, but the
-/// optimizer may assume that it *would* evaluate to `true`. Failure
-/// to satisfy that assumption in -Ounchecked builds is a serious
-/// programming error.
+/// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
+/// may assume that it *always* evaluates to `true`. Failure to satisfy that
+/// assumption is a serious programming error.
+///
+/// - Parameters:
+/// - condition: The condition to test. `condition` is only evaluated in
+/// playgrounds and `-Onone` builds.
+/// - message: A string to print if `condition` is evaluated to `false`. The
+/// default is an empty string.
+/// - file: The file name to print with `message` if the assertion fails. The
+/// default is the file where `assert(_:_:file:line:)` is called.
+/// - line: The line number to print along with `message` if the assertion
+/// fails. The default is the line number where `assert(_:_:file:line:)`
+/// is called.
@_transparent
public func assert(
_ condition: @autoclosure () -> Bool,
@@ -42,22 +52,33 @@
}
}
-/// Check a necessary condition for making forward progress.
+/// Checks a necessary condition for making forward progress.
///
-/// Use this function to detect conditions that must prevent the
-/// program from proceeding even in shipping code.
+/// Use this function to detect conditions that must prevent the program from
+/// proceeding, even in shipping code.
///
-/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-/// configuration): if `condition` evaluates to false, stop program
+/// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
+/// configuration): If `condition` evaluates to `false`, stop program
/// execution in a debuggable state after printing `message`.
///
-/// * In -O builds (the default for Xcode's Release configuration):
-/// if `condition` evaluates to false, stop program execution.
+/// * In `-O` builds (the default for Xcode's Release configuration): If
+/// `condition` evaluates to `false`, stop program execution.
///
-/// * In -Ounchecked builds, `condition` is not evaluated, but the
-/// optimizer may assume that it *would* evaluate to `true`. Failure
-/// to satisfy that assumption in -Ounchecked builds is a serious
-/// programming error.
+/// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
+/// may assume that it *always* evaluates to `true`. Failure to satisfy that
+/// assumption is a serious programming error.
+///
+/// - Parameters:
+/// - condition: The condition to test. `condition` is not evaluated in
+/// `-Ounchecked` builds.
+/// - message: A string to print if `condition` is evaluated to `false` in a
+/// playground or `-Onone` build. The default is an empty string.
+/// - file: The file name to print with `message` if the precondition fails.
+/// The default is the file where `precondition(_:_:file:line:)` is
+/// called.
+/// - line: The line number to print along with `message` if the assertion
+/// fails. The default is the line number where
+/// `precondition(_:_:file:line:)` is called.
@_transparent
public func precondition(
_ condition: @autoclosure () -> Bool,
@@ -76,24 +97,31 @@
}
}
-/// Indicate that an internal sanity check failed.
+/// Indicates that an internal sanity check failed.
///
-/// Use this function to stop the program, without impacting the
-/// performance of shipping code, when control flow is not expected to
-/// reach the call (e.g. in the `default` case of a `switch` where you
-/// have knowledge that one of the other cases must be satisfied). To
-/// protect code from invalid usage in Release builds; see
-/// `preconditionFailure`.
+/// Use this function to stop the program, without impacting the performance of
+/// shipping code, when control flow is not expected to reach the call---for
+/// example, in the `default` case of a `switch` where you have knowledge that
+/// one of the other cases must be satisfied. To protect code from invalid
+/// usage in Release builds, see `preconditionFailure(_:file:line:)`.
///
/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-/// configuration) stop program execution in a debuggable state
-/// after printing `message`.
+/// configuration), stop program execution in a debuggable state after
+/// printing `message`.
///
/// * In -O builds, has no effect.
///
-/// * In -Ounchecked builds, the optimizer may assume that this
-/// function will never be called. Failure to satisfy that assumption
-/// is a serious programming error.
+/// * In -Ounchecked builds, the optimizer may assume that this function is
+/// never called. Failure to satisfy that assumption is a serious
+/// programming error.
+///
+/// - Parameters:
+/// - message: A string to print in a playground or `-Onone` build. The
+/// default is an empty string.
+/// - file: The file name to print with `message`. The default is the file
+/// where `assertionFailure(_:file:line:)` is called.
+/// - line: The line number to print along with `message`. The default is the
+/// line number where `assertionFailure(_:file:line:)` is called.
@inline(__always)
public func assertionFailure(
_ message: @autoclosure () -> String = String(),
@@ -108,21 +136,30 @@
}
}
-/// Indicate that a precondition was violated.
+/// Indicates that a precondition was violated.
///
-/// Use this function to stop the program when control flow can only
-/// reach the call if your API was improperly used.
+/// Use this function to stop the program when control flow can only reach the
+/// call if your API was improperly used. This function's effects vary
+/// depending on the build flag used:
///
-/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-/// configuration), stop program execution in a debuggable state
-/// after printing `message`.
+/// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
+/// configuration), stops program execution in a debuggable state after
+/// printing `message`.
///
-/// * In -O builds (the default for Xcode's Release configuration),
-/// stop program execution.
+/// * In `-O` builds (the default for Xcode's Release configuration), stops
+/// program execution.
///
-/// * In -Ounchecked builds, the optimizer may assume that this
-/// function will never be called. Failure to satisfy that assumption
-/// is a serious programming error.
+/// * In `-Ounchecked` builds, the optimizer may assume that this function is
+/// never called. Failure to satisfy that assumption is a serious
+/// programming error.
+///
+/// - Parameters:
+/// - message: A string to print in a playground or `-Onone` build. The
+/// default is an empty string.
+/// - file: The file name to print with `message`. The default is the file
+/// where `preconditionFailure(_:file:line:)` is called.
+/// - line: The line number to print along with `message`. The default is the
+/// line number where `preconditionFailure(_:file:line:)` is called.
@_transparent
public func preconditionFailure(
_ message: @autoclosure () -> String = String(),
@@ -138,7 +175,14 @@
_conditionallyUnreachable()
}
-/// Unconditionally print a `message` and stop execution.
+/// Unconditionally prints a given message and stops execution.
+///
+/// - Parameters:
+/// - message: The string to print. The default is an empty string.
+/// - file: The file name to print with `message`. The default is the file
+/// where `fatalError(_:file:line:)` is called.
+/// - line: The line number to print along with `message`. The default is the
+/// line number where `fatalError(_:file:line:)` is called.
@_transparent
public func fatalError(
_ message: @autoclosure () -> String = String(),
diff --git a/stdlib/public/core/CTypes.swift b/stdlib/public/core/CTypes.swift
index 94d5329..cd74a0d 100644
--- a/stdlib/public/core/CTypes.swift
+++ b/stdlib/public/core/CTypes.swift
@@ -86,64 +86,62 @@
self._rawValue = v
}
- /// Construct an `OpaquePointer` from a given address in memory.
+ /// Creates an `OpaquePointer` from a given address in memory.
@_transparent
public init?(bitPattern: Int) {
if bitPattern == 0 { return nil }
self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
}
- /// Construct an `OpaquePointer` from a given address in memory.
+ /// Creates an `OpaquePointer` from a given address in memory.
@_transparent
public init?(bitPattern: UInt) {
if bitPattern == 0 { return nil }
self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
}
- /// Convert a typed `UnsafePointer` to an opaque C pointer.
+ /// Converts a typed `UnsafePointer` to an opaque C pointer.
@_transparent
public init<T>(_ from: UnsafePointer<T>) {
self._rawValue = from._rawValue
}
- /// Convert a typed `UnsafePointer` to an opaque C pointer.
+ /// Converts a typed `UnsafePointer` to an opaque C pointer.
///
- /// Returns nil if `from` is nil.
+ /// The result is `nil` if `from` is `nil`.
@_transparent
public init?<T>(_ from: UnsafePointer<T>?) {
guard let unwrapped = from else { return nil }
self.init(unwrapped)
}
- /// Convert a typed `UnsafeMutablePointer` to an opaque C pointer.
+ /// Converts a typed `UnsafeMutablePointer` to an opaque C pointer.
@_transparent
public init<T>(_ from: UnsafeMutablePointer<T>) {
self._rawValue = from._rawValue
}
- /// Convert a typed `UnsafeMutablePointer` to an opaque C pointer.
+ /// Converts a typed `UnsafeMutablePointer` to an opaque C pointer.
///
- /// Returns nil if `from` is nil.
+ /// The result is `nil` if `from` is `nil`.
@_transparent
public init?<T>(_ from: UnsafeMutablePointer<T>?) {
guard let unwrapped = from else { return nil }
self.init(unwrapped)
}
- /// The hash value.
+ /// The pointer's hash value.
///
- /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
- ///
- /// - Note: The hash value is not guaranteed to be stable across
- /// different invocations of the same program. Do not persist the
- /// hash value across program runs.
+ /// The hash value is not guaranteed to be stable across different
+ /// invocations of the same program. Do not persist the hash value across
+ /// program runs.
public var hashValue: Int {
return Int(Builtin.ptrtoint_Word(_rawValue))
}
}
extension OpaquePointer : CustomDebugStringConvertible {
- /// A textual representation of `self`, suitable for debugging.
+ /// A textual representation of the pointer, suitable for debugging.
public var debugDescription: String {
return _rawPointerToString(_rawValue)
}
@@ -179,7 +177,7 @@
}
extension CVaListPointer : CustomDebugStringConvertible {
- /// A textual representation of `self`, suitable for debugging.
+ /// A textual representation of the pointer, suitable for debugging.
public var debugDescription: String {
return value.debugDescription
}
diff --git a/stdlib/public/core/ClosedRange.swift b/stdlib/public/core/ClosedRange.swift
index c4d0f82..c5dddee 100644
--- a/stdlib/public/core/ClosedRange.swift
+++ b/stdlib/public/core/ClosedRange.swift
@@ -385,7 +385,9 @@
/// Returns a closed range that contains both of its bounds.
///
-/// For example:
+/// Use the closed range operator (`...`) to create a closed range of any type
+/// that conforms to the `Comparable` protocol. This example creates a
+/// `ClosedRange<Character>` from "a" up to, and including, "z".
///
/// let lowercase = "a"..."z"
/// print(lowercase.contains("z"))
@@ -404,12 +406,23 @@
/// Returns a countable closed range that contains both of its bounds.
///
-/// For example:
-///
+/// Use the closed range operator (`...`) to create a closed range of any type
+/// that conforms to the `Strideable` protocol with an associated signed
+/// integer `Stride` type, such as any of the standard library's integer
+/// types. This example creates a `CountableClosedRange<Int>` from zero up to,
+/// and including, nine.
+///
/// let singleDigits = 0...9
/// print(singleDigits.contains(9))
/// // Prints "true"
///
+/// You can use sequence or collection methods on the `singleDigits` range.
+///
+/// print(singleDigits.count)
+/// // Prints "10"
+/// print(singleDigits.last)
+/// // Prints "9"
+///
/// - Parameters:
/// - minimum: The lower bound for the range.
/// - maximum: The upper bound for the range.
diff --git a/stdlib/public/core/Collection.swift b/stdlib/public/core/Collection.swift
index 029f8f5..e69b144 100644
--- a/stdlib/public/core/Collection.swift
+++ b/stdlib/public/core/Collection.swift
@@ -174,9 +174,8 @@
/// print(s[i])
/// // Prints "t"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
///
/// - Parameters:
/// - i: A valid index of the collection.
@@ -197,9 +196,9 @@
/// unless that distance is beyond a given limiting index.
///
/// The following example obtains an index advanced four positions from a
- /// string's starting index and then prints the character at that position. The
- /// operation doesn't require going beyond the limiting `s.endIndex` value,
- /// so it succeeds.
+ /// string's starting index and then prints the character at that position.
+ /// The operation doesn't require going beyond the limiting `s.endIndex`
+ /// value, so it succeeds.
///
/// let s = "Swift"
/// if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
@@ -215,17 +214,17 @@
/// print(j)
/// // Prints "nil"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
///
/// - Parameters:
/// - i: A valid index of the collection.
/// - n: The distance to offset `i`. `n` must not be negative unless the
/// collection conforms to the `BidirectionalCollection` protocol.
/// - limit: A valid index of the collection to use as a limit. If `n > 0`,
- /// `limit` has no effect if it is less than `i`. Likewise, if `n < 0`,
- /// `limit` has no effect if it is greater than `i`.
+ /// a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+ /// limit that is greater than `i` has no effect.
/// - Returns: An index offset by `n` from the index `i`, unless that index
/// would be beyond `limit` in the direction of movement. In that case,
/// the method returns `nil`.
@@ -240,11 +239,10 @@
/// Offsets the given index by the specified distance.
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
///
- /// - Parameters
+ /// - Parameters:
/// - i: A valid index of the collection.
/// - n: The distance to offset `i`. `n` must not be negative unless the
/// collection conforms to the `BidirectionalCollection` protocol.
@@ -258,9 +256,9 @@
/// Offsets the given index by the specified distance, or so that it equals
/// the given limiting index.
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. Make
- /// sure the value passed as `n` does not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
///
/// - Parameters:
/// - i: A valid index of the collection.
@@ -645,8 +643,10 @@
/// Returns a subsequence from the start of the collection up to, but not
/// including, the specified position.
///
- /// The resulting subsequence *does not include* the element at the
- /// position `end`.
+ /// The resulting subsequence *does not include* the element at the position
+ /// `end`. The following example searches for the index of the number `40`
+ /// in an array of integers, and then prints the prefix of the array up to,
+ /// but not including, that index:
///
/// let numbers = [10, 20, 30, 40, 50, 60]
/// if let i = numbers.index(of: 40) {
@@ -671,7 +671,9 @@
/// Returns a subsequence from the specified position to the end of the
/// collection.
///
- /// For example:
+ /// The following example searches for the index of the number `40` in an
+ /// array of integers, and then prints the suffix of the array starting at
+ /// that index:
///
/// let numbers = [10, 20, 30, 40, 50, 60]
/// if let i = numbers.index(of: 40) {
@@ -695,7 +697,10 @@
/// Returns a subsequence from the start of the collection through the
/// specified position.
///
- /// The resulting subsequence *includes* the element at the position `end`.
+ /// The resulting subsequence *includes* the element at the position `end`.
+ /// The following example searches for the index of the number `40` in an
+ /// array of integers, and then prints the prefix of the array up to, and
+ /// including, that index:
///
/// let numbers = [10, 20, 30, 40, 50, 60]
/// if let i = numbers.index(of: 40) {
@@ -768,9 +773,8 @@
/// print(s[i])
/// // Prints "t"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. Make
- /// sure the value passed as `n` does not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
///
/// - Parameters:
/// - i: A valid index of the collection.
@@ -809,17 +813,17 @@
/// print(j)
/// // Prints "nil"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
///
/// - Parameters:
/// - i: A valid index of the collection.
/// - n: The distance to offset `i`. `n` must not be negative unless the
/// collection conforms to the `BidirectionalCollection` protocol.
/// - limit: A valid index of the collection to use as a limit. If `n > 0`,
- /// `limit` has no effect if it is less than `i`. Likewise, if `n < 0`,
- /// `limit` has no effect if it is greater than `i`.
+ /// a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+ /// limit that is greater than `i` has no effect.
/// - Returns: An index offset by `n` from the index `i`, unless that index
/// would be beyond `limit` in the direction of movement. In that case,
/// the method returns `nil`.
@@ -898,9 +902,8 @@
/// print(s[i])
/// // Prints "t"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
///
/// - Parameters:
/// - i: A valid index of the collection.
@@ -941,17 +944,17 @@
/// print(j)
/// // Prints "nil"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
///
/// - Parameters:
/// - i: A valid index of the collection.
/// - n: The distance to offset `i`. `n` must not be negative unless the
/// collection conforms to the `BidirectionalCollection` protocol.
/// - limit: A valid index of the collection to use as a limit. If `n > 0`,
- /// `limit` has no effect if it is less than `i`. Likewise, if `n < 0`,
- /// `limit` has no effect if it is greater than `i`.
+ /// a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+ /// limit that is greater than `i` has no effect.
/// - Returns: An index offset by `n` from the index `i`, unless that index
/// would be beyond `limit` in the direction of movement. In that case,
/// the method returns `nil`.
@@ -968,11 +971,10 @@
/// Offsets the given index by the specified distance.
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
///
- /// - Parameters
+ /// - Parameters:
/// - i: A valid index of the collection.
/// - n: The distance to offset `i`. `n` must not be negative unless the
/// collection conforms to the `BidirectionalCollection` protocol.
@@ -988,9 +990,9 @@
/// Offsets the given index by the specified distance, or so that it equals
/// the given limiting index.
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. Make
- /// sure the value passed as `n` does not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
///
/// - Parameters:
/// - i: A valid index of the collection.
@@ -1372,8 +1374,10 @@
/// Returns a subsequence from the start of the collection up to, but not
/// including, the specified position.
///
- /// The resulting subsequence *does not include* the element at the
- /// position `end`.
+ /// The resulting subsequence *does not include* the element at the position
+ /// `end`. The following example searches for the index of the number `40`
+ /// in an array of integers, and then prints the prefix of the array up to,
+ /// but not including, that index:
///
/// let numbers = [10, 20, 30, 40, 50, 60]
/// if let i = numbers.index(of: 40) {
@@ -1400,7 +1404,9 @@
/// Returns a subsequence from the specified position to the end of the
/// collection.
///
- /// For example:
+ /// The following example searches for the index of the number `40` in an
+ /// array of integers, and then prints the suffix of the array starting at
+ /// that index:
///
/// let numbers = [10, 20, 30, 40, 50, 60]
/// if let i = numbers.index(of: 40) {
@@ -1414,8 +1420,8 @@
/// print(numbers.suffix(from: numbers.endIndex))
/// // Prints "[]"
///
- /// - Parameter start: The index at which to start the resulting
- /// subsequence. `start` must be a valid index of the collection.
+ /// - Parameter start: The index at which to start the resulting subsequence.
+ /// `start` must be a valid index of the collection.
/// - Returns: A subsequence starting at the `start` position.
///
/// - Complexity: O(1)
@@ -1426,8 +1432,10 @@
/// Returns a subsequence from the start of the collection through the
/// specified position.
///
- /// The resulting subsequence *includes* the element at the position
- /// `end`.
+ /// The resulting subsequence *includes* the element at the position `end`.
+ /// The following example searches for the index of the number `40` in an
+ /// array of integers, and then prints the prefix of the array up to, and
+ /// including, that index:
///
/// let numbers = [10, 20, 30, 40, 50, 60]
/// if let i = numbers.index(of: 40) {
diff --git a/stdlib/public/core/CollectionAlgorithms.swift.gyb b/stdlib/public/core/CollectionAlgorithms.swift.gyb
index 2ad5fe4..3045ff5 100644
--- a/stdlib/public/core/CollectionAlgorithms.swift.gyb
+++ b/stdlib/public/core/CollectionAlgorithms.swift.gyb
@@ -127,9 +127,9 @@
/// hold:
///
/// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity)
- /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are both `true`,
- /// then `areInIncreasingOrder(a, c)` is also `true`. (Transitive
- /// comparability)
+ /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are
+ /// both `true`, then `areInIncreasingOrder(a, c)` is also `true`.
+ /// (Transitive comparability)
/// - Two elements are *incomparable* if neither is ordered before the other
/// according to the predicate. If `a` and `b` are incomparable, and `b`
/// and `c` are incomparable, then `a` and `c` are also incomparable.
diff --git a/stdlib/public/core/CollectionOfOne.swift b/stdlib/public/core/CollectionOfOne.swift
index 215fd33..5c458ad 100644
--- a/stdlib/public/core/CollectionOfOne.swift
+++ b/stdlib/public/core/CollectionOfOne.swift
@@ -39,7 +39,7 @@
public struct CollectionOfOne<Element>
: MutableCollection, RandomAccessCollection {
- /// Construct an instance containing just `element`.
+ /// Creates an instance containing just `element`.
public init(_ element: Element) {
self._element = element
}
@@ -81,7 +81,7 @@
return IteratorOverOne(_elements: _element)
}
- /// Access the element at `position`.
+ /// Accesses the element at `position`.
///
/// - Precondition: `position == 0`.
public subscript(position: Int) -> Element {
diff --git a/stdlib/public/core/CompilerProtocols.swift b/stdlib/public/core/CompilerProtocols.swift
index b3f75e7..e3f3102 100644
--- a/stdlib/public/core/CompilerProtocols.swift
+++ b/stdlib/public/core/CompilerProtocols.swift
@@ -569,7 +569,7 @@
associatedtype Key
/// The value type of a dictionary literal.
associatedtype Value
- /// Create an instance initialized with `elements`.
+ /// Creates an instance initialized with the given key-value pairs.
init(dictionaryLiteral elements: (Key, Value)...)
}
diff --git a/stdlib/public/core/ContiguousArrayBuffer.swift b/stdlib/public/core/ContiguousArrayBuffer.swift
index 22b3c21..5e1b2be 100644
--- a/stdlib/public/core/ContiguousArrayBuffer.swift
+++ b/stdlib/public/core/ContiguousArrayBuffer.swift
@@ -115,7 +115,7 @@
) rethrows {
if _isBridgedVerbatimToObjectiveC(Element.self) {
let count = __manager.header.count
- let elements = UnsafeMutableRawPointer(__manager._elementPointer)
+ let elements = UnsafeRawPointer(__manager._elementPointer)
.assumingMemoryBound(to: AnyObject.self)
defer { _fixLifetime(__manager) }
try body(UnsafeBufferPointer(start: elements, count: count))
@@ -288,7 +288,7 @@
_uncheckedUnsafeBufferObject: _emptyArrayStorage)
}
- public init(_ buffer: _ContiguousArrayBuffer, shiftedToStartIndex: Int) {
+ public init(_buffer buffer: _ContiguousArrayBuffer, shiftedToStartIndex: Int) {
_sanityCheck(shiftedToStartIndex == 0, "shiftedToStartIndex must be 0")
self = buffer
}
diff --git a/stdlib/public/core/EmptyCollection.swift b/stdlib/public/core/EmptyCollection.swift
index 648699e..c8999bf 100644
--- a/stdlib/public/core/EmptyCollection.swift
+++ b/stdlib/public/core/EmptyCollection.swift
@@ -21,7 +21,7 @@
///
/// - SeeAlso: `EmptyCollection<Element>`.
public struct EmptyIterator<Element> : IteratorProtocol, Sequence {
- /// Construct an instance.
+ /// Creates an instance.
public init() {}
/// Returns `nil`, indicating that there are no more elements.
@@ -42,7 +42,7 @@
public typealias IndexDistance = Int
public typealias SubSequence = EmptyCollection<Element>
- /// Construct an instance.
+ /// Creates an instance.
public init() {}
/// Always zero, just like `endIndex`.
@@ -57,7 +57,7 @@
/// Always traps.
///
- /// EmptyCollection does not have any element indices, so it is not
+ /// `EmptyCollection` does not have any element indices, so it is not
/// possible to advance indices.
public func index(after i: Index) -> Index {
_preconditionFailure("EmptyCollection can't advance indices")
@@ -65,22 +65,20 @@
/// Always traps.
///
- /// EmptyCollection does not have any element indices, so it is not
+ /// `EmptyCollection` does not have any element indices, so it is not
/// possible to advance indices.
public func index(before i: Index) -> Index {
_preconditionFailure("EmptyCollection can't advance indices")
}
/// Returns an empty iterator.
- ///
- /// - Complexity: O(1).
public func makeIterator() -> EmptyIterator<Element> {
return EmptyIterator()
}
- /// Access the element at `position`.
+ /// Accesses the element at the given position.
///
- /// Should never be called, since this collection is always empty.
+ /// Must never be called, since this collection is always empty.
public subscript(position: Index) -> Element {
get {
_preconditionFailure("Index out of range")
diff --git a/stdlib/public/core/Equatable.swift b/stdlib/public/core/Equatable.swift
index fb26955..980cecb 100644
--- a/stdlib/public/core/Equatable.swift
+++ b/stdlib/public/core/Equatable.swift
@@ -184,10 +184,54 @@
// Reference comparison
//===----------------------------------------------------------------------===//
-/// Returns `true` iff `lhs` and `rhs` are references to the same object
-/// instance (in other words, are identical pointers).
+/// Returns a Boolean value indicating whether two references point to the same
+/// object instance.
///
-/// - SeeAlso: `Equatable`, `==`
+/// This operator tests whether two instances have the same identity, not the
+/// same value. For value equality, see the equal-to operator (`==`) and the
+/// `Equatable` protocol.
+///
+/// The following example defines an `IntegerRef` type; an integer type with
+/// reference semantics.
+///
+/// class IntegerRef: Equatable {
+/// let value: Int
+/// init(_ value: Int) {
+/// self.value = value
+/// }
+/// }
+///
+/// func ==(lhs: IntegerRef, rhs: IntegerRef) -> Bool {
+/// return lhs.value == rhs.value
+/// }
+///
+/// Because `IntegerRef` is a class, its instances can be compared using the
+/// identical-to operator (`===`). In addition, because `IntegerRef` conforms
+/// to the `Equatable` protocol, instances can also be compared using the
+/// equal-to operator (`==`).
+///
+/// let a = IntegerRef(10)
+/// let b = a
+/// print(a == b)
+/// // Prints "true"
+/// print(a === b)
+/// // Prints "true"
+///
+/// The identical-to operator (`===`) returns `false` when comparing two
+/// references to different objects instances, even if the two instances have
+/// the same value.
+///
+/// let c = IntegerRef(10)
+/// print(a == c)
+/// // Prints "true"
+/// print(a === c)
+/// // Prints "false"
+///
+/// - Parameters:
+/// - lhs: A reference to compare.
+/// - rhs: Another reference to compare.
+///
+/// - SeeAlso: `Equatable`, `==`, `!==`
public func === (lhs: AnyObject?, rhs: AnyObject?) -> Bool {
switch (lhs, rhs) {
case let (l?, r?):
@@ -202,6 +246,18 @@
}
}
+/// Returns a Boolean value indicating whether two references point to
+/// different object instances.
+///
+/// This operator tests whether two instances have different identities, not
+/// different values. For value inequality, see the not-equal-to operator
+/// (`!=`) and the `Equatable` protocol.
+///
+/// - Parameters:
+/// - lhs: A reference to compare.
+/// - rhs: Another reference to compare.
+///
+/// - SeeAlso: `Equatable`, `===`, `!=`
public func !== (lhs: AnyObject?, rhs: AnyObject?) -> Bool {
return !(lhs === rhs)
}
diff --git a/stdlib/public/core/ExistentialCollection.swift.gyb b/stdlib/public/core/ExistentialCollection.swift.gyb
index e673d7b..9d67ef4 100644
--- a/stdlib/public/core/ExistentialCollection.swift.gyb
+++ b/stdlib/public/core/ExistentialCollection.swift.gyb
@@ -43,32 +43,47 @@
///
/// - SeeAlso: `AnySequence`
public struct AnyIterator<Element> : IteratorProtocol {
- /// Creates an iterator that wraps `base` but whose type depends only on the
- /// type of `I.Element`.
+ /// Creates an iterator that wraps a base iterator but whose type depends
+ /// only on the base iterator's element type.
///
- /// Example:
+ /// You can use `AnyIterator` to hide the type signature of a more complex
+ /// iterator. For example, the `digits()` function in the following example
+ /// creates an iterator over a collection that lazily maps the elements of a
+ /// `CountableRange<Int>` instance to strings. Instead of returning an
+ /// iterator with a type that encapsulates the implementation of the
+ /// collection, the `digits()` function first wraps the iterator in an
+ /// `AnyIterator` instance.
///
/// func digits() -> AnyIterator<String> {
- /// let lazyStrings = (0..<10).lazy.map { String($0) }
+ /// let lazyStrings = (0..<10).lazy.map { String($0) }
+ /// let iterator:
+ /// LazyMapIterator<IndexingIterator<CountableRange<Int>>, String>
+ /// = lazyStrings.makeIterator()
///
- /// // This is a really complicated type of no interest to our
- /// // clients.
- /// let iterator: MapSequenceIterator<RangeIterator<Int>, String>
- /// = lazyStrings.makeIterator()
- /// return AnyIterator(iterator)
+ /// return AnyIterator(iterator)
/// }
+ ///
+ /// - Parameter base: An iterator to type-erase.
public init<I : IteratorProtocol>(_ base: I) where I.Element == Element {
self._box = _IteratorBox(base)
}
- /// Creates an iterator whose `next` method invokes `body` and returns the
- /// result.
+ /// Creates an iterator that wraps the given closure in its `next()` method.
///
- /// Example:
+ /// The following example creates an iterator that counts up from the initial
+ /// value of an integer `x` to 15:
///
/// var x = 7
- /// let iterator = AnyIterator { x < 15 ? x++ : nil }
- /// let a = Array(iterator) // [ 7, 8, 9, 10, 11, 12, 13, 14 ]
+ /// let iterator: AnyIterator<Int> = AnyIterator {
+ /// defer { x += 1 }
+ /// return x < 15 ? x : nil
+ /// }
+ /// let a = Array(iterator)
+ /// // a == [7, 8, 9, 10, 11, 12, 13, 14]
+ ///
+ /// - Parameter body: A closure that returns an optional element. `body` is
+ /// executed each time the `next()` method is called on the resulting
+ /// iterator.
public init(_ body: @escaping () -> Element?) {
self._box = _IteratorBox(_ClosureBasedIterator(body))
}
@@ -527,9 +542,9 @@
/// A type-erased sequence.
///
-/// Forwards operations to an arbitrary underlying sequence having the
-/// same `Element` type, hiding the specifics of the underlying
-/// `Sequence`.
+/// An instance of `AnySequence` forwards its operations to an underlying base
+/// sequence having the same `Element` type, hiding the specifics of the
+/// underlying sequence.
///
/// - SeeAlso: `AnyIterator`
public struct AnySequence<Element> : Sequence {
@@ -565,8 +580,6 @@
% else:
/// Returns an iterator over the elements of this collection.
% end
- ///
- /// - Complexity: O(1).
public func makeIterator() -> AnyIterator<Element> {
return _box._makeIterator()
}
@@ -680,8 +693,7 @@
}
}
-/// A wrapper over an underlying index that hides
-/// the specific underlying type.
+/// A wrapper over an underlying index that hides the specific underlying type.
///
/// - SeeAlso: `AnyCollection`
public struct AnyIndex {
@@ -702,15 +714,27 @@
}
extension AnyIndex : Comparable {
- /// Returns `true` iff `lhs` and `rhs` wrap equal underlying indices.
+ /// Returns a Boolean value indicating whether two indices wrap equal
+ /// underlying indices.
///
- /// - Precondition: The types of indices wrapped by `lhs` and `rhs` are
- /// identical.
+ /// The types of the two underlying indices must be identical.
+ ///
+ /// - Parameters:
+ /// - lhs: An index to compare.
+ /// - rhs: Another index to compare.
public static func == (lhs: AnyIndex, rhs: AnyIndex) -> Bool {
_precondition(lhs._typeID == rhs._typeID, "base index types differ")
return lhs._box._isEqual(to: rhs._box)
}
+ /// Returns a Boolean value indicating whether the first argument represents a
+ /// position before the second argument.
+ ///
+ /// The types of the two underlying indices must be identical.
+ ///
+ /// - Parameters:
+ /// - lhs: An index to compare.
+ /// - rhs: Another index to compare.
public static func < (lhs: AnyIndex, rhs: AnyIndex) -> Bool {
_precondition(lhs._typeID == rhs._typeID, "base index types differ")
return lhs._box._isLess(than: rhs._box)
@@ -733,9 +757,9 @@
/// A type-erased wrapper over any collection with indices that
/// support ${Traversal.lower().replace('omacc', 'om acc')} traversal.
///
-/// Forwards operations to an arbitrary underlying collection having the
+/// An `${Self}` instance forwards its operations to a base collection having the
/// same `Element` type, hiding the specifics of the underlying
-/// `Collection`.
+/// collection.
///
/// - SeeAlso: ${', '.join('`Any%sCollection`' % t for t in (2 * TRAVERSALS)[ti + 1 : ti + 3]) }
public struct ${Self}<Element>
@@ -747,8 +771,9 @@
% for SubTraversal in TRAVERSALS[ti:]:
% SubProtocol = collectionForTraversal(SubTraversal)
- /// Creates an `${Self}` that
- /// stores `base` as its underlying collection.
+ /// Creates a type-erased collection that wraps the given collection.
+ ///
+ /// - Parameter base: The collection to wrap.
///
/// - Complexity: O(1).
public init<C : ${SubProtocol}>(_ base: C)
@@ -775,12 +800,9 @@
_base: base)
}
- /// Creates an `Any${Traversal}Collection` having the same underlying
- /// collection as `other`.
+ /// Creates an `${Self}` having the same underlying collection as `other`.
///
- /// - Postcondition: The result is `===` to `other`.
- ///
- /// - Complexity: O(1).
+ /// - Complexity: O(1)
public init(
_ other: Any${SubProtocol}<Element>
) {
@@ -789,12 +811,12 @@
% end
% for SuperTraversal in TRAVERSALS[:ti]:
- /// If the underlying collection stored by `other` satisfies
- /// `${SelfProtocol}`, creates an `${Self}` having the same
- /// underlying collection as `other`. Otherwise, the result is
- /// `nil`.
+ /// Creates an `${Self}` having the same underlying collection as `other`.
///
- /// - Complexity: O(1).
+ /// If the underlying collection stored by `other` does not satisfy
+ /// `${SelfProtocol}`, the result is `nil`.
+ ///
+ /// - Complexity: O(1)
public init?(
_ other: Any${collectionForTraversal(SuperTraversal)}<Element>
) {
@@ -906,7 +928,7 @@
/// The number of elements.
///
- /// - Complexity: ${'O(1)' if Traversal == 'RandomAccess' else 'O(N)'}.
+ /// - Complexity: ${'O(1)' if Traversal == 'RandomAccess' else 'O(N)'}
public var count: IntMax {
return _box._count
}
diff --git a/stdlib/public/core/Filter.swift.gyb b/stdlib/public/core/Filter.swift.gyb
index 5212bca..e7edb1a 100644
--- a/stdlib/public/core/Filter.swift.gyb
+++ b/stdlib/public/core/Filter.swift.gyb
@@ -12,7 +12,6 @@
%{
from gyb_stdlib_support import (
- TRAVERSALS,
collectionForTraversal,
sliceTypeName
)
@@ -187,7 +186,7 @@
public typealias IndexDistance = Base.IndexDistance
- /// Construct an instance containing the elements of `base` that
+ /// Creates an instance containing the elements of `base` that
/// satisfy `isIncluded`.
public // @testable
init(
@@ -256,7 +255,7 @@
}
% end
- /// Access the element at `position`.
+ /// Accesses the element at `position`.
///
/// - Precondition: `position` is a valid position in `self` and
/// `position != endIndex`.
diff --git a/stdlib/public/core/Flatten.swift.gyb b/stdlib/public/core/Flatten.swift.gyb
index bc30595..9bc5506 100644
--- a/stdlib/public/core/Flatten.swift.gyb
+++ b/stdlib/public/core/Flatten.swift.gyb
@@ -138,7 +138,8 @@
Elements.Iterator.Element == Iterator.Element,
Iterator.Element : Sequence {
- /// A concatenation of the elements of `self`.
+ /// Returns a lazy sequence that concatenates the elements of this sequence of
+ /// sequences.
public func joined() -> LazySequence<
FlattenSequence<Elements>
> {
@@ -328,7 +329,7 @@
}
% end
- /// Access the element at `position`.
+ /// Accesses the element at `position`.
///
/// - Precondition: `position` is a valid position in `self` and
/// `position != endIndex`.
diff --git a/stdlib/public/core/FloatingPointParsing.swift.gyb b/stdlib/public/core/FloatingPointParsing.swift.gyb
index 8c53115..e113b57 100644
--- a/stdlib/public/core/FloatingPointParsing.swift.gyb
+++ b/stdlib/public/core/FloatingPointParsing.swift.gyb
@@ -46,7 +46,7 @@
/// Creates a new instance from the given string.
///
/// The string passed as `text` can represent a real number in decimal or
- /// hexidecimal format or special floating-point values for infinty and NaN
+ /// hexadecimal format or special floating-point values for infinty and NaN
/// ("not a number").
///
/// The given string may begin with a plus or minus sign character (`+` or
@@ -71,17 +71,17 @@
/// let e = ${Self}("2837.5e-2")
/// // e == 28.375
///
- /// - A *hexidecimal value* contains the significand, either `0X` or `0x`,
- /// followed by a sequence of hexidecimal digits. The significand may
+ /// - A *hexadecimal value* contains the significand, either `0X` or `0x`,
+ /// followed by a sequence of hexadecimal digits. The significand may
/// include a decimal point.
///
/// let f = ${Self}("0x1c.6")
/// // f == 28.375
///
- /// A hexidecimal value may also include an exponent following the
+ /// A hexadecimal value may also include an exponent following the
/// significand, indicating the power of 2 by which the significand should
/// be multiplied. If included, the exponent is separated by a single
- /// character `p` or `P` and consists of an optional plus or minus sign
+ /// character, `p` or `P`, and consists of an optional plus or minus sign
/// character and a sequence of decimal digits.
///
/// let g = ${Self}("0x1.c6p4")
@@ -102,9 +102,9 @@
/// // n?.isNaN == true
/// // n?.sign == .minus
///
- /// An NaN value may also include a payload in parentheses following the
+ /// A NaN value may also include a payload in parentheses following the
/// `"nan"` keyword. The payload consists of a sequence of decimal digits,
- /// or the characters `0X` or `0x` followed by a sequence of hexidecimal
+ /// or the characters `0X` or `0x` followed by a sequence of hexadecimal
/// digits. If the payload contains any other characters, it is ignored.
/// If the value of the payload is larger than can be stored as the
/// payload of a `${Self}.nan`, the least significant bits are used.
diff --git a/stdlib/public/core/HashedCollections.swift.gyb b/stdlib/public/core/HashedCollections.swift.gyb
index 3818421..b7ebc61 100644
--- a/stdlib/public/core/HashedCollections.swift.gyb
+++ b/stdlib/public/core/HashedCollections.swift.gyb
@@ -520,7 +520,8 @@
/// Returns a Boolean value that indicates whether the given element exists
/// in the set.
///
- /// For example:
+ /// This example uses the `contains(_:)` method to test whether an integer is
+ /// a member of a set of prime numbers.
///
/// let primes: Set = [2, 3, 5, 7]
/// let x = 5
@@ -611,7 +612,7 @@
/// Removes the specified element from the set.
///
- /// For example:
+ /// This example removes the element `"sugar"` from a set of ingredients.
///
/// var ingredients: Set = ["cocoa beans", "sugar", "cocoa butter", "salt"]
/// let toRemove = "sugar"
@@ -871,7 +872,8 @@
/// Returns a Boolean value that indicates whether the set has no members in
/// common with the given sequence.
///
- /// For example:
+ /// In the following example, the `employees` set is disjoint with the
+ /// elements of the `visitors` array because no name appears in both.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let visitors = ["Marcia", "Nathaniel", "Olivia"]
@@ -891,7 +893,8 @@
/// Returns a new set with the elements of both this set and the given
/// sequence.
///
- /// For example:
+ /// In the following example, the `attendeesAndVisitors` set is made up
+ /// of the elements of the `attendees` set and the `visitors` array:
///
/// let attendees: Set = ["Alicia", "Bethany", "Diana"]
/// let visitors = ["Marcia", "Nathaniel"]
@@ -901,8 +904,7 @@
///
/// If the set already contains one or more elements that are also in
/// `other`, the existing members are kept. If `other` contains multiple
- /// instances of equivalent elements, only the first instance is kept. For
- /// example:
+ /// instances of equivalent elements, only the first instance is kept.
///
/// let initialIndices = Set(0..<5)
/// let expandedIndices = initialIndices.union([2, 3, 6, 6, 7, 7])
@@ -941,7 +943,8 @@
/// Returns a new set containing the elements of this set that do not occur
/// in the given sequence.
///
- /// For example:
+ /// In the following example, the `nonNeighbors` set is made up of the
+ /// elements of the `employees` set that are not elements of `neighbors`:
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -965,7 +968,9 @@
/// Removes the elements of the given sequence from the set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also elements of the `neighbors` array are removed. In particular, the
+ /// names `"Bethany"` and `"Eric"` are removed from `employees`.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -989,7 +994,10 @@
/// Returns a new set with the elements that are common to both this set and
/// the given sequence.
///
- /// For example:
+ /// In the following example, the `bothNeighborsAndEmployees` set is made up
+ /// of the elements that are in *both* the `employees` and `neighbors` sets.
+ /// Elements that are only in one or the other are left out of the result of
+ /// the intersection.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -1007,7 +1015,9 @@
/// Removes the elements of the set that aren't also in the given sequence.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// not also members of the `neighbors` set are removed. In particular, the
+ /// names `"Alicia"`, `"Chris"`, and `"Diana"` are removed.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -1037,7 +1047,10 @@
/// Returns a new set with the elements that are either in this set or in the
/// given sequence, but not in both.
///
- /// For example:
+ /// In the following example, the `eitherNeighborsOrEmployees` set is made up
+ /// of the elements of the `employees` and `neighbors` sets that are not in
+ /// both `employees` *and* `neighbors`. In particular, the names `"Bethany"`
+ /// and `"Eric"` do not appear in `eitherNeighborsOrEmployees`.
///
/// let employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
/// let neighbors = ["Bethany", "Eric", "Forlani"]
@@ -1057,7 +1070,12 @@
/// Replace this set with the elements contained in this set or the given
/// set, but not both.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also members of `neighbors` are removed from `employees`, while the
+ /// elements of `neighbors` that are not members of `employees` are added to
+ /// `employees`. In particular, the names `"Alicia"`, `"Chris"`, and
+ /// `"Diana"` are removed from `employees` while the name `"Forlani"` is
+ /// added.
///
/// var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
/// let neighbors = ["Bethany", "Eric", "Forlani"]
@@ -5066,10 +5084,12 @@
extension Set {
/// Removes the elements of the given set from this set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also members of the `neighbors` set are removed. In particular, the
+ /// names `"Bethany"` and `"Eric"` are removed from `employees`.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
- /// let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
+ /// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
/// employees.subtract(neighbors)
/// print(employees)
/// // Prints "["Diana", "Chris", "Alicia"]"
@@ -5079,19 +5099,19 @@
_subtract(other)
}
- /// Returns a Boolean value that indicates whether this set is a subset of the
- /// given set.
+ /// Returns a Boolean value that indicates whether this set is a subset of
+ /// the given set.
///
/// Set *A* is a subset of another set *B* if every member of *A* is also a
/// member of *B*.
///
- /// let employees = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
+ /// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let attendees: Set = ["Alicia", "Bethany", "Diana"]
/// print(attendees.isSubset(of: employees))
/// // Prints "true"
///
- /// - Parameter other: A sequence of elements. `possibleSuperset`
- /// must be finite.
+ /// - Parameter other: A sequence of elements. `possibleSuperset` must be
+ /// finite.
/// - Returns: `true` if the set is a subset of `possibleSuperset`;
/// otherwise, `false`.
public func isSubset(of other: Set<Element>) -> Bool {
@@ -5120,7 +5140,8 @@
/// Returns a Boolean value that indicates whether this set has no members in
/// common with the given set.
///
- /// For example:
+ /// In the following example, the `employees` set is disjoint with the
+ /// `visitors` set because no name appears in both sets.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
@@ -5142,7 +5163,8 @@
/// Returns a new set containing the elements of this set that do not occur
/// in the given set.
///
- /// For example:
+ /// In the following example, the `nonNeighbors` set is made up of the
+ /// elements of the `employees` set that are not elements of `neighbors`:
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -5203,7 +5225,10 @@
/// Returns a new set with the elements that are common to both this set and
/// the given sequence.
///
- /// For example:
+ /// In the following example, the `bothNeighborsAndEmployees` set is made up
+ /// of the elements that are in *both* the `employees` and `neighbors` sets.
+ /// Elements that are only in one or the other are left out of the result of
+ /// the intersection.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -5226,7 +5251,12 @@
/// Removes the elements of the set that are also in the given sequence and
/// adds the members of the sequence that are not already in the set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also members of `neighbors` are removed from `employees`, while the
+ /// elements of `neighbors` that are not members of `employees` are added to
+ /// `employees`. In particular, the names `"Alicia"`, `"Chris"`, and
+ /// `"Diana"` are removed from `employees` while the names `"Forlani"` and
+ /// `"Greta"` are added.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
diff --git a/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb b/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb
index 8844d49..18e3c0f 100644
--- a/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb
+++ b/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb
@@ -28,16 +28,6 @@
// properly expressed in the language.
extension Set {
@inline(__always)
- internal func _concreteElement_contains(_ member: Element) -> Bool {
- return contains(member)
- }
-
- @inline(__always)
- internal func _concreteElement_index(of member: Element) -> Index? {
- return index(of: member)
- }
-
- @inline(__always)
internal mutating func _concreteElement_insert(
_ newMember: Element
) -> (inserted: Bool, memberAfterInsert: Element) {
@@ -61,18 +51,6 @@
// FIXME(ABI)(compiler limitation): replace with `where Element == AnyHashable`.
extension Set where Element : _AnyHashableProtocol {
- public func contains<ConcreteElement : Hashable>(
- _ member: ConcreteElement
- ) -> Bool {
- return _concreteElement_contains(AnyHashable(member) as! Element)
- }
-
- public func index<ConcreteElement : Hashable>(
- of member: ConcreteElement
- ) -> SetIndex<Element>? {
- return _concreteElement_index(of: AnyHashable(member) as! Element)
- }
-
public mutating func insert<ConcreteElement : Hashable>(
_ newMember: ConcreteElement
) -> (inserted: Bool, memberAfterInsert: ConcreteElement) {
@@ -107,11 +85,6 @@
// FIXME: remove these trampolines when extensions below can be
// properly expressed in the language.
extension Dictionary {
- @inline(__always)
- internal func _concreteKey_index(forKey key: Key) -> Index? {
- return index(forKey: key)
- }
-
internal subscript(_concreteKey key: Key) -> Value? {
@inline(__always)
get {
@@ -138,12 +111,6 @@
// FIXME(ABI)(compiler limitation): replace with `where Element == AnyHashable`.
extension Dictionary where Key : _AnyHashableProtocol {
- public func index<ConcreteKey : Hashable>(forKey key: ConcreteKey)
- -> DictionaryIndex<Key, Value>?
- {
- return _concreteKey_index(forKey: AnyHashable(key) as! Key)
- }
-
public subscript(_ key: _Hashable) -> Value? {
// FIXME(ABI)(compiler limitation): replace this API with a
// generic subscript.
diff --git a/stdlib/public/core/InputStream.swift b/stdlib/public/core/InputStream.swift
index 0dc48b9..6a839eb 100644
--- a/stdlib/public/core/InputStream.swift
+++ b/stdlib/public/core/InputStream.swift
@@ -12,15 +12,20 @@
import SwiftShims
-/// Returns `Character`s read from standard input through the end of the
-/// current line or until EOF is reached, or `nil` if EOF has already been
-/// reached.
+/// Returns a string read from standard input through the end of the current
+/// line or until EOF is reached.
///
-/// If `strippingNewline` is `true`, newline characters and character
-/// combinations will be stripped from the result. This is the default.
+/// Standard input is interpreted as `UTF-8`. Invalid bytes are replaced by
+/// Unicode [replacement characters][rc].
///
-/// Standard input is interpreted as `UTF-8`. Invalid bytes
-/// will be replaced by Unicode [replacement characters](http://en.wikipedia.org/wiki/Specials_(Unicode_block)#Replacement_character).
+/// [rc]:
+/// http://en.wikipedia.org/wiki/Specials_(Unicode_block)#Replacement_character
+///
+/// - Parameter strippingNewline: If `true`, newline characters and character
+/// combinations are stripped from the result; otherwise, newline characters
+/// or character combinations are preserved. The default is `true`.
+/// - Returns: The string of characters read from standard input. If EOF has
+/// already been reached when `readLine()` is called, the result is `nil`.
public func readLine(strippingNewline: Bool = true) -> String? {
var linePtrVar: UnsafeMutablePointer<UInt8>? = nil
var readBytes = swift_stdlib_readLine_stdin(&linePtrVar)
diff --git a/stdlib/public/core/Integers.swift.gyb b/stdlib/public/core/Integers.swift.gyb
index 4b7aebd..4d4357e 100644
--- a/stdlib/public/core/Integers.swift.gyb
+++ b/stdlib/public/core/Integers.swift.gyb
@@ -230,6 +230,7 @@
public init?<T : FloatingPoint>(exactly source: T) {
// FIXME(integers): implement
fatalError()
+ return nil
}
public init<T : FloatingPoint>(_ source: T) {
diff --git a/stdlib/public/core/Join.swift b/stdlib/public/core/Join.swift
index d2bac36..f137972 100644
--- a/stdlib/public/core/Join.swift
+++ b/stdlib/public/core/Join.swift
@@ -18,7 +18,7 @@
}
/// An iterator that presents the elements of the sequences traversed
-/// by `Base`, concatenated using a given separator.
+/// by a base iterator, concatenated using a given separator.
public struct JoinedIterator<Base : IteratorProtocol> : IteratorProtocol
where Base.Element : Sequence {
@@ -86,7 +86,7 @@
internal var _state: _JoinIteratorState = .start
}
-/// A sequence that presents the elements of the `Base` sequences
+/// A sequence that presents the elements of a base sequence of sequences
/// concatenated using a given separator.
public struct JoinedSequence<Base : Sequence> : Sequence
where Base.Iterator.Element : Sequence {
diff --git a/stdlib/public/core/LazyCollection.swift.gyb b/stdlib/public/core/LazyCollection.swift.gyb
index be2a22e..e0166ff 100644
--- a/stdlib/public/core/LazyCollection.swift.gyb
+++ b/stdlib/public/core/LazyCollection.swift.gyb
@@ -51,10 +51,10 @@
/// - See also: `LazySequenceProtocol`, `LazyCollection`
public struct ${Self}<Base : ${TraversalCollection}> : LazyCollectionProtocol {
- /// The type of the underlying collection
+ /// The type of the underlying collection.
public typealias Elements = Base
- /// The underlying collection
+ /// The underlying collection.
public var elements: Elements { return _base }
/// A type that represents a valid position in the collection.
@@ -63,7 +63,7 @@
/// "past the end" position that's not valid for use as a subscript.
public typealias Index = Base.Index
- /// Construct an instance with `base` as its underlying Collection
+ /// Creates an instance with `base` as its underlying Collection
/// instance.
internal init(_base: Base) {
self._base = _base
@@ -134,7 +134,7 @@
return _base.index(after: i)
}
- /// Access the element at `position`.
+ /// Accesses the element at `position`.
///
/// - Precondition: `position` is a valid position in `self` and
/// `position != endIndex`.
@@ -150,7 +150,7 @@
return ${Slice}(base: _base, bounds: bounds).lazy
}
- /// Returns `true` iff `self` is empty.
+ /// A Boolean value indicating whether the collection is empty.
public var isEmpty: Bool {
return _base.isEmpty
}
diff --git a/stdlib/public/core/ManagedBuffer.swift b/stdlib/public/core/ManagedBuffer.swift
index 882f073..9dfd62d 100644
--- a/stdlib/public/core/ManagedBuffer.swift
+++ b/stdlib/public/core/ManagedBuffer.swift
@@ -450,28 +450,30 @@
// FIXME: when our calling convention changes to pass self at +0,
// inout should be dropped from the arguments to these functions.
-/// Returns `true` iff `object` is known to be a class instance with a single
-/// strong reference.
+/// Returns a Boolean value indicating whether the given object is a
+/// class instance known to have a single strong reference.
///
-/// * Does *not* modify `object`; the use of `inout` is an
-/// implementation artifact.
-/// * Weak references do not affect the result of this function.
-///
-/// Useful for implementing the copy-on-write optimization for the
-/// deep storage of value types:
+/// The `isKnownUniquelyReferenced(_:)` function is useful for implementating
+/// the copy-on-write optimization for the deep storage of value types:
///
/// mutating func modifyMe(_ arg: X) {
-/// if isKnownUniquelyReferenced(&myStorage) {
-/// myStorage.modifyInPlace(arg)
-/// }
-/// else {
-/// myStorage = self.createModified(myStorage, arg)
-/// }
+/// if isKnownUniquelyReferenced(&myStorage) {
+/// myStorage.modifyInPlace(arg)
+/// } else {
+/// myStorage = self.createModified(myStorage, arg)
+/// }
/// }
///
-/// This function is safe to use for `mutating` functions in
-/// multithreaded code because a false positive would imply that there
-/// is already a user-level data race on the value being mutated.
+/// Weak references do not affect the result of this function.
+///
+/// This function is safe to use for mutating functions in multithreaded code
+/// because a false positive implies that there is already a user-level data
+/// race on the value being mutated.
+///
+/// - Parameter object: An instance of a class. This function does *not* modify
+/// `object`; the use of `inout` is an implementation artifact.
+/// - Returns: `true` if `object` is a known to have a
+/// single strong reference; otherwise, `false`.
public func isKnownUniquelyReferenced<T : AnyObject>(_ object: inout T) -> Bool
{
return _isUnique(&object)
@@ -481,28 +483,31 @@
return _isUniqueOrPinned(&object)
}
-/// Returns `true` iff `object` is known to be a class instance with a single
-/// strong reference.
+/// Returns a Boolean value indicating whether the given object is a
+/// class instance known to have a single strong reference.
///
-/// * Does *not* modify `object`; the use of `inout` is an
-/// implementation artifact.
-/// * Weak references do not affect the result of this function.
-///
-/// Useful for implementing the copy-on-write optimization for the
-/// deep storage of value types:
+/// The `isKnownUniquelyReferenced(_:)` function is useful for implementating
+/// the copy-on-write optimization for the deep storage of value types:
///
/// mutating func modifyMe(_ arg: X) {
-/// if isKnownUniquelyReferenced(&myStorage) {
-/// myStorage.modifyInPlace(arg)
-/// }
-/// else {
-/// myStorage = self.createModified(myStorage, arg)
-/// }
+/// if isKnownUniquelyReferenced(&myStorage) {
+/// myStorage.modifyInPlace(arg)
+/// } else {
+/// myStorage = self.createModified(myStorage, arg)
+/// }
/// }
///
-/// This function is safe to use for `mutating` functions in
-/// multithreaded code because a false positive would imply that there
-/// is already a user-level data race on the value being mutated.
+/// Weak references do not affect the result of this function.
+///
+/// This function is safe to use for mutating functions in multithreaded code
+/// because a false positive implies that there is already a user-level data
+/// race on the value being mutated.
+///
+/// - Parameter object: An instance of a class. This function does *not* modify
+/// `object`; the use of `inout` is an implementation artifact.
+/// - Returns: `true` if `object` is a known to have a
+/// single strong reference; otherwise, `false`. If `object` is `nil`, the
+/// return value is `false`.
public func isKnownUniquelyReferenced<T : AnyObject>(
_ object: inout T?
) -> Bool {
diff --git a/stdlib/public/core/Map.swift.gyb b/stdlib/public/core/Map.swift.gyb
index 33117cd..5f10ad9 100644
--- a/stdlib/public/core/Map.swift.gyb
+++ b/stdlib/public/core/Map.swift.gyb
@@ -65,7 +65,7 @@
return _base.underestimatedCount
}
- /// Create an instance with elements `transform(x)` for each element
+ /// Creates an instance with elements `transform(x)` for each element
/// `x` of base.
internal init(_base: Base, transform: @escaping (Base.Iterator.Element) -> Element) {
self._base = _base
@@ -114,7 +114,7 @@
}
% end
- /// Access the element at `position`.
+ /// Accesses the element at `position`.
///
/// - Precondition: `position` is a valid position in `self` and
/// `position != endIndex`.
@@ -144,10 +144,10 @@
return _base.indices
}
- /// Returns `true` iff `self` is empty.
+ /// A Boolean value indicating whether the collection is empty.
public var isEmpty: Bool { return _base.isEmpty }
- /// Returns the number of elements.
+ /// The number of elements in the collection.
///
/// - Complexity: O(1) if `Index` conforms to `RandomAccessIndex`;
/// O(N) otherwise.
diff --git a/stdlib/public/core/MemoryLayout.swift b/stdlib/public/core/MemoryLayout.swift
index a3cb8af..a588c99 100644
--- a/stdlib/public/core/MemoryLayout.swift
+++ b/stdlib/public/core/MemoryLayout.swift
@@ -10,33 +10,32 @@
//
//===----------------------------------------------------------------------===//
-/// Accesses the memory layout of `T` through its
-/// `size`, `stride`, and `alignment` properties
+/// The memory layout of a type, describing its size, stride, and alignment.
public enum MemoryLayout<T> {
- /// Returns the contiguous memory footprint of `T`.
+ /// The contiguous memory footprint of the type.
///
- /// Does not include any dynamically-allocated or "remote"
- /// storage. In particular, `MemoryLayout<T>.size`, when
- /// `T` is a class type, is the same regardless of how many
- /// stored properties `T` has.
+ /// The `size` property for a type `T` does not include any
+ /// dynamically-allocated or "remote" storage. In particular,
+ /// `MemoryLayout<T>.size`, when `T` is a class type, is the same regardless
+ /// of how many stored properties `T` has.
@_transparent
public static var size: Int {
return Int(Builtin.sizeof(T.self))
}
- /// For instances of `T` in an `Array<T>`, returns the number of
- /// bytes from the start of one instance to the start of the
- /// next. This is the same as the number of bytes moved when an
- /// `UnsafePointer<T>` is incremented. `T` may have a lower minimal
- /// alignment that trades runtime performance for space
- /// efficiency. The result is always positive.
+ /// The number of bytes from the start of one instance to the start of the
+ /// next, when stored in a contiguous array.
+ ///
+ /// This is the same as the number of bytes moved when an `UnsafePointer<T>`
+ /// is incremented. The type may have a lower minimal alignment that trades
+ /// runtime performance for space efficiency. The result is always positive.
@_transparent
public static var stride: Int {
return Int(Builtin.strideof_nonzero(T.self))
}
- /// Returns the default memory alignment of `T`.
+ /// The default memory alignment of the type.
@_transparent
public static var alignment: Int {
return Int(Builtin.alignof(T.self))
diff --git a/stdlib/public/core/Mirror.swift b/stdlib/public/core/Mirror.swift
index da9a99d..ddce305 100644
--- a/stdlib/public/core/Mirror.swift
+++ b/stdlib/public/core/Mirror.swift
@@ -385,7 +385,7 @@
///
/// Do not declare new conformances to this protocol; they will not
/// work as expected.
-// FIXME(ABI): this protocol should be “non-open” and you shouldn't be able to
+// FIXME(ABI): this protocol should be "non-open" and you shouldn't be able to
// create conformances.
public protocol MirrorPath {}
extension IntMax : MirrorPath {}
@@ -596,7 +596,7 @@
//===--- QuickLooks -------------------------------------------------------===//
-/// The sum of types that can be used as a quick look representation.
+/// The sum of types that can be used as a Quick Look representation.
public enum PlaygroundQuickLook {
/// Plain text.
case text(String)
@@ -680,7 +680,7 @@
/// - Note: If the dynamic type of `subject` has value semantics,
/// subsequent mutations of `subject` will not observable in
/// `Mirror`. In general, though, the observability of such
- /// mutations is unspecified.
+ /// mutations is unspecified.
public init(reflecting subject: Any) {
if let customized = subject as? CustomPlaygroundQuickLookable {
self = customized.customPlaygroundQuickLook
@@ -699,15 +699,15 @@
}
}
-/// A type that explicitly supplies its own PlaygroundQuickLook.
+/// A type that explicitly supplies its own playground Quick Look.
///
-/// Instances of any type can be `PlaygroundQuickLook(reflect:)`'ed
-/// upon, but if you are not satisfied with the `PlaygroundQuickLook`
-/// supplied for your type by default, you can make it conform to
-/// `CustomPlaygroundQuickLookable` and return a custom
-/// `PlaygroundQuickLook`.
+/// A Quick Look can be created for an instance of any type by using the
+/// `PlaygroundQuickLook(reflecting:)` initializer. If you are not satisfied
+/// with the representation supplied for your type by default, you can make it
+/// conform to the `CustomPlaygroundQuickLookable` protocol and provide a
+/// custom `PlaygroundQuickLook` instance.
public protocol CustomPlaygroundQuickLookable {
- /// A custom playground quick look for this instance.
+ /// A custom playground Quick Look for this instance.
///
/// If this type has value semantics, the `PlaygroundQuickLook` instance
/// should be unaffected by subsequent mutations.
diff --git a/stdlib/public/core/OptionSet.swift b/stdlib/public/core/OptionSet.swift
index cdfb9e5..b5c4aad 100644
--- a/stdlib/public/core/OptionSet.swift
+++ b/stdlib/public/core/OptionSet.swift
@@ -214,10 +214,12 @@
return self.isSuperset(of: member)
}
- /// Inserts the given element into the option set if it is not already a
- /// member.
+ /// Adds the given element to the option set if it is not already a member.
///
- /// For example:
+ /// In the following example, the `.secondDay` shipping option is added to
+ /// the `freeOptions` option set if `purchasePrice` is greating than 50. For
+ /// the `ShippingOptions` declaration, see the `OptionSet` protocol
+ /// discussion.
///
/// let purchasePrice = 87.55
///
@@ -249,7 +251,10 @@
/// Removes the given element and all elements subsumed by the given element.
///
- /// For example:
+ /// In the following example, the `.priority` shipping option is removed from
+ /// the `options` option set. Attempting to remove the same shipping option
+ /// a second time results in `nil`, because `options` no longer contains
+ /// `.priority` as a member.
///
/// var options: ShippingOptions = [.secondDay, .priority]
/// let priorityOption = options.remove(.priority)
@@ -259,11 +264,11 @@
/// print(options.remove(.priority))
/// // Prints "nil"
///
- /// In the following example, the `.express` element is passed to
- /// `remove(_:)`. Although `.express` is not a member of `options`,
- /// `.express` subsumes the remaining `.secondDay` element of the option
- /// set. Therefore, `options` is emptied and the intersection between
- /// `.express` and `options` is returned.
+ /// In the next example, the `.express` element is passed to `remove(_:)`.
+ /// Although `.express` is not a member of `options`, `.express` subsumes
+ /// the remaining `.secondDay` element of the option set. Therefore,
+ /// `options` is emptied and the intersection between `.express` and
+ /// `options` is returned.
///
/// let expressOption = options.remove(.express)
/// print(expressOption == .express)
diff --git a/stdlib/public/core/OutputStream.swift b/stdlib/public/core/OutputStream.swift
index 99be36b..f49c0a1 100644
--- a/stdlib/public/core/OutputStream.swift
+++ b/stdlib/public/core/OutputStream.swift
@@ -20,23 +20,24 @@
///
/// You can send the output of the standard library's `print(_:to:)` and
/// `dump(_:to:)` functions to an instance of a type that conforms to the
-/// `TextOutputStream` protocol instead of to standard output. Swift's `String`
-/// type conforms to `TextOutputStream` already, so you can capture the output
-/// from `print(_:to:)` and `dump(_:to:)` in a string instead of logging it to
-/// standard output.
+/// `TextOutputStream` protocol instead of to standard output. Swift's
+/// `String` type conforms to `TextOutputStream` already, so you can capture
+/// the output from `print(_:to:)` and `dump(_:to:)` in a string instead of
+/// logging it to standard output.
///
/// var s = ""
-/// for n in 1 ... 5 {
+/// for n in 1...5 {
/// print(n, terminator: "", to: &s)
/// }
/// // s == "12345"
///
/// Conforming to the TextOutputStream Protocol
-/// =======================================
+/// ===========================================
///
-/// To make your custom type conform to the `TextOutputStream` protocol, implement
-/// the required `write(_:)` method. Functions that use an `TextOutputStream`
-/// target may call `write(_:)` multiple times per writing operation.
+/// To make your custom type conform to the `TextOutputStream` protocol,
+/// implement the required `write(_:)` method. Functions that use a
+/// `TextOutputStream` target may call `write(_:)` multiple times per writing
+/// operation.
///
/// As an example, here's an implementation of an output stream that converts
/// any input to its plain ASCII representation before sending it to standard
@@ -101,10 +102,11 @@
///
/// Types that conform to the `CustomStringConvertible` protocol can provide
/// their own representation to be used when converting an instance to a
-/// string. The `String(_:)` initializer is the preferred way to convert an
-/// instance of *any* type to a string. If the passed instance conforms to
-/// `CustomStringConvertible`, the `String(_:)` initializer and the
-/// `print(_:)` function use the instance's custom `description` property.
+/// string. The `String(describing:)` initializer is the preferred way to
+/// convert an instance of *any* type to a string. If the passed instance
+/// conforms to `CustomStringConvertible`, the `String(describing:)`
+/// initializer and the `print(_:)` function use the instance's custom
+/// `description` property.
///
/// Accessing a type's `description` property directly or using
/// `CustomStringConvertible` as a generic constraint is discouraged.
@@ -144,7 +146,8 @@
/// A textual representation of this instance.
///
/// Instead of accessing this property directly, convert an instance of any
- /// type to a string by using the `String(_:)` initializer. For example:
+ /// type to a string by using the `String(describing:)` initializer. For
+ /// example:
///
/// struct Point: CustomStringConvertible {
/// let x: Int, y: Int
@@ -155,7 +158,7 @@
/// }
///
/// let p = Point(x: 21, y: 30)
- /// let s = String(p)
+ /// let s = String(describing: p)
/// print(s)
/// // Prints "(21, 30)"
///
diff --git a/stdlib/public/core/Pointer.swift b/stdlib/public/core/Pointer.swift
index 44cabb1..c1e2ac0 100644
--- a/stdlib/public/core/Pointer.swift
+++ b/stdlib/public/core/Pointer.swift
@@ -17,7 +17,7 @@
/// The underlying raw pointer value.
var _rawValue: Builtin.RawPointer { get }
- /// Construct a pointer from a raw value.
+ /// Creates a pointer from a raw value.
init(_ _rawValue: Builtin.RawPointer)
}
diff --git a/stdlib/public/core/Policy.swift b/stdlib/public/core/Policy.swift
index 1f99a49..78e5630 100644
--- a/stdlib/public/core/Policy.swift
+++ b/stdlib/public/core/Policy.swift
@@ -25,7 +25,6 @@
/// func crashAndBurn() -> Never {
/// fatalError("Something very, very bad happened")
/// }
-
@_fixed_layout
public enum Never {}
@@ -138,11 +137,11 @@
/// that bridges to an Objective-C class. Many value types in Swift bridge to
/// Objective-C counterparts, like `String` and `Int`.
///
-/// let s: AnyObject = "This is a bridged string."
+/// let s: AnyObject = "This is a bridged string." as NSString
/// print(s is NSString)
/// // Prints "true"
///
-/// let v: AnyObject = 100
+/// let v: AnyObject = 100 as NSNumber
/// print(type(of: v))
/// // Prints "__NSCFNumber"
///
@@ -158,34 +157,30 @@
/// type and can be cast to that type using one of the type-cast operators
/// (`as`, `as?`, or `as!`).
///
-/// In the code samples that follow, the elements of the `NSArray` instance
-/// `numberObjects` have `AnyObject` as their type. The first example uses the
-/// conditional downcast operator (`as?`) to conditionally cast the first
-/// object in the `numberObjects` array to an instance of Swift's `String`
-/// type.
+/// This example uses the conditional downcast operator (`as?`) to
+/// conditionally cast the `s` constant declared above to an instance of
+/// Swift's `String` type.
///
-/// let numberObjects: NSArray = ["one", "two", 3, 4]
-///
-/// let first: AnyObject = numberObjects[0]
-/// if let first = first as? String {
-/// print("The first object, '\(first)', is a String")
+/// if let message = s as? String {
+/// print("Succesful cast to String: \(message)")
/// }
-/// // Prints("The first object, 'one', is a String")
+/// // Prints "Succesful cast to String: This is a bridged string."
///
/// If you have prior knowledge that an `AnyObject` instance has a particular
/// type, you can use the unconditional downcast operator (`as!`). Performing
/// an invalid cast triggers a runtime error.
///
-/// let second = numberObjects.object(at: 1) as! String
-/// print("'\(second)' is also a String")
-/// // Prints "'two' is also a String"
+/// let message = s as! String
+/// print("Succesful cast to String: \(message)")
+/// // Prints "Succesful cast to String: This is a bridged string."
///
-/// let badCase = numberObjects.object(at: 2) as! NSDate
+/// let badCase = v as! String
/// // Runtime error
///
/// Casting is always safe in the context of a `switch` statement.
///
-/// for object in numberObjects {
+/// let mixedArray: [AnyObject] = [s, v]
+/// for object in mixedArray {
/// switch object {
/// case let x as String:
/// print("'\(x)' is a String")
@@ -193,25 +188,8 @@
/// print("'\(object)' is not a String")
/// }
/// }
-/// // Prints "'one' is a String"
-/// // Prints "'two' is a String"
-/// // Prints "'3' is not a String"
-/// // Prints "'4' is not a String"
-///
-/// You can call a method that takes an `AnyObject` parameter with an instance
-/// of any class, `@objc` protocol, or type that bridges to Objective-C. In
-/// the following example, the `toFind` constant is of type `Int`, which
-/// bridges to `NSNumber` when passed to an `NSArray` method that expects an
-/// `AnyObject` parameter:
-///
-/// let toFind = 3
-/// let i = numberObjects.index(of: toFind)
-/// if i != NSNotFound {
-/// print("Found '\(numberObjects[i])' at index \(i)")
-/// } else {
-/// print("Couldn't find \(toFind)")
-/// }
-/// // Prints "Found '3' at index 2"
+/// // Prints "'This is a bridged string.' is a String"
+/// // Prints "'100' is not a String"
///
/// Accessing Objective-C Methods and Properties
/// ============================================
@@ -225,7 +203,7 @@
/// properties, respectively.
///
/// This example defines an `IntegerRef` type with an `@objc` method named
-/// `getIntegerValue`.
+/// `getIntegerValue()`.
///
/// class IntegerRef {
/// let value: Int
@@ -242,35 +220,36 @@
/// return IntegerRef(100)
/// }
///
-/// let x: AnyObject = getObject()
+/// let obj: AnyObject = getObject()
///
-/// In the example, `x` has a static type of `AnyObject` and a dynamic type of
-/// `IntegerRef`. You can use optional chaining to call the `@objc` method
-/// `getIntegerValue()` on `x` safely. If you're sure of the dynamic type of
-/// `x`, you can call `getIntegerValue()` directly.
+/// In the example, `obj` has a static type of `AnyObject` and a dynamic type
+/// of `IntegerRef`. You can use optional chaining to call the `@objc` method
+/// `getIntegerValue()` on `obj` safely. If you're sure of the dynamic type of
+/// `obj`, you can call `getIntegerValue()` directly.
///
-/// let possibleValue = x.getIntegerValue?()
+/// let possibleValue = obj.getIntegerValue?()
/// print(possibleValue)
/// // Prints "Optional(100)"
///
-/// let certainValue = x.getIntegerValue()
+/// let certainValue = obj.getIntegerValue()
/// print(certainValue)
/// // Prints "100"
///
-/// If the dynamic type of `x` doesn't implement a `getIntegerValue()` method,
-/// the system returns a runtime error when you initialize `certainValue`.
+/// If the dynamic type of `obj` doesn't implement a `getIntegerValue()`
+/// method, the system returns a runtime error when you initialize
+/// `certainValue`.
///
-/// Alternatively, if you need to test whether `x.getValue()` exists, use
-/// optional binding before calling the method.
+/// Alternatively, if you need to test whether `obj.getIntegerValue()` exists,
+/// use optional binding before calling the method.
///
-/// if let f = x.getIntegerValue {
-/// print("The value of 'x' is \(f())")
+/// if let f = obj.getIntegerValue {
+/// print("The value of 'obj' is \(f())")
/// } else {
-/// print("'x' does not have a 'getIntegerValue()' method")
+/// print("'obj' does not have a 'getIntegerValue()' method")
/// }
-/// // Prints "The value of 'x' is 100"
+/// // Prints "The value of 'obj' is 100"
///
-/// - SeeAlso: `AnyClass`, `Any`
+/// - SeeAlso: `AnyClass`
@objc
public protocol AnyObject : class {}
#else
@@ -316,7 +295,7 @@
/// print(getDefaultValue(NSString.self))
/// // Prints "nil"
///
-/// - SeeAlso: `AnyObject`, `Any`
+/// - SeeAlso: `AnyObject`
public typealias AnyClass = AnyObject.Type
/// A type that supports standard bitwise arithmetic operators.
diff --git a/stdlib/public/core/Print.swift b/stdlib/public/core/Print.swift
index 620ae84..d5cb76a 100644
--- a/stdlib/public/core/Print.swift
+++ b/stdlib/public/core/Print.swift
@@ -10,17 +10,48 @@
//
//===----------------------------------------------------------------------===//
-/// Writes the textual representations of `items`, separated by
-/// `separator` and terminated by `terminator`, into the standard
+/// Writes the textual representations of the given items into the standard
/// output.
///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(item)`.
+/// You can pass zero or more items to the `print(_:separator:terminator:)`
+/// function. The textual representation for each item is the same as that
+/// obtained by calling `String(item)`. The following example prints a string,
+/// a closed range of integers, and a group of floating-point values to
+/// standard output:
///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+/// print("One two three four five")
+/// // Prints "One two three four five"
///
-/// - SeeAlso: `debugPrint`, `Streamable`, `CustomStringConvertible`,
-/// `CustomDebugStringConvertible`
+/// print(1...5)
+/// // Prints "1...5"
+///
+/// print(1.0, 2.0, 3.0, 4.0, 5.0)
+/// // Prints "1.0 2.0 3.0 4.0 5.0"
+///
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+/// print(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ")
+/// // Prints "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0"
+///
+/// The output from each call to `print(_:separator:terminator:)` includes a
+/// newline by default. To print the items without a trailing newline, pass an
+/// empty string as `terminator`.
+///
+/// for n in 1...5 {
+/// print(n, terminator: "")
+/// }
+/// // Prints "12345"
+///
+/// - Parameters:
+/// - items: Zero or more items to print.
+/// - separator: A string to print between each item. The default is a single
+/// space (`" "`).
+/// - terminator: The string to print after all items have been printed. The
+/// default is a newline (`"\n"`).
+///
+/// - SeeAlso: `debugPrint(_:separator:terminator:)`, `Streamable`,
+/// `CustomStringConvertible`, `CustomDebugStringConvertible`
@inline(never)
@_semantics("stdlib_binary_only")
public func print(
@@ -41,17 +72,49 @@
}
}
-/// Writes the textual representations of `items` most suitable for
-/// debugging, separated by `separator` and terminated by
-/// `terminator`, into the standard output.
+/// Writes the textual representations of the given items most suitable for
+/// debugging into the standard output.
///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(reflecting: item)`.
+/// You can pass zero or more items to the
+/// `debugPrint(_:separator:terminator:)` function. The textual representation
+/// for each item is the same as that obtained by calling
+/// `String(reflecting: item)`. The following example prints the debugging
+/// representation of a string, a closed range of integers, and a group of
+/// floating-point values to standard output:
///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+/// debugPrint("One two three four five")
+/// // Prints "One two three four five"
///
-/// - SeeAlso: `print`, `Streamable`, `CustomStringConvertible`,
-/// `CustomDebugStringConvertible`
+/// debugPrint(1...5)
+/// // Prints "CountableClosedRange(1...5)"
+///
+/// debugPrint(1.0, 2.0, 3.0, 4.0, 5.0)
+/// // Prints "1.0 2.0 3.0 4.0 5.0"
+///
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+/// debugPrint(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ")
+/// // Prints "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0"
+///
+/// The output from each call to `debugPrint(_:separator:terminator:)` includes
+/// a newline by default. To print the items without a trailing newline, pass
+/// an empty string as `terminator`.
+///
+/// for n in 1...5 {
+/// debugPrint(n, terminator: "")
+/// }
+/// // Prints "12345"
+///
+/// - Parameters:
+/// - items: Zero or more items to print.
+/// - separator: A string to print between each item. The default is a single
+/// space (`" "`).
+/// - terminator: The string to print after all items have been printed. The
+/// default is a newline (`"\n"`).
+///
+/// - SeeAlso: `print(_:separator:terminator:)`, `Streamable`,
+/// `CustomStringConvertible`, `CustomDebugStringConvertible`
@inline(never)
@_semantics("stdlib_binary_only")
public func debugPrint(
@@ -71,16 +134,47 @@
}
}
-/// Writes the textual representations of `items`, separated by
-/// `separator` and terminated by `terminator`, into `output`.
+/// Writes the textual representations of the given items into the given output
+/// stream.
///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(item)`.
+/// You can pass zero or more items to the `print(_:separator:terminator:to:)`
+/// function. The textual representation for each item is the same as that
+/// obtained by calling `String(item)`. The following example prints a closed
+/// range of integers to a string:
///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+/// var range = "My range: "
+/// print(1...5, to: &range)
+/// // range == "My range: 1...5\n"
///
-/// - SeeAlso: `debugPrint`, `Streamable`, `CustomStringConvertible`,
-/// `CustomDebugStringConvertible`
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+/// var separated = ""
+/// print(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ", to: &separated)
+/// // separated == "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0\n"
+///
+/// The output from each call to `print(_:separator:terminator:to:)` includes a
+/// newline by default. To print the items without a trailing newline, pass an
+/// empty string as `terminator`.
+///
+/// var numbers = ""
+/// for n in 1...5 {
+/// print(n, terminator: "", to: &numbers)
+/// }
+/// // numbers == "12345"
+///
+/// - Parameters:
+/// - items: Zero or more items to print.
+/// - separator: A string to print between each item. The default is a single
+/// space (`" "`).
+/// - terminator: The string to print after all items have been printed. The
+/// default is a newline (`"\n"`).
+/// - output: An output stream to receive the text representation of each
+/// item.
+///
+/// - SeeAlso: `print(_:separator:terminator:)`,
+/// `debugPrint(_:separator:terminator:to:)`, `TextOutputStream`,
+/// `Streamable`, `CustomStringConvertible`, `CustomDebugStringConvertible`
@inline(__always)
public func print<Target : TextOutputStream>(
_ items: Any...,
@@ -91,17 +185,48 @@
_print(items, separator: separator, terminator: terminator, to: &output)
}
-/// Writes the textual representations of `items` most suitable for
-/// debugging, separated by `separator` and terminated by
-/// `terminator`, into `output`.
+/// Writes the textual representations of the given items most suitable for
+/// debugging into the given output stream.
///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(reflecting: item)`.
+/// You can pass zero or more items to the
+/// `debugPrint(_:separator:terminator:to:)` function. The textual
+/// representation for each item is the same as that obtained by calling
+/// `String(reflecting: item)`. The following example prints a closed range of
+/// integers to a string:
///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+/// var range = "My range: "
+/// debugPrint(1...5, to: &range)
+/// // range == "My range: CountableClosedRange(1...5)\n"
///
-/// - SeeAlso: `print`, `Streamable`, `CustomStringConvertible`,
-/// `CustomDebugStringConvertible`
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+/// var separated = ""
+/// debugPrint(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ", to: &separated)
+/// // separated == "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0\n"
+///
+/// The output from each call to `debugPrint(_:separator:terminator:to:)`
+/// includes a newline by default. To print the items without a trailing
+/// newline, pass an empty string as `terminator`.
+///
+/// var numbers = ""
+/// for n in 1...5 {
+/// debugPrint(n, terminator: "", to: &numbers)
+/// }
+/// // numbers == "12345"
+///
+/// - Parameters:
+/// - items: Zero or more items to print.
+/// - separator: A string to print between each item. The default is a single
+/// space (`" "`).
+/// - terminator: The string to print after all items have been printed. The
+/// default is a newline (`"\n"`).
+/// - output: An output stream to receive the text representation of each
+/// item.
+///
+/// - SeeAlso: `debugPrint(_:separator:terminator:)`,
+/// `print(_:separator:terminator:to:)`, `TextOutputStream`, `Streamable`,
+/// `CustomStringConvertible`, `CustomDebugStringConvertible`
@inline(__always)
public func debugPrint<Target : TextOutputStream>(
_ items: Any...,
diff --git a/stdlib/public/core/RandomAccessCollection.swift b/stdlib/public/core/RandomAccessCollection.swift
index 8553822..609bbc2 100644
--- a/stdlib/public/core/RandomAccessCollection.swift
+++ b/stdlib/public/core/RandomAccessCollection.swift
@@ -125,9 +125,9 @@
/// print(j)
/// // Prints "nil"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
///
/// - Parameters:
/// - i: A valid index of the array.
@@ -211,9 +211,8 @@
/// print(numbers[i])
/// // Prints "50"
///
- /// Advancing an index beyond a collection's ending index or offsetting it
- /// before a collection's starting index may trigger a runtime error. The
- /// value passed as `n` must not result in such an operation.
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
///
/// - Parameters:
/// - i: A valid index of the collection.
diff --git a/stdlib/public/core/Range.swift.gyb b/stdlib/public/core/Range.swift.gyb
index 3fd47fb..b7ff5f9 100644
--- a/stdlib/public/core/Range.swift.gyb
+++ b/stdlib/public/core/Range.swift.gyb
@@ -420,12 +420,28 @@
/// Returns a Boolean value indicating whether this range and the given range
/// contain an element in common.
///
- /// For example:
+ /// This example shows two overlapping ranges:
///
/// let x: ${Self} = 0${op}20
/// print(x.overlaps(10${other_op}1000 as ${OtherSelf}))
/// // Prints "true"
///
+% if 'Closed' in Self:
+ /// Because a closed range includes its upper bound, the ranges in the
+ /// following example also overlap:
+ ///
+ /// let y: ${OtherSelf} = 20${op}30
+ /// print(x.overlaps(y))
+ /// // Prints "true"
+% else:
+ /// Because a half-open range does not include its upper bound, the ranges
+ /// in the following example do not overlap:
+ ///
+ /// let y: ${OtherSelf} = 20${op}30
+ /// print(x.overlaps(y))
+ /// // Prints "false"
+% end
+ ///
/// - Parameter other: A range to check for elements in common.
/// - Returns: `true` if this range and `other` have at least one element in
/// common; otherwise, `false`.
@@ -543,7 +559,9 @@
/// Returns a half-open range that contains its lower bound but not its upper
/// bound.
///
-/// For example:
+/// 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
/// print(lessThanFive.contains(3.14)) // Prints "true"
@@ -563,12 +581,21 @@
/// Returns a countable half-open range that contains its lower bound but not
/// its upper bound.
///
-/// For example:
+/// Use the half-open range operator (`..<`) to create a range of any type that
+/// conforms to the `Strideable` protocol with an associated integer `Stride`
+/// type, such as any of the standard library's integer types. This example
+/// creates a `CountableRange<Int>` from zero up to, but not including, 5.
///
/// let upToFive = 0..<5
/// print(upToFive.contains(3)) // Prints "true"
/// print(upToFive.contains(5)) // Prints "false"
///
+/// You can use sequence or collection methods on the `upToFive` countable
+/// range.
+///
+/// print(upToFive.count) // Prints "5"
+/// print(upToFive.last) // Prints "4"
+///
/// - Parameters:
/// - minimum: The lower bound for the range.
/// - maximum: The upper bound for the range.
diff --git a/stdlib/public/core/RangeReplaceableCollection.swift.gyb b/stdlib/public/core/RangeReplaceableCollection.swift.gyb
index 42cc1d7..a5ac802 100644
--- a/stdlib/public/core/RangeReplaceableCollection.swift.gyb
+++ b/stdlib/public/core/RangeReplaceableCollection.swift.gyb
@@ -346,7 +346,9 @@
/// Adds an element to the end of the collection.
///
- /// For example:
+ /// If the collection does not have sufficient capacity for another element,
+ /// additional storage is allocated before appending `newElement`. The
+ /// following example adds a new number to an array of integers:
///
/// var numbers = [1, 2, 3, 4, 5]
/// numbers.append(100)
@@ -372,9 +374,12 @@
/// Adds the elements of a sequence to the end of the collection.
///
- /// Use this method to append the elements of a sequence to the end of a
- /// collection. This example appends the elements of a `Range<Int>` instance
- /// to an array of integers.
+ /// Use this method to append the elements of a sequence or collection to the
+ /// end of this collection. The collection being appended to allocates any
+ /// additional necessary storage to hold the new elements.
+ ///
+ /// The following example appends the elements of a `Range<Int>` instance to
+ /// an array of integers:
///
/// var numbers = [1, 2, 3, 4, 5]
/// numbers.append(contentsOf: 10...15)
@@ -383,7 +388,8 @@
///
/// - Parameter newElements: The elements to append to the collection.
///
- /// - Complexity: O(*n*), where *n* is the length of the resulting collection.
+ /// - Complexity: O(*n*), where *n* is the length of the resulting
+ /// collection.
mutating func append<S : Sequence>(contentsOf newElements: S)
where S.Iterator.Element == Iterator.Element
@@ -565,7 +571,9 @@
/// Adds an element to the end of the collection.
///
- /// For example:
+ /// If the collection does not have sufficient capacity for another element,
+ /// additional storage is allocated before appending `newElement`. The
+ /// following example adds a new number to an array of integers:
///
/// var numbers = [1, 2, 3, 4, 5]
/// numbers.append(100)
@@ -583,9 +591,12 @@
/// Adds the elements of a sequence to the end of the collection.
///
- /// Use this method to append the elements of a sequence to the end of a
- /// collection. This example appends the elements of a `Range<Int>` instance
- /// to an array of integers.
+ /// Use this method to append the elements of a sequence or collection to the
+ /// end of this collection. The collection being appended to allocates any
+ /// additional necessary storage to hold the new elements.
+ ///
+ /// The following example appends the elements of a `Range<Int>` instance to
+ /// an array of integers:
///
/// var numbers = [1, 2, 3, 4, 5]
/// numbers.append(contentsOf: 10...15)
@@ -594,7 +605,8 @@
///
/// - Parameter newElements: The elements to append to the collection.
///
- /// - Complexity: O(*n*), where *n* is the length of the resulting collection.
+ /// - Complexity: O(*n*), where *n* is the length of the resulting
+ /// collection.
public mutating func append<S : Sequence>(contentsOf newElements: S)
where S.Iterator.Element == Iterator.Element {
diff --git a/stdlib/public/core/Reflection.swift b/stdlib/public/core/Reflection.swift
index db55b97..ea78719 100644
--- a/stdlib/public/core/Reflection.swift
+++ b/stdlib/public/core/Reflection.swift
@@ -18,30 +18,59 @@
internal let _value: Builtin.RawPointer
// FIXME: Better hashing algorithm
- /// The hash value.
+ /// The identifier's hash value.
///
- /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
+ /// The hash value is not guaranteed to be stable across different
+ /// invocations of the same program. Do not persist the hash value across
+ /// program runs.
///
- /// - Note: The hash value is not guaranteed to be stable across
- /// different invocations of the same program. Do not persist the
- /// hash value across program runs.
+ /// - SeeAlso: `Hashable`
public var hashValue: Int {
return Int(Builtin.ptrtoint_Word(_value))
}
- /// Construct an instance that uniquely identifies the class instance `x`.
+ /// Creates an instance that uniquely identifies the given class instance.
+ ///
+ /// The following example creates an example class `A` and compares instances
+ /// of the class using their object identifiers and the identical-to
+ /// operator (`===`):
+ ///
+ /// class IntegerRef {
+ /// let value: Int
+ /// init(_ value: Int) {
+ /// self.value = value
+ /// }
+ /// }
+ ///
+ /// let x = IntegerRef(10)
+ /// let y = x
+ ///
+ /// print(ObjectIdentifier(x) == ObjectIdentifier(y))
+ /// // Prints "true"
+ /// print(x === y)
+ /// // Prints "true"
+ ///
+ /// let z = IntegerRef(10)
+ /// print(ObjectIdentifier(x) == ObjectIdentifier(z))
+ /// // Prints "false"
+ /// print(x === z)
+ /// // Prints "false"
+ ///
+ /// - Parameter x: An instance of a class.
public init(_ x: AnyObject) {
self._value = Builtin.bridgeToRawPointer(x)
}
- /// Construct an instance that uniquely identifies the metatype `x`.
+ /// Creates an instance that uniquely identifies the given metatype.
+ ///
+ /// - Parameter: A metatype.
public init(_ x: Any.Type) {
self._value = unsafeBitCast(x, to: Builtin.RawPointer.self)
}
}
extension ObjectIdentifier : CustomDebugStringConvertible {
- /// A textual representation of `self`, suitable for debugging.
+ /// A textual representation of the identifier, suitable for debugging.
public var debugDescription: String {
return "ObjectIdentifier(\(_rawPointerToString(_value)))"
}
@@ -58,14 +87,16 @@
}
extension UInt {
- /// Create a `UInt` that captures the full value of `objectID`.
+ /// Creates an integer that captures the full value of the given object
+ /// identifier.
public init(bitPattern objectID: ObjectIdentifier) {
self.init(Builtin.ptrtoint_Word(objectID._value))
}
}
extension Int {
- /// Create an `Int` that captures the full value of `objectID`.
+ /// Creates an integer that captures the full value of the given object
+ /// identifier.
public init(bitPattern objectID: ObjectIdentifier) {
self.init(bitPattern: UInt(bitPattern: objectID))
}
@@ -140,7 +171,7 @@
@_silgen_name("swift_reflectAny")
internal func _reflect<T>(_ x: T) -> _Mirror
-/// Dump an object's contents using its mirror to the specified output stream.
+/// Dumps an object's contents using its mirror to the specified output stream.
@discardableResult
public func dump<T, TargetStream : TextOutputStream>(
_ value: T,
@@ -165,7 +196,7 @@
return value
}
-/// Dump an object's contents using its mirror to standard output.
+/// Dumps an object's contents using its mirror to standard output.
@discardableResult
public func dump<T>(
_ value: T,
diff --git a/stdlib/public/core/Repeat.swift b/stdlib/public/core/Repeat.swift
index e81c466..fdcadd8 100644
--- a/stdlib/public/core/Repeat.swift
+++ b/stdlib/public/core/Repeat.swift
@@ -10,18 +10,32 @@
//
//===----------------------------------------------------------------------===//
-/// A collection whose elements are all identical `Element`s.
+/// A collection whose elements are all identical.
+///
+/// You create an instance of the `Repeated` collection by calling the
+/// `repeatElement(_:count:)` function. The following example creates a
+/// collection containing the name "Humperdinck" repeated five times:
+///
+/// let repeatedName = repeatElement("Humperdinck", count: 5)
+/// for name in repeatedName {
+/// print(name)
+/// }
+/// // "Humperdinck"
+/// // "Humperdinck"
+/// // "Humperdinck"
+/// // "Humperdinck"
+/// // "Humperdinck"
public struct Repeated<Element> : RandomAccessCollection {
public typealias Indices = CountableRange<Int>
/// A type that represents a valid position in the collection.
- ///
- /// Valid indices consist of the position of every element and a
- /// "past the end" position that's not valid for use as a subscript.
+ ///
+ /// Valid indices consist of the position of every element and a "past the
+ /// end" position that's not valid for use as a subscript.
public typealias Index = Int
- /// Construct an instance that contains `count` elements having the
+ /// Creates an instance that contains `count` elements having the
/// value `repeatedValue`.
internal init(_repeating repeatedValue: Element, count: Int) {
_precondition(count >= 0, "Repetition count should be non-negative")
@@ -29,22 +43,28 @@
self.repeatedValue = repeatedValue
}
- /// Always zero, which is the index of the first element in a
- /// non-empty instance.
+ /// The position of the first element in a nonempty collection.
+ ///
+ /// In a `Repeated` collection, `startIndex` is always equal to zero. If the
+ /// collection is empty, `startIndex` is equal to `endIndex`.
public var startIndex: Index {
return 0
}
- /// Always equal to `count`, which is one greater than the index of
- /// the last element in a non-empty instance.
+ /// The collection's "past the end" position---that is, the position one
+ /// greater than the last valid subscript argument.
+ ///
+ /// In a `Repeated` collection, `endIndex` is always equal to `count`. If the
+ /// collection is empty, `endIndex` is equal to `startIndex`.
public var endIndex: Index {
return count
}
- /// Access the element at `position`.
+ /// Accesses the element at the specified position.
///
- /// - Precondition: `position` is a valid position in `self` and
- /// `position != endIndex`.
+ /// - Parameter position: The position of the element to access. `position`
+ /// must be a valid index of the collection that is not equal to the
+ /// `endIndex` property.
public subscript(position: Int) -> Element {
_precondition(position >= 0 && position < count, "Index out of range")
return repeatedValue
@@ -57,7 +77,26 @@
public let repeatedValue: Element
}
-/// Return a collection containing `n` repetitions of `elementInstance`.
+/// Creates a collection containing the specified number of the given element.
+///
+/// The following example creates a `Repeated<Int>` collection containing five
+/// zeroes:
+///
+/// let zeroes = repeatElement(0, count: 5)
+/// for x in zeroes {
+/// print(x)
+/// }
+/// // 0
+/// // 0
+/// // 0
+/// // 0
+/// // 0
+///
+/// - Parameters:
+/// - element: The element to repeat.
+/// - count: The number of times to repeat `element`.
+/// - Returns: A collection that contains `count` elements that are all
+/// `element`.
public func repeatElement<T>(_ element: T, count n: Int) -> Repeated<T> {
return Repeated(_repeating: element, count: n)
}
diff --git a/stdlib/public/core/Reverse.swift b/stdlib/public/core/Reverse.swift
index 8cb7978..2a396f7 100644
--- a/stdlib/public/core/Reverse.swift
+++ b/stdlib/public/core/Reverse.swift
@@ -13,6 +13,8 @@
extension MutableCollection where Self : BidirectionalCollection {
/// Reverses the elements of the collection in place.
///
+ /// The following example reverses the elements of an array of characters:
+ ///
/// var characters: [Character] = ["C", "a", "f", "é"]
/// characters.reverse()
/// print(cafe.characters)
@@ -65,7 +67,7 @@
}
}
-/// A Collection that presents the elements of its `Base` collection
+/// A collection that presents the elements of its base collection
/// in reverse order.
///
/// - Note: This type is the result of `x.reversed()` where `x` is a
@@ -176,7 +178,7 @@
}
}
-/// A Collection that presents the elements of its `Base` collection
+/// A collection that presents the elements of its base collection
/// in reverse order.
///
/// - Note: This type is the result of `x.reversed()` where `x` is a
@@ -326,7 +328,7 @@
Self : BidirectionalCollection,
Elements : BidirectionalCollection {
- /// Returns the elements of `self` in reverse order.
+ /// Returns the elements of the collection in reverse order.
///
/// - Complexity: O(1)
public func reversed() -> LazyBidirectionalCollection<
@@ -341,7 +343,7 @@
Self : RandomAccessCollection,
Elements : RandomAccessCollection {
- /// Returns the elements of `self` in reverse order.
+ /// Returns the elements of the collection in reverse order.
///
/// - Complexity: O(1)
public func reversed() -> LazyRandomAccessCollection<
diff --git a/stdlib/public/core/Sequence.swift b/stdlib/public/core/Sequence.swift
index 4074b2c..9444a18 100644
--- a/stdlib/public/core/Sequence.swift
+++ b/stdlib/public/core/Sequence.swift
@@ -60,8 +60,8 @@
/// more idiomatic approach to traversing a sequence in Swift. Some
/// algorithms, however, may call for direct iterator use.
///
-/// One example is the `reduce1(_:)` method. Similar to the `reduce(_:)` method
-/// defined in the standard library, which takes an initial value and a
+/// One example is the `reduce1(_:)` method. Similar to the `reduce(_:_:)`
+/// method defined in the standard library, which takes an initial value and a
/// combining closure, `reduce1(_:)` uses the first element of the sequence as
/// the initial value.
///
@@ -466,6 +466,7 @@
///
/// - Parameter n: The number of elements to drop off the end of the
/// sequence. `n` must be greater than or equal to zero.
+ /// - Returns: A subsequence leaving off the specified number of elements.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
func dropLast(_ n: Int) -> SubSequence
@@ -1084,11 +1085,11 @@
return AnySequence(_DropFirstSequence(_iterator: makeIterator(), limit: n))
}
- /// Returns a subsequence containing all but the given number of final
+ /// Returns a subsequence containing all but the given number of final
/// elements.
///
/// The sequence must be finite. If the number of elements to drop exceeds
- /// the number of elements in the sequence, the result is an empty
+ /// the number of elements in the sequence, the result is an empty
/// subsequence.
///
/// let numbers = [1, 2, 3, 4, 5]
@@ -1099,6 +1100,8 @@
///
/// - Parameter n: The number of elements to drop off the end of the
/// sequence. `n` must be greater than or equal to zero.
+ /// - Returns: A subsequence leaving off the specified number of elements.
+ ///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
public func dropLast(_ n: Int) -> AnySequence<Iterator.Element> {
_precondition(n >= 0, "Can't drop a negative number of elements from a sequence")
@@ -1158,23 +1161,42 @@
/// Returns a subsequence containing all but the first element of the
/// sequence.
///
- /// For example:
+ /// The following example drops the first element from an array of integers.
///
/// let numbers = [1, 2, 3, 4, 5]
/// print(numbers.dropFirst())
/// // Prints "[2, 3, 4, 5]"
///
+ /// If the sequence has no elements, the result is an empty subsequence.
+ ///
+ /// let empty: [Int] = []
+ /// print(empty.dropFirst())
+ /// // Prints "[]"
+ ///
+ /// - Returns: A subsequence starting after the first element of the
+ /// sequence.
+ ///
/// - Complexity: O(1)
public func dropFirst() -> SubSequence { return dropFirst(1) }
- /// Returns a subsequence containing all but the last element of the sequence.
+ /// Returns a subsequence containing all but the last element of the
+ /// sequence.
///
- /// The sequence must be finite.
+ /// The sequence must be finite. If the sequence has no elements, the result
+ /// is an empty subsequence.
///
/// let numbers = [1, 2, 3, 4, 5]
/// print(numbers.dropLast())
/// // Prints "[1, 2, 3, 4]"
///
+ /// If the sequence has no elements, the result is an empty subsequence.
+ ///
+ /// let empty: [Int] = []
+ /// print(empty.dropLast())
+ /// // Prints "[]"
+ ///
+ /// - Returns: A subsequence leaving off the last element of the sequence.
+ ///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
public func dropLast() -> SubSequence { return dropLast(1) }
}
@@ -1204,7 +1226,7 @@
public struct IteratorSequence<
Base : IteratorProtocol
> : IteratorProtocol, Sequence {
- /// Construct an instance whose iterator is a copy of `base`.
+ /// Creates an instance whose iterator is a copy of `base`.
public init(_ base: Base) {
_base = base
}
diff --git a/stdlib/public/core/SequenceAlgorithms.swift.gyb b/stdlib/public/core/SequenceAlgorithms.swift.gyb
index 353e27e..2e8843b 100644
--- a/stdlib/public/core/SequenceAlgorithms.swift.gyb
+++ b/stdlib/public/core/SequenceAlgorithms.swift.gyb
@@ -56,7 +56,7 @@
/// This example enumerates the characters of the string "Swift" and prints
/// each character along with its place in the string.
///
- /// > for (n, c) in "Swift".characters.enumerated() {
+ /// for (n, c) in "Swift".characters.enumerated() {
/// print("\(n): '\(c)'")
/// }
/// // Prints "0: 'S'"
@@ -65,6 +65,35 @@
/// // Prints "3: 'f'"
/// // Prints "4: 't'"
///
+ /// When enumerating a collection, the integer part of each pair is a counter
+ /// for the enumeration, not necessarily the index of the paired value.
+ /// These counters can only be used as indices in instances of zero-based,
+ /// integer-indexed collections, such as `Array` and `ContiguousArray`. For
+ /// other collections the counters may be out of range or of the wrong type
+ /// to use as an index. To iterate over the elements of collection with its
+ /// indices, use the `zip(_:_:)` function.
+ ///
+ /// This example iterates over the indices and elements of a set, building a
+ /// list of indices of names with five or fewer letters.
+ ///
+ /// let names: Set = ["Sofia", "Camilla", "Martina", "Mateo", "Nicolás"]
+ /// var shorterIndices: [SetIndex<String>] = []
+ /// for (i, name) in zip(names.indices, names) {
+ /// if name.characters.count <= 5 {
+ /// shorterIndices.append(i)
+ /// }
+ /// }
+ ///
+ /// Now that the `shorterIndices` array holds the indices of the shorter
+ /// names in the `names` set, you can use those indices to access elements in
+ /// the set.
+ ///
+ /// for i in shorterIndices {
+ /// print(names[i])
+ /// }
+ /// // Prints "Sofia"
+ /// // Prints "Mateo"
+ ///
/// - Returns: A sequence of pairs enumerating the sequence.
public func enumerated() -> EnumeratedSequence<Self> {
return EnumeratedSequence(_base: self)
@@ -214,28 +243,33 @@
/// - areEquivalent: A predicate that returns `true` if its two arguments
/// are equivalent; otherwise, `false`.
/// - Returns: `true` if the initial elements of the sequence are equivalent
- /// to the elements of `possiblePrefix`; otherwise, `false`. Returns
- /// `true` if `possiblePrefix` has no elements.
+ /// to the elements of `possiblePrefix`; otherwise, `false`. If
+ /// `possiblePrefix` has no elements, the return value is `true`.
///
/// - SeeAlso: `starts(with:)`
% else:
/// Returns a Boolean value indicating whether the initial elements of the
/// sequence are the same as the elements in another sequence.
///
- /// For example:
+ /// This example tests whether one countable range begins with the elements
+ /// of another countable range.
///
/// let a = 1...3
/// let b = 1...10
///
/// print(b.starts(with: a))
/// // Prints "true"
+ ///
+ /// Passing a sequence with no elements or an empty collection as
+ /// `possiblePrefix` always results in `true`.
+ ///
/// print(b.starts(with: []))
/// // Prints "true"
///
/// - Parameter possiblePrefix: A sequence to compare to this sequence.
/// - Returns: `true` if the initial elements of the sequence are the same as
- /// the elements of `possiblePrefix`; otherwise, `false`. Returns `true`
- /// if `possiblePrefix` has no elements.
+ /// the elements of `possiblePrefix`; otherwise, `false`. If
+ /// `possiblePrefix` has no elements, the return value is `true`.
///
/// - SeeAlso: `starts(with:by:)`
% end
@@ -299,7 +333,8 @@
///
/// At least one of the sequences must be finite.
///
- /// For example:
+ /// This example tests whether one countable range shares the same elements
+ /// as another countable range and as an array with the same elements.
///
/// let a = 1...3
/// let b = 1...10
@@ -380,7 +415,8 @@
/// sequence in a lexicographical ("dictionary") ordering, using the
/// less-than operator (`<`) to compare elements.
///
- /// For example:
+ /// This example uses the `lexicographicallyPrecedes` method to test which
+ /// array of integers comes first in a lexicographical ordering.
///
/// let a = [1, 2, 2, 2]
/// let b = [1, 2, 3, 4]
@@ -551,7 +587,7 @@
/// value and an element of the sequence into a new accumulating
/// value, to be used in the next call of the
/// `nextPartialResult` closure or returned to the caller.
- /// - Returns: The final accumulated value.
+ /// - Returns: The final accumulated value.
public func reduce<Result>(
_ initialResult: Result,
_ nextPartialResult:
diff --git a/stdlib/public/core/SetAlgebra.swift b/stdlib/public/core/SetAlgebra.swift
index 92405bf..9de5a5a 100644
--- a/stdlib/public/core/SetAlgebra.swift
+++ b/stdlib/public/core/SetAlgebra.swift
@@ -75,10 +75,11 @@
/// Returns a Boolean value that indicates whether the given element exists
/// in the set.
- ///
- /// For example:
///
- /// let primes: Set = [2, 3, 5, 7]
+ /// This example uses the `contains(_:)` method to test whether an integer is
+ /// a member of a set of prime numbers.
+ ///
+ /// let primes: Set = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37]
/// let x = 5
/// if primes.contains(x) {
/// print("\(x) is prime!")
@@ -93,7 +94,8 @@
/// Returns a new set with the elements of both this and the given set.
///
- /// For example:
+ /// In the following example, the `attendeesAndVisitors` set is made up
+ /// of the elements of the `attendees` and `visitors` sets:
///
/// let attendees: Set = ["Alicia", "Bethany", "Diana"]
/// let visitors = ["Marcia", "Nathaniel"]
@@ -102,7 +104,7 @@
/// // Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"
///
/// If the set already contains one or more elements that are also in
- /// `other`, the existing members are kept. For example:
+ /// `other`, the existing members are kept.
///
/// let initialIndices = Set(0..<5)
/// let expandedIndices = initialIndices.union([2, 3, 6, 7])
@@ -120,7 +122,10 @@
/// Returns a new set with the elements that are common to both this set and
/// the given set.
///
- /// For example:
+ /// In the following example, the `bothNeighborsAndEmployees` set is made up
+ /// of the elements that are in *both* the `employees` and `neighbors` sets.
+ /// Elements that are only in one or the other are left out of the result of
+ /// the intersection.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -139,7 +144,10 @@
/// Returns a new set with the elements that are either in this set or in the
/// given set, but not in both.
///
- /// For example:
+ /// In the following example, the `eitherNeighborsOrEmployees` set is made up
+ /// of the elements of the `employees` and `neighbors` sets that are not in
+ /// both `employees` *and* `neighbors`. In particular, the names `"Bethany"`
+ /// and `"Eric"` do not appear in `eitherNeighborsOrEmployees`.
///
/// let employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani"]
@@ -229,7 +237,8 @@
/// Adds the elements of the given set to the set.
///
- /// For example:
+ /// In the following example, the elements of the `visitors` set are added to
+ /// the `attendees` set:
///
/// var attendees: Set = ["Alicia", "Bethany", "Diana"]
/// let visitors: Set = ["Marcia", "Nathaniel"]
@@ -238,7 +247,7 @@
/// // Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"
///
/// If the set already contains one or more elements that are also in
- /// `other`, the existing members are kept. For example:
+ /// `other`, the existing members are kept.
///
/// var initialIndices = Set(0..<5)
/// initialIndices.formUnion([2, 3, 6, 7])
@@ -250,7 +259,9 @@
/// Removes the elements of this set that aren't also in the given set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// not also members of the `neighbors` set are removed. In particular, the
+ /// names `"Alicia"`, `"Chris"`, and `"Diana"` are removed.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -261,16 +272,21 @@
/// - Parameter other: A set of the same type as the current set.
mutating func formIntersection(_ other: Self)
- /// Removes the elements of the set that are also in the given set and
- /// adds the members of the given set that are not already in the set.
+ /// Removes the elements of the set that are also in the given set and adds
+ /// the members of the given set that are not already in the set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also members of `neighbors` are removed from `employees`, while the
+ /// elements of `neighbors` that are not members of `employees` are added to
+ /// `employees`. In particular, the names `"Alicia"`, `"Chris"`, and
+ /// `"Diana"` are removed from `employees` while the names `"Forlani"` and
+ /// `"Greta"` are added.
///
- /// var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
- /// let neighbors: Set = ["Bethany", "Eric", "Forlani"]
+ /// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
+ /// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
/// employees.formSymmetricDifference(neighbors)
/// print(employees)
- /// // Prints "["Diana", "Forlani", "Alicia"]"
+ /// // Prints "["Diana", "Chris", "Forlani", "Alicia", "Greta"]"
///
/// - Parameter other: A set of the same type.
mutating func formSymmetricDifference(_ other: Self)
@@ -279,7 +295,8 @@
/// Returns a new set containing the elements of this set that do not occur
/// in the given set.
///
- /// For example:
+ /// In the following example, the `nonNeighbors` set is made up of the
+ /// elements of the `employees` set that are not elements of `neighbors`:
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -309,7 +326,8 @@
/// Returns a Boolean value that indicates whether the set has no members in
/// common with the given set.
///
- /// For example:
+ /// In the following example, the `employees` set is disjoint with the
+ /// `visitors` set because no name appears in both sets.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
@@ -354,7 +372,9 @@
/// Removes the elements of the given set from this set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also members of the `neighbors` set are removed. In particular, the
+ /// names `"Bethany"` and `"Eric"` are removed from `employees`.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -413,7 +433,9 @@
/// Removes the elements of the given set from this set.
///
- /// For example:
+ /// In the following example, the elements of the `employees` set that are
+ /// also members of the `neighbors` set are removed. In particular, the
+ /// names `"Bethany"` and `"Eric"` are removed from `employees`.
///
/// var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -464,7 +486,8 @@
/// Returns a Boolean value that indicates whether the set has no members in
/// common with the given set.
///
- /// For example:
+ /// In the following example, the `employees` set is disjoint with the
+ /// `visitors` set because no name appears in both sets.
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
@@ -481,7 +504,8 @@
/// Returns a new set containing the elements of this set that do not occur
/// in the given set.
///
- /// For example:
+ /// In the following example, the `nonNeighbors` set is made up of the
+ /// elements of the `employees` set that are not elements of `neighbors`:
///
/// let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
/// let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -511,6 +535,8 @@
/// let attendees: Set = ["Alicia", "Bethany", "Diana"]
/// print(employees.isStrictSuperset(of: attendees))
/// // Prints "true"
+ ///
+ /// // A set is never a strict superset of itself:
/// print(employees.isStrictSuperset(of: employees))
/// // Prints "false"
///
diff --git a/stdlib/public/core/Slice.swift.gyb b/stdlib/public/core/Slice.swift.gyb
index 571b5c8..2f52815 100644
--- a/stdlib/public/core/Slice.swift.gyb
+++ b/stdlib/public/core/Slice.swift.gyb
@@ -421,6 +421,10 @@
/// print(Array(subSequence))
/// // Prints "[5, 6, 7, 8, 9]"
///
+ /// In this example, the expression `singleDigits.dropFirst(5))` is
+ /// equivalent to calling this initializer with with `singleDigits` and a
+ /// range covering the last five items of `singleDigits.indices`.
+ ///
/// - Parameters:
/// - base: The collection to create a view into.
/// - bounds: The range of indices to allow access to in the new slice.
@@ -437,6 +441,23 @@
% end
/// The underlying collection of the slice.
+ ///
+ /// You can use a slice's `base` property to access its base collection. The
+ /// following example declares `singleDigits`, a range of single digit
+ /// integers, and then drops the first element to create a slice of that
+ /// range, `singleNonZeroDigits`. The `base` property of the slice is equal
+ /// to `singleDigits`.
+ ///
+ /// let singleDigits = 0..<10
+ /// let singleNonZeroDigits = singleDigits.dropFirst()
+ /// // singleNonZeroDigits is a RandomAccessSlice<CountableRange<Int>>
+ ///
+ /// print(singleNonZeroDigits.count)
+ /// // Prints "9"
+ /// prints(singleNonZeroDigits.base.count)
+ /// // Prints "10"
+ /// print(singleDigits == singleNonZeroDigits.base)
+ /// // Prints "true"
public var base: Base {
return _base
}
diff --git a/stdlib/public/core/SliceBuffer.swift b/stdlib/public/core/SliceBuffer.swift
index cf66905..8e96bc1 100644
--- a/stdlib/public/core/SliceBuffer.swift
+++ b/stdlib/public/core/SliceBuffer.swift
@@ -37,7 +37,7 @@
_invariantCheck()
}
- public init(_ buffer: NativeBuffer, shiftedToStartIndex: Int) {
+ public init(_buffer buffer: NativeBuffer, shiftedToStartIndex: Int) {
let shift = buffer.startIndex - shiftedToStartIndex
self.init(
owner: buffer.owner,
diff --git a/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb b/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
index c62fb0b..2667d72 100644
--- a/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
+++ b/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
@@ -35,7 +35,11 @@
/// In an empty string, `endIndex` is equal to `startIndex`.
public var endIndex: Index { return characters.endIndex }
- // TODO: swift-3-indexing-model - add docs
+ /// 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 value immediately after `i`.
public func index(after i: Index) -> Index {
return characters.index(after: i)
}
@@ -45,19 +49,86 @@
return characters.index(before: i)
}
- // TODO: swift-3-indexing-model - add docs
+ /// Returns an index that is the specified distance from the given index.
+ ///
+ /// The following example obtains an index advanced four positions from a
+ /// string's starting index and then prints the character at that position.
+ ///
+ /// let s = "Swift"
+ /// let i = s.index(s.startIndex, offsetBy: 4)
+ /// print(s[i])
+ /// // Prints "t"
+ ///
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection.
+ ///
+ /// - Parameters:
+ /// - i: A valid index of the collection.
+ /// - n: The distance to offset `i`.
+ /// - Returns: An index offset by `n` from the index `i`. If `n` is positive,
+ /// this is the same value as the result of `n` calls to `index(after:)`.
+ /// If `n` is negative, this is the same value as the result of `-n` calls
+ /// to `index(before:)`.
+ ///
+ /// - SeeAlso: `index(_:offsetBy:limitedBy:)`
+ /// - Complexity: O(*n*), where *n* is the absolute value of `n`.
public func index(_ i: Index, offsetBy n: IndexDistance) -> Index {
return characters.index(i, offsetBy: n)
}
- // TODO: swift-3-indexing-model - add docs
+ /// Returns an index that is the specified distance from the given index,
+ /// unless that distance is beyond a given limiting index.
+ ///
+ /// The following example obtains an index advanced four positions from a
+ /// string's starting index and then prints the character at that position.
+ /// The operation doesn't require going beyond the limiting `s.endIndex`
+ /// value, so it succeeds.
+ ///
+ /// let s = "Swift"
+ /// if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
+ /// print(s[i])
+ /// }
+ /// // Prints "t"
+ ///
+ /// The next example attempts to retrieve an index six positions from
+ /// `s.startIndex` but fails, because that distance is beyond the index
+ /// passed as `limit`.
+ ///
+ /// let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
+ /// print(j)
+ /// // Prints "nil"
+ ///
+ /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+ /// before the `startIndex` of this collection, unless the index passed as
+ /// `limit` prevents offsetting beyond those bounds.
+ ///
+ /// - Parameters:
+ /// - i: A valid index of the collection.
+ /// - n: The distance to offset `i`.
+ /// - limit: A valid index of the collection to use as a limit. If `n > 0`,
+ /// a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+ /// limit that is greater than `i` has no effect.
+ /// - Returns: An index offset by `n` from the index `i`, unless that index
+ /// would be beyond `limit` in the direction of movement. In that case,
+ /// the method returns `nil`.
+ ///
+ /// - SeeAlso: `index(_:offsetBy:)`
+ /// - Complexity: O(*n*), where *n* is the absolute value of `n`.
public func index(
_ i: Index, offsetBy n: IndexDistance, limitedBy limit: Index
) -> Index? {
return characters.index(i, offsetBy: n, limitedBy: limit)
}
- // TODO: swift-3-indexing-model - add docs
+ /// Returns the distance between two indices.
+ ///
+ /// - Parameters:
+ /// - start: A valid index of the collection.
+ /// - end: Another valid index of the collection. If `end` is equal to
+ /// `start`, the result is zero.
+ /// - Returns: The distance between `start` and `end`.
+ ///
+ /// - Complexity: O(*n*), where *n* is the resulting distance.
public func distance(from start: Index, to end: Index) -> IndexDistance {
return characters.distance(from: start, to: end)
}
diff --git a/stdlib/public/core/Tuple.swift.gyb b/stdlib/public/core/Tuple.swift.gyb
index 9740aee..e3d6d7f 100644
--- a/stdlib/public/core/Tuple.swift.gyb
+++ b/stdlib/public/core/Tuple.swift.gyb
@@ -12,14 +12,44 @@
// Generate comparison functions for tuples up to some reasonable arity.
+%{
+
+comparableOperators = [
+ ('<', 'before'),
+ ('<=', 'before or the same as'),
+ ('>', 'after'),
+ ('>=', 'after or the same as')
+]
+
+}%
+
% for arity in range(2,7):
% typeParams = [chr(ord("A") + i) for i in range(arity)]
% tupleT = "({})".format(",".join(typeParams))
-
% equatableTypeParams = ", ".join(["{} : Equatable".format(c) for c in typeParams])
-/// Returns `true` iff each component of `lhs` is equal to the corresponding
-/// component of `rhs`.
+% originalTuple = "(\"a\", {})".format(", ".join(map(str, range(1, arity))))
+% greaterTuple = "(\"a\", {})".format(", ".join(map(str, range(1, arity - 1) + [arity])))
+
+/// Returns a Boolean value indicating whether the corresponding components of
+/// two tuples are equal.
+///
+/// For two tuples to compare as equal, each corresponding pair of components
+/// must be equal. The following example compares tuples made up of ${arity}
+/// components:
+///
+/// let a = ${originalTuple}
+/// let b = ${originalTuple}
+/// print(a == b)
+/// // Prints "true"
+///
+/// let c = ${greaterTuple}
+/// print(a == c)
+/// // Prints "false"
+///
+/// - Parameters:
+/// - lhs: A tuple of `Equatable` elements.
+/// - rhs: Another tuple of elements of the same type as `lhs`.
public func == <${equatableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
guard lhs.0 == rhs.0 else { return false }
/*tail*/ return (
@@ -29,8 +59,25 @@
)
}
-/// Returns `true` iff any component of `lhs` is not equal to the corresponding
-/// component of `rhs`.
+/// Returns a Boolean value indicating whether any corresponding components of
+/// the two tuples are not equal.
+///
+/// For two tuples to compare as equal, each corresponding pair of components
+/// must be equal. The following example compares tuples made up of ${arity}
+/// components:
+///
+/// let a = ${originalTuple}
+/// let b = ${originalTuple}
+/// print(a != b)
+/// // Prints "false"
+///
+/// let c = ${greaterTuple}
+/// print(a != c)
+/// // Prints "true"
+///
+/// - Parameters:
+/// - lhs: A tuple of `Equatable` elements.
+/// - rhs: Another tuple of elements of the same type as `lhs`.
public func != <${equatableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
guard lhs.0 == rhs.0 else { return true }
/*tail*/ return (
@@ -41,22 +88,25 @@
}
% comparableTypeParams = ", ".join(["{} : Comparable".format(c) for c in typeParams])
-% for op in ["<", ">"]:
-% for opeq in ["", "="]:
-/// A [lexicographical order](https://en.wikipedia.org/wiki/Lexicographical_order)
-/// over tuples of `Comparable` elements.
+% for op, phrase in comparableOperators:
+/// Returns a Boolean value indicating whether the first tuple is ordered
+/// ${phrase} the second in a lexicographical ordering.
///
-/// Given two tuples `(a1, a2, ..., aN)` and `(b1, b2, ..., bN)`, the
-/// first tuple is `${op}${opeq}` the second tuple iff `a1 ${op} b1` or
-/// (`a1 == b1` and `(a2, ..., aN) ${op}${opeq} (b2, ..., bN)`).
-public func ${op}${opeq} <${comparableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
- if lhs.0 != rhs.0 { return lhs.0 ${op}${opeq} rhs.0 }
+/// Given two tuples `(a1, a2, ..., aN)` and `(b1, b2, ..., bN)`, the first
+/// tuple is ${phrase} the second tuple if and only if
+/// `a1 ${op.replace('=', '')} b1` or (`a1 == b1` and
+/// `(a2, ..., aN) ${op} (b2, ..., bN)`).
+///
+/// - Parameters:
+/// - lhs: A tuple of `Comparable` elements.
+/// - rhs: Another tuple of elements of the same type as `lhs`.
+public func ${op} <${comparableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
+ if lhs.0 != rhs.0 { return lhs.0 ${op} rhs.0 }
/*tail*/ return (
${", ".join("lhs.{}".format(i) for i in range(1, arity))}
- ) ${op}${opeq} (
+ ) ${op} (
${", ".join("rhs.{}".format(i) for i in range(1, arity))}
)
}
-% end
% end
% end
diff --git a/stdlib/public/core/UnicodeScalar.swift b/stdlib/public/core/UnicodeScalar.swift
index 822b626..9c7439b 100644
--- a/stdlib/public/core/UnicodeScalar.swift
+++ b/stdlib/public/core/UnicodeScalar.swift
@@ -404,10 +404,11 @@
return 0 + UTF16.width(value)
}
- /// Access the code unit at `position`.
+ /// Accesses the code unit at the specified position.
///
- /// - Precondition: `position` is a valid position in `self` and
- /// `position != endIndex`.
+ /// - Parameter position: The position of the element to access. `position`
+ /// must be a valid index of the collection that is not equal to the
+ /// `endIndex` property.
subscript(position: Int) -> UTF16.CodeUnit {
return position == 0 ? (
endIndex == 1 ? UTF16.CodeUnit(value.value) : UTF16.leadSurrogate(value)
diff --git a/stdlib/public/core/Unmanaged.swift b/stdlib/public/core/Unmanaged.swift
index e2b2988..23e6a39 100644
--- a/stdlib/public/core/Unmanaged.swift
+++ b/stdlib/public/core/Unmanaged.swift
@@ -22,41 +22,50 @@
@_transparent
internal init(_private: Instance) { _value = _private }
- /// Unsafely turn an opaque C pointer into an unmanaged
- /// class reference.
+ /// Unsafely turns an opaque C pointer into an unmanaged class reference.
///
/// This operation does not change reference counts.
///
/// let str: CFString = Unmanaged.fromOpaque(ptr).takeUnretainedValue()
+ ///
+ /// - Parameter value: An opaque C pointer.
+ /// - Returns: An unmanaged class reference to `value`.
@_transparent
public static func fromOpaque(_ value: UnsafeRawPointer) -> Unmanaged {
return Unmanaged(_private: unsafeBitCast(value, to: Instance.self))
}
- /// Unsafely convert an unmanaged class reference to a pointer
+ /// Unsafely converts an unmanaged class reference to a pointer.
///
/// This operation does not change reference counts.
///
/// let str0: CFString = "boxcar"
/// let bits = Unmanaged.passUnretained(str0)
/// let ptr = bits.toOpaque()
+ ///
+ /// - Returns: An opaque pointer to the value of this unmanaged reference.
@_transparent
public func toOpaque() -> UnsafeMutableRawPointer {
return unsafeBitCast(_value, to: UnsafeMutableRawPointer.self)
}
- /// Create an unmanaged reference with an unbalanced retain.
- /// The object will leak if nothing eventually balances the retain.
+ /// Creates an unmanaged reference with an unbalanced retain.
///
- /// This is useful when passing an object to an API which Swift
- /// does not know the ownership rules for, but you know that the
- /// API expects you to pass the object at +1.
+ /// The instance passed as `value` will leak if nothing eventually balances
+ /// the retain.
+ ///
+ /// This is useful when passing an object to an API which Swift does not know
+ /// the ownership rules for, but you know that the API expects you to pass
+ /// the object at +1.
+ ///
+ /// - Parameter value: A class instance.
+ /// - Returns: An unmanaged reference to the object passed as `value`.
@_transparent
public static func passRetained(_ value: Instance) -> Unmanaged {
return Unmanaged(_private: value).retain()
}
- /// Create an unmanaged reference without performing an unbalanced
+ /// Creates an unmanaged reference without performing an unbalanced
/// retain.
///
/// This is useful when passing a reference to an API which Swift
@@ -65,33 +74,40 @@
///
/// CFArraySetValueAtIndex(.passUnretained(array), i,
/// .passUnretained(object))
+ ///
+ /// - Parameter value: A class instance.
+ /// - Returns: An unmanaged reference to the object passed as `value`.
@_transparent
public static func passUnretained(_ value: Instance) -> Unmanaged {
return Unmanaged(_private: value)
}
- /// Get the value of this unmanaged reference as a managed
+ /// Gets the value of this unmanaged reference as a managed
/// reference without consuming an unbalanced retain of it.
///
/// This is useful when a function returns an unmanaged reference
/// and you know that you're not responsible for releasing the result.
+ ///
+ /// - Returns: The object referenced by this `Unmanaged` instance.
public func takeUnretainedValue() -> Instance {
return _value
}
- /// Get the value of this unmanaged reference as a managed
- /// reference and consume an unbalanced retain of it.
+ /// Gets the value of this unmanaged reference as a managed
+ /// reference and consumes an unbalanced retain of it.
///
/// This is useful when a function returns an unmanaged reference
/// and you know that you're responsible for releasing the result.
+ ///
+ /// - Returns: The object referenced by this `Unmanaged` instance.
public func takeRetainedValue() -> Instance {
let result = _value
release()
return result
}
- /// Get the value of the unmanaged referenced as a managed reference without
- /// consuming an unbalanced retain of it and pass it to the closure. Asserts
+ /// Gets the value of the unmanaged referenced as a managed reference without
+ /// consuming an unbalanced retain of it and passes it to the closure. Asserts
/// that there is some other reference ('the owning reference') to the
/// instance referenced by the unmanaged reference that guarantees the
/// lifetime of the instance for the duration of the
@@ -191,21 +207,21 @@
return result
}
- /// Perform an unbalanced retain of the object.
+ /// Performs an unbalanced retain of the object.
@_transparent
public func retain() -> Unmanaged {
Builtin.retain(_value)
return self
}
- /// Perform an unbalanced release of the object.
+ /// Performs an unbalanced release of the object.
@_transparent
public func release() {
Builtin.release(_value)
}
#if _runtime(_ObjC)
- /// Perform an unbalanced autorelease of the object.
+ /// Performs an unbalanced autorelease of the object.
@_transparent
public func autorelease() -> Unmanaged {
Builtin.autorelease(_value)
diff --git a/stdlib/public/core/UnsafeBufferPointer.swift.gyb b/stdlib/public/core/UnsafeBufferPointer.swift.gyb
index 4ef34f0..b2f4ba2 100644
--- a/stdlib/public/core/UnsafeBufferPointer.swift.gyb
+++ b/stdlib/public/core/UnsafeBufferPointer.swift.gyb
@@ -142,7 +142,7 @@
return startIndex..<endIndex
}
- /// Access the `i`th element in the buffer.
+ /// Accesses the `i`th element in the buffer.
public subscript(i: Int) -> Element {
get {
_debugPrecondition(i >= 0)
@@ -177,7 +177,7 @@
% end
}
- /// Construct an Unsafe${Mutable}Pointer over the `count` contiguous
+ /// Creates an Unsafe${Mutable}Pointer over the `count` contiguous
/// `Element` instances beginning at `start`.
///
/// If `start` is nil, `count` must be 0. However, `count` may be 0 even for
diff --git a/stdlib/public/core/UnsafePointer.swift.gyb b/stdlib/public/core/UnsafePointer.swift.gyb
index e8c8621..2451e80 100644
--- a/stdlib/public/core/UnsafePointer.swift.gyb
+++ b/stdlib/public/core/UnsafePointer.swift.gyb
@@ -40,52 +40,54 @@
/// The underlying raw (untyped) pointer.
public let _rawValue: Builtin.RawPointer
- /// Construct ${a_Self} from a builtin raw pointer.
+ /// Creates ${a_Self} from a builtin raw pointer.
@_transparent
public init(_ _rawValue : Builtin.RawPointer) {
self._rawValue = _rawValue
}
- /// Convert from an opaque pointer to a typed pointer.
+ /// Converts from an opaque pointer to a typed pointer.
@_transparent
public init(_ from : OpaquePointer) {
_rawValue = from._rawValue
}
- /// Convert from an opaque pointer to a typed pointer.
+ /// Converts from an opaque pointer to a typed pointer.
///
- /// Returns nil if `from` is nil.
+ /// Returns `nil` if `from` is `nil`.
@_transparent
public init?(_ from : OpaquePointer?) {
guard let unwrapped = from else { return nil }
self.init(unwrapped)
}
- /// Construct ${a_Self} with a given pattern of bits.
+ /// Creates ${a_Self} with a given pattern of bits.
+ ///
+ /// Returns `nil` if `bitPattern` is zero.
@_transparent
public init?(bitPattern: Int) {
if bitPattern == 0 { return nil }
self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
}
- /// Construct ${a_Self} with a given pattern of bits.
+ /// Creates ${a_Self} with a given pattern of bits.
///
- /// Returns nil if `bitPattern` is zero.
+ /// Returns `nil` if `bitPattern` is zero.
@_transparent
public init?(bitPattern: UInt) {
if bitPattern == 0 { return nil }
self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
}
- /// Construct ${a_Self} from another ${a_Self}.
+ /// Creates ${a_Self} from another `${Self}`.
@_transparent
public init(_ other: ${Self}<Pointee>) {
self = other
}
- /// Construct ${a_Self} from another ${a_Self}.
+ /// Creates ${a_Self} from another `${Self}`.
///
- /// Returns nil if `other` is nil.
+ /// Returns `nil` if `other` is `nil`.
@_transparent
public init?(_ other: ${Self}<Pointee>?) {
guard let unwrapped = other else { return nil }
@@ -93,14 +95,14 @@
}
% if mutable:
- /// Convert from `UnsafePointer` to `UnsafeMutablePointer` of the same
+ /// Converts from `UnsafePointer` to `UnsafeMutablePointer` of the same
/// `Pointee`.
@_transparent
public init(mutating other: UnsafePointer<Pointee>) {
self._rawValue = other._rawValue
}
- /// Convert from `UnsafePointer` to `UnsafeMutablePointer` of the same
+ /// Converts from `UnsafePointer` to `UnsafeMutablePointer` of the same
/// `Pointee`.
///
/// Returns nil if `bitPattern` is zero.
@@ -110,13 +112,13 @@
self.init(mutating: unwrapped)
}
% else:
- /// Convert from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
+ /// Converts from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
@_transparent
public init(_ other: UnsafeMutablePointer<Pointee>) {
self._rawValue = other._rawValue
}
- /// Convert from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
+ /// Converts from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
///
/// Returns nil if `from` is nil.
@_transparent
@@ -127,7 +129,7 @@
% end
% if mutable:
- /// Allocate and point at uninitialized aligned memory for `count`
+ /// Allocates and points at uninitialized aligned memory for `count`
/// instances of `Pointee`.
///
/// - Postcondition: The pointee is allocated, but not initialized.
@@ -140,7 +142,7 @@
return UnsafeMutablePointer(rawPtr)
}
- /// Deallocate uninitialized memory allocated for `count` instances
+ /// Deallocates uninitialized memory allocated for `count` instances
/// of `Pointee`.
///
/// - Precondition: The memory is not initialized.
@@ -153,7 +155,7 @@
}
% end
- /// Access the `Pointee` instance referenced by `self`.
+ /// Accesses the `Pointee` instance referenced by `self`.
///
/// - Precondition: the pointee has been initialized with an instance of
/// type `Pointee`.
@@ -173,7 +175,7 @@
}
% if mutable:
- /// Initialize `self.pointee` with `count` consecutive copies of `newValue`
+ /// Initializes `self.pointee` with `count` consecutive copies of `newValue`
///
/// - Precondition: The pointee is not initialized.
///
@@ -192,7 +194,7 @@
}
}
- /// Retrieve the `pointee`, returning the referenced memory to an
+ /// Retrieves the `pointee`, returning the referenced memory to an
/// uninitialized state.
///
/// Equivalent to `{ defer { deinitialize() }; return pointee }()`, but
@@ -205,7 +207,7 @@
return Builtin.take(_rawValue)
}
- /// Replace `count` initialized `Pointee`s starting at `self` with
+ /// Replaces `count` initialized `Pointee`s starting at `self` with
/// the `count` `Pointee`s at `source`.
///
/// - Precondition: `count >= 0`
@@ -231,7 +233,7 @@
}
}
- /// Initialize memory starting at `self` with `count` `Pointee`s
+ /// Initializes memory starting at `self` with `count` `Pointee`s
/// beginning at `source`, and returning the source memory to an
/// uninitialized state.
///
@@ -269,7 +271,7 @@
}
}
- /// Initialize memory starting at `self` with `count` `Pointee`s
+ /// Initializes memory starting at `self` with `count` `Pointee`s
/// beginning at `source`.
///
/// - Precondition: `count >= 0`
@@ -298,7 +300,7 @@
// }
}
- /// Initialize memory starting at `self` with the elements of `source`.
+ /// Initializes memory starting at `self` with the elements of `source`.
///
/// - Precondition: The memory at `self..<self + count` is
/// uninitialized.
@@ -310,7 +312,7 @@
source._copyContents(initializing: self)
}
- /// Replace `count` initialized `Pointee`s starting at `self` with
+ /// Replaces `count` initialized `Pointee`s starting at `self` with
/// the `count` `Pointee`s starting at `source`, returning the
/// source memory to an uninitialized state.
///
@@ -340,7 +342,7 @@
// }
}
- /// De-initialize the `count` `Pointee`s starting at `self`, returning
+ /// De-initializes the `count` `Pointee`s starting at `self`, returning
/// their memory to an uninitialized state.
///
/// Returns an UnsafeMutableRawPointer to this memory.
@@ -359,12 +361,11 @@
}
% end
- /// Rebind memory at `self` to type `T` with capacity to hold `count` adjacent
- /// `T` values while executing the `body` closure. After executing the
- /// closure, rebind memory back to `Pointee`.
+ /// Rebinds memory at `self` to type `T` with capacity to hold `count`
+ /// adjacent `T` values while executing the `body` closure. After executing
+ /// the closure, rebinds memory back to `Pointee`.
///
/// - Precondition: Type 'T' is layout compatible with type 'Pointee'.
- ///
/// - Precondition: The memory `self..<self + count * MemoryLayout<T>.stride`
/// is bound to `Pointee`.
public func withMemoryRebound<T, Result>(to: T.Type, capacity count: Int,
@@ -377,7 +378,7 @@
return try body(UnsafeMutablePointer<T>(_rawValue))
}
- /// Access the pointee at `self + i`.
+ /// Accesses the pointee at `self + i`.
///
/// - Precondition: the pointee at `self + i` is initialized.
public subscript(i: Int) -> Pointee {
@@ -402,13 +403,11 @@
// Protocol conformance
//
- /// The hash value.
+ /// The pointer's hash value.
///
- /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
- ///
- /// - Note: The hash value is not guaranteed to be stable across
- /// different invocations of the same program. Do not persist the
- /// hash value across program runs.
+ /// The hash value is not guaranteed to be stable across different
+ /// invocations of the same program. Do not persist the hash value across
+ /// program runs.
public var hashValue: Int {
return Int(bitPattern: self)
}
@@ -423,19 +422,19 @@
return self - 1
}
- /// Return `end - self`.
+ /// Returns `end - self`.
public func distance(to x: ${Self}) -> Int {
return x - self
}
- /// Return `self + n`.
+ /// Returns `self + n`.
public func advanced(by n: Int) -> ${Self} {
return self + n
}
}
extension ${Self} : CustomDebugStringConvertible {
- /// A textual representation of `self`, suitable for debugging.
+ /// A textual representation of the pointer, suitable for debugging.
public var debugDescription: String {
return _rawPointerToString(_rawValue)
}
@@ -517,6 +516,30 @@
}
extension ${Self} {
+ @available(*, unavailable, message:
+ "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+ public init<U>(_ from : UnsafeMutablePointer<U>) { Builtin.unreachable() }
+
+ @available(*, unavailable, message:
+ "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+ public init?<U>(_ from : UnsafeMutablePointer<U>?) { Builtin.unreachable(); return nil }
+
+ @available(*, unavailable, message:
+ "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+ public init<U>(_ from : UnsafePointer<U>) { Builtin.unreachable() }
+
+ @available(*, unavailable, message:
+ "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+ public init?<U>(_ from : UnsafePointer<U>?) { Builtin.unreachable(); return nil }
+
+% if mutable:
+ @available(*, unavailable, renamed: "init(mutating:)")
+ public init(_ from : UnsafePointer<Pointee>) { Builtin.unreachable() }
+
+ @available(*, unavailable, renamed: "init(mutating:)")
+ public init?(_ from : UnsafePointer<Pointee>?) { Builtin.unreachable(); return nil }
+% end
+
@available(*, unavailable, renamed: "Pointee")
public typealias Memory = Pointee
diff --git a/stdlib/public/core/UnsafeRawPointer.swift.gyb b/stdlib/public/core/UnsafeRawPointer.swift.gyb
index a35effd..e086595 100644
--- a/stdlib/public/core/UnsafeRawPointer.swift.gyb
+++ b/stdlib/public/core/UnsafeRawPointer.swift.gyb
@@ -27,65 +27,69 @@
/// Implements conformance to the public protocol `_Pointer`.
public let _rawValue: Builtin.RawPointer
- /// Construct ${a_Self} from another ${a_Self}.
+ /// Creates ${a_Self} from another `${Self}`.
@_transparent
public init(_ other: Unsafe${Mutable}RawPointer) {
self = other
}
- /// Construct ${a_Self} from another ${a_Self}.
+ /// Creates ${a_Self} from another `${Self}`.
///
- /// Returns nil if `other` is nil.
+ /// Returns `nil` if `other` is `nil`.
@_transparent
public init?(_ other: Unsafe${Mutable}RawPointer?) {
guard let unwrapped = other else { return nil }
self = unwrapped
}
- /// Convert a builtin raw pointer to ${a_Self}.
+ /// Converts a builtin raw pointer to ${a_Self}.
@_transparent
public init(_ _rawValue: Builtin.RawPointer) {
self._rawValue = _rawValue
}
- /// Convert an opaque pointer to ${a_Self}.
+ /// Converts an opaque pointer to ${a_Self}.
@_transparent
public init(_ other: OpaquePointer) {
_rawValue = other._rawValue
}
- /// Convert an opaque pointer to ${a_Self}.
+ /// Converts an opaque pointer to ${a_Self}.
///
- /// Returns nil if `from` is nil.
+ /// Returns `nil` if `from` is `nil`.
@_transparent
public init?(_ other: OpaquePointer?) {
guard let unwrapped = other else { return nil }
_rawValue = unwrapped._rawValue
}
- /// Convert a pattern of bits to ${a_Self}.
+ /// Converts a pattern of bits to ${a_Self}.
+ ///
+ /// Returns `nil` if `bitPattern` is zero.
@_transparent
public init?(bitPattern: Int) {
if bitPattern == 0 { return nil }
_rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
}
- /// Convert a pattern of bits to ${a_Self}.
+ /// Converts a pattern of bits to ${a_Self}.
+ ///
+ /// Returns `nil` if `bitPattern` is zero.
@_transparent
public init?(bitPattern: UInt) {
if bitPattern == 0 { return nil }
_rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
}
- /// Convert an Unsafe${Mutable}Pointer to ${a_Self}.
+ /// Converts an Unsafe${Mutable}Pointer to ${a_Self}.
@_transparent
public init<T>(_ other: Unsafe${Mutable}Pointer<T>) {
_rawValue = other._rawValue
}
- /// Convert an Unsafe${Mutable}Pointer to ${a_Self}.
+ /// Converts an Unsafe${Mutable}Pointer to ${a_Self}.
///
- /// Returns nil if `other` is nil.
+ /// Returns `nil` if `other` is `nil`.
@_transparent
public init?<T>(_ other: Unsafe${Mutable}Pointer<T>?) {
guard let unwrapped = other else { return nil }
@@ -93,45 +97,45 @@
}
% if mutable:
- /// Convert an UnsafeRawPointer to ${a_Self}.
+ /// Converts an UnsafeRawPointer to ${a_Self}.
@_transparent
public init(mutating other: UnsafeRawPointer) {
_rawValue = other._rawValue
}
- /// Convert an UnsafeRawPointer to ${a_Self}.
+ /// Converts an UnsafeRawPointer to ${a_Self}.
///
- /// Returns nil if `other` is nil.
+ /// Returns `nil` if `other` is `nil`.
@_transparent
public init?(mutating other: UnsafeRawPointer?) {
guard let unwrapped = other else { return nil }
_rawValue = unwrapped._rawValue
}
% else: # !mutable
- /// Convert an UnsafeMutableRawPointer to ${a_Self}.
+ /// Converts an UnsafeMutableRawPointer to ${a_Self}.
@_transparent
public init(_ other: UnsafeMutableRawPointer) {
_rawValue = other._rawValue
}
- /// Convert an UnsafeMutableRawPointer to ${a_Self}.
+ /// Converts an UnsafeMutableRawPointer to ${a_Self}.
///
- /// Returns nil if `other` is nil.
+ /// Returns `nil` if `other` is `nil`.
@_transparent
public init?(_ other: UnsafeMutableRawPointer?) {
guard let unwrapped = other else { return nil }
_rawValue = unwrapped._rawValue
}
- /// Convert an UnsafeMutablePointer to ${a_Self}.
+ /// Converts an UnsafeMutablePointer to ${a_Self}.
@_transparent
public init<T>(_ other: UnsafeMutablePointer<T>) {
_rawValue = other._rawValue
}
- /// Convert an UnsafeMutablePointer to ${a_Self}.
+ /// Converts an UnsafeMutablePointer to ${a_Self}.
///
- /// Returns nil if `other` is nil.
+ /// Returns `nil` if `other` is `nil`.
@_transparent
public init?<T>(_ other: UnsafeMutablePointer<T>?) {
guard let unwrapped = other else { return nil }
@@ -140,7 +144,7 @@
% end # !mutable
% if mutable:
- /// Allocate and point at uninitialized memory for `size` bytes with
+ /// Allocates and points at uninitialized memory for `size` bytes with
/// `alignedTo` alignment.
///
/// - Postcondition: The memory is allocated, but not initialized.
@@ -151,25 +155,22 @@
}
% end # mutable
- /// Deallocate uninitialized memory allocated for `bytes` number of bytes with
- /// `alignedTo` alignment.
+ /// Deallocates uninitialized memory allocated for `bytes` number of bytes
+ /// with `alignedTo` alignment.
///
/// - Precondition: The memory is not initialized.
- ///
/// - Postcondition: The memory has been deallocated.
public func deallocate(bytes: Int, alignedTo: Int) {
Builtin.deallocRaw(
_rawValue, bytes._builtinWordValue, alignedTo._builtinWordValue)
}
- /// Binding the allocated memory to type `T`.
- /// Returns an Unsafe${Mutable}Pointer<T> to the bound memory at `self`.
- ///
- /// - Precondition: The memory is uninitialized.
+ /// Binds the allocated memory to type `T` and returns an
+ /// `Unsafe${Mutable}Pointer<T>` to the bound memory at `self`.
///
+ /// - Precondition: The memory is uninitialized.
/// - Postcondition: The memory is bound to 'T' starting at `self` continuing
/// through `self` + `count` * `MemoryLayout<T>.stride`
- ///
/// - Warning: Binding memory to a type is potentially undefined if the
/// memory is ever accessed as an unrelated type.
@_transparent
@@ -180,7 +181,7 @@
return Unsafe${Mutable}Pointer<T>(_rawValue)
}
- /// Convert from ${a_Self} to Unsafe${Mutable}Pointer<T> given that
+ /// Converts from ${a_Self} to Unsafe${Mutable}Pointer<T> given that
/// the region of memory starting at `self` is already bound to type `T`.
///
/// - Precondition: The memory is bound to 'T' starting at `self` for some
@@ -194,8 +195,8 @@
}
% if mutable:
- /// Initialize this memory location `self + strideof(T) * index`
- /// with `count` consecutive copies `value`, and bind the
+ /// Initializes this memory location `self + strideof(T) * index`
+ /// with `count` consecutive copies of `value` and binds the
/// initialized memory to type `T`.
///
/// Returns an `UnsafeMutablePointer<T>` to this memory.
@@ -233,29 +234,24 @@
return UnsafeMutablePointer(_rawValue)
}
- /// Initialize memory starting at `self` with `count` `T` values
- /// beginning at `source`, and bind the initialized memory to type
- /// `T`.
+ /// Initializes memory starting at `self` with `count` `T` values beginning
+ /// at `source` and binds the initialized memory to type `T`.
///
/// Returns an `UnsafeMutablePointer<T>` this memory.
///
/// - Precondition: `count >= 0`
- ///
/// - Precondition: The memory regions `source..<source + count` and
/// `self..<self + count * MemoryLayout<T>.stride` do not overlap.
- ///
- /// - Precondition: The memory at `self..<self + count * MemoryLayout<T>.stride`
- /// is uninitialized, and the `T` values at `source..<source + count` are
- /// initialized.
- ///
- /// - Precondition: The underlying pointer is properly aligned for
- /// accessing `T`.
- ///
- /// - Postcondition: The memory at `self..<self + count * MemoryLayout<T>.stride`
- /// is bound to type `T`.
- ///
- /// - Postcondition: The `T` values at `self..<self + count *
- /// MemoryLayout<T>.stride` and `source..<source + count` are initialized.
+ /// - Precondition: The memory at
+ /// `self..<self + count * MemoryLayout<T>.stride` is uninitialized, and
+ /// the `T` values at `source..<source + count` are initialized.
+ /// - Precondition: The underlying pointer is properly aligned for accessing
+ /// `T`.
+ /// - Postcondition: The memory at
+ /// `self..<self + count * MemoryLayout<T>.stride` is bound to type `T`.
+ /// - Postcondition: The `T` values at
+ /// `self..<self + count * MemoryLayout<T>.stride` and
+ /// `source..<source + count` are initialized.
@discardableResult
public func initializeMemory<T>(
as type: T.Type, from source: UnsafePointer<T>, count: Int
@@ -279,8 +275,8 @@
return UnsafeMutablePointer(_rawValue)
}
- /// Initialize memory starting at `self` with the elements of
- /// `source`, and bind the initialized memory to type `T`.
+ /// Initializes memory starting at `self` with the elements of
+ /// `source` and binds the initialized memory to type `T`.
///
/// Returns an `UnsafeMutablePointer<T>` this memory.
///
@@ -305,9 +301,9 @@
return UnsafeMutablePointer(_rawValue)
}
- /// Initialize memory starting at `self` with `count` `T` values
- /// beginning at `source`, bind the initialized memory to type `T`,
- /// and return the source memory to an uninitialized state.
+ /// Initializes memory starting at `self` with `count` `T` values
+ /// beginning at `source`, binds the initialized memory to type `T`,
+ /// and returns the source memory to an uninitialized state.
///
/// Returns an `UnsafeMutablePointer<T>` this memory.
///
@@ -358,7 +354,7 @@
}
% end # mutable
- /// Read raw bytes from memory at `self + offset` and construct a
+ /// Reads raw bytes from memory at `self + offset` and constructs a
/// value of type `T`.
///
/// - Precondition: The underlying pointer plus `offset` is properly
@@ -375,7 +371,7 @@
}
% if mutable:
- /// Store a value's bytes into raw memory at `self + offset`.
+ /// Stores a value's bytes into raw memory at `self + offset`.
///
/// - Precondition: The underlying pointer plus `offset` is properly
/// aligned for storing type `T`.
@@ -423,7 +419,7 @@
}
}
- /// Copy `count` bytes from `source` into memory at `self`.
+ /// Copies `count` bytes from `source` into memory at `self`.
///
/// - Precondition: `count` is non-negative.
///
@@ -450,24 +446,22 @@
// Protocol conformance
//
- /// The hash value.
+ /// The pointer's hash value.
///
- /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
- ///
- /// - Note: The hash value is not guaranteed to be stable across
- /// different invocations of the same program. Do not persist the
- /// hash value across program runs.
+ /// The hash value is not guaranteed to be stable across different
+ /// invocations of the same program. Do not persist the hash value across
+ /// program runs.
public var hashValue: Int {
return Int(bitPattern: self)
}
- /// Return `x - self`.
+ /// Returns `x - self`.
public func distance(to x: ${Self}) -> Int {
return Int(Builtin.sub_Word(Builtin.ptrtoint_Word(x._rawValue),
Builtin.ptrtoint_Word(_rawValue)))
}
- /// Return `self + n`.
+ /// Returns `self + n`.
public func advanced(by n: Int) -> ${Self} {
return ${Self}(Builtin.gep_Word(_rawValue, n._builtinWordValue))
}
@@ -487,7 +481,7 @@
}
extension Unsafe${Mutable}RawPointer : CustomDebugStringConvertible {
- /// A textual representation of `self`, suitable for debugging.
+ /// A textual representation of the pointer, suitable for debugging.
public var debugDescription: String {
return _rawPointerToString(_rawValue)
}
@@ -549,3 +543,16 @@
% end # for mutable
+extension UnsafeMutableRawPointer {
+ @available(*, unavailable, renamed: "init(mutating:)")
+ public init(_ from : UnsafeRawPointer) { Builtin.unreachable() }
+
+ @available(*, unavailable, renamed: "init(mutating:)")
+ public init?(_ from : UnsafeRawPointer?) { Builtin.unreachable(); return nil }
+
+ @available(*, unavailable, renamed: "init(mutating:)")
+ public init<T>(_ from : UnsafePointer<T>) { Builtin.unreachable() }
+
+ @available(*, unavailable, renamed: "init(mutating:)")
+ public init?<T>(_ from : UnsafePointer<T>?) { Builtin.unreachable(); return nil }
+}
diff --git a/stdlib/public/core/VarArgs.swift b/stdlib/public/core/VarArgs.swift
index fc7f370..08cd194 100644
--- a/stdlib/public/core/VarArgs.swift
+++ b/stdlib/public/core/VarArgs.swift
@@ -94,7 +94,7 @@
/// - Warning: This function is best avoided in favor of
/// `withVaList`, but occasionally (i.e. in a `class` initializer) you
/// may find that the language rules don't allow you to use
-/// `withVaList` as intended.
+/// `withVaList` as intended.
public func getVaList(_ args: [CVarArg]) -> CVaListPointer {
let builder = _VaListBuilder()
for a in args {
diff --git a/stdlib/public/core/Zip.swift b/stdlib/public/core/Zip.swift
index 50b501c..ce96f3b 100644
--- a/stdlib/public/core/Zip.swift
+++ b/stdlib/public/core/Zip.swift
@@ -10,9 +10,37 @@
//
//===----------------------------------------------------------------------===//
-/// A sequence of pairs built out of two underlying sequences, where
-/// the elements of the `i`th pair are the `i`th elements of each
-/// underlying sequence.
+/// Creates a sequence of pairs built out of two underyling sequences.
+///
+/// In the `Zip2Sequence` instance returned by this function, the elements of
+/// the *i*th pair are the *i*th elements of each underlying sequence. The
+/// following example uses the `zip(_:_:)` function to iterate over an array
+/// of strings and a countable range at the same time:
+///
+/// let words = ["one", "two", "three", "four"]
+/// let numbers = 1...4
+///
+/// for (word, number) in zip(words, numbers) {
+/// print("\(word): \(number)")
+/// }
+/// // Prints "one: 1"
+/// // Prints "two: 2
+/// // Prints "three: 3"
+/// // Prints "four: 4"
+///
+/// If the two sequences passed to `zip(_:_:)` are different lengths, the
+/// resulting sequence is the same length as the shorter sequence. In this
+/// example, the resulting array is the same length as `words`:
+///
+/// let naturalNumbers = 1...Int.max
+/// let zipped = Array(zip(words, naturalNumbers))
+/// // zipped == [("one", 1), ("two", 2), ("three", 3), ("four", 4)]
+///
+/// - Parameters:
+/// - sequence1: The first sequence or collection to zip.
+/// - sequence2: The second sequence or collection to zip.
+/// - Returns: A sequence of tuple pairs, where the elements of each pair are
+/// corresponding elements of `sequence1` and `sequence2`.
public func zip<Sequence1 : Sequence, Sequence2 : Sequence>(
_ sequence1: Sequence1, _ sequence2: Sequence2
) -> Zip2Sequence<Sequence1, Sequence2> {
@@ -26,7 +54,7 @@
/// The type of element returned by `next()`.
public typealias Element = (Iterator1.Element, Iterator2.Element)
- /// Construct around a pair of underlying iterators.
+ /// Creates an instance around a pair of underlying iterators.
internal init(_ iterator1: Iterator1, _ iterator2: Iterator2) {
(_baseStream1, _baseStream2) = (iterator1, iterator2)
}
@@ -35,9 +63,6 @@
/// exists.
///
/// Once `nil` has been returned, all subsequent calls return `nil`.
- ///
- /// - Precondition: `next()` has not been applied to a copy of `self`
- /// since the copy was made.
public mutating func next() -> Element? {
// The next() function needs to track if it has reached the end. If we
// didn't, and the first sequence is longer than the second, then when we
@@ -63,9 +88,27 @@
internal var _reachedEnd: Bool = false
}
-/// A sequence of pairs built out of two underlying sequences, where
-/// the elements of the `i`th pair are the `i`th elements of each
-/// underlying sequence.
+/// A sequence of pairs built out of two underlying sequences.
+///
+/// In a `Zip2Sequence` instance, the elements of the *i*th pair are the *i*th
+/// elements of each underlying sequence. To create a `Zip2Sequence` instance,
+/// use the `zip(_:_:)` function.
+///
+/// The following example uses the `zip(_:_:)` function to iterate over an
+/// array of strings and a countable range at the same time:
+///
+/// let words = ["one", "two", "three", "four"]
+/// let numbers = 1...4
+///
+/// for (word, number) in zip(words, numbers) {
+/// print("\(word): \(number)")
+/// }
+/// // Prints "one: 1"
+/// // Prints "two: 2
+/// // Prints "three: 3"
+/// // Prints "four: 4"
+///
+/// - SeeAlso: `zip(_:_:)`
public struct Zip2Sequence<Sequence1 : Sequence, Sequence2 : Sequence>
: Sequence {
@@ -79,7 +122,7 @@
@available(*, unavailable, renamed: "Iterator")
public typealias Generator = Iterator
- /// Construct an instance that makes pairs of elements from `sequence1` and
+ /// Creates an instance that makes pairs of elements from `sequence1` and
/// `sequence2`.
public // @testable
init(_sequence1 sequence1: Sequence1, _sequence2 sequence2: Sequence2) {
@@ -87,8 +130,6 @@
}
/// Returns an iterator over the elements of this sequence.
- ///
- /// - Complexity: O(1).
public func makeIterator() -> Iterator {
return Iterator(
_sequence1.makeIterator(),
diff --git a/test/1_stdlib/BridgeNonVerbatim.swift b/test/1_stdlib/BridgeNonVerbatim.swift
index 9400740..67bb904 100644
--- a/test/1_stdlib/BridgeNonVerbatim.swift
+++ b/test/1_stdlib/BridgeNonVerbatim.swift
@@ -23,8 +23,9 @@
import Swift
import SwiftShims
-import ObjectiveC
+import Foundation
import StdlibUnittest
+import StdlibUnittestFoundationExtras
struct X : _ObjectiveCBridgeable {
init(_ value: Int) {
@@ -65,7 +66,7 @@
func testScope() {
let a = [X(1), X(2), X(3)]
- let nsx = a._buffer._asCocoaArray()
+ let nsx: NSArray = a._bridgeToObjectiveC()
// construction of these tracked objects is lazy
// CHECK-NEXT: trackedCount = 0 .
@@ -73,12 +74,12 @@
// We can get a single element out
// CHECK-NEXT: nsx[0]: 1 .
- let one = nsx.objectAt(0) as! LifetimeTracked
+ let one = nsx.object(at: 0) as! LifetimeTracked
print("nsx[0]: \(one.value) .")
// We can get the element again, but it may not have the same identity
// CHECK-NEXT: object identity matches?
- let anotherOne = nsx.objectAt(0) as! LifetimeTracked
+ let anotherOne = nsx.object(at: 0) as! LifetimeTracked
print("object identity matches? \(one === anotherOne)")
// Because the elements come back at +0, we really don't want to
@@ -88,9 +89,10 @@
objects.withUnsafeMutableBufferPointer {
// FIXME: Can't elide signature and use $0 here <rdar://problem/17770732>
(buf: inout UnsafeMutableBufferPointer<Int>) -> () in
- let objPtr = UnsafeMutableRawPointer(buf.baseAddress!).bindMemory(
- to: AnyObject.self, capacity: 2)
- nsx.getObjects(objPtr, range: _SwiftNSRange(location: 1, length: 2))
+ nsx.available_getObjects(
+ AutoreleasingUnsafeMutablePointer(buf.baseAddress!),
+ range: NSRange(location: 1, length: 2))
+ return
}
// CHECK-NEXT: getObjects yields them at +0: true
diff --git a/test/1_stdlib/CollectionCasts.swift.gyb b/test/1_stdlib/CollectionCasts.swift.gyb
index f893ce3..60bdee4 100644
--- a/test/1_stdlib/CollectionCasts.swift.gyb
+++ b/test/1_stdlib/CollectionCasts.swift.gyb
@@ -1,4 +1,4 @@
-//===--- CollectionCasts.swift.gyb ----------------------------------------===//
+//===--- CollectionCasts.swift.gyb ----------------------------*- swift -*-===//
//
// This source file is part of the Swift.org open source project
//
diff --git a/test/1_stdlib/UnsafePointerDiagnostics.swift b/test/1_stdlib/UnsafePointerDiagnostics.swift
new file mode 100644
index 0000000..ce10abc
--- /dev/null
+++ b/test/1_stdlib/UnsafePointerDiagnostics.swift
@@ -0,0 +1,80 @@
+// RUN: %target-parse-verify-swift
+
+// Test availability attributes on UnsafePointer initializers.
+// Assume the original source contains no UnsafeRawPointer types.
+//
+// TODO:
+// - implement the Unsafe[Mutable]Pointer<Void> to Unsafe[Mutable]RawPointer rename
+// - test multiple fix-its per line: type rename + initializer rename/diagnostic
+func unsafePointerConversionAvailability(
+ mrp: UnsafeMutableRawPointer,
+ rp: UnsafeRawPointer,
+ umpv: UnsafeMutablePointer<Void>,
+ upv: UnsafePointer<Void>,
+ umpi: UnsafeMutablePointer<Int>,
+ upi: UnsafePointer<Int>,
+ umps: UnsafeMutablePointer<String>,
+ ups: UnsafePointer<String>) {
+
+ _ = UnsafeMutableRawPointer(mrp)
+ _ = UnsafeMutableRawPointer(rp) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+ _ = UnsafeMutableRawPointer(umpv)
+ _ = UnsafeMutableRawPointer(upv) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+ _ = UnsafeMutableRawPointer(umpi)
+ _ = UnsafeMutableRawPointer(upi) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+ _ = UnsafeMutableRawPointer(umps)
+ _ = UnsafeMutableRawPointer(ups) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+
+ // These all correctly pass with no error.
+ _ = UnsafeRawPointer(mrp)
+ _ = UnsafeRawPointer(rp)
+ _ = UnsafeRawPointer(umpv)
+ _ = UnsafeRawPointer(upv)
+ _ = UnsafeRawPointer(umpi)
+ _ = UnsafeRawPointer(upi)
+ _ = UnsafeRawPointer(umps)
+ _ = UnsafeRawPointer(ups)
+
+ // FIXME: All of these should yield a fix-it to rename
+ // UnsafeMutablePointer<Void> to UnsafeMutableRawPointer(umpv)
+ _ = UnsafeMutablePointer<Void>(rp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Void>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+ _ = UnsafeMutablePointer<Void>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Void>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+ _ = UnsafeMutablePointer<Void>(umpv)
+ _ = UnsafeMutablePointer<Void>(upv) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+ _ = UnsafeMutablePointer<Void>(umpi)
+ _ = UnsafeMutablePointer<Void>(upi) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+ _ = UnsafeMutablePointer<Void>(umps)
+ _ = UnsafeMutablePointer<Void>(ups) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+
+ // FIXME: All of these should yield a fix-it to rename
+ // UnsafePointer<Void> to UnsafeRawPointer(umpv)
+ _ = UnsafePointer<Void>(rp) // expected-error {{cannot invoke initializer for type 'UnsafePointer<Void>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+ _ = UnsafePointer<Void>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafePointer<Void>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+ _ = UnsafePointer<Void>(umpv)
+ _ = UnsafePointer<Void>(upv)
+ _ = UnsafePointer<Void>(umpi)
+ _ = UnsafePointer<Void>(upi)
+ _ = UnsafePointer<Void>(umps)
+ _ = UnsafePointer<Void>(ups)
+
+ // FIXME: Conversion from UnsafePointer<Void> or UnsafeRawPointer to a typed
+ // pointer should have a diagnostic: 'init' is unavailable: Conversion
+ // restricted. Use 'assumingMemoryBound(to:)' or 'bindMemory(to:capacity:)'
+ _ = UnsafeMutablePointer<Int>(rp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Int>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+ _ = UnsafeMutablePointer<Int>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Int>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+ _ = UnsafeMutablePointer<Int>(umpv) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+ _ = UnsafeMutablePointer<Int>(upv) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+ _ = UnsafeMutablePointer<Int>(umpi)
+ _ = UnsafeMutablePointer<Int>(upi) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+ _ = UnsafeMutablePointer<Int>(umps) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+ _ = UnsafeMutablePointer<Int>(ups) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+
+ _ = UnsafePointer<Int>(rp) // expected-error {{cannot invoke initializer for type 'UnsafePointer<Int>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+ _ = UnsafePointer<Int>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafePointer<Int>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+ _ = UnsafePointer<Int>(umpv) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+ _ = UnsafePointer<Int>(upv) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+ _ = UnsafePointer<Int>(umpi)
+ _ = UnsafePointer<Int>(upi)
+ _ = UnsafePointer<Int>(umps) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+ _ = UnsafePointer<Int>(ups) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+}
diff --git a/test/AutolinkExtract/empty.swift b/test/AutolinkExtract/empty.swift
index 8dd98ea..2e32546 100644
--- a/test/AutolinkExtract/empty.swift
+++ b/test/AutolinkExtract/empty.swift
@@ -4,3 +4,4 @@
// REQUIRES: autolink-extract
// CHECK-elf: -lswiftCore
+// CHECK-coff: -lswiftCore
diff --git a/test/AutolinkExtract/empty_archive.swift b/test/AutolinkExtract/empty_archive.swift
index 54ebece..030ef63 100644
--- a/test/AutolinkExtract/empty_archive.swift
+++ b/test/AutolinkExtract/empty_archive.swift
@@ -6,3 +6,4 @@
// REQUIRES: autolink-extract
// CHECK-elf: -lswiftCore
+// CHECK-coff: -lswiftCore
diff --git a/test/AutolinkExtract/import.swift b/test/AutolinkExtract/import.swift
index 225dfff..c87a7bc 100644
--- a/test/AutolinkExtract/import.swift
+++ b/test/AutolinkExtract/import.swift
@@ -9,4 +9,7 @@
// CHECK-elf-DAG: -lswiftCore
// CHECK-elf-DAG: -lempty
+// CHECK-coff-DAG: -lswiftCore
+// CHECK-coff-DAG: -lempty
+
import empty
diff --git a/test/AutolinkExtract/import_archive.swift b/test/AutolinkExtract/import_archive.swift
index 0cba4a1..d3fa6a6 100644
--- a/test/AutolinkExtract/import_archive.swift
+++ b/test/AutolinkExtract/import_archive.swift
@@ -10,4 +10,7 @@
// CHECK-elf-DAG: -lswiftCore
// CHECK-elf-DAG: -lempty
+// CHECK-coff-DAG: -lswiftCore
+// CHECK-coff-DAG: -lempty
+
import empty
diff --git a/test/AutolinkExtract/linker-order.ll b/test/AutolinkExtract/linker-order.ll
index 8f84a20..7da7d60 100644
--- a/test/AutolinkExtract/linker-order.ll
+++ b/test/AutolinkExtract/linker-order.ll
@@ -1,4 +1,6 @@
; RUN: llc -mtriple armv7--linux-gnueabihf -filetype obj -o - %s | %target-swift-autolink-extract -o - - | FileCheck %s
+; RUN: llc -mtriple x86_64--windows-gnu -filetype obj -o - %s | %target-swift-autolink-extract -o - - | FileCheck %s
+; RUN: llc -mtriple x86_64--windows-cygnus -filetype obj -o - %s | %target-swift-autolink-extract -o - - | FileCheck %s
; REQUIRES: autolink-extract
; Ensure that the options in the object file preserve ordering. The linker
diff --git a/test/Constraints/diagnostics.swift b/test/Constraints/diagnostics.swift
index 0235bad..beaa533 100644
--- a/test/Constraints/diagnostics.swift
+++ b/test/Constraints/diagnostics.swift
@@ -412,7 +412,7 @@
// <rdar://problem/20491794> Error message does not tell me what the problem is
enum Color {
- case Red // expected-note 2 {{did you mean 'Red'?}}
+ case Red
case Unknown(description: String)
static func rainbow() -> Color {}
@@ -446,8 +446,8 @@
let _: Color = .frob(1, b: i) // expected-error {{passing value of type 'Int' to an inout parameter requires explicit '&'}}
let _: Color = .frob(1, &d) // expected-error {{cannot convert value of type 'Double' to expected argument type 'Int'}}
let _: Color = .frob(1, b: &d) // expected-error {{cannot convert value of type 'Double' to expected argument type 'Int'}}
-var someColor : Color = .red // expected-error {{type 'Color' has no member 'red'}}
-someColor = .red // expected-error {{type 'Color' has no member 'red'}}
+var someColor : Color = .red // expected-error {{enum type 'Color' has no case 'red'; did you mean 'Red'}}
+someColor = .red // expected-error {{enum type 'Color' has no case 'red'; did you mean 'Red'}}
func testTypeSugar(_ a : Int) {
typealias Stride = Int
diff --git a/test/Interpreter/SDK/objc_fast_enumeration.swift b/test/Interpreter/SDK/objc_fast_enumeration.swift
index 53e90c3..fba5d7d 100644
--- a/test/Interpreter/SDK/objc_fast_enumeration.swift
+++ b/test/Interpreter/SDK/objc_fast_enumeration.swift
@@ -91,7 +91,7 @@
// CHECK: 2
// CHECK: 1
var a2 = [3, 2, 1]
-var nsa2 = (a2._buffer._asCocoaArray() as AnyObject) as! NSArray
+var nsa2: NSArray = a2._bridgeToObjectiveC()
for x in nsa2 {
print(x)
}
@@ -107,7 +107,7 @@
// CHECK: X(2)
// CHECK: X(1)
var a3 = [X(3), X(2), X(1)]
-var nsa3 = (a3._buffer._asCocoaArray() as AnyObject) as! NSArray
+var nsa3: NSArray = a3._bridgeToObjectiveC()
for x in nsa3 {
print(x)
}
diff --git a/test/NameBinding/accessibility.swift b/test/NameBinding/accessibility.swift
index 68c3fe8..fbba954 100644
--- a/test/NameBinding/accessibility.swift
+++ b/test/NameBinding/accessibility.swift
@@ -16,7 +16,7 @@
#endif
// This deliberately has the wrong import kind.
-import var has_accessibility.zz // expected-error {{no such decl in module}}
+import var has_accessibility.zz // expected-error {{variable 'zz' does not exist in module 'has_accessibility'}}
func markUsed<T>(_ t: T) {}
diff --git a/test/NameBinding/name_lookup.swift b/test/NameBinding/name_lookup.swift
index 8b94566..964f784 100644
--- a/test/NameBinding/name_lookup.swift
+++ b/test/NameBinding/name_lookup.swift
@@ -522,7 +522,8 @@
enum MyEnum {
case one
case two
-
+ case oneTwoThree
+
static let kMyConstant = "myConstant"
}
@@ -535,3 +536,8 @@
break
}
+func foo() {
+ _ = MyEnum.One // expected-error {{enum type 'MyEnum' has no case 'One'; did you mean 'one'}}{{14-17=one}}
+ _ = MyEnum.Two // expected-error {{enum type 'MyEnum' has no case 'Two'; did you mean 'two'}}{{14-17=two}}
+ _ = MyEnum.OneTwoThree // expected-error {{enum type 'MyEnum' has no case 'OneTwoThree'; did you mean 'oneTwoThree'}}{{14-25=oneTwoThree}}
+}
diff --git a/test/Prototypes/Algorithms.swift.gyb b/test/Prototypes/Algorithms.swift.gyb
index 7e96e7c..0047fa3 100644
--- a/test/Prototypes/Algorithms.swift.gyb
+++ b/test/Prototypes/Algorithms.swift.gyb
@@ -1,4 +1,4 @@
-//===--- Algorithms.swift.gyb ---------------------------------------------===//
+//===--- Algorithms.swift.gyb ---------------------------------*- swift -*-===//
//
// This source file is part of the Swift.org open source project
//
diff --git a/test/Sema/diag_init.swift b/test/Sema/diag_init.swift
index 96685e1..5f97333 100644
--- a/test/Sema/diag_init.swift
+++ b/test/Sema/diag_init.swift
@@ -1,5 +1,5 @@
// RUN: %target-parse-verify-swift
func foo(a : UnsafePointer<Void>)->UnsafeMutablePointer<Void> {
- return UnsafeMutablePointer(a) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<_>' with an argument list of type '(UnsafePointer<Void>)'}} // expected-note {{do you want to add 'mutating'}}{{31-31=mutating: }} // expected-note {{overloads for 'UnsafeMutablePointer<_>' exist with these partially matching parameter lists: (RawPointer), (OpaquePointer), (OpaquePointer?), (UnsafeMutablePointer<Pointee>), (UnsafeMutablePointer<Pointee>?)}}
-}
\ No newline at end of file
+ return UnsafeMutablePointer(a) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+}
diff --git a/test/SourceKit/DocSupport/doc_clang_module.swift.response b/test/SourceKit/DocSupport/doc_clang_module.swift.response
index 38dcef1..0c5e104 100644
--- a/test/SourceKit/DocSupport/doc_clang_module.swift.response
+++ b/test/SourceKit/DocSupport/doc_clang_module.swift.response
@@ -5487,7 +5487,7 @@
key.name: "insert(_:)",
key.usr: "s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__::SYNTHESIZED::c:@E@FooRuncingOptions",
key.original_usr: "s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__",
- key.doc.full_as_xml: "<Function><Name>insert(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__</USR><Declaration>mutating func insert(_ newMember: Self) -> (inserted: Bool, memberAfterInsert: Self)</Declaration><Abstract><Para>Inserts the given element into the option set if it is not already a member.</Para></Abstract><Parameters><Parameter><Name>newMember</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element to insert.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>(true, newMember)</codeVoice> if <codeVoice>newMember</codeVoice> was not contained in <codeVoice>self</codeVoice>. Otherwise, returns <codeVoice>(false, oldMember)</codeVoice>, where <codeVoice>oldMember</codeVoice> is the member of the set equal to <codeVoice>newMember</codeVoice>.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let purchasePrice = 87.55]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[var freeOptions: ShippingOptions = [.standard, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[if purchasePrice > 50 {]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[ freeOptions.insert(.secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[}]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(freeOptions.contains(.secondDay))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+ key.doc.full_as_xml: "<Function><Name>insert(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__</USR><Declaration>mutating func insert(_ newMember: Self) -> (inserted: Bool, memberAfterInsert: Self)</Declaration><Abstract><Para>Adds the given element to the option set if it is not already a member.</Para></Abstract><Parameters><Parameter><Name>newMember</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element to insert.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>(true, newMember)</codeVoice> if <codeVoice>newMember</codeVoice> was not contained in <codeVoice>self</codeVoice>. Otherwise, returns <codeVoice>(false, oldMember)</codeVoice>, where <codeVoice>oldMember</codeVoice> is the member of the set equal to <codeVoice>newMember</codeVoice>.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>.secondDay</codeVoice> shipping option is added to the <codeVoice>freeOptions</codeVoice> option set if <codeVoice>purchasePrice</codeVoice> is greating than 50. For the <codeVoice>ShippingOptions</codeVoice> declaration, see the <codeVoice>OptionSet</codeVoice> protocol discussion.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let purchasePrice = 87.55]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[var freeOptions: ShippingOptions = [.standard, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[if purchasePrice > 50 {]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[ freeOptions.insert(.secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[}]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(freeOptions.contains(.secondDay))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
key.offset: 1962,
key.length: 110,
key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.attribute.builtin><syntaxtype.attribute.name>@discardableResult</syntaxtype.attribute.name></syntaxtype.attribute.builtin> <syntaxtype.keyword>mutating</syntaxtype.keyword> <syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>insert</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>newMember</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -> <decl.function.returntype><tuple>(<tuple.element><tuple.element.argument_label>inserted</tuple.element.argument_label>: <tuple.element.type><ref.struct usr=\"s:Sb\">Bool</ref.struct></tuple.element.type></tuple.element>, <tuple.element><tuple.element.argument_label>memberAfterInsert</tuple.element.argument_label>: <tuple.element.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></tuple.element.type></tuple.element>)</tuple></decl.function.returntype></decl.function.method.instance>",
@@ -5506,7 +5506,7 @@
key.name: "remove(_:)",
key.usr: "s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__::SYNTHESIZED::c:@E@FooRuncingOptions",
key.original_usr: "s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__",
- key.doc.full_as_xml: "<Function><Name>remove(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__</USR><Declaration>mutating func remove(_ member: Self) -> Self?</Declaration><Abstract><Para>Removes the given element and all elements subsumed by the given element.</Para></Abstract><Parameters><Parameter><Name>member</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element of the set to remove.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>The intersection of <codeVoice>[member]</codeVoice> and the set if the intersection was nonempty; otherwise, <codeVoice>nil</codeVoice>.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var options: ShippingOptions = [.secondDay, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let priorityOption = options.remove(.priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(priorityOption == .priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(options.remove(.priority))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"nil\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing><Para>In the following example, the <codeVoice>.express</codeVoice> element is passed to <codeVoice>remove(_:)</codeVoice>. Although <codeVoice>.express</codeVoice> is not a member of <codeVoice>options</codeVoice>, <codeVoice>.express</codeVoice> subsumes the remaining <codeVoice>.secondDay</codeVoice> element of the option set. Therefore, <codeVoice>options</codeVoice> is emptied and the intersection between <codeVoice>.express</codeVoice> and <codeVoice>options</codeVoice> is returned.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let expressOption = options.remove(.express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+ key.doc.full_as_xml: "<Function><Name>remove(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__</USR><Declaration>mutating func remove(_ member: Self) -> Self?</Declaration><Abstract><Para>Removes the given element and all elements subsumed by the given element.</Para></Abstract><Parameters><Parameter><Name>member</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element of the set to remove.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>The intersection of <codeVoice>[member]</codeVoice> and the set if the intersection was nonempty; otherwise, <codeVoice>nil</codeVoice>.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>.priority</codeVoice> shipping option is removed from the <codeVoice>options</codeVoice> option set. Attempting to remove the same shipping option a second time results in <codeVoice>nil</codeVoice>, because <codeVoice>options</codeVoice> no longer contains <codeVoice>.priority</codeVoice> as a member.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var options: ShippingOptions = [.secondDay, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let priorityOption = options.remove(.priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(priorityOption == .priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(options.remove(.priority))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"nil\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing><Para>In the next example, the <codeVoice>.express</codeVoice> element is passed to <codeVoice>remove(_:)</codeVoice>. Although <codeVoice>.express</codeVoice> is not a member of <codeVoice>options</codeVoice>, <codeVoice>.express</codeVoice> subsumes the remaining <codeVoice>.secondDay</codeVoice> element of the option set. Therefore, <codeVoice>options</codeVoice> is emptied and the intersection between <codeVoice>.express</codeVoice> and <codeVoice>options</codeVoice> is returned.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let expressOption = options.remove(.express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
key.offset: 2078,
key.length: 71,
key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.attribute.builtin><syntaxtype.attribute.name>@discardableResult</syntaxtype.attribute.name></syntaxtype.attribute.builtin> <syntaxtype.keyword>mutating</syntaxtype.keyword> <syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>remove</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>member</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -> <decl.function.returntype><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct>?</decl.function.returntype></decl.function.method.instance>",
@@ -5691,7 +5691,7 @@
key.name: "subtract(_:)",
key.usr: "s:FEsPs10SetAlgebra8subtractFxT_::SYNTHESIZED::c:@E@FooRuncingOptions",
key.original_usr: "s:FEsPs10SetAlgebra8subtractFxT_",
- key.doc.full_as_xml: "<Function><Name>subtract(_:)</Name><USR>s:FEsPs10SetAlgebra8subtractFxT_</USR><Declaration>mutating func subtract(_ other: Self)</Declaration><Abstract><Para>Removes the elements of the given set from this set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+ key.doc.full_as_xml: "<Function><Name>subtract(_:)</Name><USR>s:FEsPs10SetAlgebra8subtractFxT_</USR><Declaration>mutating func subtract(_ other: Self)</Declaration><Abstract><Para>Removes the elements of the given set from this set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><Discussion><Para>In the following example, the elements of the <codeVoice>employees</codeVoice> set that are also members of the <codeVoice>neighbors</codeVoice> set are removed. In particular, the names <codeVoice>"Bethany"</codeVoice> and <codeVoice>"Eric"</codeVoice> are removed from <codeVoice>employees</codeVoice>.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
key.offset: 2688,
key.length: 50,
key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>mutating</syntaxtype.keyword> <syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>subtract</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>)</decl.function.method.instance>",
@@ -5748,7 +5748,7 @@
key.name: "isDisjoint(with:)",
key.usr: "s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb::SYNTHESIZED::c:@E@FooRuncingOptions",
key.original_usr: "s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb",
- key.doc.full_as_xml: "<Function><Name>isDisjoint(with:)</Name><USR>s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb</USR><Declaration>func isDisjoint(with other: Self) -> Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether the set has no members in common with the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set has no elements in common with <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let visitors: Set = [\"Marcia\", \"Nathaniel\", \"Olivia\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isDisjoint(with: visitors))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+ key.doc.full_as_xml: "<Function><Name>isDisjoint(with:)</Name><USR>s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb</USR><Declaration>func isDisjoint(with other: Self) -> Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether the set has no members in common with the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set has no elements in common with <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>employees</codeVoice> set is disjoint with the <codeVoice>visitors</codeVoice> set because no name appears in both sets.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let visitors: Set = [\"Marcia\", \"Nathaniel\", \"Olivia\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isDisjoint(with: visitors))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
key.offset: 2858,
key.length: 54,
key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>isDisjoint</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>with</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -> <decl.function.returntype><ref.struct usr=\"s:Sb\">Bool</ref.struct></decl.function.returntype></decl.function.method.instance>",
@@ -5767,7 +5767,7 @@
key.name: "subtracting(_:)",
key.usr: "s:FEsPs10SetAlgebra11subtractingFxx::SYNTHESIZED::c:@E@FooRuncingOptions",
key.original_usr: "s:FEsPs10SetAlgebra11subtractingFxx",
- key.doc.full_as_xml: "<Function><Name>subtracting(_:)</Name><USR>s:FEsPs10SetAlgebra11subtractingFxx</USR><Declaration>func subtracting(_ other: Self) -> Self</Declaration><Abstract><Para>Returns a new set containing the elements of this set that do not occur in the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A new set.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let nonNeighbors = employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(nonNeighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+ key.doc.full_as_xml: "<Function><Name>subtracting(_:)</Name><USR>s:FEsPs10SetAlgebra11subtractingFxx</USR><Declaration>func subtracting(_ other: Self) -> Self</Declaration><Abstract><Para>Returns a new set containing the elements of this set that do not occur in the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A new set.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>nonNeighbors</codeVoice> set is made up of the elements of the <codeVoice>employees</codeVoice> set that are not elements of <codeVoice>neighbors</codeVoice>:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let nonNeighbors = employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(nonNeighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
key.offset: 2918,
key.length: 65,
key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>subtracting</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -> <decl.function.returntype><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.function.returntype></decl.function.method.instance>",
@@ -5796,7 +5796,7 @@
key.name: "isStrictSuperset(of:)",
key.usr: "s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb::SYNTHESIZED::c:@E@FooRuncingOptions",
key.original_usr: "s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb",
- key.doc.full_as_xml: "<Function><Name>isStrictSuperset(of:)</Name><USR>s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb</USR><Declaration>func isStrictSuperset(of other: Self) -> Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether this set is a strict superset of the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set is a strict superset of <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>Set <emphasis>A</emphasis> is a strict superset of another set <emphasis>B</emphasis> if every member of <emphasis>B</emphasis> is also a member of <emphasis>A</emphasis> and <emphasis>A</emphasis> contains at least one element that is <emphasis>not</emphasis> a member of <emphasis>B</emphasis>.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let attendees: Set = [\"Alicia\", \"Bethany\", \"Diana\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: attendees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: employees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+ key.doc.full_as_xml: "<Function><Name>isStrictSuperset(of:)</Name><USR>s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb</USR><Declaration>func isStrictSuperset(of other: Self) -> Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether this set is a strict superset of the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set is a strict superset of <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>Set <emphasis>A</emphasis> is a strict superset of another set <emphasis>B</emphasis> if every member of <emphasis>B</emphasis> is also a member of <emphasis>A</emphasis> and <emphasis>A</emphasis> contains at least one element that is <emphasis>not</emphasis> a member of <emphasis>B</emphasis>.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let attendees: Set = [\"Alicia\", \"Bethany\", \"Diana\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: attendees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// A set is never a strict superset of itself:]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: employees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
key.offset: 3020,
key.length: 58,
key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>isStrictSuperset</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>of</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -> <decl.function.returntype><ref.struct usr=\"s:Sb\">Bool</ref.struct></decl.function.returntype></decl.function.method.instance>",
diff --git a/test/decl/import/import.swift b/test/decl/import/import.swift
index aceeeb8..03f0edc 100644
--- a/test/decl/import/import.swift
+++ b/test/decl/import/import.swift
@@ -41,7 +41,7 @@
import func Swift.min
import var x // expected-error {{expected module name}}
-import struct Swift.nonexistent // expected-error {{no such decl in module}}
+import struct Swift.nonexistent // expected-error {{struct 'nonexistent' does not exist in module 'Swift'}}
import Swift.import.abc // expected-error {{expected identifier in import declaration}}
// expected-error @-1 {{keyword 'import' cannot be used as an identifier here}}
diff --git a/test/lit.cfg b/test/lit.cfg
index a6a34af..2e1ed5f 100644
--- a/test/lit.cfg
+++ b/test/lit.cfg
@@ -691,17 +691,30 @@
"%s clang++ %s" %
(xcrun_prefix, config.target_cc_options))
-elif run_os == 'linux-gnu' or run_os == 'linux-gnueabihf' or run_os == 'freebsd':
- # Linux/FreeBSD
- if run_os == 'freebsd':
+elif run_os in ['linux-gnu', 'linux-gnueabihf', 'freebsd', 'windows-cygnus', 'windows-gnu']:
+ # Linux/FreeBSD/Cygwin
+ if run_os == 'windows-cygnus':
+ lit_config.note("Testing Cygwin " + config.variant_triple)
+ config.target_object_format = "coff"
+ config.target_dylib_extension = "dll"
+ config.target_sdk_name = "cygwin"
+ elif run_os == 'windows-gnu':
+ lit_config.note("Testing MinGW " + config.variant_triple)
+ config.target_object_format = "coff"
+ config.target_dylib_extension = "dll"
+ config.target_sdk_name = "mingw"
+ elif run_os == 'freebsd':
lit_config.note("Testing FreeBSD " + config.variant_triple)
+ config.target_object_format = "elf"
+ config.target_dylib_extension = "so"
+ config.target_sdk_name = "freebsd"
else:
lit_config.note("Testing Linux " + config.variant_triple)
- config.target_object_format = "elf"
- config.target_dylib_extension = "so"
+ config.target_object_format = "elf"
+ config.target_dylib_extension = "so"
+ config.target_sdk_name = "linux"
config.target_runtime = "native"
config.target_swift_autolink_extract = inferSwiftBinary("swift-autolink-extract")
- config.target_sdk_name = "freebsd" if run_os == "freebsd" else "linux"
config.target_build_swift = (
'%s -target %s %s %s %s %s'
% (config.swiftc, config.variant_triple, resource_dir_opt, mcp_opt,
diff --git a/tools/driver/autolink_extract_main.cpp b/tools/driver/autolink_extract_main.cpp
index 949aca3..64cca89 100644
--- a/tools/driver/autolink_extract_main.cpp
+++ b/tools/driver/autolink_extract_main.cpp
@@ -31,6 +31,7 @@
#include "llvm/Option/Option.h"
#include "llvm/Object/Archive.h"
#include "llvm/Object/ObjectFile.h"
+#include "llvm/Object/COFF.h"
#include "llvm/Object/ELFObjectFile.h"
using namespace swift;
@@ -106,32 +107,44 @@
}
};
-// Look inside the binary 'Bin' and append any linker flags found in its
-// ".swift1_autolink_entries" section to 'LinkerFlags'. If 'Bin' is an archive,
-// recursively look inside all children within the archive. Return 'true' if
-// there was an error, and 'false' otherwise.
+/// Look inside the object file 'ObjectFile' and append any linker flags found in
+/// its ".swift1_autolink_entries" section to 'LinkerFlags'.
+static void
+extractLinkerFlagsFromObjectFile(const llvm::object::ObjectFile *ObjectFile,
+ std::vector<std::string> &LinkerFlags) {
+ // Search for the section we hold autolink entries in
+ for (auto &Section : ObjectFile->sections()) {
+ llvm::StringRef SectionName;
+ Section.getName(SectionName);
+ if (SectionName == ".swift1_autolink_entries") {
+ llvm::StringRef SectionData;
+ Section.getContents(SectionData);
+
+ // entries are null-terminated, so extract them and push them into
+ // the set.
+ llvm::SmallVector<llvm::StringRef, 4> SplitFlags;
+ SectionData.split(SplitFlags, llvm::StringRef("\0", 1), -1,
+ /*KeepEmpty=*/false);
+ for (const auto &Flag : SplitFlags)
+ LinkerFlags.push_back(Flag);
+ }
+ }
+}
+
+/// Look inside the binary 'Bin' and append any linker flags found in its
+/// ".swift1_autolink_entries" section to 'LinkerFlags'. If 'Bin' is an archive,
+/// recursively look inside all children within the archive. Return 'true' if
+/// there was an error, and 'false' otherwise.
static bool extractLinkerFlags(const llvm::object::Binary *Bin,
CompilerInstance &Instance,
StringRef BinaryFileName,
std::vector<std::string> &LinkerFlags) {
if (auto *ObjectFile = llvm::dyn_cast<llvm::object::ELFObjectFileBase>(Bin)) {
- // Search for the section we hold autolink entries in
- for (auto &Section : ObjectFile->sections()) {
- llvm::StringRef SectionName;
- Section.getName(SectionName);
- if (SectionName == ".swift1_autolink_entries") {
- llvm::StringRef SectionData;
- Section.getContents(SectionData);
-
- // entries are null-terminated, so extract them and push them into
- // the set.
- llvm::SmallVector<llvm::StringRef, 4> SplitFlags;
- SectionData.split(SplitFlags, llvm::StringRef("\0", 1), -1,
- /*KeepEmpty=*/false);
- for (const auto &Flag : SplitFlags)
- LinkerFlags.push_back(Flag);
- }
- }
+ extractLinkerFlagsFromObjectFile(ObjectFile, LinkerFlags);
+ return false;
+ } else if (auto *ObjectFile =
+ llvm::dyn_cast<llvm::object::COFFObjectFile>(Bin)) {
+ extractLinkerFlagsFromObjectFile(ObjectFile, LinkerFlags);
return false;
} else if (auto *Archive = llvm::dyn_cast<llvm::object::Archive>(Bin)) {
for (const auto &Child : Archive->children()) {
diff --git a/utils/SwiftBuildSupport.py b/utils/SwiftBuildSupport.py
index f7e6a04..5a19524 100644
--- a/utils/SwiftBuildSupport.py
+++ b/utils/SwiftBuildSupport.py
@@ -24,7 +24,6 @@
# E402 means module level import not at top of file
from swift_build_support import diagnostics # noqa (E402)
-from swift_build_support import shell # noqa (E402)
HOME = os.environ.get("HOME", "/")
diff --git a/utils/swift_build_support/tests/products/test_swift.py b/utils/swift_build_support/tests/products/test_swift.py
index be9dd47..7bd9757 100644
--- a/utils/swift_build_support/tests/products/test_swift.py
+++ b/utils/swift_build_support/tests/products/test_swift.py
@@ -11,7 +11,6 @@
import argparse
import os
-import platform
import shutil
import sys
import tempfile
@@ -24,7 +23,6 @@
from io import StringIO
from swift_build_support import shell
-from swift_build_support import xcrun
from swift_build_support.products import Swift
from swift_build_support.toolchain import host_toolchain
from swift_build_support.workspace import Workspace
diff --git a/validation-test/StdlibUnittest/Assertions.swift.gyb b/validation-test/StdlibUnittest/Assertions.swift.gyb
index e66b9e4..ea73f2d 100644
--- a/validation-test/StdlibUnittest/Assertions.swift.gyb
+++ b/validation-test/StdlibUnittest/Assertions.swift.gyb
@@ -219,5 +219,36 @@
}
}
+AssertionsTestSuite.test("expectEqual<T : Equatable, U : Equatable, V : Equatable, W : Equatable>") {
+ let _0 = MinimalEquatableValue(0)
+ let _1 = MinimalEquatableValue(1)
+
+ for a in [_0, _1] {
+ for b in [_0, _1] {
+ for c in [_0, _1] {
+ for d in [_0, _1] {
+ for e in [_0, _1] {
+ for f in [_0, _1] {
+ for g in [_0, _1] {
+ for h in [_0, _1] {
+ let lhs = (a, b, c, d)
+ let rhs = (e, f, g, h)
+ if lhs == rhs {
+ expectEqual(lhs, rhs)
+ } else {
+ expectFailure {
+ expectEqual(lhs, rhs)
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+
runAllTests()
diff --git a/validation-test/compiler_crashers/28385-swift-constraints-constraintgraph-addconstraint.swift b/validation-test/compiler_crashers/28385-swift-constraints-constraintgraph-addconstraint.swift
new file mode 100644
index 0000000..b1e489b
--- /dev/null
+++ b/validation-test/compiler_crashers/28385-swift-constraints-constraintgraph-addconstraint.swift
@@ -0,0 +1,10 @@
+// This source file is part of the Swift.org open source project
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+
+// RUN: not --crash %target-swift-frontend %s -parse
+// REQUIRES: asserts
+assert((n:String{
diff --git a/validation-test/compiler_crashers/28386-swift-typebase-getdesugaredtype.swift b/validation-test/compiler_crashers/28386-swift-typebase-getdesugaredtype.swift
new file mode 100644
index 0000000..877522d
--- /dev/null
+++ b/validation-test/compiler_crashers/28386-swift-typebase-getdesugaredtype.swift
@@ -0,0 +1,12 @@
+// This source file is part of the Swift.org open source project
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+
+// RUN: not --crash %target-swift-frontend %s -parse
+struct A{init(){let:A
+class B:A
+class A:B{
+init()
diff --git a/validation-test/compiler_crashers/28387-swift-typebase-gatherallsubstitutions.swift b/validation-test/compiler_crashers/28387-swift-typebase-gatherallsubstitutions.swift
new file mode 100644
index 0000000..b766f71
--- /dev/null
+++ b/validation-test/compiler_crashers/28387-swift-typebase-gatherallsubstitutions.swift
@@ -0,0 +1,13 @@
+// This source file is part of the Swift.org open source project
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+
+// RUN: not --crash %target-swift-frontend %s -parse
+protocol a{typealias B<>:a{}typealias d)class B<T>:a{
+struct B<T>:a
+protocol c{
+}
+func c:d
diff --git a/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift b/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift
index 7feed32..54eb70c 100644
--- a/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift
+++ b/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift
@@ -35,8 +35,8 @@
_ preprocess: (Self) -> R
) -> R?
- func _copyToNativeArrayBuffer()
- -> _ContiguousArrayBuffer<Iterator.Element>
+ func _copyToContiguousArray()
+ -> ContiguousArray<Iterator.Element>
func _copyContents(
initializing ptr: UnsafeMutablePointer<Iterator.Element>
@@ -71,8 +71,8 @@
return nil
}
- public func _copyToNativeArrayBuffer()
- -> _ContiguousArrayBuffer<Iterator.Element> {
+ public func _copyToContiguousArray()
+ -> ContiguousArray<Iterator.Element> {
fatalError()
}
@@ -224,7 +224,7 @@
public static var filter = TypeIndexed(0)
public static var _customContainsEquatableElement = TypeIndexed(0)
public static var _preprocessingPass = TypeIndexed(0)
- public static var _copyToNativeArrayBuffer = TypeIndexed(0)
+ public static var _copyToContiguousArray = TypeIndexed(0)
public static var _copyContents = TypeIndexed(0)
}
@@ -281,10 +281,10 @@
/// Create a native array buffer containing the elements of `self`,
/// in the same order.
- public func _copyToNativeArrayBuffer()
- -> _ContiguousArrayBuffer<Base.Iterator.Element> {
- Log._copyToNativeArrayBuffer[selfType] += 1
- return base._copyToNativeArrayBuffer()
+ public func _copyToContiguousArray()
+ -> ContiguousArray<Base.Iterator.Element> {
+ Log._copyToContiguousArray[selfType] += 1
+ return base._copyToContiguousArray()
}
/// Copy a Sequence into an array.
diff --git a/validation-test/stdlib/ArrayNew.swift.gyb b/validation-test/stdlib/ArrayNew.swift.gyb
index 542f6bd..e5b6bcc 100644
--- a/validation-test/stdlib/ArrayNew.swift.gyb
+++ b/validation-test/stdlib/ArrayNew.swift.gyb
@@ -19,23 +19,14 @@
all_array_types = ['ContiguousArray', 'ArraySlice', 'Array']
}%
-extension Array {
- var identity: UnsafeRawPointer {
- return self._buffer.identity
+%for Self in all_array_types:
+extension ${Self} {
+ typealias _BufferID = UnsafeRawPointer?
+ var _bufferID: _BufferID {
+ return unsafeBitCast(_owner, to: _BufferID.self)
}
}
-
-extension ArraySlice {
- var identity: UnsafeRawPointer {
- return self._buffer.identity
- }
-}
-
-extension ContiguousArray {
- var identity: UnsafeRawPointer {
- return self._buffer.identity
- }
-}
+%end
var ArrayTestSuite = TestSuite("Array")
@@ -64,21 +55,21 @@
${element_type}(40), ${element_type}(50), ${element_type}(60),
${element_type}(70)
]]
- let identityOuter = a.identity
- var identityInner = a[0].identity
+ let identityOuter = a._bufferID
+ var identityInner = a[0]._bufferID
func checkIdentity(_ stackTrace: SourceLocStack) {
% if element_type == 'TestValueTy':
// Does not reallocate storage because we changed a property based on a
// reference; array storage was not changed. Writeback of the inner array
// does not happen.
- expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
- expectEqual(identityInner, a[0].identity, stackTrace: stackTrace)
+ expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
+ expectEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
% else:
- expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
+ expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
// Should not reallocate storage.
- expectEqual(identityInner, a[0].identity, stackTrace: stackTrace)
+ expectEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
% end
}
@@ -134,23 +125,23 @@
${element_type}(40), ${element_type}(50), ${element_type}(60),
${element_type}(70), ${element_type}(80), ${element_type}(90),
]]
- let identityOuter = a.identity
- var identityInner = a[0].identity
+ let identityOuter = a._bufferID
+ var identityInner = a[0]._bufferID
func checkIdentity(_ stackTrace: SourceLocStack) {
% if element_type == 'TestValueTy':
// Does not reallocate storage because we changed a property based on a
// reference; array storage was not changed.
- expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
- expectEqual(identityInner, a[0].identity, stackTrace: stackTrace)
+ expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
+ expectEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
% else:
- expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
+ expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
// Writeback happens in subscript(Range<Int>), but array notices that the new
// value did not change.
// Another writeback happens in Array.subscript(Int), but this is not what we
// want.
- expectNotEqual(identityInner, a[0].identity, stackTrace: stackTrace)
- identityInner = a[0].identity
+ expectNotEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
+ identityInner = a[0]._bufferID
% end
}
@@ -158,9 +149,9 @@
a[0..<1][0][0] = ${element_type}(1010)
// Reallocates storage because of the writeback in Array.subscript(Int).
- expectEqual(identityOuter, a.identity)
- expectNotEqual(identityInner, a[0].identity)
- identityInner = a[0].identity
+ expectEqual(identityOuter, a._bufferID)
+ expectNotEqual(identityInner, a[0]._bufferID)
+ identityInner = a[0]._bufferID
a[0..<1][0][1].value = 1020
@@ -195,9 +186,9 @@
// Reallocates storage because of the writeback in Array.subscript(Int)
// (writeback is being requested for the array element even though it is not
// needed).
- expectEqual(identityOuter, a.identity)
- expectNotEqual(identityInner, a[0].identity)
- identityInner = a[0].identity
+ expectEqual(identityOuter, a._bufferID)
+ expectNotEqual(identityInner, a[0]._bufferID)
+ identityInner = a[0]._bufferID
withInoutT(&a[0..<1][0][6].value) {
(x: inout Int) in
diff --git a/validation-test/stdlib/Arrays.swift.gyb b/validation-test/stdlib/Arrays.swift.gyb
index 6c56286..def3a35 100644
--- a/validation-test/stdlib/Arrays.swift.gyb
+++ b/validation-test/stdlib/Arrays.swift.gyb
@@ -73,23 +73,14 @@
all_array_types = ['ContiguousArray', 'ArraySlice', 'Array']
}%
-extension Array {
- var identity: UnsafeRawPointer {
- return self._buffer.identity
+%for Self in all_array_types:
+extension ${Self} {
+ typealias _BufferID = UnsafeRawPointer?
+ var _bufferID: _BufferID {
+ return unsafeBitCast(_owner, to: _BufferID.self)
}
}
-
-extension ArraySlice {
- var identity: UnsafeRawPointer {
- return self._buffer.identity
- }
-}
-
-extension ContiguousArray {
- var identity: UnsafeRawPointer {
- return self._buffer.identity
- }
-}
+%end
var ArrayTestSuite = TestSuite("Array")
@@ -246,10 +237,10 @@
let arr0 = ${array_type}<Int>()
let arr1 = ${array_type}<LifetimeTracked>(repeating: LifetimeTracked(0), count: 0)
// Empty arrays all use the same buffer
- expectEqual(arr0._buffer.identity, arr1._buffer.identity)
+ expectEqual(arr0._bufferID, arr1._bufferID)
let arr2: ${array_type}<LifetimeTracked> = []
- let emptyLiteralsShareBuffer = arr0._buffer.identity == arr2._buffer.identity
+ let emptyLiteralsShareBuffer = arr0._bufferID == arr2._bufferID
expectTrue(emptyLiteralsShareBuffer)
}
diff --git a/validation-test/stdlib/NewArray.swift.gyb b/validation-test/stdlib/NewArray.swift.gyb
index 1e3a19a..80e33c2 100644
--- a/validation-test/stdlib/NewArray.swift.gyb
+++ b/validation-test/stdlib/NewArray.swift.gyb
@@ -32,16 +32,39 @@
print("]")
}
-typealias BufferID = UnsafeRawPointer?
+typealias _BufferID = UnsafeRawPointer?
-func bufferID<T : _ArrayProtocol>(_ x: T) -> BufferID {
- return x._buffer.identity
+protocol MyArrayProtocol
+ : RandomAccessCollection,
+ RangeReplaceableCollection,
+ MutableCollection,
+ ArrayLiteralConvertible {
+
+ associatedtype Iterator : IteratorProtocol
+
+ var _owner: AnyObject? { get }
+
+ var capacity: Int { get }
+
+ func += <
+ S : Sequence
+ where
+ S.Iterator.Element == Iterator.Element
+ >(lhs: inout Self, rhs: S)
}
+extension MyArrayProtocol {
+ var _bufferID: _BufferID {
+ return unsafeBitCast(_owner, to: _BufferID.self)
+ }
+}
+extension Array : MyArrayProtocol {}
+extension ArraySlice : MyArrayProtocol {}
+extension ContiguousArray : MyArrayProtocol {}
-func checkReallocation<T : _ArrayProtocol>(
- _ x: T, _ lastBuffer: BufferID, _ reallocationExpected: Bool
-) -> BufferID {
- let currentBuffer = bufferID(x)
+func checkReallocation<T : MyArrayProtocol>(
+ _ x: T, _ lastBuffer: _BufferID, _ reallocationExpected: Bool
+) -> _BufferID {
+ let currentBuffer = x._bufferID
if (currentBuffer != lastBuffer) != reallocationExpected {
let message = reallocationExpected ? "lack of" : ""
print("unexpected \(message) reallocation")
@@ -62,13 +85,12 @@
}
func test<
- T : _ArrayProtocol
+ T : MyArrayProtocol
where
- T.Iterator.Element == T._Buffer.Element,
- T._Buffer.Element == T.Element,
- T.Element == LifetimeTracked,
+ T.Iterator.Element == LifetimeTracked,
+ T.Iterator.Element == T.Element,
T.Index == Int,
- T : RandomAccessCollection
+ T.IndexDistance == Int
>(_: T.Type, _ label: String) {
print("test: \(label)...", terminator: "")
@@ -85,7 +107,7 @@
x.reserveCapacity(x.count + 2)
checkEqual(x, LifetimeTracked(1)...LifetimeTracked(5), true)
- let bufferId0 = bufferID(x)
+ let bufferId0 = x._bufferID
// Append a range of integers
x += LifetimeTracked(0)..<LifetimeTracked(2)
@@ -113,9 +135,9 @@
// has shown that using 1.5, the other popular growth factor,
// slows things down.
for _ in a.count..<(a.capacity * 4) {
- let oldId = bufferID(a)
+ let oldId = a._bufferID
growBy1(&a)
- if oldId != bufferID(a) {
+ if oldId != a._bufferID {
reallocations += 1
}
}
@@ -156,29 +178,29 @@
// CHECK: == AsArray ==
let x = ContiguousArray(w)
- print(bufferID(w) == bufferID(x))
+ print(w._bufferID == x._bufferID)
// CHECK-NEXT: true
let y = Array(x)
- print(bufferID(x) == bufferID(y))
+ print(x._bufferID == y._bufferID)
// CHECK-NEXT: true
// Because of their indirection, arrays of classes can share
// buffers.
let y1 = Array(y)
- print(bufferID(y1) == bufferID(y))
+ print(y1._bufferID == y._bufferID)
// CHECK-NEXT: true
let z = ArraySlice(y)
- print(bufferID(y) == bufferID(z))
+ print(y._bufferID == z._bufferID)
// CHECK-NEXT: true
w = ContiguousArray(z)
- print(bufferID(w) == bufferID(z))
+ print(w._bufferID == z._bufferID)
// CHECK-NEXT: true
let zz = y[0..<2]
- print(bufferID(zz))
+ print(zz._bufferID)
// CHECK-NEXT: 0x
}
testAsArray()
diff --git a/validation-test/stdlib/StringViews.swift b/validation-test/stdlib/StringViews.swift
index ef0cc6a..3f8da63 100644
--- a/validation-test/stdlib/StringViews.swift
+++ b/validation-test/stdlib/StringViews.swift
@@ -14,6 +14,7 @@
import Swift
import StdlibUnittest
+import StdlibCollectionUnittest
#if _runtime(_ObjC)
// FIXME: Foundation leaks through StdlibUnittest. It adds some conformances
@@ -740,5 +741,123 @@
}
}
+struct StringViewTest {
+ var string: String
+ var utf8: [UInt8]
+ var utf16: [UInt16]
+ var unicodeScalars: [UnicodeScalar]
+
+ init(string: String, utf8: [UInt8], utf16: [UInt16], utf32: [UInt32]) {
+ self.string = string
+ self.utf8 = utf8
+ self.utf16 = utf16
+ self.unicodeScalars = utf32.map { UnicodeScalar($0)! }
+ }
+}
+
+var stringViewTests: [StringViewTest] = [
+ StringViewTest(
+ string: "",
+ utf8: [],
+ utf16: [],
+ utf32: []),
+ StringViewTest(
+ string: "\u{0000}",
+ utf8: [0x00],
+ utf16: [0x00],
+ utf32: [0x00]),
+ StringViewTest(
+ string: "a",
+ utf8: [0x61],
+ utf16: [0x61],
+ utf32: [0x61]),
+ StringViewTest(
+ string: "aa",
+ utf8: [0x61, 0x61],
+ utf16: [0x61, 0x61],
+ utf32: [0x61, 0x61]),
+ StringViewTest(
+ string: "ab",
+ utf8: [0x61, 0x62],
+ utf16: [0x61, 0x62],
+ utf32: [0x61, 0x62]),
+ StringViewTest(
+ string: "abc",
+ utf8: [0x61, 0x62, 0x63],
+ utf16: [0x61, 0x62, 0x63],
+ utf32: [0x61, 0x62, 0x63]),
+ StringViewTest(
+ string: "\u{007f}",
+ utf8: [0x7f],
+ utf16: [0x7f],
+ utf32: [0x7f]),
+ StringViewTest(
+ string: "\u{0430}",
+ utf8: [0xd0, 0xb0],
+ utf16: [0x0430],
+ utf32: [0x0430]),
+ StringViewTest(
+ string: "\u{0430}\u{0431}\u{0432}",
+ utf8: [0xd0, 0xb0, 0xd0, 0xb1, 0xd0, 0xb2],
+ utf16: [0x0430, 0x0431, 0x0432],
+ utf32: [0x0430, 0x0431, 0x0432]),
+ StringViewTest(
+ string: "\u{1f425}",
+ utf8: [0xf0, 0x9f, 0x90, 0xa5],
+ utf16: [0xd83d, 0xdc25],
+ utf32: [0x1f425]),
+]
+
+#if _runtime(_ObjC)
+tests.test("String.UTF16View.Index/Strideable")
+ .forEach(in: stringViewTests) {
+ test in
+
+ func allIndices<C : Collection>(of c: C) -> [C.Index]
+ where C.Indices.Iterator.Element == C.Index
+ {
+ var result = Array(c.indices)
+ result.append(c.endIndex)
+ return result
+ }
+
+ checkStrideable(
+ instances: allIndices(of: test.string.utf16),
+ distances: Array(0..<test.string.utf16.count),
+ distanceOracle: { $1 - $0 })
+}
+#endif
+
+tests.test("String.UTF8View/Collection")
+ .forEach(in: stringViewTests) {
+ test in
+
+ // FIXME(ABI): should be `checkBidirectionalCollection`.
+ checkForwardCollection(test.utf8, test.string.utf8) { $0 == $1 }
+}
+
+#if _runtime(_Native)
+tests.test("String.UTF16View/BidirectionalCollection")
+ .forEach(in: stringViewTests) {
+ test in
+
+ checkBidirectionalCollection(test.utf16, test.string.utf16) { $0 == $1 }
+}
+#else
+tests.test("String.UTF16View/RandomAccessCollection")
+ .forEach(in: stringViewTests) {
+ test in
+
+ checkRandomAccessCollection(test.utf16, test.string.utf16) { $0 == $1 }
+}
+#endif
+
+tests.test("String.UTF32View/BidirectionalCollection")
+ .forEach(in: stringViewTests) {
+ test in
+
+ checkBidirectionalCollection(
+ test.unicodeScalars, test.string.unicodeScalars) { $0 == $1 }
+}
runAllTests()
