Let deque have its capacity shrunk

Sources/DequeModule/Deque+Collection.swift

@@ -525,6 +525,22 @@ extension Deque: RangeReplaceableCollection {
     _storage.ensureUnique(minimumCapacity: minimumCapacity, linearGrowth: true)
   }
 
+  /// Reduces the capacity to store at least the specified number of elements.
+  ///
+  /// Use this method to request that the deque reduces its storage capacity.
+  /// If the capacity of the deque is larger than the target capacity then
+  /// the capacity _may_ be reduced. If the capacity of the deque is smaller
+  /// than the requested capacity, or the deque contains more elements than
+  /// the requested capacity, then the capacity won't be changed.
+  ///
+  /// - Parameters:
+  ///   - targetCapacity: The requested capacity of the deque.
+  ///
+  /// - Complexity: O(`count`)
+  public mutating func shrinkCapacity(_ targetCapacity: Int) {
+    _storage.shrink(targetCapacity: targetCapacity)
+  }
+
   /// Replaces a range of elements with the elements in the specified
   /// collection.
   ///

Sources/DequeModule/Deque+Testing.swift

@@ -41,6 +41,11 @@ extension Deque {
     _storage.capacity
   }
 
+  @_spi(Testing)
+  public var _requestedCapacity: Int {
+    _storage.requestedCapacity
+  }
+
   /// The number of the storage slot in this deque that holds the first element.
   /// (Or would hold it after an insertion in case the deque is currently
   /// empty.)
@@ -67,7 +72,10 @@ extension Deque {
     precondition(contents.count <= capacity)
     let startSlot = _Slot(at: startSlot)
     let buffer = _DequeBuffer<Element>.create(minimumCapacity: capacity) { _ in
-      _DequeBufferHeader(capacity: capacity, count: contents.count, startSlot: startSlot)
+      _DequeBufferHeader(capacity: capacity, 
+                         requestedCapacity: capacity,
+                         count: contents.count,
+                         startSlot: startSlot)
     }
     let storage = Deque<Element>._Storage(unsafeDowncast(buffer, to: _DequeBuffer.self))
     if contents.count > 0 {

Sources/DequeModule/Deque._Storage.swift

@@ -55,7 +55,10 @@ extension Deque._Storage {
         #else
         let capacity = $0.capacity
         #endif
-        return _DequeBufferHeader(capacity: capacity, count: 0, startSlot: .zero)
+        return _DequeBufferHeader(capacity: capacity,
+                                  requestedCapacity: minimumCapacity,
+                                  count: 0,
+                                  startSlot: .zero)
       })
     self.init(_buffer: _Buffer(unsafeBufferObject: object))
   }
@@ -85,6 +88,12 @@ extension Deque._Storage {
     _buffer.withUnsafeMutablePointerToHeader { $0.pointee.capacity }
   }
 
+  @inlinable
+  @inline(__always)
+  internal var requestedCapacity: Int {
+    _buffer.withUnsafeMutablePointerToHeader { $0.pointee.requestedCapacity }
+  }
+
   @inlinable
   @inline(__always)
   internal var count: Int {
@@ -94,8 +103,7 @@ extension Deque._Storage {
   @inlinable
   @inline(__always)
   internal var startSlot: _DequeSlot {
-    _buffer.withUnsafeMutablePointerToHeader { $0.pointee.startSlot
-    }
+    _buffer.withUnsafeMutablePointerToHeader { $0.pointee.startSlot }
   }
 }
 
@@ -170,6 +178,11 @@ extension Deque._Storage {
                      minimumCapacity)
   }
 
+  @usableFromInline
+  internal func _reduceCapacity(to targetCapacity: Int) -> Int {
+    return Swift.max(0, Swift.min(requestedCapacity, targetCapacity))
+  }
+
   /// Ensure that we have a uniquely referenced buffer with enough space to
   /// store at least `minimumCapacity` elements.
   ///
@@ -211,4 +224,27 @@ extension Deque._Storage {
       }
     }
   }
+
+  @inlinable
+  @inline(__always)
+  internal mutating func shrink(targetCapacity: Int) {
+    if count > targetCapacity { return }
+    if _slowPath(targetCapacity < requestedCapacity) {
+      _shrink(targetCapacity: targetCapacity)
+    }
+  }
+
+  @inlinable
+  internal mutating func _shrink(targetCapacity: Int) {
+    let minimumCapacity = _reduceCapacity(to: targetCapacity)
+    if isUnique() {
+      self = self.update { source in
+        source.moveElements(minimumCapacity: minimumCapacity)
+      }
+    } else {
+      self = self.read { source in
+        source.copyElements(minimumCapacity: minimumCapacity)
+      }
+    }
+  }
 }

