/// Provides a dynamically-resizing array that is initially backed by a stack
/// allocation of the requested capacity, spilling over to the heap only if it
/// grows beyond it.
///
/// This is the primary way to create a `TemporaryArray`. The array passed to
/// `body` starts empty with room for `capacity` elements. As long as the
/// array's element count stays at or below that capacity, no heap allocation
/// occurs, provided the requested storage fits within the stack budget.
///
/// To keep latency predictable, the initial buffer is placed on the stack only
/// if it occupies at most 1024 bytes; a larger initial `capacity` is heap
/// allocated up front instead. Either way the array grows on the heap once it
/// exceeds its initial capacity.
///
/// The array cannot escape `body` (it is non-escapable), so when nothing is
/// moved out, small inputs never touch the heap:
///
///     let sum = withTemporaryArray(of: Int.self, capacity: 64) { scratch in
///       for x in numbers where isHot(x) {
///         scratch.append(x * x)
///       }
///       var total = 0
///       for i in scratch.indices { total += scratch[i] }
///       return total
///     }
///
/// To keep the elements themselves, move them into an owning container with
/// `take()`.
///
/// - Parameters:
///   - type: The element type of the array.
///   - capacity: The number of elements to reserve up front.
///   - body: A closure that receives the freshly created, empty array.
/// - Returns: The result of `body`.
func withTemporaryArray<Element: ~Copyable, E: Error, R: ~Copyable>(
  of type: Element.Type,
  capacity: Int,
  _ body: (inout TemporaryArray<Element>) throws(E) -> R
) throws(E) -> R

struct TemporaryArray<Element: ~Copyable>: ~Copyable, ~Escapable {

  /// Move the contents of this array into a newly created `UniqueArray`,
  /// leaving this array empty.
  ///
  /// Use this to hand the accumulated elements back out of the scope that owns
  /// the array's seed buffer: the result is an ordinary heap-backed, escapable
  /// container. If the array had already spilled to the heap, its existing
  /// storage is transferred without copying; otherwise the elements are moved
  /// out of the borrowed buffer into a fresh allocation.
  ///
  /// - Complexity: O(1) if the array has already spilled to the heap;
  ///    O(`count`) otherwise.
  mutating func take() -> UniqueArray<Element>

}

extension TemporaryArray /* where Element: Copyable */ {
  /// Appends `count` copies of `repeatedValue` to the end of the array, growing
  /// (and, if needed, spilling to the heap) to make room.
  ///
  /// This is `TemporaryArray`'s analogue of `UniqueArray`'s
  /// `init(repeating:count:)`: it's an append rather than an initializer,
  /// because a `TemporaryArray` is meant to be seeded (typically on the stack)
  /// via `withTemporaryArray` and then filled.
  ///
  /// - Complexity: O(`count`), amortized.
  mutating func append(repeating: Element, count: Int)
}

extension TemporaryArray where Element: ~Copyable {

  // Initializers
  @_lifetime(immortal) init()
  @_lifetime(immortal) init(capacity: Int)
  @_lifetime(immortal) init<E>(capacity: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)

  // Basics
  var capacity: Int
  var freeCapacity: Int
  @_lifetime(borrow self) var span: Span<Element>
  @_lifetime(&self) var mutableSpan: MutableSpan<Element>
  func isTriviallyIdentical(to: borrowing Self) -> Bool
  mutating func edit<E, R>(_: (inout OutputSpan<Element>) throws(E) -> R) throws(E) -> R
  mutating func reallocate(capacity: Int)
  mutating func reserveCapacity(_: Int)

  // Collection
  typealias Index = Int
  var isEmpty: Bool
  var count: Int
  var startIndex: Int
  var endIndex: Int
  var indices: Range<Int>
  subscript(position: Int) -> Element
  mutating func swapAt(_: Int, _: Int)
  func index(after: Int) -> Int
  func index(before: Int) -> Int
  func formIndex(after: inout Int)
  func formIndex(before: inout Int)
  func index(_: Int, offsetBy: Int) -> Int
  func distance(from: Int, to: Int) -> Int
  func formIndex(_: inout Int, offsetBy: inout Int, limitedBy: Int)

  // Appends
  mutating func append(_: consuming Element)
  mutating func append<E>(addingCount: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)
  mutating func append(moving: UnsafeMutableBufferPointer<Element>)
  mutating func append(moving: inout OutputSpan<Element>)
  mutating func append(copying: UnsafeBufferPointer<Element>)
  mutating func append(copying: UnsafeMutableBufferPointer<Element>)
  mutating func append(copying: Span<Element>)
  mutating func append(copying: some Sequence<Element>)

