Merge pull request #450 from lorentey/merge.release-1.2→main

Merge release/1.2 to main

Author: lorentey

.editorconfig

@@ -0,0 +1,41 @@
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+end_of_line = lf
+trim_trailing_whitespace = true
+
+[*.{swift,swift.gyb,cpp,h,yml}]
+indent_style = space
+tab_width = 4
+indent_size = 2
+
+[*.{sh,py}]
+indent_style = space
+indent_size = 4
+
+[.swiftci/*}]
+indent_style = space
+indent_size = 4
+
+[CMakeLists.txt]
+indent_style = space
+indent_size = 2
+
+[*.cmake{,.in}]
+indent_style = space
+indent_size = 2
+
+[*.{md,txt}]
+indent_style = space
+indent_size = 2
+
+[*.xcconfig]
+indent_style = space
+indent_size = 2
+
+[*.pbxproj]
+indent_style = tab
+tab_width = 4
+indent_size = 4

.github/workflows/pull_request.yml

@@ -8,6 +8,9 @@ jobs:
   tests:
     name: Test
     uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
+    with:
+      linux_exclude_swift_versions: '[{"swift_version": "5.8"}, {"swift_version": "5.9"}]'
+      windows_exclude_swift_versions: '[{"swift_version": "5.9"}]'
   soundness:
     name: Soundness
     uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main

CMakeLists.txt

@@ -15,6 +15,16 @@ list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake/modules)
 
 include(PlatformInfo)
 
+if(NOT SWIFT_SYSTEM_NAME)
+  if(CMAKE_SYSTEM_NAME STREQUAL Darwin)
+    set(SWIFT_SYSTEM_NAME macosx)
+  else()
+    set(SWIFT_SYSTEM_NAME "$<LOWER_CASE:${CMAKE_SYSTEM_NAME}>")
+  endif()
+endif()
+
+include(PlatformInfo)
+
 set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)
 set(CMAKE_Swift_COMPILE_OPTIONS_MSVC_RUNTIME_LIBRARY MultiThreadedDLL)
 
@@ -36,6 +46,7 @@ if(COLLECTIONS_FOUNDATION_TOOLCHAIN_MODULE)
 endif()
 
 include(CTest)
+include(GNUInstallDirs)
 include(SwiftSupport)
 
 add_subdirectory(Sources)

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.7
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the Swift Collections open source project
@@ -188,17 +188,13 @@ let targets: [CustomTarget] = [
     name: "InternalCollectionsUtilities",
     exclude: [
       "CMakeLists.txt",
-      "Compatibility/UnsafeMutableBufferPointer+SE-0370.swift.gyb",
-      "Compatibility/UnsafeMutablePointer+SE-0370.swift.gyb",
-      "Compatibility/UnsafeRawPointer extensions.swift.gyb",
       "Debugging.swift.gyb",
       "Descriptions.swift.gyb",
       "IntegerTricks/FixedWidthInteger+roundUpToPowerOfTwo.swift.gyb",
       "IntegerTricks/Integer rank.swift.gyb",
       "IntegerTricks/UInt+first and last set bit.swift.gyb",
       "IntegerTricks/UInt+reversed.swift.gyb",
       "RandomAccessCollection+Offsets.swift.gyb",
-      "Specialize.swift.gyb",
       "UnsafeBitSet/_UnsafeBitSet+Index.swift.gyb",
       "UnsafeBitSet/_UnsafeBitSet+_Word.swift.gyb",
       "UnsafeBitSet/_UnsafeBitSet.swift.gyb",

README.md

@@ -31,11 +31,6 @@ The package currently provides the following implementations:
 [TreeSet]: https://swiftpackageindex.com/apple/swift-collections/1.1.0/documentation/hashtreecollections/treeset
 [TreeDictionary]: https://swiftpackageindex.com/apple/swift-collections/1.1.0/documentation/hashtreecollections/treedictionary
 
-The following additional data structures are currently under development but they aren't stable enough to preview yet.
-
-- [`SortedSet` and `SortedDictionary`](https://github.com/apple/swift-collections/pull/65), sorted collections backed by in-memory persistent b-trees.
-- [`SparseSet`](https://github.com/apple/swift-collections/pull/80), a constant time set construct, trading off memory for speed.
-
 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:
 
 ``` swift
@@ -53,10 +48,11 @@ The Swift Collections package is source stable. The version numbers follow [Sema
 
 [semver]: https://semver.org
 
-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.
+### Public API 
+
+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. 
 
-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][enhancement] describing it! We'd like the public interface to be as useful as possible -- although preferably without compromising safety or limiting future evolution.
+Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
 
 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:
 
@@ -65,36 +61,42 @@ By "underscored declarations" we mean declarations that have a leading underscor
 - `_FooModule.Bar` (underscored module)
 - `FooModule.Bar.init(_value:)` (underscored initializer)
 
-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. 
+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.
+
+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.)
+
+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.
 
 Future minor versions of the package may update these rules as needed.
 
+### Minimum Required Swift Toolchain Version
+
 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:
+The following table maps package releases to their minimum required Swift toolchain release:
 
 | Package version         | Swift version   | Xcode release |
 | ----------------------- | --------------- | ------------- |
 | swift-collections 1.0.x | >= Swift 5.3.2  | >= Xcode 12.4 |
 | swift-collections 1.1.x | >= Swift 5.7.2  | >= Xcode 14.2 |
+| swift-collections 1.2.x | >= Swift 5.10.0 | >= Xcode 15.3 |
 
 (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.)
 
-
 ## Using **Swift Collections** in your project
 
 To use this package in a SwiftPM project, you need to set it up as a package dependency:
 
 ```swift
-// swift-tools-version:5.9
+// swift-tools-version:6.1
 import PackageDescription
 
 let package = Package(
   name: "MyPackage",
   dependencies: [
     .package(
       url: "https://github.com/apple/swift-collections.git", 
-      .upToNextMinor(from: "1.1.0") // or `.upToNextMajor
+      .upToNextMinor(from: "1.2.0") // or `.upToNextMajor
     )
   ],
   targets: [
@@ -120,17 +122,19 @@ If you find something that looks like a bug, please open a [Bug Report][bugrepor
 
 We maintain separate branches for each minor version of the package:
 
-| Package version         | Branch      | 
-| ----------------------- | ----------- |
-| swift-collections 1.0.x | release/1.0 |
-| swift-collections 1.1.x | release/1.1 |
-| swift-collections 1.2.x | main        |
+| Package version         | Branch      | Status   |
+| ----------------------- | ----------- | -------- |
+| swift-collections 1.0.x | release/1.0 | Obsolete |
+| swift-collections 1.1.x | release/1.1 | Critical bugfixes only | 
+| swift-collections 1.2.x | release/1.2 | Critical bugfixes only |
+| swift-collections 1.3.x | main        | Feature work towards next minor release |
+| n.a.                    | future      | Experimental prototyping |
 
 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:
 
-`release/1.0` → `release/1.1` → `main`
+`release/1.0` → `release/1.1` → `release/1.2` → `main`
 
-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.)
+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.
 
 ### Working on the package
 
@@ -160,6 +164,10 @@ By submitting a pull request, you represent that you have the right to license y
 
 #### Proposing the addition of a new data structure
 
+**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.
+
+<!--
+
 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. 
@@ -174,6 +182,7 @@ Participate in the review discussion, and adapt code accordingly. Sometimes we m
 
 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.
 
+-->
 
 ### Code of Conduct
 

Sources/BitCollections/CMakeLists.txt

@@ -32,11 +32,13 @@ target_sources(${module_name} PRIVATE
   "BitArray/BitArray+Descriptions.swift"
   "BitArray/BitArray+Equatable.swift"
   "BitArray/BitArray+ExpressibleByArrayLiteral.swift"
+  "BitArray/BitArray+ExpressibleByStringLiteral.swift"
   "BitArray/BitArray+Extras.swift"
   "BitArray/BitArray+Fill.swift"
   "BitArray/BitArray+Hashable.swift"
   "BitArray/BitArray+Initializers.swift"
   "BitArray/BitArray+Invariants.swift"
+  "BitArray/BitArray+LosslessStringConvertible.swift"
   "BitArray/BitArray+RandomBits.swift"
   "BitArray/BitArray+RangeReplaceableCollection.swift"
   "BitArray/BitArray+Testing.swift"

Sources/DequeModule/CMakeLists.txt

@@ -31,7 +31,6 @@ target_sources(${module_name} PRIVATE
   "Deque+ExpressibleByArrayLiteral.swift"
   "Deque+Extras.swift"
   "Deque+Hashable.swift"
-  "Deque+Sendable.swift"
   "Deque+Testing.swift"
   "Deque._Storage.swift"
   "Deque._UnsafeHandle.swift"

Sources/DequeModule/Deque+Collection.swift

@@ -164,7 +164,7 @@ extension Deque: Sequence {
   }
 }
 
-extension Deque.Iterator: Sendable where Element: Sendable {}
+extension Deque.Iterator: @unchecked Sendable where Element: Sendable {}
 
 extension Deque: RandomAccessCollection {
   public typealias Index = Int

Sources/DequeModule/Deque+Sendable.swift

@@ -103,3 +103,5 @@ public struct Deque<Element> {
     self._storage = _Storage(minimumCapacity: minimumCapacity)
   }
 }
+
+extension Deque: @unchecked Sendable where Element: Sendable {}