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.
Unit tests
Beware! The contents of this directory are not source stable. They are provided as is, with no compatibility promises across package releases. Future versions of this package can arbitrarily change these files or remove them, without any advance notice. (This can include patch releases.)