Swift Collections is an open-source package of data structure implementations for the Swift programming language.
Read more about the package, and the intent behind it, in the announcement on swift.org.
The package currently provides the following implementations:
Deque<Element>, a double-ended queue backed by a ring buffer. Deques are range-replaceable, mutable, random-access collections.
OrderedSet<Element>, a variant of the standard
Set where the order of items is well-defined and items can be arbitrarily reordered. Uses a
ContiguousArray as its backing store, augmented by a separate hash table of bit packed offsets into it.
OrderedDictionary<Key, Value>, an ordered variant of the standard
Dictionary, providing similar benefits.
The following additional types are expected to ship soon, in version 1.1:
Heap, a min-max heap backed by an array, suitable for use as a priority queue.
TreeDictionary, persistent hashed collections implementing Compressed Hash-Array Mapped Prefix Trees (CHAMP). These work similar to the standard
Dictionary, but they excel at use cases that mutate shared copies, offering dramatic memory savings and radical time improvements.
Preview versions of these new types are available on the
release/1.1 branch. Note that until these types ship in a tagged release, their API and implementation may change without notice -- it isn't a good idea to rely on them in production code yet. However, you can try these in experimental projects by using a branch- or commit-based dependency requirement in your package manifest.
The following additional data structures are currently under development on but they aren't stable enough to preview yet.
SortedDictionary, sorted collections backed by in-memory persistent b-trees.
SparseSet, a constant time set construct, trading off memory for speed.
Swift Collections uses the same modularization approach as Swift Numerics: it provides a standalone module for each thematic group of data structures it implements. For instance, if you only need a double-ended queue type, you can pull in only that by importing
OrderedDictionary share much of the same underlying implementation, so they are provided by a single module, called
OrderedCollections. However, there is also a top-level
Collections module that gives you every collection type with a single import statement:
import Collections var deque: Deque<String> = ["Ted", "Rebecca"] deque.prepend("Keeley") deque.append("Nathan") print(deque) // ["Keeley", "Ted", "Rebecca", "Nathan"]
The Swift Collections package is source stable. The version numbers follow Semantic Versioning -- source breaking changes to public API can only land in a new major version.
The public API of version 1.1 of the
swift-collections package consists of non-underscored declarations that are marked
public in the
Interfaces that aren't part of the public API may continue to change in any release, including patch releases. If you have a use case that requires using underscored APIs, please submit a Feature Request describing it! We'd like the public interface to be as useful as possible -- although preferably without compromising safety or limiting future evolution.
By "underscored declarations" we mean declarations that have a leading underscore anywhere in their fully qualified name. For instance, here are some names that wouldn't be considered part of the public API, even if they were technically marked public:
Note that contents of the
Benchmarks subdirectories aren't public API. We don't make any source compatibility promises about them -- they may change at whim, and code may be removed in any new release. Do not rely on anything about them.
Future minor versions of the package may update these rules as needed.
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, new versions of this package require clients to upgrade to a more recent Swift toolchain release. (This allows the package to make use of new language/stdlib features, build on compiler bug fixes, and adopt new package manager functionality as soon as they are available.) Patch (i.e., bugfix) releases will not increase the required toolchain version, but any minor (i.e., new feature) release may do so.
The following table maps existing package releases to their minimum required Swift toolchain release:
|Package version||Swift version||Xcode release|
|swift-collections 1.0.x||>= Swift 5.3||>= Xcode 12|
|swift-collections 1.1.x||>= Swift 5.5||>= Xcode 13|
(Note: the package has no minimum deployment target, so while it does require clients to use a recent Swift toolchain to build it, the code itself is able to run on any OS release that supports running Swift code.)
To use this package in a SwiftPM project, you need to set it up as a package dependency:
// swift-tools-version:5.7 import PackageDescription let package = Package( name: "MyPackage", dependencies: [ .package( url: "https://github.com/apple/swift-collections.git", .upToNextMinor(from: "1.1.0") // or `.upToNextMajor ) ], targets: [ .target( name: "MyTarget", dependencies: [ .product(name: "Collections", package: "swift-collections") ] ) ] )
We have a dedicated Swift Collections Forum where people can ask and answer questions on how to use or work on this package. It's also a great place to discuss its evolution.
If you find something that looks like a bug, please open a Bug Report! Fill out as many details as you can.
We have some basic documentation on package internals that will help you get started.
By submitting a pull request, you represent that you have the right to license your contribution to Apple and the community, and agree by submitting the patch that your contributions are licensed under the Swift License, a copy of which is provided in this repository.
We intend this package to collect generally useful data structures -- the ones that ought to be within easy reach of every Swift engineer's basic toolbox. The implementations we ship need to be of the highest technical quality, polished to the same shine as anything that gets included in the Swift Standard Library. (The only real differences are that this package isn't under the formal Swift Evolution process, and its code isn't ABI stable.)
Accordingly, adding a new data structure to this package is not an easy or quick process, and not all useful data structures are going to be a good fit.
If you have an idea for a data structure that might make a good addition to this package, please start a topic on the forum, explaining why you believe it would be important to implement it. This way we can figure out if it would be right for the package, discuss implementation strategies, and plan to allocate capacity to help.
Not all data structures will reach a high enough level of usefulness to ship in this package -- those that have a more limited audience might work better as a standalone package. Of course, reasonable people might disagree on the importance of including any particular data structure; but at the end of the day, the decision whether to take an implementation is up to the maintainers of this package.
If maintainers have agreed that your implementation would likely make a good addition, then it's time to start work on it. Submit a PR with your implementation as soon as you have something that's ready to show! We'd love to get involved as early as you like. Historically, the best additions resulted from close work between the contributor and a package maintainer.
Participate in the review discussion, and adapt code accordingly. Sometimes we may need to go through several revisions over multiple months! This is fine -- it makes the end result that much better. When there is a consensus that the feature is ready, and the implementation is fully tested and documented, the PR will be merged by a maintainer. This is good time for a small celebration -- merging is a good indicator that the addition will ship at some point.
Historically, PRs adding a new data structure have typically been merged to a new feature branch rather than directly to a release branch or
main, and there was an extended amount of time between the initial merge and the tag that shipped the new feature. Nobody likes to wait, but getting a new data structure implementation from a state that was ready to merge to a state that's ready to ship is actually quite difficult work, and it takes maintainer time and effort that needs to be scheduled in advance. The closer an implementation is to the coding conventions and performance baseline of the Standard Library, the shorter this wait is likely to become, and the fewer changes there will be between merging and shipping.
Like all Swift.org projects, we would like the Swift Collections project to foster a diverse and friendly community. We expect contributors to adhere to the Swift.org Code of Conduct. A copy of this document is available in this repository.
The current code owner of this package is Karoy Lorentey (@lorentey). You can contact him on the Swift forums, or by writing an email to klorentey at apple dot com. (Please keep it related to this project.)
In case of moderation issues, you can also directly contact a member of the Swift Core Team.
|Last commit: 3 days ago|
This is a documentation update, including the addition of basic DocC documentation bundles. This release has no functional changes.
rethrowsposition (by @ensan-hcl)
Full Changelog: https://github.com/apple/swift-collections/compare/1.0.3...1.0.4
Thank you to everyone who contributed to this release! Your bug reports, discussions and pull requests all help improve this package.
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics