[stdlib] Propagate RangeReplaceableCollectionType docs

240 undocumented public non-operator APIs remain in core

Swift SVN r22235

stdlib/core/ArrayType.swift

@@ -69,11 +69,16 @@ internal protocol ArrayType
   /// the removed element. Requires: count > 0
   mutating func removeLast() -> Self.Generator.Element
   
-  /// Insert an element at the given index in O(N).  Requires: atIndex
+  /// Insert `newElement` at index `i`.
-  /// <= count
+  ///
-  mutating func insert(newElement: Self.Generator.Element, atIndex: Int)
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
+  ///
+  /// Requires: `atIndex` <= `count`
+  mutating func insert(newElement: Self.Generator.Element, atIndex i: Int)
 
-  /// Remove the element at the given index.  Returns: the removed
+  /// Remove and return the element at the given index.  Returns: the removed
   /// element.  Worst case complexity: O(N).  Requires: count > index
   mutating func removeAtIndex(index: Int) -> Self.Generator.Element
 

stdlib/core/Arrays.swift.gyb

@@ -449,23 +449,32 @@ extension ${Self} : ArrayType {
     return result
   }
   
-  /// Insert an element at index `i` in O(N).  Requires: `i` <=
+  /// Insert `newElement` at index `i`.
-  /// `count`
+  ///
+  /// Requires: `i <= count`
+  ///
+  /// Complexity: O(\ `count`\ ).
   public mutating func insert(newElement: T, atIndex i: Int) {
     _checkIndex(i)
     self.replaceRange(i..<i, with: CollectionOfOne(newElement))
   }
 
-  /// Remove the element at the given index.  Worst case complexity:
+  /// Remove and return the element at index `i`
-  /// O(N).  Requires: `index` < `count`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `count`\ ).
   public mutating func removeAtIndex(index: Int) -> T {
     let result = self[index]
     self.replaceRange(index..<(index + 1), with: EmptyCollection())
     return result
   }
 
-  /// Erase all the elements.  If `keepCapacity` is `true`, `capacity`
+  /// Remove all elements.
-  /// will not change
+  ///
+  /// Postcondition: `capacity == 0` iff `keepCapacity` is `false`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeAll(keepCapacity: Bool = false) {
     if !keepCapacity {
       _buffer = _Buffer()
@@ -784,14 +793,15 @@ func _growArrayCapacity(capacity: Int) -> Int {
 
 % for (Self, a_Self) in arrayTypes:
 extension ${Self} {
-  /// Replace the given `subRange` of elements with `newValues`.
+  /// Replace the given `subRange` of elements with `newElements`.
+  ///
   /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex
-  /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise.
+  /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise.
   @semantics("array.mutate_unknown")
   public mutating func replaceRange<
     C: CollectionType where C.Generator.Element == _Buffer.Element
   >(
-    subRange: Range<Int>, with newValues: C
+    subRange: Range<Int>, with newElements: C
   ) {
     _precondition(subRange.startIndex >= 0,
       "${Self} replace: subRange start is negative")
@@ -801,26 +811,32 @@ extension ${Self} {
 
     let oldCount = self._buffer.count
     let eraseCount = countElements(subRange)
-    let insertCount = numericCast(countElements(newValues)) as Int
+    let insertCount = numericCast(countElements(newElements)) as Int
     let growth = insertCount - eraseCount
 
     if self._buffer.requestUniqueMutableBackingBuffer(oldCount + growth) != nil {
-      self._buffer.replace(subRange: subRange, with: insertCount, elementsOf: newValues)
+      self._buffer.replace(subRange: subRange, with: insertCount, elementsOf: newElements)
     } else {
-      _arrayOutOfPlaceReplace(&self._buffer, subRange, newValues, insertCount)
+      _arrayOutOfPlaceReplace(&self._buffer, subRange, newElements, insertCount)
     }
   }
   
-  /// Insert the elements of `s` at index `i`
+  /// Insert `newElements` at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `count + countElements(newElements)`\ ).
   public mutating func splice<
     S: CollectionType where S.Generator.Element == T
-  >(s: S, atIndex i: Int) {
+  >(newElements: S, atIndex i: Int) {
     // FIXME: <rdar://problem/17866066> 
-    // Swift.splice(&self, s, atIndex: i)
+    // Swift.splice(&self, newElements, atIndex: i)
-    self.replaceRange(i..<i, with: s)
+    self.replaceRange(i..<i, with: newElements)
   }
 
-  /// Remove the elements in the given subrange.  Complexity: O(N)
+  /// Remove the indicated `subRange` of elements
+  ///
+  /// Complexity: O(\ `count`\ ).
   public mutating func removeRange(subRange: Range<Int>) {
     Swift.removeRange(&self, subRange)
   }

stdlib/core/Dictionary.swift

@@ -2047,7 +2047,11 @@ public struct Dictionary<
     return _variantStorage.updateValue(value, forKey: key)
   }
 
-  /// Remove the key-value pair referenced by the given index.
+  /// Remove the key-value pair at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `count`\ ).
   public mutating func removeAtIndex(index: Index) {
     _variantStorage.removeAtIndex(index)
   }
@@ -2059,8 +2063,13 @@ public struct Dictionary<
     return _variantStorage.removeValueForKey(key)
   }
 
-  /// Erase all the elements.  If `keepCapacity` is `true`, `capacity`
+  /// Remove all elements.
-  /// will not decrease.
+  ///
+  /// Postcondition: `capacity == 0` iff `keepCapacity` is `false`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `count`\ ).
   public mutating func removeAll(keepCapacity: Bool = false) {
     // The 'will not decrease' part in the documentation comment is worded very
     // carefully.  The capacity can increase if we replace Cocoa storage with

stdlib/core/RangeReplaceableCollectionType.swift

@@ -19,17 +19,17 @@
 public protocol RangeReplaceableCollectionType : ExtensibleCollectionType {
   //===--- Fundamental Requirements ---------------------------------------===//
 
-  /// Replace the given `subRange` of elements with `newValues`.
+  /// Replace the given `subRange` of elements with `newElements`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
   /// Complexity: O(\ `countElements(subRange)`\ ) if
-  /// `subRange.endIndex == self.endIndex` and `isEmpty(newValues)`\ ,
+  /// `subRange.endIndex == self.endIndex` and `isEmpty(newElements)`\ ,
-  /// O(\ `countElements(self)`\ + \`countElements(newValues)`\ ) otherwise.
+  /// O(\ `countElements(self)`\ + \`countElements(newElements)`\ ) otherwise.
   mutating func replaceRange<
     C: CollectionType where C.Generator.Element == Self.Generator.Element
   >(
-    subRange: Range<Index>, with newValues: C
+    subRange: Range<Index>, with newElements: C
   )
 
   //===--- Derivable Requirements (see free functions below) --------------===//
@@ -44,18 +44,18 @@ public protocol RangeReplaceableCollectionType : ExtensibleCollectionType {
   ///   Swift.insert(&self, newElement, atIndex: i)
   mutating func insert(newElement: Generator.Element, atIndex i: Index)
 
-  /// Insert `newValues` at index `i`
+  /// Insert `newElements` at index `i`
   ///
   /// Invalidates all indices with respect to `self`.
   ///
-  /// Complexity: O(\ `countElements(self) + countElements(newValues)`\ ).
+  /// Complexity: O(\ `countElements(self) + countElements(newElements)`\ ).
   ///
   /// Can be implemented as::
   ///
-  ///   Swift.splice(&self, newValues, atIndex: i)
+  ///   Swift.splice(&self, newElements, atIndex: i)
   mutating func splice<
     S : CollectionType where S.Generator.Element == Generator.Element
-  >(newValues: S, atIndex i: Index)
+  >(newElements: S, atIndex i: Index)
 
   /// Remove the element at index `i`
   ///
@@ -95,19 +95,27 @@ public protocol RangeReplaceableCollectionType : ExtensibleCollectionType {
   mutating func removeAll(#keepCapacity: Bool /*= false*/)
 }
 
-/// Insert an element at index `i` in O(N).
+/// Insert `newElement` into `x` at index `i`.
+///
+/// Invalidates all indices with respect to `x`.
+///
+/// Complexity: O(\ `countElements(x)`\ ).
 public func insert<
   C: RangeReplaceableCollectionType
 >(inout x: C, newElement: C.Generator.Element, atIndex i: C.Index) {
     x.replaceRange(i..<i, with: CollectionOfOne(newElement))
 }
 
-/// Insert the elements of `newValues` at index `i` 
+/// Insert `newElements` into `x` at index `i`
+///
+/// Invalidates all indices with respect to `x`.
+///
+/// Complexity: O(\ `countElements(x) + countElements(newElements)`\ ).
 public func splice<
   C: RangeReplaceableCollectionType,
   S : CollectionType where S.Generator.Element == C.Generator.Element
->(inout x: C, newValues: S, atIndex i: C.Index) {
+>(inout x: C, newElements: S, atIndex i: C.Index) {
-  x.replaceRange(i..<i, with: newValues)
+  x.replaceRange(i..<i, with: newElements)
 }
 
 // FIXME: Trampoline helper to make the typechecker happy.  For some
@@ -117,13 +125,16 @@ internal func _replaceRange<
   C0: RangeReplaceableCollectionType, C1: CollectionType
     where C0.Generator.Element == C1.Generator.Element
 >(
-  inout x: C0,  subRange: Range<C0.Index>, with newValues: C1
+  inout x: C0,  subRange: Range<C0.Index>, with newElements: C1
 ) {
-  x.replaceRange(subRange, with: newValues)
+  x.replaceRange(subRange, with: newElements)
 }
 
-/// Remove and return the element at the given index.  Worst case complexity:
+/// Remove from `x` and return the element at index `i` 
-/// O(N).  Requires: `index` < `count`
+///
+/// Invalidates all indices with respect to `x`.
+///
+/// Complexity: O(\ `countElements(x)`\ ).
 public func removeAtIndex<
   C: RangeReplaceableCollectionType
 >(inout x: C, index: C.Index) -> C.Generator.Element {
@@ -133,15 +144,26 @@ public func removeAtIndex<
   return result
 }
 
-/// Remove the elements in the given subrange.  Complexity: O(N)
+/// Remove from `x` the indicated `subRange` of elements
+///
+/// Invalidates all indices with respect to `x`.
+///
+/// Complexity: O(\ `countElements(x)`\ ).
 public func removeRange<
   C: RangeReplaceableCollectionType
 >(inout x: C, subRange: Range<C.Index>) {
   _replaceRange(&x, subRange, with: EmptyCollection())
 }
 
-/// Erase all the elements of `x`.  `keepCapacity` is a non-binding
+/// Remove all elements from `x`
-/// request to maintain allocated memory. Complexity: O(N)
+///
+/// Invalidates all indices with respect to `x`.
+///
+/// :param: `keepCapacity`, if `true`, is a non-binding request to
+///    avoid releasing storage, which can be a useful optimization
+///    when `x` is going to be grown again.
+///
+/// Complexity: O(\ `countElements(x)`\ ).
 public func removeAll<
   C: RangeReplaceableCollectionType
 >(inout x: C, keepCapacity: Bool = false) {

stdlib/core/String.swift

@@ -598,40 +598,70 @@ extension String {
 }
 
 extension String : RangeReplaceableCollectionType {
-  /// Replace the given `subRange` of elements with `newValues`.
+  /// Replace the given `subRange` of elements with `newElements`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
   /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex
-  /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise.
+  /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise.
   public mutating func replaceRange<
     C: CollectionType where C.Generator.Element == Character
   >(
-    subRange: Range<Index>, with newValues: C
+    subRange: Range<Index>, with newElements: C
   ) {
     _core.replaceRange(
       subRange.startIndex._base._position
       ..< subRange.endIndex._base._position,
       with:
-        _lazyConcatenate(lazy(newValues).map { $0.utf16 })
+        _lazyConcatenate(lazy(newElements).map { $0.utf16 })
     )
   }
 
+  /// Insert `newElement` at index `i`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func insert(newElement: Character, atIndex i: Index) {
     Swift.insert(&self, newElement, atIndex: i)
   }
   
+  /// Insert `newElements` at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self) + countElements(newElements)`\ ).
   public mutating func splice<
     S : CollectionType where S.Generator.Element == Character
-  >(newValues: S, atIndex i: Index) {
+  >(newElements: S, atIndex i: Index) {
-    Swift.splice(&self, newValues, atIndex: i)
+    Swift.splice(&self, newElements, atIndex: i)
   }
 
+  /// Remove and return the element at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeAtIndex(i: Index) -> Character {
     return Swift.removeAtIndex(&self, i)
   }
   
+  /// Remove the indicated `subRange` of characters
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeRange(subRange: Range<Index>) {
     Swift.removeRange(&self, subRange)
   }
 
+  /// Remove all characters.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// :param: `keepCapacity`, if `true`, prevents the release of
+  ////   allocated storage, which can be a useful optimization
+  ///    when `self` is going to be grown again.
   public mutating func removeAll(keepCapacity: Bool = false) {
     Swift.removeAll(&self, keepCapacity: keepCapacity)
   }

stdlib/core/StringCore.swift

@@ -600,13 +600,14 @@ var _emptyStringBase: COpaquePointer {
 }
 
 extension _StringCore : RangeReplaceableCollectionType {
-  /// Replace the given `subRange` of elements with `newValues`.
+  /// Replace the given `subRange` of elements with `newElements`.
+  ///
   /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex
-  /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise.
+  /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise.
   public mutating func replaceRange<
     C: CollectionType where C.Generator.Element == UTF16.CodeUnit
   >(
-    subRange: Range<Int>, with newValues: C
+    subRange: Range<Int>, with newElements: C
   ) {
     _precondition(
       subRange.startIndex >= 0,
@@ -616,8 +617,8 @@ extension _StringCore : RangeReplaceableCollectionType {
       subRange.endIndex <= count,
       "replaceRange: subRange extends past String end")
     
-    let width = elementWidth == 2 || contains(newValues) { $0 > 0x7f } ? 2 : 1
+    let width = elementWidth == 2 || contains(newElements) { $0 > 0x7f } ? 2 : 1
-    let replacementCount = numericCast(countElements(newValues)) as Int
+    let replacementCount = numericCast(countElements(newElements)) as Int
     let replacedCount = countElements(subRange)
     let tailCount = count - subRange.endIndex
     let growth = replacementCount - replacedCount
@@ -646,13 +647,13 @@ extension _StringCore : RangeReplaceableCollectionType {
       
       if _fastPath(elementWidth == 1) {
         var dst = rangeStart
-        for u in newValues {
+        for u in newElements {
           dst++.memory = UInt8(u & 0xFF)
         }
       }
       else {
         var dst = UnsafeMutablePointer<UTF16.CodeUnit>(rangeStart)
-        for u in newValues {
+        for u in newElements {
           dst++.memory = u
         }
       }
@@ -669,11 +670,11 @@ extension _StringCore : RangeReplaceableCollectionType {
           initialSize: 0,
           elementWidth:
             width == 1 ? 1
-            : representableAsASCII() && !contains(newValues) { $0 > 0x7f } ? 1
+            : representableAsASCII() && !contains(newElements) { $0 > 0x7f } ? 1
             : 2
         ))
       r.extend(self[0..<subRange.startIndex])
-      r.extend(newValues)
+      r.extend(newElements)
       r.extend(self[subRange.endIndex..<count])
       self = r
     }
@@ -685,8 +686,8 @@ extension _StringCore : RangeReplaceableCollectionType {
   
   public mutating func splice<
     S : CollectionType where S.Generator.Element == UTF16.CodeUnit
-  >(newValues: S, atIndex i: Int) {
+  >(newElements: S, atIndex i: Int) {
-    Swift.splice(&self, newValues, atIndex: i)
+    Swift.splice(&self, newElements, atIndex: i)
   }
 
   public mutating func removeAtIndex(i: Int) -> UTF16.CodeUnit {

stdlib/core/StringUnicodeScalarView.swift

@@ -211,40 +211,70 @@ extension String.UnicodeScalarView : ExtensibleCollectionType {
 
 extension String.UnicodeScalarView : RangeReplaceableCollectionType {
 
-  /// Replace the given `subRange` of elements with `newValues`.
+  /// Replace the given `subRange` of elements with `newElements`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
   /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex
-  /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise.
+  /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise.
   public mutating func replaceRange<
     C: CollectionType where C.Generator.Element == UnicodeScalar
   >(
-    subRange: Range<Index>, with newValues: C
+    subRange: Range<Index>, with newElements: C
   ) {
     _core.replaceRange(
       subRange.startIndex._position
       ..< subRange.endIndex._position,
       with:
-        _lazyConcatenate(lazy(newValues).map { $0.utf16 })
+        _lazyConcatenate(lazy(newElements).map { $0.utf16 })
     )
   }
 
+  /// Insert `newElement` at index `i`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func insert(newElement: UnicodeScalar, atIndex i: Index) {
     Swift.insert(&self, newElement, atIndex: i)
   }
   
+  /// Insert `newElements` at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self) + countElements(newElements)`\ ).
   public mutating func splice<
     S : CollectionType where S.Generator.Element == UnicodeScalar
-  >(newValues: S, atIndex i: Index) {
+  >(newElements: S, atIndex i: Index) {
-    Swift.splice(&self, newValues, atIndex: i)
+    Swift.splice(&self, newElements, atIndex: i)
   }
 
+  /// Remove the and return element at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeAtIndex(i: Index) -> UnicodeScalar {
     return Swift.removeAtIndex(&self, i)
   }
   
+  /// Remove the indicated `subRange` of elements
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeRange(subRange: Range<Index>) {
     Swift.removeRange(&self, subRange)
   }
 
+  /// Remove all elements.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// :param: `keepCapacity`, if `true`, prevents the release of
+  ////   allocated storage, which can be a useful optimization
+  ///    when `self` is going to be grown again.
   public mutating func removeAll(keepCapacity: Bool = false) {
     Swift.removeAll(&self, keepCapacity: keepCapacity)
   }