Sources/DequeModule/Deque._UnsafeHandle.swift

@@ -306,6 +306,7 @@ extension Deque._UnsafeHandle {
         #endif
         return _DequeBufferHeader(
           capacity: capacity,
+          requestedCapacity: minimumCapacity,
           count: count,
           startSlot: .zero)
       })
@@ -340,6 +341,7 @@ extension Deque._UnsafeHandle {
         #endif
         return _DequeBufferHeader(
           capacity: capacity,
+          requestedCapacity: minimumCapacity,
           count: count,
           startSlot: .zero)
       })

Sources/DequeModule/_DequeBuffer.swift

@@ -44,6 +44,6 @@ extension _DequeBuffer: CustomStringConvertible {
 internal let _emptyDequeStorage = _DequeBuffer<Void>.create(
   minimumCapacity: 0,
   makingHeaderWith: { _ in
-    _DequeBufferHeader(capacity: 0, count: 0, startSlot: .init(at: 0))
+    _DequeBufferHeader(capacity: 0, requestedCapacity: 0, count: 0, startSlot: .init(at: 0))
   })
 

Sources/DequeModule/_DequeBufferHeader.swift

@@ -14,15 +14,19 @@ internal struct _DequeBufferHeader {
   @usableFromInline
   var capacity: Int
 
+  @usableFromInline
+  var requestedCapacity: Int
+
   @usableFromInline
   var count: Int
 
   @usableFromInline
   var startSlot: _DequeSlot
 
   @usableFromInline
-  init(capacity: Int, count: Int, startSlot: _DequeSlot) {
+  init(capacity: Int, requestedCapacity: Int, count: Int, startSlot: _DequeSlot) {
     self.capacity = capacity
+    self.requestedCapacity = requestedCapacity
     self.count = count
     self.startSlot = startSlot
     _checkInvariants()
@@ -32,6 +36,7 @@ internal struct _DequeBufferHeader {
   @usableFromInline @inline(never) @_effects(releasenone)
   internal func _checkInvariants() {
     precondition(capacity >= 0)
+    precondition(requestedCapacity <= capacity)
     precondition(count >= 0 && count <= capacity)
     precondition(startSlot.position >= 0 && startSlot.position <= capacity)
   }

Tests/DequeTests/DequeTests.swift

@@ -374,5 +374,40 @@ final class DequeTests: CollectionTestCase {
     }
   }
 
+  func test_shrinkCapacityWhenEmpty() {
+    withEvery("capacity", in: [0, 1, 2, 5, 10, 50, 100]) { capacity in
+      var deque = Deque<Int>(minimumCapacity: capacity)
+
+      XCTAssertGreaterThanOrEqual(deque._capacity, capacity)
+      XCTAssertLessThanOrEqual(deque._requestedCapacity, capacity)
+
+      let actual = deque._capacity
+      let reducedCapacity = deque._requestedCapacity / 4
+      deque.shrinkCapacity(reducedCapacity)
+
+      print(actual, deque._capacity)
+      // Shrinkage isn't guaranteed.
+      XCTAssertGreaterThanOrEqual(deque._capacity, reducedCapacity)
+      XCTAssertLessThanOrEqual(deque._requestedCapacity, reducedCapacity)
+    }
+  }
+
+  func test_shrinkCapacityWhenMoreElementsThanTarget() {
+    withEvery("count", in: [0, 1, 2, 5, 10, 50, 100]) { count in
+      var deque = Deque(repeating: 0, count: count)
+      let capacity = deque._capacity
+      deque.shrinkCapacity(0)
+      XCTAssertEqual(deque._capacity, capacity)
+    }
+  }
+
+  func test_shrinkCapacityWhenTargetIsLargerThanCurrent() {
+    withEvery("capacity", in: [0, 1, 2, 5, 10, 50, 100]) { capacity in
+      var deque = Deque<Int>(minimumCapacity: capacity)
+      let capacity = deque._capacity
+      deque.shrinkCapacity(capacity + 1)
+      XCTAssertEqual(deque._capacity, capacity)
+    }
+  }
 }