  // Insertions
  mutating func insert(_: consuming Element, at: Int)
  mutating func insert<E>(addingCount: Int, at: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)
  mutating func insert(moving: UnsafeMutableBufferPointer<Element>, at: Int)
  mutating func insert(moving: inout OutputSpan<Element>, at: Int)
  mutating func insert(copying: UnsafeBufferPointer<Element>, at: Int)
  mutating func insert(copying: UnsafeMutableBufferPointer<Element>, at: Int)
  mutating func insert(copying: Span<Element>, at: Int)
  mutating func insert(copying: some Collection<Element>, at: Int)

  // Removals
  mutating func popLast() -> Element?
  mutating func removeLast() -> Element
  mutating func removeLast(_ k: Int)
  mutating func remove(at: Int) -> Element
  mutating func removeSubrange(_: Range<Index>)
  mutating func removeSubrange(_: some RangeExpression<Index>)
  mutating func removeAll(keepingCapacity: Bool = false)

  // Replacements
  mutating func replaceSubrange<E>(_: Range<Int>, addingCount: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)
  mutating func replaceSubrange(_: Range<Int>, moving: UnsafeMutableBufferPointer<Element>)
  mutating func replaceSubrange(_: Range<Int>, moving: inout OutputSpan<Element>)
  mutating func replaceSubrange(_: Range<Int>, copying: UnsafeBufferPointer<Element>)
  mutating func replaceSubrange(_: Range<Int>, copying: UnsafeMutableBufferPointer<Element>)
  mutating func replaceSubrange(_: Range<Int>, copying: Span<Element>)
  mutating func replaceSubrange(_: Range<Int>, copying: some Collection<Element>)

  // Consumption (closure-based; needs no stored back-reference)
  mutating func consume(_: Range<Index>, consumingWith: (inout InputSpan<Element>) -> Void)
  mutating func replace<E>(removing: Range<Int>, consumingWith: (inout InputSpan<Element>) -> Void, addingCount: Int, initializingWith: (inout OutputSpan<Element>) throws(E) -> Void) throws(E)

  // Copying (Element: Copyable): result owns its storage; pair with take()
  @_lifetime(immortal) func clone() -> Self
  @_lifetime(immortal) func clone(capacity: Int) -> Self

  // Bulk access
  @_lifetime(borrow self) func nextSpan(after: inout Int, maximumCount: Int) -> Span<Element>
  @_lifetime(&self) mutating func nextMutableSpan(after: inout Int, maximumCount: Int) -> MutableSpan<Element>
  @_lifetime(borrow self) func previousSpan(before: inout Int, maximumCount: Int) -> Span<Element>
}

extension TemporaryArray: Equatable where Element: Equatable & ~Copyable {
  static func == (_: borrowing Self, _: borrowing Self) -> Bool
}

extension TemporaryArray: Iterable_ where Element: ~Copyable {
  typealias IterableIterator_ = SpanIterator<Element>
  var underestimatedCount_: Int
  @_lifetime(borrow self) func makeIterableIterator_() -> IterableIterator_
}

extension TemporaryArray: Container              where Element: ~Copyable {}
extension TemporaryArray: BidirectionalContainer where Element: ~Copyable {}
extension TemporaryArray: RandomAccessContainer  where Element: ~Copyable {}

// Methods implemented; conformance pending protocol support for ~Copyable/~Escapable:
extension TemporaryArray /*: Hashable */ where Element: Hashable {
  func hash(into: inout Hasher)
}
extension TemporaryArray /*: CustomStringConvertible */ where Element: ~Copyable {
  var description: String
}
extension TemporaryArray /*: CustomDebugStringConvertible */ where Element: ~Copyable {
  var debugDescription: String
}

// Value-populating initializers (Element: Copyable)
init(repeating: Element, count: Int)                        // use append(repeating:count:) instead
init(capacity: Int? = nil, copying: Span<Element>)          // use append(copying: Span<Element>) instead
init(capacity: Int? = nil, copying: some Sequence<Element>) // use append(copying: some Sequence<Element>) instead

// Non-proposal consumption helpers carried by the concrete UniqueArray type
mutating func consumeAll(consumingWith: (inout InputSpan<Element>) -> Void)
mutating func consumeLast(_: Int, consumingWith: (inout InputSpan<Element>) -> Void)
mutating func consume<R: RangeExpression<Index>>(_: R, consumingWith: (inout InputSpan<Element>) -> Void)

// Not available, blocked by ~Escapable: 
// DynamicContainer, RangeReplaceableContainer, MutableContainer