[stdlib] rename RawSpan.extracting functions

Author: glessard

stdlib/public/core/Span/RawSpan.swift

@@ -378,13 +378,20 @@ extension RawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(_ bounds: Range<Int>) -> Self {
+  public func extracting(_ bounds: Range<Int>) -> Self {
     _precondition(
       UInt(bitPattern: bounds.lowerBound) <= UInt(bitPattern: _count) &&
       UInt(bitPattern: bounds.upperBound) <= UInt(bitPattern: _count),
       "Byte offset 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<Int>) -> Self {
+    extracting(bounds)
   }
 
   /// Constructs a new span over the bytes within the supplied range of
@@ -405,12 +412,20 @@ extension RawSpan {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(unchecked bounds: Range<Int>) -> Self {
+  public func extracting(unchecked bounds: Range<Int>) -> Self {
     let newStart = unsafe _pointer?.advanced(by: bounds.lowerBound)
     let newSpan = unsafe RawSpan(_unchecked: newStart, byteCount: bounds.count)
     return unsafe _overrideLifetime(newSpan, copying: self)
   }
 
+  @unsafe
+  @available(*, deprecated, renamed: "extracting(unchecked:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
+  public func _extracting(unchecked bounds: Range<Int>) -> Self {
+    unsafe extracting(unchecked: bounds)
+  }
+
   /// Constructs a new span over the bytes within the supplied range of
   /// positions within this span.
   ///
@@ -426,8 +441,15 @@ extension RawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(copy self)
+  public func extracting(_ bounds: some RangeExpression<Int>) -> Self {
+    extracting(bounds.relative(to: byteOffsets))
+  }
+
+  @available(*, deprecated, renamed: "extracting(_:)")
+  @_alwaysEmitIntoClient
+  @lifetime(copy self)
   public func _extracting(_ bounds: some RangeExpression<Int>) -> Self {
-    _extracting(bounds.relative(to: byteOffsets))
+    extracting(bounds)
   }
 
   /// Constructs a new span over the bytes within the supplied range of
@@ -448,13 +470,21 @@ extension RawSpan {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(copy self)
-  public func _extracting(
+  public func extracting(
     unchecked bounds: ClosedRange<Int>
   ) -> 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<Int>) -> Self {
+    unsafe extracting(unchecked: bounds)
   }
 
   /// Constructs a new span over all the bytes of this span.
@@ -468,6 +498,13 @@ extension RawSpan {
   /// - 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
   }
@@ -708,13 +745,20 @@ extension RawSpan {
   /// - 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, byteCount)
     let newSpan = unsafe Self(_unchecked: _pointer, byteCount: 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 bytes.
   ///
   /// If the number of elements to drop exceeds the number of elements in
@@ -731,14 +775,21 @@ extension RawSpan {
   /// - 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 bytes")
     let droppedCount = min(k, byteCount)
     let count = byteCount &- droppedCount
     let newSpan = unsafe Self(_unchecked: _pointer, byteCount: count)
     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 trailing bytes of the span,
   /// up to the given maximum length.
   ///
@@ -756,7 +807,7 @@ extension RawSpan {
   /// - 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, byteCount)
     let newStart = unsafe _pointer?.advanced(by: byteCount &- newCount)
@@ -766,6 +817,13 @@ extension RawSpan {
     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 bytes.
   ///
   /// If the number of elements to drop exceeds the number of bytes in
@@ -782,7 +840,7 @@ extension RawSpan {
   /// - 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 bytes")
     let droppedCount = min(k, byteCount)
     let newStart = unsafe _pointer?.advanced(by: droppedCount)
@@ -792,4 +850,11 @@ extension RawSpan {
     // lifetime of 'self'. 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)
+  }
 }

test/stdlib/Span/RawSpanTests.swift

@@ -129,7 +129,7 @@ suite.test("unsafeLoadUnaligned(as:)")
   a.withUnsafeBytes {
     let span = RawSpan(_unsafeBytes: $0)
 
-    let suffix = span._extracting(droppingFirst: 2)
+    let suffix = span.extracting(droppingFirst: 2)
     let u0 = suffix.unsafeLoadUnaligned(as: UInt64.self)
     expectEqual(u0.littleEndian & 0xff, 2)
     expectEqual(u0.bigEndian & 0xff, 9)
@@ -139,7 +139,7 @@ suite.test("unsafeLoadUnaligned(as:)")
   }
 }
 
-suite.test("_extracting() functions")
+suite.test("extracting() functions")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -151,10 +151,10 @@ suite.test("_extracting() functions")
   let b = (0..<capacity).map(Int8.init)
   b.withUnsafeBytes {
     let span = RawSpan(_unsafeBytes: $0)
-    let sub1 = span._extracting(0..<2)
-    let sub2 = span._extracting(..<2)
-    let sub3 = span._extracting(...)
-    let sub4 = span._extracting(2...)
+    let sub1 = span.extracting(0..<2)
+    let sub2 = span.extracting(..<2)
+    let sub3 = span.extracting(...)
+    let sub4 = span.extracting(2...)
 
     sub1.withUnsafeBytes { p1 in
       sub2.withUnsafeBytes { p2 in
@@ -174,7 +174,7 @@ suite.test("_extracting() functions")
   }
 }
 
-suite.test("_extracting(unchecked:) functions")
+suite.test("extracting(unchecked:) functions")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -186,14 +186,14 @@ suite.test("_extracting(unchecked:) functions")
   let b = (0..<capacity).map(UInt8.init)
   b.withUnsafeBytes {
     let span = RawSpan(_unsafeBytes: $0)
-    let prefix = span._extracting(0..<8)
-    let beyond = prefix._extracting(unchecked: 16...23)
+    let prefix = span.extracting(0..<8)
+    let beyond = prefix.extracting(unchecked: 16...23)
     expectEqual(beyond.byteCount, 8)
     expectEqual(beyond.unsafeLoad(as: UInt8.self), 16)
   }
 }
 
-suite.test("prefix _extracting() functions")
+suite.test("prefix extracting() functions")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -206,35 +206,35 @@ suite.test("prefix _extracting() functions")
   a.withUnsafeBytes {
     let span = RawSpan(_unsafeBytes: $0)
     expectEqual(span.byteCount, capacity)
-    expectEqual(span._extracting(first: 1).unsafeLoad(as: UInt8.self), 0)
+    expectEqual(span.extracting(first: 1).unsafeLoad(as: UInt8.self), 0)
     expectEqual(
-      span._extracting(first: capacity).unsafeLoad(
+      span.extracting(first: capacity).unsafeLoad(
         fromByteOffset: capacity-1, as: UInt8.self
       ),
       UInt8(capacity-1)
     )
-    expectTrue(span._extracting(droppingLast: capacity).isEmpty)
+    expectTrue(span.extracting(droppingLast: capacity).isEmpty)
     expectEqual(
-      span._extracting(droppingLast: 1).unsafeLoad(
+      span.extracting(droppingLast: 1).unsafeLoad(
         fromByteOffset: capacity-2, as: UInt8.self
       ),
       UInt8(capacity-2)
     )
-    let emptySpan = span._extracting(first: 0)
-    let emptierSpan = emptySpan._extracting(0..<0)
+    let emptySpan = span.extracting(first: 0)
+    let emptierSpan = emptySpan.extracting(0..<0)
     expectTrue(emptySpan.isIdentical(to: emptierSpan))
   }
 
   do {
     let b = UnsafeRawBufferPointer(start: nil, count: 0)
     let span = RawSpan(_unsafeBytes: b)
     expectEqual(span.byteCount, b.count)
-    expectEqual(span._extracting(first: 1).byteCount, b.count)
-    expectEqual(span._extracting(droppingLast: 1).byteCount, b.count)
+    expectEqual(span.extracting(first: 1).byteCount, b.count)
+    expectEqual(span.extracting(droppingLast: 1).byteCount, b.count)
   }
 }
 
-suite.test("suffix _extracting() functions")
+suite.test("suffix extracting() functions")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -247,19 +247,19 @@ suite.test("suffix _extracting() functions")
   a.withUnsafeBytes {
     let span = RawSpan(_unsafeBytes: $0)
     expectEqual(span.byteCount, capacity)
-    expectEqual(span._extracting(last: capacity).unsafeLoad(as: UInt8.self), 0)
-    expectEqual(span._extracting(last: capacity-1).unsafeLoad(as: UInt8.self), 1)
-    expectEqual(span._extracting(last: 1).unsafeLoad(as: UInt8.self), UInt8(capacity-1))
-    expectTrue(span._extracting(droppingFirst: capacity).isEmpty)
-    expectEqual(span._extracting(droppingFirst: 1).unsafeLoad(as: UInt8.self), 1)
+    expectEqual(span.extracting(last: capacity).unsafeLoad(as: UInt8.self), 0)
+    expectEqual(span.extracting(last: capacity-1).unsafeLoad(as: UInt8.self), 1)
+    expectEqual(span.extracting(last: 1).unsafeLoad(as: UInt8.self), UInt8(capacity-1))
+    expectTrue(span.extracting(droppingFirst: capacity).isEmpty)
+    expectEqual(span.extracting(droppingFirst: 1).unsafeLoad(as: UInt8.self), 1)
   }
 
   do {
     let b = UnsafeRawBufferPointer(start: nil, count: 0)
     let span = RawSpan(_unsafeBytes: b)
     expectEqual(span.byteCount, b.count)
-    expectEqual(span._extracting(last: 1).byteCount, b.count)
-    expectEqual(span._extracting(droppingFirst: 1).byteCount, b.count)
+    expectEqual(span.extracting(last: 1).byteCount, b.count)
+    expectEqual(span.extracting(droppingFirst: 1).byteCount, b.count)
   }
 }
 
@@ -304,9 +304,9 @@ suite.test("byteOffsets(of:)")
   defer { b.deallocate() }
 
   let span = RawSpan(_unsafeBytes: b)
-  let subSpan1 = span._extracting(first: 6)
-  let subSpan2 = span._extracting(last: 6)
-  let emptySpan = span._extracting(first: 0)
+  let subSpan1 = span.extracting(first: 6)
+  let subSpan2 = span.extracting(last: 6)
+  let emptySpan = span.extracting(first: 0)
   let nilBuffer = UnsafeRawBufferPointer(start: nil, count: 0)
   let nilSpan = RawSpan(_unsafeBytes: nilBuffer)