mirror of
https://github.com/apple/swift-collections
synced 2026-11-22 04:20:40 +00:00
TemporaryArray is a ~Copyable and ~Escapable dynamic array whose initial storage is a borrowed buffer (most usefully a stack allocation vended by withTemporaryArray(of:capacity:_:)) and which transparently spills over into freshly allocated heap storage once it outgrows that seed buffer. As long as the element count stays within a seed buffer that fit on the stack, the array incurs no heap traffic at all. Because it can hold a dependency on borrowed (stack) memory, the type is non-escapable: instances cannot outlive the scope that provides their initial buffer. Contents are lifted out into an owning container with take(), which transfers the heap buffer in O(1) if the array has already spilled, or moves the elements into a fresh UniqueArray otherwise. The API mirrors UniqueArray (SE-0527), minus the pieces that don't apply to a non-escapable scratch type (DynamicContainer, MutableContainer, and RangeReplaceableContainer conformances plus the Drain-based consumer), plus members unique to its borrow-then-spill design: take(), clone(), and append(repeating:count:). The seed-buffer initializer is kept internal for now, with withTemporaryArray as the sole entry point. Equatable/Hashable and CustomStringConvertible/CustomDebugStringConvertible are implemented as methods with FIXMEs to add the conformances once those protocols support ~Copyable/~Escapable types. The Collection/RangeReplaceable surface and container-protocol conformances are gated behind the UnstableContainersPreview trait, mirroring UniqueArray; the core API builds in the default configuration. DocC coverage is added for the type and the withTemporaryArray entry point.
1.2 KiB
1.2 KiB
BasicContainers/TemporaryArray
Topics
Creating a Temporary Array
withTemporaryArray(of:capacity:_:)init()init(capacity:)init(capacity:initializingWith:)
Inspecting a Temporary Array
isEmptycountcapacityfreeCapacityisTriviallyIdentical(to:)
Indices
IndexstartIndexendIndexindices
Accessing Elements
subscript(_:)swapAt(_:_:)edit(_:)
Memory Management
reallocate(capacity:)reserveCapacity(_:)
Moving and Copying Out
take()clone()clone(capacity:)
Spans
spanmutableSpannextSpan(after:maximumCount:)nextMutableSpan(after:maximumCount:)previousSpan(before:maximumCount:)
Appending Items
append(_:)append(addingCount:initializingWith:)append(repeating:count:)append(moving:)-(UnsafeMutableBufferPointer<Element>)append(moving:)-(OutputSpan<Element>)append(copying:)-(Sequence<Element>)append(copying:)-(Span<Element>)append(copying:)-(UnsafeBufferPointer<Element>)append(copying:)-(UnsafeMutableBufferPointer<Element>)