apple/swift-collections 1.4.0 on GitHub

This feature release supports Swift toolchain versions 6.0, 6.1 and 6.2. It includes a variety of bug fixes, and ships the following new features:

New ownership-aware ring buffer and hashed container implementations

In the DequeModule module, we have two new source-stable types that provide ownership-aware ring buffer implementations:

struct UniqueDeque<Element> is a uniquely held, dynamically resizing, noncopyable deque.
struct RigidDeque<Element> is a fixed-capacity deque implementation.

RigidDeque/UniqueDeque are to Deque like RigidArray/UniqueArray are to Array -- they provide noncopyable embodiments of the same basic data structure, with many of the same operations.

In the BasicContainers module, this release adds previews of four new types, implementing ownership-aware hashed containers:

struct UniqueSet<Element> is a uniquely held, dynamically resizing set.
struct RigidSet<Element> is a fixed-capacity set.
struct UniqueDictionary<Key, Value> is a uniquely held, dynamically resizing dictionary.
struct RigidDictionary<Key, Value> is a fixed-capacity dictionary.

These are direct analogues of the standard Set and Dictionary types. These types are built on top of the Equatable and Hashable protocol generalizations that were proposed in SE-0499; as that proposal is not yet implemented in any shipping toolchain, these new types are shipping as source-unstable previews, conditional on a new UnstableHashedContainers package trait. The final API of these types will also deeply depend on the struct Borrow and struct Inout proposals (and potentially other language/stdlib improvements) that are currently working their way through the Swift Evolution process. Accordingly, we may need to make source-breaking changes to the interfaces of these types -- they are not ready to be blessed as Public API. However, we encourage intrepid engineers to try them on for size, and report pain points. (Of which we expect there will be many in this first preview.)

We continue the pattern of Rigid- and Unique- naming prefixes with these new types:

The Unique types (UniqueArray, UniqueDeque, UniqueSet, UniqueDictionary etc.) are dynamically self-sizing containers that automatically reallocate their storage as needed to best accommodate their contents; the Unique prefix was chosen to highlight that these types are always uniquely held, avoiding the complications of mutating shared copies.
The Rigid types remove dynamic sizing, and they operate strictly within an explicitly configured capacity. Dynamic sizing is not always appropriate -- when targeting space- or time-constrained environments (think embedded use cases or real-time work), it is preferable to avoid implicit reallocations, and to instead choose to have explicit control over when (and if) storage is reallocated, and to what size. This is where the Rigid types come in: their instances are created with a specific capacity and it is a runtime error to exceed that. This makes them quite inflexible (hence the "rigid" qualifier), but in exchange, their operations provide far stricter complexity guarantees: they exhibit no random runtime latency spikes, and they can trivially fit in strict memory budgets.

Early drafts of borrowing sequence, generative iteration and container protocols

This release includes highly experimental but working implementations of new protocols supplying ownership-aware alternatives to the classic Sequence/Collection protocol hierarchy. These protocols and the generic operations built on top of them can be turned on by enabling the UnstableContainersPreview package trait.

protocol BorrowingSequence<Element> models borrowing sequences with ephemeral lifetimes. (This is already progressing through Swift Evolution.)
protocol Container<Element> models constructs that physically store their contents, and can expose stable spans over them.
protocol Producer<Element, ProducerError> models a generative iterator -- a construct that generates items demand.
protocol Drain<Element> refines Producer to model an in-place consumable elements -- primarily for use around container types.

In this version, the package has developed these protocols just enough to implement basic generic operations for moving data between containers like UniqueArray and RigidDeque. As we gain experience using these, future releases may start adding basic generic algorithms, more protocols (bidirectional, random-access, (per)mutable, range-replaceable containers etc.) convenience adapters, and other features -- or we may end up entirely overhauling or simply discarding some/all of them. Accordingly, the experimental interfaces enabled by UnstableContainersPreview are not source stable, and they are not intended for production use. We expect the eventual production version of these (or whatever designs they evolve into) to ship in the Swift Standard Library. We do highly recommend interested folks to try playing with these, to get a feel for the strange problems of Ownership.

Besides these protocols, the package also defines rudimentary substitutes of some basic primitives that belong in the Standard Library:

struct InputSpan<Element> the dual of OutputSpan -- while OutputSpan is primarily for moving items into somebody else's storage, InputSpan enables safely moving items out of storage.
struct Borrow<Target> represents a borrowing reference to an item. (This package models this with a pointer, which is an ill-fitting substitute for the real implementation in the stdlib.)
struct Inout<Target> represents a mutating reference to an item.

A formal way to access `SortedSet` and `SortedDictionary` types

