You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The following additional data structures are currently under development but they aren't stable enough to preview yet.
35
-
36
-
-[`SortedSet` and `SortedDictionary`](https://github.com/apple/swift-collections/pull/65), sorted collections backed by in-memory persistent b-trees.
37
-
-[`SparseSet`](https://github.com/apple/swift-collections/pull/80), a constant time set construct, trading off memory for speed.
38
-
39
34
Swift Collections uses the same modularization approach as [**Swift Numerics**](https://github.com/apple/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 `DequeModule`. `OrderedSet` and `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:
40
35
41
36
```swift
@@ -53,10 +48,11 @@ The Swift Collections package is source stable. The version numbers follow [Sema
53
48
54
49
[semver]: https://semver.org
55
50
56
-
The public API of version 1.1 of the `swift-collections` package consists of non-underscored declarations that are marked `public` in the `Collections`, `BitCollections`, `DequeModule`, `HeapModule`, `OrderedCollections` and `HashTreeCollections` modules.
51
+
### Public API
52
+
53
+
The public API of version 1.2 of the `swift-collections` package consists of non-underscored declarations that are marked `public` in the `Collections`, `BitCollections`, `DequeModule`, `HeapModule`, `OrderedCollections` and `HashTreeCollections` modules.
57
54
58
-
Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
59
-
If you have a use case that requires using underscored APIs, please [submit a Feature Request][enhancement] describing it! We'd like the public interface to be as useful as possible -- although preferably without compromising safety or limiting future evolution.
55
+
Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
60
56
61
57
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:
62
58
@@ -65,36 +61,42 @@ By "underscored declarations" we mean declarations that have a leading underscor
Note that contents of the `Tests`, `Utils` and `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.
64
+
If you have a use case that requires using underscored (or otherwise non-public) APIs, please [submit a Feature Request][enhancement] describing it! We'd like the public interface to be as useful as possible -- although preferably without compromising safety or limiting future evolution.
65
+
66
+
This source compatibility promise only applies to swift-collection when built as a Swift package. (The repository also contains unstable configurations for building swift-collections using CMake and Xcode. These configurations are provided for internal Swift project use only -- such as for building the (private) swift-collections binaries that ship within Swift toolchains.)
67
+
68
+
Note that the files in the `Tests`, `Utils`, `Documentation`, `Xcode`, `cmake` and `Benchmarks` subdirectories may change at whim; they may be added, modified or removed in any new release. Do not rely on anything about them.
69
69
70
70
Future minor versions of the package may update these rules as needed.
71
71
72
+
### Minimum Required Swift Toolchain Version
73
+
72
74
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.
73
75
74
-
The following table maps existing package releases to their minimum required Swift toolchain release:
76
+
The following table maps package releases to their minimum required Swift toolchain release:
75
77
76
78
| Package version | Swift version | Xcode release |
(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.)
82
85
83
-
84
86
## Using **Swift Collections** in your project
85
87
86
88
To use this package in a SwiftPM project, you need to set it up as a package dependency:
| swift-collections 1.1.x | release/1.1 | Critical bugfixes only |
129
+
| swift-collections 1.2.x | release/1.2 | Critical bugfixes only |
130
+
| swift-collections 1.3.x | main | Feature work towards next minor release |
131
+
| n.a. | future | Experimental prototyping |
128
132
129
133
Changes must land on the branch corresponding to the earliest release that they will need to ship on. They are periodically propagated to subsequent branches, in the following direction:
For example, anything landing on `release/1.0` will eventually appear on `release/1.1` and then `main` too; there is no need to file standalone PRs for each release line. (Change propagation currently requires manual work -- it is performed by project maintainers.)
137
+
For example, anything landing on `release/1.1` will eventually appear on `release/1.2` and then `main` too; there is no need to file standalone PRs for each release line. Change propagation is not instantaneous, as it currently requires manual work -- it is performed by project maintainers.
134
138
135
139
### Working on the package
136
140
@@ -160,6 +164,10 @@ By submitting a pull request, you represent that you have the right to license y
160
164
161
165
#### Proposing the addition of a new data structure
162
166
167
+
**Note:** As of 2024, we are fully preoccupied with refactoring our existing data structures to support noncopyable and/or nonescapable element types; this includes designing new container protocols around them. I don't expect we'll have capacity to work on any major new data structure implementations until this effort is complete.
168
+
169
+
<!--
170
+
163
171
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.)
164
172
165
173
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.
@@ -174,6 +182,7 @@ Participate in the review discussion, and adapt code accordingly. Sometimes we m
174
182
175
183
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.
0 commit comments