[stdlib] rename Span.extracting functions

Author: glessard

stdlib/public/core/Span/Span.swift

@@ -536,13 +536,20 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(_ bounds: Range<Index>) -> Self {
+  public func extracting(_ bounds: Range<Index>) -> Self {
     _precondition(
       UInt(bitPattern: bounds.lowerBound) <= UInt(bitPattern: _count) &&
       UInt(bitPattern: bounds.upperBound) <= UInt(bitPattern: _count),
       "Index range out of bounds"
     )
-    return unsafe _extracting(unchecked: bounds)
+    return unsafe extracting(unchecked: bounds)
+  }
+
+  @available(*, deprecated, renamed: "extracting(_:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(_ bounds: Range<Index>) -> Self {
+    extracting(bounds)
   }
 
   /// Constructs a new span over the items within the supplied range of
@@ -563,7 +570,7 @@ extension Span where Element: ~Copyable {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(unchecked bounds: Range<Index>) -> Self {
+  public func extracting(unchecked bounds: Range<Index>) -> Self {
     let delta = bounds.lowerBound &* MemoryLayout<Element>.stride
     let newStart = unsafe _pointer?.advanced(by: delta)
     let newSpan = unsafe Span(_unchecked: newStart, count: bounds.count)
@@ -572,6 +579,14 @@ extension Span where Element: ~Copyable {
     return unsafe _overrideLifetime(newSpan, copying: self)
   }
 
+  @unsafe
+  @available(*, deprecated, renamed: "extracting(unchecked:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(unchecked bounds: Range<Index>) -> Self {
+    unsafe extracting(unchecked: bounds)
+  }
+
   /// Constructs a new span over the items within the supplied range of
   /// positions within this span.
   ///
@@ -587,10 +602,17 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(
+  public func extracting(
     _ bounds: some RangeExpression<Index>
   ) -> Self {
-    _extracting(bounds.relative(to: indices))
+    extracting(bounds.relative(to: indices))
+  }
+
+  @available(*, deprecated, renamed: "extracting(_:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(_ bounds: some RangeExpression<Index>) -> Self {
+    extracting(bounds)
   }
 
   /// Constructs a new span over the items within the supplied range of
@@ -611,13 +633,21 @@ extension Span where Element: ~Copyable {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(
+  public func extracting(
     unchecked bounds: ClosedRange<Index>
   ) -> Self {
     let range = unsafe Range(
       _uncheckedBounds: (bounds.lowerBound, bounds.upperBound + 1)
     )
-    return unsafe _extracting(unchecked: range)
+    return unsafe extracting(unchecked: range)
+  }
+
+  @unsafe
+  @available(*, deprecated, renamed: "extracting(unchecked:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(unchecked bounds: ClosedRange<Index>) -> Self {
+    unsafe extracting(unchecked: bounds)
   }
 
   /// Constructs a new span over all the items of this span.
@@ -631,6 +661,13 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
+  public func extracting(_: UnboundedRange) -> Self {
+    self
+  }
+
+  @available(*, deprecated, renamed: "extracting(_:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
   public func _extracting(_: UnboundedRange) -> Self {
     self
   }
@@ -761,13 +798,20 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(first maxLength: Int) -> Self {
+  public func extracting(first maxLength: Int) -> Self {
     _precondition(maxLength >= 0, "Can't have a prefix of negative length")
     let newCount = min(maxLength, count)
     let newSpan = unsafe Self(_unchecked: _pointer, count: newCount)
     return unsafe _overrideLifetime(newSpan, copying: self)
   }
 
+  @available(*, deprecated, renamed: "extracting(first:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(first maxLength: Int) -> Self {
+    extracting(first: maxLength)
+  }
+
   /// Returns a span over all but the given number of trailing elements.
   ///
   /// If the number of elements to drop exceeds the number of elements in
@@ -784,13 +828,20 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(droppingLast k: Int) -> Self {
+  public func extracting(droppingLast k: Int) -> Self {
     _precondition(k >= 0, "Can't drop a negative number of elements")
     let droppedCount = min(k, count)
     let newSpan = unsafe Self(_unchecked: _pointer, count: count &- droppedCount)
     return unsafe _overrideLifetime(newSpan, copying: self)
   }
 
+  @available(*, deprecated, renamed: "extracting(droppingLast:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(droppingLast k: Int) -> Self {
+    extracting(droppingLast: k)
+  }
+
   /// Returns a span containing the final elements of the span,
   /// up to the given maximum length.
   ///
@@ -808,7 +859,7 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(last maxLength: Int) -> Self {
+  public func extracting(last maxLength: Int) -> Self {
     _precondition(maxLength >= 0, "Can't have a suffix of negative length")
     let newCount = min(maxLength, count)
     let offset = (count &- newCount) * MemoryLayout<Element>.stride
@@ -819,6 +870,13 @@ extension Span where Element: ~Copyable {
     return unsafe _overrideLifetime(newSpan, copying: self)
   }
 
+  @available(*, deprecated, renamed: "extracting(last:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(last maxLength: Int) -> Self {
+    extracting(last: maxLength)
+  }
+
   /// Returns a span over all but the given number of initial elements.
   ///
   /// If the number of elements to drop exceeds the number of elements in
@@ -835,7 +893,7 @@ extension Span where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(droppingFirst k: Int) -> Self {
+  public func extracting(droppingFirst k: Int) -> Self {
     _precondition(k >= 0, "Can't drop a negative number of elements")
     let droppedCount = min(k, count)
     let offset = droppedCount &* MemoryLayout<Element>.stride
@@ -846,4 +904,11 @@ extension Span where Element: ~Copyable {
     // lifetime of 'buffer'. Make the dependence explicit.
     return unsafe _overrideLifetime(newSpan, copying: self)
   }
+
+  @available(*, deprecated, renamed: "extracting(droppingFirst:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(droppingFirst k: Int) -> Self {
+    extracting(droppingFirst: k)
+  }
 }

stdlib/public/core/Substring.swift

@@ -760,7 +760,7 @@ extension Substring.UTF8View {
       let base: String.UTF8View = self._base
       let first = base._foreignDistance(from: base.startIndex, to: startIndex)
       let count = base._foreignDistance(from: startIndex, to: endIndex)
-      let span = base._underlyingSpan()._extracting(first..<(first &+ count))
+      let span = base._underlyingSpan().extracting(first..<(first &+ count))
       return unsafe _overrideLifetime(span, borrowing: self)
     }
 #endif // _runtime(_ObjC)
@@ -776,7 +776,7 @@ extension Substring.UTF8View {
     let isFastUTF8 = _wholeGuts.isFastUTF8
     _precondition(isFastUTF8, "Substring must be contiguous UTF8")
     var span = unsafe Span(_unsafeElements: _wholeGuts._object.fastUTF8)
-    span = span._extracting(first..<end)
+    span = span.extracting(first..<end)
     return unsafe _overrideLifetime(span, borrowing: self)
   }
 

stdlib/public/core/UTF8Span.swift

@@ -313,7 +313,7 @@ extension Substring {
       let base: String.UTF8View = _slice._base.utf8
       let first = base._foreignDistance(from: base.startIndex, to: startIndex)
       let count = base._foreignDistance(from: startIndex, to: endIndex)
-      let span = base._underlyingSpan()._extracting(first..<(first &+ count))
+      let span = base._underlyingSpan().extracting(first..<(first &+ count))
       return unsafe _overrideLifetime(span, borrowing: self)
     }
 #endif // _runtime(_ObjC)
@@ -329,7 +329,7 @@ extension Substring {
     let isFastUTF8 = _wholeGuts.isFastUTF8
     _precondition(isFastUTF8, "Substring must be contiguous UTF8")
     var span = unsafe Span(_unsafeElements: _wholeGuts._object.fastUTF8)
-    span = span._extracting(first..<end)
+    span = span.extracting(first..<end)
     return unsafe _overrideLifetime(span, borrowing: self)
   }
 

stdlib/public/core/UTF8SpanIterators.swift

@@ -174,7 +174,7 @@ extension UTF8Span {
     /// The resultant `UTF8Span` has the same lifetime constraints as `self`.
     @lifetime(copy self)
     public func prefix() -> UTF8Span {
-      let slice = codeUnits.span._extracting(0..<currentCodeUnitOffset)
+      let slice = codeUnits.span.extracting(0..<currentCodeUnitOffset)
       return UTF8Span(
         _uncheckedAssumingValidUTF8: slice,
         isKnownASCII: codeUnits.isKnownASCII,
@@ -187,7 +187,7 @@ extension UTF8Span {
     /// The resultant `UTF8Span` has the same lifetime constraints as `self`.
     @lifetime(copy self)
     public func suffix() -> UTF8Span {
-      let slice = codeUnits.span._extracting(currentCodeUnitOffset..<codeUnits.count)
+      let slice = codeUnits.span.extracting(currentCodeUnitOffset..<codeUnits.count)
       return UTF8Span(
         _uncheckedAssumingValidUTF8: slice,
         isKnownASCII: codeUnits.isKnownASCII,
@@ -368,7 +368,7 @@ extension UTF8Span {
     /// current position.
     @lifetime(copy self)
     public func prefix() -> UTF8Span {
-      let slice = codeUnits.span._extracting(0..<currentCodeUnitOffset)
+      let slice = codeUnits.span.extracting(0..<currentCodeUnitOffset)
       return UTF8Span(
         _uncheckedAssumingValidUTF8: slice,
         isKnownASCII: codeUnits.isKnownASCII,
@@ -379,7 +379,7 @@ extension UTF8Span {
     /// current position.
     @lifetime(copy self)
     public func suffix() -> UTF8Span {
-      let slice = codeUnits.span._extracting(currentCodeUnitOffset..<codeUnits.count)
+      let slice = codeUnits.span.extracting(currentCodeUnitOffset..<codeUnits.count)
       return UTF8Span(
         _uncheckedAssumingValidUTF8: slice,
         isKnownASCII: codeUnits.isKnownASCII,