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.
- UniqueBox is public API, so we cannot remove it in favor of the stdlib’s
- Remove Ref and MutableRef. Keep an internal _MutableRef to work around stdlib limitations.
Package traits already pass defines with their trait name when building. Instead of adding our own conditional defines based on the traits we can use the trait provided defines directly. I observed that various tooling behaves better with the trait provided defines.
`UniqueArray.replace(removing:copying:)` overloads overestimated the amount of memory they need, sometimes leading to unnecessary reallocations. Fix this.
The original code was invoking `_closeGap` with an incorrect size (from `append` rather than `replace`), leading to runtime traps and potential memory safety issues if the `resize` invocation ends up underfilling the container.
This is currently conditional on the UnstableContainersPreview trait. (Swift 6.4 has not shipped yet, so we cannot unconditionally enable this without risking breakage.)
Adds trailing underscores to the BorrowingSequence protocols and
requirements, in order to allow both parallel conformances and
the ability to evolve the requirements in this package.