[stdlib] add extracting() to MutableSpan and MutableRawSpan

Author: glessard

stdlib/public/core/Span/MutableRawSpan.swift

@@ -417,3 +417,231 @@ extension MutableRawSpan {
     update(startingAt: byteOffset, from: source.bytes)
   }
 }
+
+// MARK: sub-spans
+@available(SwiftStdlib 6.2, *)
+extension MutableRawSpan {
+
+  /// Constructs a new span over the items within the supplied range of
+  /// positions within this span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Parameter bounds: A valid range of positions. Every position in
+  ///     this range must be within the bounds of this `MutableSpan`.
+  ///
+  /// - Returns: A `MutableSpan` over the items within `bounds`
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow 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 _extracting(unchecked: bounds)
+  }
+
+  /// Constructs a new span over the items within the supplied range of
+  /// positions within this span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// This function does not validate `bounds`; this is an unsafe operation.
+  ///
+  /// - Parameter bounds: A valid range of positions. Every position in
+  ///     this range must be within the bounds of this `MutableSpan`.
+  ///
+  /// - Returns: A `MutableSpan` over the items within `bounds`
+  ///
+  /// - Complexity: O(1)
+  @unsafe
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(unchecked bounds: Range<Int>) -> Self {
+    let newStart = _pointer?.advanced(by: bounds.lowerBound)
+    let newSpan = Self(_unchecked: newStart, byteCount: bounds.count)
+    return _overrideLifetime(newSpan, mutating: &self)
+  }
+
+  /// Constructs a new span over the items within the supplied range of
+  /// positions within this span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Parameter bounds: A valid range of positions. Every position in
+  ///     this range must be within the bounds of this `MutableSpan`.
+  ///
+  /// - Returns: A `MutableSpan` over the items within `bounds`
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(
+    _ bounds: some RangeExpression<Int>
+  ) -> Self {
+    _extracting(bounds.relative(to: byteOffsets).clamped(to: byteOffsets))
+  }
+
+  /// Constructs a new span over the items within the supplied range of
+  /// positions within this span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// This function does not validate `bounds`; this is an unsafe operation.
+  ///
+  /// - Parameter bounds: A valid range of positions. Every position in
+  ///     this range must be within the bounds of this `MutableSpan`.
+  ///
+  /// - Returns: A `MutableSpan` over the items within `bounds`
+  ///
+  /// - Complexity: O(1)
+  @unsafe
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(
+    unchecked bounds: some RangeExpression<Int>
+  ) -> Self {
+    _extracting(
+      unchecked: bounds.relative(to: byteOffsets).clamped(to: byteOffsets)
+    )
+  }
+
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(
+    unchecked bounds: ClosedRange<Int>
+  ) -> Self {
+    let range = Range(
+      _uncheckedBounds: (bounds.lowerBound, bounds.upperBound&+1)
+    )
+    return _extracting(unchecked: range)
+  }
+
+  /// Constructs a new span over all the items of this span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Returns: A `MutableSpan` over all the items of this span.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(_: UnboundedRange) -> Self {
+    let newSpan = Self(_unchecked: _start(), byteCount: _count)
+    return _overrideLifetime(newSpan, mutating: &self)
+  }
+}
+
+// MARK: prefixes and suffixes
+@available(SwiftStdlib 6.2, *)
+extension MutableRawSpan {
+
+  /// Returns a span containing the initial elements of this span,
+  /// up to the specified maximum length.
+  ///
+  /// If the maximum length exceeds the length of this span,
+  /// the result contains all the elements.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Parameter maxLength: The maximum number of elements to return.
+  ///   `maxLength` must be greater than or equal to zero.
+  /// - Returns: A span with at most `maxLength` elements.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow 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 = Self(_unchecked: _pointer, byteCount: newCount)
+    return _overrideLifetime(newSpan, mutating: &self)
+  }
+
+  /// 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
+  /// the span, the result is an empty span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Parameter k: The number of elements to drop off the end of
+  ///   the span. `k` must be greater than or equal to zero.
+  /// - Returns: A span leaving off the specified number of elements at the end.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(droppingLast k: Int) -> Self {
+    _precondition(k >= 0, "Can't drop a negative number of elements")
+    let dropped = min(k, byteCount)
+    let newSpan = Self(_unchecked: _pointer, byteCount: byteCount &- dropped)
+    return _overrideLifetime(newSpan, mutating: &self)
+  }
+
+  /// Returns a span containing the final elements of the span,
+  /// up to the given maximum length.
+  ///
+  /// If the maximum length exceeds the length of this span,
+  /// the result contains all the elements.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Parameter maxLength: The maximum number of elements to return.
+  ///   `maxLength` must be greater than or equal to zero.
+  /// - Returns: A span with at most `maxLength` elements.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow 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 = _pointer?.advanced(by: byteCount &- newCount)
+    let newSpan = Self(_unchecked: newStart, byteCount: newCount)
+    return _overrideLifetime(newSpan, copying: self)
+  }
+
+  /// 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
+  /// the span, the result is an empty span.
+  ///
+  /// The returned span's first item is always at offset 0; unlike buffer
+  /// slices, extracted spans do not share their indices with the
+  /// span from which they are extracted.
+  ///
+  /// - Parameter k: The number of elements to drop from the beginning of
+  ///   the span. `k` must be greater than or equal to zero.
+  /// - Returns: A span starting after the specified number of elements.
+  ///
+  /// - Complexity: O(1)
+  @_alwaysEmitIntoClient
+  @lifetime(borrow self)
+  mutating public func _extracting(droppingFirst k: Int) -> Self {
+    _precondition(k >= 0, "Can't drop a negative number of bytes")
+    let dropped = min(k, byteCount)
+    let newStart = _pointer?.advanced(by: dropped)
+    let newSpan = Self(_unchecked: newStart, byteCount: byteCount &- dropped)
+    return _overrideLifetime(newSpan, mutating: &self)
+  }
+}