[stdlib] Requires in comments changed to Precondition

Author: Max Moiseev

stdlib/private/StdlibUnittest/LifetimeTracked.swift

@@ -32,7 +32,7 @@ public final class LifetimeTracked : ForwardIndex, CustomStringConvertible {
 
   /// Returns the next consecutive value after `self`.
   ///
-  /// Requires: the next value is representable.
+  /// Precondition: the next value is representable.
   public func successor() -> LifetimeTracked {
     return LifetimeTracked(self.value.successor())
   }

stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb

@@ -1882,7 +1882,7 @@ public func checkForwardIndex<
 /// to generate equality expectations from pairs of positions in
 /// `instances`.
 ///
-/// - Preconditions:
+/// - Precondition:
 ///   - all elements of `instances` are reachable from `startIndex`.
 ///   - `endIndex` is reachable from all elements of `instances`.
 public func checkBidirectionalIndex<
@@ -1915,7 +1915,7 @@ public func checkBidirectionalIndex<
 /// about the results of `advanced(by:)` and `distance(to:)` from pairs of
 /// positions in `instances` and `distances`.
 ///
-/// - Preconditions:
+/// - Precondition:
 ///   - all elements of `instances` are reachable from `startIndex`.
 ///   - `endIndex` is reachable from all elements of `instances`.
 public func checkRandomAccessIndex<

stdlib/public/core/ArrayBuffer.swift

@@ -35,7 +35,7 @@ public struct _ArrayBuffer<Element> : _ArrayBufferProtocol {
 
   /// Returns an `_ArrayBuffer<U>` containing the same elements.
   ///
-  /// - Requires: The elements actually have dynamic type `U`, and `U`
+  /// - Precondition: The elements actually have dynamic type `U`, and `U`
   ///   is a class or `@objc` existential.
   @warn_unused_result
   internal func cast<U>(toBufferOf _: U.Type) -> _ArrayBuffer<U> {
@@ -51,7 +51,8 @@ public struct _ArrayBuffer<Element> : _ArrayBufferProtocol {
   /// Returns an `_ArrayBuffer<U>` containing the same elements,
   /// deferring checking each element's `U`-ness until it is accessed.
   ///
-  /// - Requires: `U` is a class or `@objc` existential derived from `Element`.
+  /// - Precondition: `U` is a class or `@objc` existential derived from
+  /// `Element`.
   @warn_unused_result
   internal func downcast<U>(
     toBufferWithDeferredTypeCheckOf _: U.Type
@@ -410,7 +411,7 @@ extension _ArrayBuffer {
   /// Call `body(p)`, where `p` is an `UnsafeMutableBufferPointer`
   /// over the underlying contiguous storage.
   ///
-  /// - Requires: Such contiguous storage exists or the buffer is empty.
+  /// - Precondition: Such contiguous storage exists or the buffer is empty.
   public mutating func withUnsafeMutableBufferPointer<R>(
     @noescape body: (UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R {
@@ -430,7 +431,7 @@ extension _ArrayBuffer {
 
   /// An object that keeps the elements stored in this buffer alive.
   ///
-  /// - Requires: This buffer is backed by a `_ContiguousArrayBuffer`.
+  /// - Precondition: This buffer is backed by a `_ContiguousArrayBuffer`.
   public var nativeOwner: AnyObject {
     _sanityCheck(_isNative, "Expect a native array")
     return _native._storage
@@ -490,7 +491,7 @@ extension _ArrayBuffer {
 
   /// Our native representation.
   ///
-  /// - Requires: `_isNative`.
+  /// - Precondition: `_isNative`.
   var _native: NativeBuffer {
     return NativeBuffer(
       _isClassOrObjCExistential(Element.self)
@@ -499,7 +500,7 @@ extension _ArrayBuffer {
 
   /// Fast access to the native representation.
   ///
-  /// - Requires: `_isNativeTypeChecked`.
+  /// - Precondition: `_isNativeTypeChecked`.
   var _nativeTypeChecked: NativeBuffer {
     return NativeBuffer(_storage.nativeInstance_noSpareBits)
   }

stdlib/public/core/ArrayBufferProtocol.swift

@@ -66,7 +66,7 @@ public protocol _ArrayBufferProtocol : MutableCollection {
   /// Replace the given `subRange` with the first `newCount` elements of
   /// the given collection.
   ///
-  /// - Requires: This buffer is backed by a uniquely-referenced
+  /// - Precondition: This buffer is backed by a uniquely-referenced
   /// `_ContiguousArrayBuffer`.
   mutating func replace<C : Collection where C.Iterator.Element == Element>(
     subRange subRange: Range<Int>,
@@ -87,7 +87,7 @@ public protocol _ArrayBufferProtocol : MutableCollection {
   /// Call `body(p)`, where `p` is an `UnsafeMutableBufferPointer`
   /// over the underlying contiguous storage.
   ///
-  /// - Requires: Such contiguous storage exists or the buffer is empty.
+  /// - Precondition: Such contiguous storage exists or the buffer is empty.
   mutating func withUnsafeMutableBufferPointer<R>(
     @noescape body: (UnsafeMutableBufferPointer<Element>) throws -> R
   ) rethrows -> R

stdlib/public/core/ArrayCast.swift

@@ -40,10 +40,9 @@ internal enum _BridgeStyle {
 
 /// Implements `source as! [TargetElement]`.
 ///
-/// - Requires: At least one of `SourceElement` and `TargetElement` is a
-///   class type or ObjC existential.  May trap for other "valid" inputs
-///   when `TargetElement` is not bridged verbatim, if an element can't
-///   be converted.
+/// - Precondition: At least one of `SourceElement` and `TargetElement` is a
+/// class type or ObjC existential.  May trap for other "valid" inputs when
+/// `TargetElement` is not bridged verbatim, if an element can't be converted.
 public func _arrayForceCast<SourceElement, TargetElement>(
   source: Array<SourceElement>
 ) -> Array<TargetElement> {
@@ -181,7 +180,7 @@ ElementwiseBridging:
 /// `source` to a `TargetElement` and return the resulting array, or
 /// return `nil` if any element fails to convert.
 ///
-/// - Requires: `SourceElement` is a class or ObjC existential type.
+/// - Precondition: `SourceElement` is a class or ObjC existential type.
 /// O(n), because each element must be checked.
 public func _arrayConditionalCast<SourceElement, TargetElement>(
   source: [SourceElement]

stdlib/public/core/ArrayType.swift

@@ -55,7 +55,7 @@ protocol _ArrayProtocol
   ///
   /// - Complexity: O(`self.count`).
   ///
-  /// - Requires: `i <= count`.
+  /// - Precondition: `i <= count`.
   mutating func insert(newElement: Iterator.Element, at i: Int)
 
   /// Remove and return the element at the given index.
@@ -64,7 +64,7 @@ protocol _ArrayProtocol
   ///
   /// - Complexity: Worst case O(N).
   ///
-  /// - Requires: `count > index`.
+  /// - Precondition: `count > index`.
   mutating func remove(at index: Int) -> Iterator.Element
 
   //===--- implementation detail  -----------------------------------------===//

stdlib/public/core/Arrays.swift.gyb

@@ -300,14 +300,14 @@ public struct ${Self}<Element>
     return _buffer.capacity
   }
 
-  /// - Requires: The array has a native buffer.
+  /// - Precondition: The array has a native buffer.
   @warn_unused_result
   @_semantics("array.owner")
   internal func _getOwnerWithSemanticLabel_native() -> Builtin.NativeObject {
     return Builtin.castToNativeObject(_buffer.nativeOwner)
   }
 
-  /// - Requires: The array has a native buffer.
+  /// - Precondition: The array has a native buffer.
   @warn_unused_result
   @inline(__always)
   internal func _getOwner_native() -> Builtin.NativeObject {
@@ -453,7 +453,7 @@ extension ${Self} : ArrayLiteralConvertible {
 ///
 /// This function is referenced by the compiler to allocate array literals.
 ///
-/// - Requires: `storage` is `_ContiguousArrayStorage`.
+/// - Precondition: `storage` is `_ContiguousArrayStorage`.
 @warn_unused_result
 @inline(__always)
 public // COMPILER_INTRINSIC
@@ -556,7 +556,7 @@ extension ${Self} : _ArrayProtocol {
   /// given `storage`, and a pointer to uninitialized memory for the
   /// first element.
   ///
-  /// - Requires: `storage is _ContiguousArrayStorage`.
+  /// - Precondition: `storage is _ContiguousArrayStorage`.
   @warn_unused_result
   @_semantics("array.uninitialized")
   internal static func _adoptStorage(
@@ -715,7 +715,7 @@ extension ${Self} : _ArrayProtocol {
 
   /// Remove and return the last element in O(1).
   ///
-  /// - Requires: `!isEmpty`.
+  /// - Precondition: `!isEmpty`.
   public mutating func removeLast() -> Element {
     _precondition(count > 0, "can't removeLast from an empty ${Self}")
     let i = count
@@ -728,7 +728,7 @@ extension ${Self} : _ArrayProtocol {
 
   /// Insert `newElement` at index `i`.
   ///
-  /// - Requires: `i <= count`.
+  /// - Precondition: `i <= count`.
   ///
   /// - Complexity: O(`self.count`).
   public mutating func insert(newElement: Element, at i: Int) {
@@ -1324,7 +1324,7 @@ public func != <Element : Equatable>(
 /// Returns an `Array<Base>` containing the same elements as `a` in
 /// O(1).
 ///
-/// - Requires: `Base` is a base class or base `@objc` protocol (such
+/// - Precondition: `Base` is a base class or base `@objc` protocol (such
 ///   as `AnyObject`) of `Derived`.
 @warn_unused_result
 public func _arrayUpCast<Derived, Base>(a: Array<Derived>) -> Array<Base> {

stdlib/public/core/BridgeObjectiveC.swift

@@ -356,8 +356,8 @@ public struct AutoreleasingUnsafeMutablePointer<Pointee /* TODO : class */>
 
   /// Access the `Pointee` instance referenced by `self`.
   ///
-  /// - Requires: the pointee has been initialized with an instance of
-  ///   type `Pointee`.
+  /// - Precondition: the pointee has been initialized with an instance of type
+  ///   `Pointee`.
   public var pointee: Pointee {
     /// Retrieve the value the pointer points to.
     @_transparent get {
@@ -389,7 +389,7 @@ public struct AutoreleasingUnsafeMutablePointer<Pointee /* TODO : class */>
   /// Access the `i`th element of the raw array pointed to by
   /// `self`.
   ///
-  /// - Requires: `self != nil`.
+  /// - Precondition: `self != nil`.
   public subscript(i: Int) -> Pointee {
     @_transparent
     get {

stdlib/public/core/Builtin.swift

@@ -220,7 +220,7 @@ public func _unsafeReferenceCast<T, U>(x: T, to: U.Type) -> U {
 
 /// - returns: `x as T`.
 ///
-/// - Requires: `x is T`.  In particular, in -O builds, no test is
+/// - Precondition: `x is T`.  In particular, in -O builds, no test is
 ///   performed to ensure that `x` actually has dynamic type `T`.
 ///
 /// - Warning: Trades safety for performance.  Use `unsafeDowncast`
@@ -397,7 +397,7 @@ internal func _isObjCTaggedPointer(x: AnyObject) -> Bool {
 /// Reference-counting and other operations on this
 /// object will have access to the knowledge that it is native.
 ///
-/// - Requires: `bits & _objectPointerIsObjCBit == 0`,
+/// - Precondition: `bits & _objectPointerIsObjCBit == 0`,
 ///   `bits & _objectPointerSpareBits == bits`.
 @inline(__always)
 @warn_unused_result
@@ -426,7 +426,7 @@ func _makeObjCBridgeObject(
 /// Create a `BridgeObject` around the given `object` with the
 /// given spare bits.
 ///
-/// - Requires:
+/// - Precondition:
 ///
 ///   1. `bits & _objectPointerSpareBits == bits`
 ///   2. if `object` is a tagged pointer, `bits == 0`.  Otherwise,

stdlib/public/core/CString.swift

@@ -22,7 +22,7 @@ extension String {
   /// If `cString` contains ill-formed UTF-8 code unit sequences, replaces them
   /// with replacement characters (U+FFFD).
   ///
-  /// - Requires: `cString != nil`
+  /// - Precondition: `cString != nil`
   public init(cString: UnsafePointer<CChar>) {
     _precondition(cString != nil, "cString must not be nil")
     self = String.decodeCString(UnsafePointer(cString), as: UTF8.self,
@@ -35,7 +35,7 @@ extension String {
   /// Does not try to repair ill-formed UTF-8 code unit sequences, fails if any
   /// such sequences are found.
   ///
-  /// - Requires: `cString != nil`
+  /// - Precondition: `cString != nil`
   public init?(validatingUTF8 cString: UnsafePointer<CChar>) {
     _precondition(cString != nil, "cString must not be nil")
     guard let (result, _) = String.decodeCString(

stdlib/public/core/Character.swift

@@ -79,7 +79,7 @@ public struct Character :
 
   /// Create an instance from a single-character `String`.
   ///
-  /// - Requires: `s` contains exactly one extended grapheme cluster.
+  /// - Precondition: `s` contains exactly one extended grapheme cluster.
   public init(_ s: String) {
     // The small representation can accept up to 8 code units as long
     // as the last one is a continuation.  Since the high bit of the
@@ -161,7 +161,7 @@ public struct Character :
 
     /// Access the code unit at `position`.
     ///
-    /// - Requires: `position` is a valid position in `self` and
+    /// - Precondition: `position` is a valid position in `self` and
     ///   `position != endIndex`.
     subscript(position: Int) -> UTF8.CodeUnit {
       _sanityCheck(position >= 0)
@@ -233,7 +233,7 @@ public struct Character :
 
     /// Access the code unit at `position`.
     ///
-    /// - Requires: `position` is a valid position in `self` and
+    /// - Precondition: `position` is a valid position in `self` and
     ///   `position != endIndex`.
     subscript(position: Int) -> UTF16.CodeUnit {
       _sanityCheck(position >= 0)