[stdlib] de-underscore the extracting() methods

glessard · glessard · commit 3e893c22870f · 2025-03-11T22:59:53.000-07:00
diff --git a/stdlib/public/core/Span/MutableRawSpan.swift b/stdlib/public/core/Span/MutableRawSpan.swift
@@ -439,13 +439,13 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(_ bounds: Range<Int>) -> Self {
+  mutating public func extracting(_ bounds: Range<Int>) -> 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)
   }
 
   /// Constructs a new span over the items within the supplied range of
@@ -466,7 +466,7 @@ extension MutableRawSpan {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(unchecked bounds: Range<Int>) -> Self {
+  mutating public func extracting(unchecked bounds: Range<Int>) -> Self {
     let newStart = unsafe _pointer?.advanced(by: bounds.lowerBound)
     let newSpan = unsafe Self(_unchecked: newStart, byteCount: bounds.count)
     return unsafe _overrideLifetime(newSpan, mutating: &self)
@@ -487,10 +487,10 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(
+  mutating public func extracting(
     _ bounds: some RangeExpression<Int>
   ) -> Self {
-    _extracting(bounds.relative(to: byteOffsets))
+    extracting(bounds.relative(to: byteOffsets))
   }
 
   /// Constructs a new span over the items within the supplied range of
@@ -511,11 +511,11 @@ extension MutableRawSpan {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(unchecked bounds: ClosedRange<Int>) -> Self {
+  mutating 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)
   }
 
   /// Constructs a new span over all the items of this span.
@@ -529,7 +529,7 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(_: UnboundedRange) -> Self {
+  mutating public func extracting(_: UnboundedRange) -> Self {
     let newSpan = unsafe Self(_unchecked: _start(), byteCount: _count)
     return unsafe _overrideLifetime(newSpan, mutating: &self)
   }
@@ -556,7 +556,7 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(first maxLength: Int) -> Self {
+  mutating 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)
@@ -579,7 +579,7 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(droppingLast k: Int) -> Self {
+  mutating public func extracting(droppingLast k: Int) -> Self {
     _precondition(k >= 0, "Can't drop a negative number of elements")
     let droppedCount = min(k, byteCount)
     let newCount = byteCount &- droppedCount
@@ -604,7 +604,7 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(last maxLength: Int) -> Self {
+  mutating 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)
@@ -628,7 +628,7 @@ extension MutableRawSpan {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(droppingFirst k: Int) -> Self {
+  mutating 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)
diff --git a/stdlib/public/core/Span/MutableSpan.swift b/stdlib/public/core/Span/MutableSpan.swift
@@ -645,13 +645,13 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(_ bounds: Range<Index>) -> Self {
+  mutating 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)
   }
 
   /// Constructs a new span over the items within the supplied range of
@@ -672,7 +672,7 @@ extension MutableSpan where Element: ~Copyable {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(unchecked bounds: Range<Index>) -> Self {
+  mutating 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 Self(_unchecked: newStart, count: bounds.count)
@@ -694,10 +694,10 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(
+  mutating public func extracting(
     _ bounds: some RangeExpression<Index>
   ) -> Self {
-    _extracting(bounds.relative(to: indices))
+    extracting(bounds.relative(to: indices))
   }
 
   /// Constructs a new span over the items within the supplied range of
@@ -718,13 +718,13 @@ extension MutableSpan where Element: ~Copyable {
   @unsafe
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(
+  mutating 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)
   }
 
   /// Constructs a new span over all the items of this span.
@@ -738,7 +738,7 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(_: UnboundedRange) -> Self {
+  mutating public func extracting(_: UnboundedRange) -> Self {
     let newSpan = unsafe Self(_unchecked: _start(), count: _count)
     return unsafe _overrideLifetime(newSpan, mutating: &self)
   }
@@ -765,7 +765,7 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(first maxLength: Int) -> Self {
+  mutating 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)
@@ -788,7 +788,7 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(droppingLast k: Int) -> Self {
+  mutating public func extracting(droppingLast k: Int) -> Self {
     _precondition(k >= 0, "Can't drop a negative number of elements")
     let droppedCount = min(k, count)
     let newCount = count &- droppedCount
@@ -813,7 +813,7 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(last maxLength: Int) -> Self {
+  mutating 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
@@ -838,7 +838,7 @@ extension MutableSpan where Element: ~Copyable {
   /// - Complexity: O(1)
   @_alwaysEmitIntoClient
   @lifetime(borrow self)
-  mutating public func _extracting(droppingFirst k: Int) -> Self {
+  mutating 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
diff --git a/test/stdlib/Span/MutableRawSpanTests.swift b/test/stdlib/Span/MutableRawSpanTests.swift
@@ -214,7 +214,7 @@ suite.test("unsafeLoadUnaligned(as:)")
   a.withUnsafeMutableBytes {
     var span = MutableRawSpan(_unsafeBytes: $0)
 
-    let suffix = span._extracting(droppingFirst: 2)
+    let suffix = span.extracting(droppingFirst: 2)
     let u0 = suffix.unsafeLoadUnaligned(as: UInt64.self)
     expectEqual(u0 & 0xff, 2)
     expectEqual(u0.byteSwapped & 0xff, 9)
@@ -350,7 +350,7 @@ suite.test("update(fromContentsOf:) (contiguous memory)")
   expectEqual(a.elementsEqual(0..<capacity), true)
 }
 
-suite.test("_extracting()")
+suite.test("extracting()")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -363,25 +363,25 @@ suite.test("_extracting()")
   b.withUnsafeMutableBytes {
     var span = MutableRawSpan(_unsafeBytes: $0)
 
-    var sub = span._extracting(0..<2)
+    var sub = span.extracting(0..<2)
     expectEqual(sub.byteCount, 2)
     expectEqual(sub.unsafeLoad(as: UInt8.self), 0)
 
-    sub = span._extracting(..<2)
+    sub = span.extracting(..<2)
     expectEqual(sub.byteCount, 2)
     expectEqual(sub.unsafeLoad(as: UInt8.self), 0)
 
-    sub = span._extracting(...)
+    sub = span.extracting(...)
     expectEqual(sub.byteCount, 4)
     expectEqual(sub.unsafeLoad(as: UInt8.self), 0)
 
-    sub = span._extracting(2...)
+    sub = span.extracting(2...)
     expectEqual(sub.byteCount, 2)
     expectEqual(sub.unsafeLoad(as: UInt8.self), 2)
   }
 }
 
-suite.test("_extracting(unchecked:)")
+suite.test("extracting(unchecked:)")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -393,14 +393,14 @@ suite.test("_extracting(unchecked:)")
   var b = (0..<capacity).map(UInt8.init)
   b.withUnsafeMutableBytes {
     var span = MutableRawSpan(_unsafeBytes: $0.prefix(8))
-    let beyond = span._extracting(unchecked: 16...23)
+    let beyond = span.extracting(unchecked: 16...23)
     expectEqual(beyond.byteCount, 8)
     let fromBeyond = beyond.unsafeLoad(as: UInt8.self)
     expectEqual(fromBeyond, 16)
   }
 }
 
-suite.test("_extracting prefixes")
+suite.test("extracting prefixes")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -415,19 +415,19 @@ suite.test("_extracting prefixes")
     var span = MutableRawSpan(_unsafeBytes: $0)
     expectEqual(span.byteCount, capacity)
 
-    prefix = span._extracting(first: 1)
+    prefix = span.extracting(first: 1)
     expectEqual(prefix.unsafeLoad(as: UInt8.self), 0)
 
-    prefix = span._extracting(first: capacity)
+    prefix = span.extracting(first: capacity)
     expectEqual(
       prefix.unsafeLoad(fromByteOffset: capacity-1, as: UInt8.self),
       UInt8(capacity-1)
     )
 
-    prefix = span._extracting(droppingLast: capacity)
+    prefix = span.extracting(droppingLast: capacity)
     expectEqual(prefix.isEmpty, true)
 
-    prefix = span._extracting(droppingLast: 1)
+    prefix = span.extracting(droppingLast: 1)
     expectEqual(
       prefix.unsafeLoad(fromByteOffset: capacity-2, as: UInt8.self),
       UInt8(capacity-2)
@@ -438,12 +438,12 @@ suite.test("_extracting prefixes")
     let b = UnsafeMutableRawBufferPointer(start: nil, count: 0)
     var span = MutableRawSpan(_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("_extracting suffixes")
+suite.test("extracting suffixes")
 .skip(.custom(
   { if #available(SwiftStdlib 6.2, *) { false } else { true } },
   reason: "Requires Swift 6.2's standard library"
@@ -458,27 +458,27 @@ suite.test("_extracting suffixes")
     var span = MutableRawSpan(_unsafeBytes: $0)
     expectEqual(span.byteCount, capacity)
 
-    prefix = span._extracting(last: capacity)
+    prefix = span.extracting(last: capacity)
     expectEqual(prefix.unsafeLoad(as: UInt8.self), 0)
 
-    prefix = span._extracting(last: capacity-1)
+    prefix = span.extracting(last: capacity-1)
     expectEqual(prefix.unsafeLoad(as: UInt8.self), 1)
 
-    prefix = span._extracting(last: 1)
+    prefix = span.extracting(last: 1)
     expectEqual(prefix.unsafeLoad(as: UInt8.self), UInt8(capacity-1))
 
-    prefix = span._extracting(droppingFirst: capacity)
+    prefix = span.extracting(droppingFirst: capacity)
     expectTrue(prefix.isEmpty)
 
-    prefix = span._extracting(droppingFirst: 1)
+    prefix = span.extracting(droppingFirst: 1)
     expectEqual(prefix.unsafeLoad(as: UInt8.self), 1)
   }
 
   do {
     let b = UnsafeMutableRawBufferPointer(start: nil, count: 0)
     var span = MutableRawSpan(_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)
   }
 }
diff --git a/test/stdlib/Span/MutableSpanTests.swift b/test/stdlib/Span/MutableSpanTests.swift