The SortedCollections module contains (preexisting) early drafts of two sorted collection types SortedSet and SortedDictionary, built on top of an in-memory B-tree implementation. This release defines an UnstableSortedCollections package trait that can be used to enable building these types for experimentation without manually modifying the package. Like in previous releases, these implementations remain unfinished in this release, with known API issues; accordingly, these types remain unstable. (Issue #1 remains open.) Future package releases may change their interface in ways that break source compatibility, or they may remove these types altogether.

Minor interface-level changes

The Collections module no longer uses the unstable @_exported import feature. Instead, it publishes public typealiases of every type that it previously reexported from DequeModule, OrderedCollections, BitCollections, HeapModule and HashTreeCollections.

We renamed some RigidArray/UniqueArray operations to improve their clarity at the point of use. The old names are still available, but deprecated.

Old name	New name
`append(count:initializingWith:)`	`append(addingCount:initializingWith:)`
`insert(count:at:initializingWith:)`	`insert(addingCount:at:initializingWith:)`
`replaceSubrange(_:newCount:initializingWith:)`	`replace(removing:addingCount:initializingWith:)`
`replaceSubrange(_:moving:)`	`replace(removing:moving:)`
`replaceSubrange(_:copying:)`	`replace(removing:copying:)`
`copy()`	`clone()`
`copy(capacity:)`	`clone(capacity:)`

We have now defined a complete set of OutputSpan/InputSpan-based append/insert/replace/consume primitives, fully generalized to be implementable by piecewise contiguous containers. These operations pave the way for a Container-based analogue of the classic RangeReplaceableCollection protocol, with most of the user-facing operations becoming standard generic algorithms built on top of these primitives:

mutating func append<E: Error>(
    addingCount newItemCount: Int,
    initializingWith initializer: (inout OutputSpan<Element>) throws(E) -> Void
)

mutating func insert<E: Error>(
   addingCount newItemCount: Int,
   at index: Int,
   initializingWith initializer: (inout OutputSpan<Element>) throws(E) -> Void
) throws(E)

mutating func replace<E: Error>(
    removing subrange: Range<Int>,
    consumingWith consumer: (inout InputSpan<Element>) -> Void,
    addingCount newItemCount: Int,
    initializingWith initializer: (inout OutputSpan<Element>) throws(E) -> Void
) throws(E)

mutating func consume(
    _ subrange: Range<Int>,
    consumingWith consumer: (inout InputSpan<Element>) -> Void
)

The package no longer uses the code generation tool gyb.

What's Changed

Fix links in GitHub templates by @lorentey in #527
Adopt package access modifier and get rid of gybbing by @lorentey in #526
[Doc] Fix links in landing page by @Azoy in #531
[BigString] Refactor _Chunk to be its own managed buffer of UTF8 by @Azoy in #488
Add new package trait UnstableSortedCollections by @lorentey in #533
[RopeModule] Fix warnings by @lorentey in #534
Fix ability to build & test BigString with Xcode & CMake by @lorentey in #537
[BigString] Bring back Index._isUTF16TrailingSurrogate by @Azoy in #539
chore: restrict GitHub workflow permissions - future-proof by @incertum in #540
[BitCollections] Add missing imports for InternalCollectionsUtilities by @lorentey in #554
Compare self.value to other, not itself by @SiliconA-Z in #553
Change useFloyd heuristic to match comment by @SiliconA-Z in #551
Typo: symmetric difference should be the xor, not intersection by @SiliconA-Z in #550
first should get the Initialized elements by @SiliconA-Z in #549
Replace Container with a far less powerful (but more universal) Iterable construct by @lorentey in #543
Temporarily stop testing RigidArray & UniqueArray on release/6.3 snapshots on Linux by @lorentey in #562
[RigidArray, HashTrees] Mark deinitializers inlinable by @lorentey in #560
GHA: Add weekly dependabot by @bkhouri in #563
Work around temporary issue with current 6.3 snapshots by @lorentey in #565
Add RigidDeque and UniqueDeque by @lorentey in #557
[Collections module] Stop using @_exported import by @lorentey in #566
Delete stray benchmark results files by @lorentey in #567
Assorted RigidArray/UniqueArray updates by @lorentey in #569
RigidArray/UniqueArray: Add new copying span initializers by @Azoy in #572
RigidDeque/UniqueDeque: Add some top-level documentation by @lorentey in #571
Update docs for Container.nextSpan(after:maximumCount:) by @lorentey in #574
Remove workaround for bug in OutputSpan.wUMBP by @lorentey in #570
[RigidArray, RigidDeque].nextSpan: Validate maximumCount by @lorentey in #575
Bump swiftlang/github-workflows/.github/workflows/soundness.yml from 0.0.6 to 0.0.7 by @dependabot[bot] in #577
give constant folding an opportunity to select a much faster code path for empty dictionary (and set) literals by @tayloraswift in #578
Bump swiftlang/github-workflows/.github/workflows/swift_package_test.yml from 0.0.6 to 0.0.7 by @dependabot[bot] in #576
Ownership-aware Set and Dictionary variants by @lorentey in #573
[Prerelease] Check API for consistency, fill holes, patch incoherencies by @lorentey in #581
[BitSet] Amend return value of update(with:) method by @benrimmington in #538
[BasicContainers] Fix spelling of a source file by @lorentey in #585
Include notes about index mutation in span(after/before:) (+ other doc fixes) by @natecook1000 in #541
[BasicContainers] Finalize requirements for hashed containers by @lorentey in #586
Update README for 1.4.0 by @lorentey in #587
Working towards the 1.4.0 tag by @lorentey in #588
[BasicContainers] Avoid defining set/dictionary types unless UnstableHashedContainers is enabled by @lorentey in #589
[BasicContainers] RigidArray: Correct spelling of replacement for deprecated method by @lorentey in #590

New Contributors

@incertum made their first contribution in #540
@SiliconA-Z made their first contribution in #553
@bkhouri made their first contribution in #563
@dependabot[bot] made their first contribution in #577
@tayloraswift made their first contribution in #578
@benrimmington made their first contribution in #538

Full Changelog: 1.3.0...1.4.0

apple/swift-collections 1.4.0 Swift Collections 1.4.0 on GitHub