commit a2bcac435f31c5b0aef741b6fdf1290aab45b3f8 Author: Karoy Lorentey Date: Mon Apr 5 09:41:00 2021 -0700 Initial import. Introduce OrderedCollections module diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md new file mode 100755 index 00000000..989dfc9e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -0,0 +1,40 @@ +--- +name: 🐛 Bug Report +about: Something isn't working as expected +labels: bug +--- + + + +Replace this paragraph with a short description of the incorrect behavior. +(If this is a regression, please note the last version of the package that exhibited the correct behavior in addition to your current version.) + +### Information + +- **Package version:** What tag or branch of swift-collections are you using? +- **Platform version:** Please tell us the version number of your operating system. +- **Swift version:** Paste the output of `swift --version` here. + +### Checklist + +- [ ] If possible, I've reproduced the issue using the `main` branch of this package. +- [ ] I've searched for [existing GitHub issues](https://github.com/apple/swift-collections/issues). + +### Steps to Reproduce +Replace this paragraph with an explanation of how to reproduce the incorrect behavior. +Include a simple code example, if possible. + +### Expected behavior +Describe what you expect to happen. + +### Actual behavior +Describe or copy/paste the behavior you observe. diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md new file mode 100755 index 00000000..f22af61e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -0,0 +1,16 @@ +--- +name: 💡 Feature Request +about: A suggestion for a new feature +labels: enhancement +--- + + + +Replace this paragraph with a description of your proposed feature. +Please be sure to describe some concrete use cases for the new feature -- be as specific as possible. +Provide links to existing issues or external references/discussions, if appropriate. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..095c1d69 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: ❓ Discussion Forum + url: https://forums.swift.org/c/related-projects/collections/ + about: Questions about using Swift Collections? Ask here! diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..a53dc4df --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ + + +Replace this paragraph with a description of your changes and rationale. Provide links to an existing issue or external references/discussions, if appropriate. + +### Checklist +- [ ] I've read the [Contribution Guidelines](../CONTRIBUTING.md) +- [ ] My contributions are licensed under the [Swift license](https://swift.org/LICENSE.txt). +- [ ] I've followed the coding style of the rest of the project. +- [ ] I've added tests covering all new code paths my change adds to the project (if appropriate). +- [ ] I've added benchmarks covering new functionality (if appropriate). +- [ ] I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions. +- [ ] I've updated the documentation if necessary. diff --git a/.github/PULL_REQUEST_TEMPLATE/NEW.md b/.github/PULL_REQUEST_TEMPLATE/NEW.md new file mode 100644 index 00000000..808bd64f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/NEW.md @@ -0,0 +1,45 @@ + + +### Description +Replace this paragraph with a description of your changes and rationale. +Provide links to an existing issue or external references/discussions, if appropriate. + +### Detailed Design +Include any additional information about the design here. At minimum, describe a synopsis of any public API additions. + +```swift +/// The new feature implemented by this pull request. +public struct Example: Collection { +} +``` + +### Documentation +How has the new feature been documented? +Have the relevant portions of the guides in the Documentation folder been updated in addition to symbol-level documentation? + +### Testing +How is the new feature tested? + +### Performance +How did you verify the new feature performs as expected? + +### Source Impact +What is the impact of this change on existing users of this package? Does it deprecate or remove any existing API? + +### Checklist +- [ ] I've read the [Contribution Guidelines](../CONTRIBUTING.md) +- [ ] My contributions are licensed under the [Swift license](https://swift.org/LICENSE.txt). +- [ ] I've followed the coding style of the rest of the project. +- [ ] I've added tests covering all new code paths my change adds to the project (to the extent possible). +- [ ] I've added benchmarks covering new functionality (if appropriate). +- [ ] I've verified that my change does not break any existing tests or introduce unexpected benchmark regressions. +- [ ] I've updated the documentation (if appropriate). diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..95c43209 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +.DS_Store +/.build +/Packages +/*.xcodeproj +xcuserdata/ diff --git a/.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata b/.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata new file mode 100644 index 00000000..919434a6 --- /dev/null +++ b/.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata @@ -0,0 +1,7 @@ + + + + + diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/Collections.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/Collections.xcscheme new file mode 100644 index 00000000..a3e92863 --- /dev/null +++ b/.swiftpm/xcode/xcshareddata/xcschemes/Collections.xcscheme @@ -0,0 +1,91 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/DequeModule.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/DequeModule.xcscheme new file mode 100644 index 00000000..89302646 --- /dev/null +++ b/.swiftpm/xcode/xcshareddata/xcschemes/DequeModule.xcscheme @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/OrderedCollections.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/OrderedCollections.xcscheme new file mode 100644 index 00000000..8e6cad97 --- /dev/null +++ b/.swiftpm/xcode/xcshareddata/xcschemes/OrderedCollections.xcscheme @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/UniquedModule.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/UniquedModule.xcscheme new file mode 100644 index 00000000..76faf301 --- /dev/null +++ b/.swiftpm/xcode/xcshareddata/xcschemes/UniquedModule.xcscheme @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-Package.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-Package.xcscheme new file mode 100644 index 00000000..e8895763 --- /dev/null +++ b/.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-Package.xcscheme @@ -0,0 +1,251 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-benchmark.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-benchmark.xcscheme new file mode 100644 index 00000000..cbbc8b3a --- /dev/null +++ b/.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-benchmark.xcscheme @@ -0,0 +1,111 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Benchmarks/Benchmarks/ArrayBenchmarks.swift b/Benchmarks/Benchmarks/ArrayBenchmarks.swift new file mode 100644 index 00000000..18801349 --- /dev/null +++ b/Benchmarks/Benchmarks/ArrayBenchmarks.swift @@ -0,0 +1,276 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark + +extension Benchmark { + public mutating func addArrayBenchmarks() { + self.addSimple( + title: "Array init from range", + input: Int.self + ) { size in + blackHole(Array(0 ..< size)) + } + + self.addSimple( + title: "Array init from unsafe buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + blackHole(Array(buffer)) + } + } + + self.addSimple( + title: "Array sequential iteration", + input: [Int].self + ) { input in + for i in input { + blackHole(i) + } + } + + self.addSimple( + title: "Array subscript get, random offsets", + input: ([Int], [Int]).self + ) { input, lookups in + for i in lookups { + blackHole(input[i]) + } + } + + self.addSimple( + title: "Array successful contains", + input: ([Int], [Int]).self + ) { input, lookups in + for i in lookups { + precondition(input.contains(i)) + } + } + + self.addSimple( + title: "Array unsuccessful contains", + input: ([Int], [Int]).self + ) { input, lookups in + let c = input.count + for i in lookups { + precondition(!input.contains(i + c)) + } + } + + self.add( + title: "Array mutate through subscript", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var array = input + array.reserveCapacity(0) // Ensure unique storage + timer.measure { + var v = 0 + for i in lookups { + array[i] = v + v += 1 + } + } + blackHole(array) + } + } + + self.add( + title: "Array random swaps", + input: [Int].self + ) { input in + return { timer in + var array = Array(0 ..< input.count) + timer.measure { + var v = 0 + for i in input { + array.swapAt(i, v) + v += 1 + } + } + blackHole(array) + } + } + + self.add( + title: "Array partitioning around middle", + input: [Int].self + ) { input in + return { timer in + let pivot = input.count / 2 + var array = input + array.reserveCapacity(0) // Force unique storage + timer.measure { + let r = array.partition(by: { $0 >= pivot }) + precondition(r == pivot) + } + blackHole(array) + } + } + + self.add( + title: "Array sort", + input: [Int].self + ) { input in + return { timer in + var array = input + array.reserveCapacity(0) // Force unique storage + timer.measure { + array.sort() + } + precondition(array.elementsEqual(0 ..< input.count)) + } + } + + self.addSimple( + title: "Array append", + input: [Int].self + ) { input in + var array: [Int] = [] + for i in input { + array.append(i) + } + precondition(array.count == input.count) + blackHole(array) + } + + self.addSimple( + title: "Array append, reserving capacity", + input: [Int].self + ) { input in + var array: [Int] = [] + array.reserveCapacity(input.count) + for i in input { + array.append(i) + } + blackHole(array) + } + + self.addSimple( + title: "Array prepend", + input: [Int].self + ) { input in + var array: [Int] = [] + for i in input { + array.insert(i, at: 0) + } + blackHole(array) + } + + self.addSimple( + title: "Array prepend, reserving capacity", + input: [Int].self + ) { input in + var array: [Int] = [] + array.reserveCapacity(input.count) + for i in input { + array.insert(i, at: 0) + } + blackHole(array) + } + + self.addSimple( + title: "Array kalimba", + input: [Int].self + ) { input in + blackHole(input.kalimbaOrdered()) + } + + self.addSimple( + title: "Array kalimba fast", + input: [Int].self + ) { input in + blackHole(input.kalimbaOrdered3()) + } + + self.add( + title: "Array random insertions", + input: Insertions.self + ) { insertions in + return { timer in + let insertions = insertions.values + var array: [Int] = [] + timer.measure { + for i in insertions.indices { + array.insert(i, at: insertions[i]) + } + } + blackHole(array) + } + } + + self.add( + title: "Array random insertions, reserving capacity", + input: Insertions.self + ) { insertions in + return { timer in + let insertions = insertions.values + var array: [Int] = [] + array.reserveCapacity(insertions.count) + timer.measure { + for i in insertions.indices { + array.insert(i, at: insertions[i]) + } + } + blackHole(array) + } + } + + self.add( + title: "Array removeLast", + input: Int.self + ) { size in + return { timer in + var array = Array(0 ..< size) + timer.measure { + for _ in 0 ..< size { + array.removeLast() + } + } + precondition(array.isEmpty) + blackHole(array) + } + } + + self.add( + title: "Array removeFirst", + input: Int.self + ) { size in + return { timer in + var array = Array(0 ..< size) + timer.measure { + for _ in 0 ..< size { + array.removeFirst() + } + } + precondition(array.isEmpty) + blackHole(array) + } + } + + self.add( + title: "Array random removals", + input: Insertions.self + ) { insertions in + let removals = Array(insertions.values.reversed()) + return { timer in + var array = Array(0 ..< removals.count) + timer.measure { + for i in removals { + array.remove(at: i) + } + } + blackHole(array) + } + } + } +} diff --git a/Benchmarks/Benchmarks/CppBenchmarks.swift b/Benchmarks/Benchmarks/CppBenchmarks.swift new file mode 100644 index 00000000..19b51d8f --- /dev/null +++ b/Benchmarks/Benchmarks/CppBenchmarks.swift @@ -0,0 +1,629 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark +import CppBenchmarks + +internal class CppVector { + var ptr: UnsafeMutableRawPointer? + + init(_ input: [Int]) { + self.ptr = input.withUnsafeBufferPointer { buffer in + cpp_vector_create(buffer.baseAddress, buffer.count) + } + } + + deinit { + destroy() + } + + func destroy() { + if let ptr = ptr { + cpp_vector_destroy(ptr) + } + ptr = nil + } +} + +internal class CppDeque { + var ptr: UnsafeMutableRawPointer? + + init(_ input: [Int]) { + self.ptr = input.withUnsafeBufferPointer { buffer in + cpp_deque_create(buffer.baseAddress, buffer.count) + } + } + + deinit { + destroy() + } + + func destroy() { + if let ptr = ptr { + cpp_deque_destroy(ptr) + } + ptr = nil + } +} + +internal class CppUnorderedSet { + var ptr: UnsafeMutableRawPointer? + + init(_ input: [Int]) { + self.ptr = input.withUnsafeBufferPointer { buffer in + cpp_unordered_set_create(buffer.baseAddress, buffer.count) + } + } + + deinit { + destroy() + } + + func destroy() { + if let ptr = ptr { + cpp_unordered_set_destroy(ptr) + } + ptr = nil + } +} + +internal class CppUnorderedMap { + var ptr: UnsafeMutableRawPointer? + + init(_ input: [Int]) { + self.ptr = input.withUnsafeBufferPointer { buffer in + cpp_unordered_map_create(buffer.baseAddress, buffer.count) + } + } + + deinit { + destroy() + } + + func destroy() { + if let ptr = ptr { + cpp_unordered_map_destroy(ptr) + } + ptr = nil + } +} + + +extension Benchmark { + public mutating func addCppBenchmarks() { + cpp_set_hash_fn { value in value._rawHashValue(seed: 0) } + + self.addSimple( + title: "std::hash", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_hash(buffer.baseAddress, buffer.count) + } + } + + self.addSimple( + title: "custom_intptr_hash (using Swift.Hasher)", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_custom_hash(buffer.baseAddress, buffer.count) + } + } + + self.addSimple( + title: "std::vector push_back from integer range", + input: Int.self + ) { count in + cpp_vector_from_int_range(count) + } + + self.addSimple( + title: "std::deque push_back from integer range", + input: Int.self + ) { count in + cpp_deque_from_int_range(count) + } + + //-------------------------------------------------------------------------- + + self.addSimple( + title: "std::vector constructor from buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_vector_from_int_buffer(buffer.baseAddress, buffer.count) + } + } + + self.addSimple( + title: "std::deque constructor from buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_deque_from_int_buffer(buffer.baseAddress, buffer.count) + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector sequential iteration", + input: [Int].self + ) { input in + let vector = CppVector(input) + return { timer in + cpp_vector_iterate(vector.ptr) + } + } + + self.add( + title: "std::deque sequential iteration", + input: [Int].self + ) { input in + let deque = CppDeque(input) + return { timer in + cpp_deque_iterate(deque.ptr) + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector random-access offset lookups (operator [])", + input: ([Int], [Int]).self + ) { input, lookups in + let vector = CppVector(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_vector_lookups_subscript(vector.ptr, buffer.baseAddress, buffer.count) + } + } + } + + self.add( + title: "std::deque random-access offset lookups (operator [])", + input: ([Int], [Int]).self + ) { input, lookups in + let vector = CppDeque(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_deque_lookups_subscript(vector.ptr, buffer.baseAddress, buffer.count) + } + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector random-access offset lookups (at)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = CppVector(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_vector_lookups_at(deque.ptr, buffer.baseAddress, buffer.count) + } + } + } + + self.add( + title: "std::deque at, random offsets", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = CppDeque(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_deque_lookups_at(deque.ptr, buffer.baseAddress, buffer.count) + } + } + } + + //-------------------------------------------------------------------------- + + self.addSimple( + title: "std::vector push_back", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_vector_append_integers(buffer.baseAddress, buffer.count, false) + } + } + + self.addSimple( + title: "std::vector push_back, reserving capacity", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_vector_append_integers(buffer.baseAddress, buffer.count, true) + } + } + + self.addSimple( + title: "std::deque push_back", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_deque_append_integers(buffer.baseAddress, buffer.count) + } + } + + //-------------------------------------------------------------------------- + + self.addSimple( + title: "std::vector insert at front", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_vector_prepend_integers(buffer.baseAddress, buffer.count, false) + } + } + + self.addSimple( + title: "std::vector insert at front, reserving capacity", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_vector_prepend_integers(buffer.baseAddress, buffer.count, true) + } + } + + self.addSimple( + title: "std::deque push_front", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_deque_prepend_integers(buffer.baseAddress, buffer.count) + } + } + + //-------------------------------------------------------------------------- + + self.addSimple( + title: "std::vector random insertions", + input: Insertions.self + ) { insertions in + insertions.values.withUnsafeBufferPointer { buffer in + cpp_vector_random_insertions(buffer.baseAddress, buffer.count, false) + } + } + + self.addSimple( + title: "std::deque random insertions", + input: Insertions.self + ) { insertions in + insertions.values.withUnsafeBufferPointer { buffer in + cpp_deque_random_insertions(buffer.baseAddress, buffer.count) + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector pop_back", + input: Int.self + ) { size in + return { timer in + let vector = CppVector(Array(0 ..< size)) + timer.measure { + cpp_vector_pop_back(vector.ptr) + } + vector.destroy() + } + } + + self.add( + title: "std::deque pop_back", + input: Int.self + ) { size in + return { timer in + let deque = CppDeque(Array(0 ..< size)) + timer.measure { + cpp_deque_pop_back(deque.ptr) + } + deque.destroy() + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector erase first", + input: Int.self + ) { size in + return { timer in + let vector = CppVector(Array(0 ..< size)) + timer.measure { + cpp_vector_pop_front(vector.ptr) + } + vector.destroy() + } + } + + self.add( + title: "std::deque pop_front", + input: Int.self + ) { size in + return { timer in + let deque = CppDeque(Array(0 ..< size)) + timer.measure { + cpp_deque_pop_front(deque.ptr) + } + deque.destroy() + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector random removals", + input: Insertions.self + ) { insertions in + let removals = Array(insertions.values.reversed()) + return { timer in + let vector = CppVector(Array(0 ..< removals.count)) + timer.measure { + removals.withUnsafeBufferPointer { buffer in + cpp_vector_random_removals(vector.ptr, buffer.baseAddress, buffer.count) + } + } + vector.destroy() + } + } + + self.add( + title: "std::deque random removals", + input: Insertions.self + ) { insertions in + let removals = Array(insertions.values.reversed()) + return { timer in + let deque = CppDeque(Array(0 ..< removals.count)) + timer.measure { + removals.withUnsafeBufferPointer { buffer in + cpp_deque_random_removals(deque.ptr, buffer.baseAddress, buffer.count) + } + } + deque.destroy() + } + } + + //-------------------------------------------------------------------------- + + self.add( + title: "std::vector sort", + input: [Int].self + ) { input in + return { timer in + let vector = CppVector(input) + timer.measure { + cpp_vector_sort(vector.ptr) + } + vector.destroy() + } + } + + self.add( + title: "std::deque sort", + input: [Int].self + ) { input in + return { timer in + let deque = CppDeque(input) + timer.measure { + cpp_deque_sort(deque.ptr) + } + deque.destroy() + } + } + + //-------------------------------------------------------------------------- + + self.addSimple( + title: "std::unordered_set insert from integer range", + input: Int.self + ) { count in + cpp_unordered_set_from_int_range(count) + } + + self.addSimple( + title: "std::unordered_set constructor from buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_unordered_set_from_int_buffer(buffer.baseAddress, buffer.count) + } + } + + self.add( + title: "std::unordered_set sequential iteration", + input: [Int].self + ) { input in + let set = CppUnorderedSet(input) + return { timer in + cpp_unordered_set_iterate(set.ptr) + } + } + + self.add( + title: "std::unordered_set successful find", + input: ([Int], [Int]).self + ) { input, lookups in + let set = CppUnorderedSet(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_unordered_set_lookups(set.ptr, buffer.baseAddress, buffer.count, true) + } + } + } + + self.add( + title: "std::unordered_set unsuccessful find", + input: ([Int], [Int]).self + ) { input, lookups in + let set = CppUnorderedSet(input) + let lookups = lookups.map { $0 + input.count } + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_unordered_set_lookups(set.ptr, buffer.baseAddress, buffer.count, false) + } + } + } + + self.addSimple( + title: "std::unordered_set insert", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_unordered_set_insert_integers(buffer.baseAddress, buffer.count, false) + } + } + + self.addSimple( + title: "std::unordered_set insert, reserving capacity", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_unordered_set_insert_integers(buffer.baseAddress, buffer.count, true) + } + } + + self.add( + title: "std::unordered_set erase", + input: ([Int], [Int]).self + ) { input, removals in + return { timer in + let set = CppUnorderedSet(input) + timer.measure { + removals.withUnsafeBufferPointer { buffer in + cpp_unordered_set_removals(set.ptr, buffer.baseAddress, buffer.count) + } + } + set.destroy() + } + } + + //-------------------------------------------------------------------------- + + self.addSimple( + title: "std::unordered_map insert from integer range", + input: Int.self + ) { count in + cpp_unordered_map_from_int_range(count) + } + + self.add( + title: "std::unordered_map sequential iteration", + input: [Int].self + ) { input in + let set = CppUnorderedMap(input) + return { timer in + cpp_unordered_map_iterate(set.ptr) + } + } + + self.add( + title: "std::unordered_map successful find", + input: ([Int], [Int]).self + ) { input, lookups in + let map = CppUnorderedMap(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_unordered_map_lookups(map.ptr, buffer.baseAddress, buffer.count, true) + } + } + } + + self.add( + title: "std::unordered_map unsuccessful find", + input: ([Int], [Int]).self + ) { input, lookups in + let map = CppUnorderedMap(input) + let lookups = lookups.map { $0 + input.count } + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_unordered_map_lookups(map.ptr, buffer.baseAddress, buffer.count, false) + } + } + } + + self.add( + title: "std::unordered_map subscript, existing key", + input: ([Int], [Int]).self + ) { input, lookups in + let map = CppUnorderedMap(input) + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_unordered_map_subscript(map.ptr, buffer.baseAddress, buffer.count) + } + } + } + + self.add( + title: "std::unordered_map subscript, new key", + input: ([Int], [Int]).self + ) { input, lookups in + let map = CppUnorderedMap(input) + let lookups = lookups.map { $0 + input.count } + return { timer in + lookups.withUnsafeBufferPointer { buffer in + cpp_unordered_map_subscript(map.ptr, buffer.baseAddress, buffer.count) + } + } + } + + self.addSimple( + title: "std::unordered_map insert", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_unordered_map_insert_integers(buffer.baseAddress, buffer.count, false) + } + } + + self.addSimple( + title: "std::unordered_map insert, reserving capacity", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + cpp_unordered_map_insert_integers(buffer.baseAddress, buffer.count, true) + } + } + + self.add( + title: "std::unordered_map erase existing", + input: ([Int], [Int]).self + ) { input, removals in + return { timer in + let map = CppUnorderedMap(input) + timer.measure { + removals.withUnsafeBufferPointer { buffer in + cpp_unordered_map_removals(map.ptr, buffer.baseAddress, buffer.count) + } + } + map.destroy() + } + } + + self.add( + title: "std::unordered_map erase missing", + input: ([Int], [Int]).self + ) { input, removals in + return { timer in + let map = CppUnorderedMap(input.map { input.count + $0 }) + timer.measure { + removals.withUnsafeBufferPointer { buffer in + cpp_unordered_map_removals(map.ptr, buffer.baseAddress, buffer.count) + } + } + map.destroy() + } + } + } +} diff --git a/Benchmarks/Benchmarks/DequeBenchmarks.swift b/Benchmarks/Benchmarks/DequeBenchmarks.swift new file mode 100644 index 00000000..b801934f --- /dev/null +++ b/Benchmarks/Benchmarks/DequeBenchmarks.swift @@ -0,0 +1,460 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark +@_spi(Testing) import DequeModule + +extension Deque { + @inline(__always) + internal init(discontiguous contents: [Element]) { + self.init(_capacity: contents.count, + startSlot: contents.count / 4, + contents: contents) + } +} + +extension Benchmark { + public mutating func addDequeBenchmarks() { + self.addSimple( + title: "Deque init from range", + input: Int.self + ) { size in + blackHole(Deque(0 ..< size)) + } + + self.addSimple( + title: "Deque init from unsafe buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + blackHole(Deque(buffer)) + } + } + + self.add( + title: "Deque sequential iteration (contiguous)", + input: [Int].self + ) { input in + let deque = Deque(input) + return { timer in + for i in deque { + blackHole(i) + } + } + } + + self.add( + title: "Deque sequential iteration (discontiguous)", + input: [Int].self + ) { input in + let deque = Deque(discontiguous: input) + return { timer in + for i in deque { + blackHole(i) + } + } + } + + self.add( + title: "Deque subscript get, random offsets (contiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = Deque(input) + return { timer in + for i in lookups { + blackHole(deque[i]) + } + } + } + + self.add( + title: "Deque subscript get, random offsets (discontiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = Deque(discontiguous: input) + return { timer in + for i in lookups { + blackHole(deque[i]) + } + } + } + + self.add( + title: "Deque successful contains (contiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = Deque(input) + return { timer in + for i in lookups { + precondition(deque.contains(i)) + } + } + } + + self.add( + title: "Deque successful contains (discontiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = Deque(discontiguous: input) + return { timer in + for i in lookups { + precondition(deque.contains(i)) + } + } + } + + self.add( + title: "Deque unsuccessful contains (contiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = Deque(input) + return { timer in + let c = input.count + for i in lookups { + precondition(!deque.contains(i + c)) + } + } + } + + self.add( + title: "Deque unsuccessful contains (discontiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + let deque = Deque(discontiguous: input) + return { timer in + let c = input.count + for i in lookups { + precondition(!deque.contains(i + c)) + } + } + } + + self.add( + title: "Deque mutate through subscript (contiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var deque = Deque(input) + timer.measure { + var v = 0 + for i in lookups { + deque[i] = v + v += 1 + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque mutate through subscript (discontiguous)", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var deque = Deque(discontiguous: input) + timer.measure { + var v = 0 + for i in lookups { + deque[i] = v + v += 1 + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque random swaps (contiguous)", + input: [Int].self + ) { input in + return { timer in + var deque = Deque(0 ..< input.count) + timer.measure { + var v = 0 + for i in input { + deque.swapAt(i, v) + v += 1 + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque random swaps (discontiguous)", + input: [Int].self + ) { input in + return { timer in + var deque = Deque(discontiguous: input) + timer.measure { + var v = 0 + for i in input { + deque.swapAt(i, v) + v += 1 + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque partitioning around middle (contiguous)", + input: [Int].self + ) { input in + return { timer in + let pivot = input.count / 2 + var deque = Deque(input) + timer.measure { + let r = deque.partition(by: { $0 >= pivot }) + precondition(r == pivot) + } + blackHole(deque) + } + } + + self.add( + title: "Deque partitioning around middle (discontiguous)", + input: [Int].self + ) { input in + return { timer in + let pivot = input.count / 2 + var deque = Deque(discontiguous: input) + timer.measure { + let r = deque.partition(by: { $0 >= pivot }) + precondition(r == pivot) + } + blackHole(deque) + } + } + + self.add( + title: "Deque sort (contiguous)", + input: [Int].self + ) { input in + return { timer in + var deque = Deque(input) + timer.measure { + deque.sort() + } + precondition(deque.elementsEqual(0 ..< input.count)) + } + } + + self.add( + title: "Deque sort (discontiguous)", + input: [Int].self + ) { input in + return { timer in + var deque = Deque(discontiguous: input) + timer.measure { + deque.sort() + } + precondition(deque.elementsEqual(0 ..< input.count)) + } + } + + self.addSimple( + title: "Deque append from range", + input: Int.self + ) { count in + var deque: Deque = [] + for i in 0 ..< count { + deque.append(i) + } + precondition(deque.count == count) + blackHole(deque) + } + + self.addSimple( + title: "Deque append", + input: [Int].self + ) { input in + var deque: Deque = [] + for i in input { + deque.append(i) + } + precondition(deque.count == input.count) + blackHole(deque) + } + + self.addSimple( + title: "Deque append, reserving capacity", + input: [Int].self + ) { input in + var deque: Deque = [] + deque.reserveCapacity(input.count) + for i in input { + deque.append(i) + } + blackHole(deque) + } + + self.addSimple( + title: "Deque prepend", + input: [Int].self + ) { input in + var deque: Deque = [] + for i in input { + deque.prepend(i) + } + blackHole(deque) + } + + self.addSimple( + title: "Deque prepend, reserving capacity", + input: [Int].self + ) { input in + var deque: Deque = [] + deque.reserveCapacity(input.count) + for i in input { + deque.prepend(i) + } + blackHole(deque) + } + + self.addSimple( + title: "Deque kalimba", + input: [Int].self + ) { input in + blackHole(input.kalimbaOrdered2()) + } + + self.add( + title: "Deque random insertions", + input: Insertions.self + ) { insertions in + return { timer in + let insertions = insertions.values + var deque: Deque = [] + timer.measure { + for i in insertions.indices { + deque.insert(i, at: insertions[i]) + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque random insertions, reserving capacity", + input: Insertions.self + ) { insertions in + return { timer in + let insertions = insertions.values + var deque: Deque = [] + deque.reserveCapacity(insertions.count) + timer.measure { + for i in insertions.indices { + deque.insert(i, at: insertions[i]) + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque removeLast (contiguous)", + input: Int.self + ) { size in + return { timer in + var deque = Deque(0 ..< size) + timer.measure { + for _ in 0 ..< size { + deque.removeLast() + } + } + precondition(deque.isEmpty) + blackHole(deque) + } + } + + self.add( + title: "Deque removeLast (discontiguous)", + input: Int.self + ) { size in + return { timer in + var deque = Deque(discontiguous: Array(0 ..< size)) + timer.measure { + for _ in 0 ..< size { + deque.removeLast() + } + } + precondition(deque.isEmpty) + blackHole(deque) + } + } + + self.add( + title: "Deque removeFirst (contiguous)", + input: Int.self + ) { size in + return { timer in + var deque = Deque(0 ..< size) + timer.measure { + for _ in 0 ..< size { + deque.removeFirst() + } + } + precondition(deque.isEmpty) + blackHole(deque) + } + } + + self.add( + title: "Deque removeFirst (discontiguous)", + input: Int.self + ) { size in + return { timer in + var deque = Deque(discontiguous: Array(0 ..< size)) + timer.measure { + for _ in 0 ..< size { + deque.removeFirst() + } + } + precondition(deque.isEmpty) + blackHole(deque) + } + } + + self.add( + title: "Deque random removals (contiguous)", + input: Insertions.self + ) { insertions in + let removals = Array(insertions.values.reversed()) + return { timer in + var deque = Deque(0 ..< removals.count) + timer.measure { + for i in removals { + deque.remove(at: i) + } + } + blackHole(deque) + } + } + + self.add( + title: "Deque random removals (discontiguous)", + input: Insertions.self + ) { insertions in + let removals = Array(insertions.values.reversed()) + return { timer in + let size = removals.count + var deque = Deque(discontiguous: Array(0 ..< size)) + timer.measure { + for i in removals { + deque.remove(at: i) + } + } + blackHole(deque) + } + } + } +} diff --git a/Benchmarks/Benchmarks/DictionaryBenchmarks.swift b/Benchmarks/Benchmarks/DictionaryBenchmarks.swift new file mode 100644 index 00000000..8388fe61 --- /dev/null +++ b/Benchmarks/Benchmarks/DictionaryBenchmarks.swift @@ -0,0 +1,342 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark + +extension Benchmark { + public mutating func addDictionaryBenchmarks() { + self.add( + title: "Dictionary init(uniqueKeysWithValues:)", + input: [Int].self + ) { input in + let keysAndValues = input.map { ($0, 2 * $0) } + return { timer in + blackHole(Dictionary(uniqueKeysWithValues: keysAndValues)) + } + } + + self.add( + title: "Dictionary sequential iteration", + input: [Int].self + ) { input in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for item in d { + blackHole(item) + } + } + } + + self.add( + title: "Dictionary.Keys sequential iteration", + input: [Int].self + ) { input in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for item in d.keys { + blackHole(item) + } + } + } + + self.add( + title: "Dictionary.Values sequential iteration", + input: [Int].self + ) { input in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for item in d.values { + blackHole(item) + } + } + } + + self.add( + title: "Dictionary subscript, successful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for i in lookups { + precondition(d[i] == 2 * i) + } + } + } + + self.add( + title: "Dictionary subscript, unsuccessful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + let c = input.count + return { timer in + for i in lookups { + precondition(d[i + c] == nil) + } + } + } + + self.add( + title: "Dictionary subscript, noop setter", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + let c = input.count + timer.measure { + for i in lookups { + d[i + c] = nil + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary subscript, set existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i] = 0 + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary subscript, _modify", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i]! *= 2 + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.addSimple( + title: "Dictionary subscript, insert", + input: [Int].self + ) { input in + var d: [Int: Int] = [:] + for i in input { + d[i] = 2 * i + } + precondition(d.count == input.count) + blackHole(d) + } + + self.addSimple( + title: "Dictionary subscript, insert, reserving capacity", + input: [Int].self + ) { input in + var d: [Int: Int] = [:] + d.reserveCapacity(input.count) + for i in input { + d[i] = 2 * i + } + precondition(d.count == input.count) + blackHole(d) + } + + self.add( + title: "Dictionary subscript, remove existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i] = nil + } + } + precondition(d.isEmpty) + blackHole(d) + } + } + + self.add( + title: "Dictionary subscript, remove missing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + let c = input.count + timer.measure { + for i in lookups { + d[i + c] = nil + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary defaulted subscript, successful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for i in lookups { + precondition(d[i, default: -1] != -1) + } + } + } + + self.add( + title: "Dictionary defaulted subscript, unsuccessful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + let c = d.count + for i in lookups { + precondition(d[i + c, default: -1] == -1) + } + } + } + + self.add( + title: "Dictionary defaulted subscript, _modify existing", + input: [Int].self + ) { input in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in input { + d[i, default: -1] *= 2 + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary defaulted subscript, _modify missing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + let c = input.count + timer.measure { + for i in lookups { + d[c + i, default: -1] *= 2 + } + } + precondition(d.count == 2 * input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary successful index(forKey:)", + input: ([Int], [Int]).self + ) { input, lookups in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for i in lookups { + precondition(d.index(forKey: i) != nil) + } + } + } + + self.add( + title: "Dictionary unsuccessful index(forKey:)", + input: ([Int], [Int]).self + ) { input, lookups in + let d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + return { timer in + for i in lookups { + precondition(d.index(forKey: lookups.count + i) == nil) + } + } + } + + self.add( + title: "Dictionary updateValue(_:forKey:), existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d.updateValue(0, forKey: i) + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary updateValue(_:forKey:), insert", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d.updateValue(0, forKey: input.count + i) + } + } + precondition(d.count == 2 * input.count) + blackHole(d) + } + } + + self.add( + title: "Dictionary random removals (existing keys)", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + precondition(d.removeValue(forKey: i) != nil) + } + } + precondition(d.count == 0) + blackHole(d) + } + } + + self.add( + title: "Dictionary random removals (missing keys)", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + let c = input.count + var d = Dictionary(uniqueKeysWithValues: input.lazy.map { (c + $0, 2 * $0) }) + timer.measure { + for i in lookups { + precondition(d.removeValue(forKey: i) == nil) + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + } +} diff --git a/Benchmarks/Benchmarks/Kalimba.swift b/Benchmarks/Benchmarks/Kalimba.swift new file mode 100644 index 00000000..5da2e92c --- /dev/null +++ b/Benchmarks/Benchmarks/Kalimba.swift @@ -0,0 +1,64 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import DequeModule + +extension Sequence { + func kalimbaOrdered() -> [Element] { + var kalimba: [Element] = [] + kalimba.reserveCapacity(underestimatedCount) + var insertAtStart = false + for element in self { + if insertAtStart { + kalimba.insert(element, at: 0) + } else { + kalimba.append(element) + } + insertAtStart.toggle() + } + return kalimba + } + + func kalimbaOrdered2() -> Deque { + var kalimba: Deque = [] + kalimba.reserveCapacity(underestimatedCount) + var insertAtStart = false + for element in self { + if insertAtStart { + kalimba.prepend(element) + } else { + kalimba.append(element) + } + insertAtStart.toggle() + } + return kalimba + } + + func kalimbaOrdered3() -> [Element] { + var odds: [Element] = [] + var evens: [Element] = [] + odds.reserveCapacity(underestimatedCount) + evens.reserveCapacity(underestimatedCount / 2) + var insertAtStart = false + for element in self { + if insertAtStart { + odds.append(element) + } else { + evens.append(element) + } + insertAtStart.toggle() + } + odds.reverse() + odds.append(contentsOf: evens) + return odds + } + +} diff --git a/Benchmarks/Benchmarks/Library.json b/Benchmarks/Benchmarks/Library.json new file mode 100644 index 00000000..4d3cad8b --- /dev/null +++ b/Benchmarks/Benchmarks/Library.json @@ -0,0 +1,2001 @@ +{ + "kind": "group", + "title": "All results", + "directory": "Results", + "contents": [ + { + "kind": "group", + "title": "Individual types", + "directory": "single", + "contents": [ + { + "kind": "group", + "title": "Array", + "contents": [ + { + "kind": "chart", + "title": "operations", + "tasks": [ + "Array init from unsafe buffer", + "Array sequential iteration", + "Array subscript get, random offsets", + "Array append", + "Array append, reserving capacity", + "Array prepend", + "Array prepend, reserving capacity", + "Array removeFirst", + "Array removeLast", + "Array sort" + ] + }, + { + "kind": "chart", + "title": "access", + "tasks": [ + "Array sequential iteration", + "Array subscript get, random offsets" + ] + }, + { + "kind": "chart", + "title": "mutate", + "tasks": [ + "Array mutate through subscript", + "Array random swaps", + "Array partitioning around middle", + "Array sort" + ] + }, + ] + }, + { + "kind": "group", + "title": "Set", + "contents": [ + { + "kind": "chart", + "title": "operations", + "tasks": [ + "Set init from range", + "Set init from unsafe buffer", + "Set sequential iteration", + "Set successful contains", + "Set unsuccessful contains", + "Set insert", + "Set insert, reserving capacity", + "Set remove" + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "union with Self", + "tasks": [ + "Set union with Self (0% overlap)", + "Set union with Self (25% overlap)", + "Set union with Self (50% overlap)", + "Set union with Self (75% overlap)", + "Set union with Self (100% overlap)" + ] + }, + { + "kind": "chart", + "title": "union with Array", + "tasks": [ + "Set union with Array (0% overlap)", + "Set union with Array (25% overlap)", + "Set union with Array (50% overlap)", + "Set union with Array (75% overlap)", + "Set union with Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion with Self", + "tasks": [ + "Set formUnion with Self (0% overlap)", + "Set formUnion with Self (25% overlap)", + "Set formUnion with Self (50% overlap)", + "Set formUnion with Self (75% overlap)", + "Set formUnion with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion with Array", + "tasks": [ + "Set formUnion with Array (0% overlap)", + "Set formUnion with Array (25% overlap)", + "Set formUnion with Array (50% overlap)", + "Set formUnion with Array (75% overlap)", + "Set formUnion with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "intersection with Self", + "tasks": [ + "Set intersection with Self (0% overlap)", + "Set intersection with Self (25% overlap)", + "Set intersection with Self (50% overlap)", + "Set intersection with Self (75% overlap)", + "Set intersection with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "intersection with Array", + "tasks": [ + "Set intersection with Array (0% overlap)", + "Set intersection with Array (25% overlap)", + "Set intersection with Array (50% overlap)", + "Set intersection with Array (75% overlap)", + "Set intersection with Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection with Self", + "tasks": [ + "Set formIntersection with Self (0% overlap)", + "Set formIntersection with Self (25% overlap)", + "Set formIntersection with Self (50% overlap)", + "Set formIntersection with Self (75% overlap)", + "Set formIntersection with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection with Array", + "tasks": [ + "Set formIntersection with Array (0% overlap)", + "Set formIntersection with Array (25% overlap)", + "Set formIntersection with Array (50% overlap)", + "Set formIntersection with Array (75% overlap)", + "Set formIntersection with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "symmetricDifference with Self", + "tasks": [ + "Set symmetricDifference with Self (0% overlap)", + "Set symmetricDifference with Self (25% overlap)", + "Set symmetricDifference with Self (50% overlap)", + "Set symmetricDifference with Self (75% overlap)", + "Set symmetricDifference with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "symmetricDifference with Array", + "tasks": [ + "Set symmetricDifference with Array (0% overlap)", + "Set symmetricDifference with Array (25% overlap)", + "Set symmetricDifference with Array (50% overlap)", + "Set symmetricDifference with Array (75% overlap)", + "Set symmetricDifference with Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference with Self", + "tasks": [ + "Set formSymmetricDifference with Self (0% overlap)", + "Set formSymmetricDifference with Self (25% overlap)", + "Set formSymmetricDifference with Self (50% overlap)", + "Set formSymmetricDifference with Self (75% overlap)", + "Set formSymmetricDifference with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference with Array", + "tasks": [ + "Set formSymmetricDifference with Array (0% overlap)", + "Set formSymmetricDifference with Array (25% overlap)", + "Set formSymmetricDifference with Array (50% overlap)", + "Set formSymmetricDifference with Array (75% overlap)", + "Set formSymmetricDifference with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "subtracting Self", + "tasks": [ + "Set subtracting Self (0% overlap)", + "Set subtracting Self (25% overlap)", + "Set subtracting Self (50% overlap)", + "Set subtracting Self (75% overlap)", + "Set subtracting Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtracting Array", + "tasks": [ + "Set subtracting Array (0% overlap)", + "Set subtracting Array (25% overlap)", + "Set subtracting Array (50% overlap)", + "Set subtracting Array (75% overlap)", + "Set subtracting Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract Self", + "tasks": [ + "Set subtract Self (0% overlap)", + "Set subtract Self (25% overlap)", + "Set subtract Self (50% overlap)", + "Set subtract Self (75% overlap)", + "Set subtract Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract with Array", + "tasks": [ + "Set subtract Array (0% overlap)", + "Set subtract Array (25% overlap)", + "Set subtract Array (50% overlap)", + "Set subtract Array (75% overlap)", + "Set subtract Array (100% overlap)", + ] + }, + ] + }, + ] + }, + { + "kind": "group", + "title": "Dictionary", + "contents": [ + { + "kind": "chart", + "title": "operations", + "tasks": [ + "Dictionary init(uniqueKeysWithValues:)", + "Dictionary sequential iteration", + "Dictionary subscript, successful lookups", + "Dictionary subscript, insert", + "Dictionary subscript, remove existing", + ] + }, + { + "kind": "chart", + "title": "iteration", + "tasks": [ + "Dictionary sequential iteration", + "Dictionary.Keys sequential iteration", + "Dictionary.Values sequential iteration" + ] + }, + { + "kind": "chart", + "title": "lookups", + "tasks": [ + "Dictionary subscript, successful lookups", + "Dictionary subscript, unsuccessful lookups", + "Dictionary defaulted subscript, successful lookups", + "Dictionary defaulted subscript, unsuccessful lookups", + "Dictionary successful index(forKey:)", + "Dictionary unsuccessful index(forKey:)", + ] + }, + { + "kind": "chart", + "title": "subscript", + "tasks": [ + "Dictionary subscript, successful lookups", + "Dictionary subscript, unsuccessful lookups", + "Dictionary subscript, noop setter", + "Dictionary subscript, set existing", + "Dictionary subscript, _modify", + "Dictionary subscript, insert", + "Dictionary subscript, insert, reserving capacity", + "Dictionary subscript, remove existing", + "Dictionary subscript, remove missing", + ] + }, + { + "kind": "chart", + "title": "defaulted subscript", + "tasks": [ + "Dictionary defaulted subscript, successful lookups", + "Dictionary defaulted subscript, unsuccessful lookups", + "Dictionary defaulted subscript, _modify existing", + "Dictionary defaulted subscript, _modify missing", + ] + }, + { + "kind": "chart", + "title": "mutations", + "tasks": [ + "Dictionary updateValue(_:forKey:), existing", + "Dictionary subscript, set existing", + "Dictionary subscript, _modify", + "Dictionary defaulted subscript, _modify existing", + ] + }, + { + "kind": "chart", + "title": "removals", + "tasks": [ + "Dictionary subscript, remove existing", + "Dictionary subscript, remove missing", + "Dictionary random removals (existing keys)", + "Dictionary random removals (missing keys)", + ] + }, + ] + }, + { + "kind": "group", + "title": "Deque", + "contents": [ + { + "kind": "chart", + "title": "operations", + "tasks": [ + "Deque init from unsafe buffer", + "Deque sequential iteration (contiguous)", + "Deque subscript get, random offsets (contiguous)", + "Deque append", + "Deque append, reserving capacity", + "Deque prepend", + "Deque prepend, reserving capacity", + "Deque removeFirst (contiguous)", + "Deque removeLast (contiguous)", + "Deque sort (contiguous)", + "Deque sort (discontiguous)" + ] + }, + { + "kind": "chart", + "title": "access", + "tasks": [ + "Deque sequential iteration (contiguous)", + "Deque sequential iteration (discontiguous)", + "Deque subscript get, random offsets (contiguous)", + "Deque subscript get, random offsets (discontiguous)", + "Deque mutate through subscript (contiguous)", + "Deque mutate through subscript (discontiguous)" + ] + }, + { + "kind": "chart", + "title": "mutate", + "tasks": [ + "Deque mutate through subscript (contiguous)", + "Deque mutate through subscript (discontiguous)", + "Deque random swaps (contiguous)", + "Deque random swaps (discontiguous)", + "Deque partitioning around middle (contiguous)", + "Deque partitioning around middle (discontiguous)", + "Deque sort (contiguous)", + "Deque sort (discontiguous)" + ] + }, + { + "kind": "chart", + "title": "push", + "tasks": [ + "Deque append", + "Deque append, reserving capacity", + "Deque prepend", + "Deque prepend, reserving capacity" + ] + }, + { + "kind": "chart", + "title": "pop", + "tasks": [ + "Deque removeFirst (contiguous)", + "Deque removeFirst (discontiguous)", + "Deque removeLast (contiguous)", + "Deque removeLast (discontiguous)" + ] + }, + ] + }, + { + "kind": "group", + "title": "OrderedSet", + "contents": [ + { + "kind": "chart", + "title": "operations", + "tasks": [ + "OrderedSet init from range", + "OrderedSet init from unsafe buffer", + "OrderedSet sequential iteration", + "OrderedSet successful contains", + "OrderedSet unsuccessful contains", + "OrderedSet append", + "OrderedSet append, reserving capacity", + "OrderedSet remove", + ] + }, + { + "kind": "chart", + "title": "initializers", + "tasks": [ + "OrderedSet init from range", + "OrderedSet init from unsafe buffer", + "OrderedSet init(uncheckedUniqueElements:) from range" + ] + }, + { + "kind": "chart", + "title": "mutations", + "tasks": [ + "OrderedSet random swaps", + "OrderedSet partitioning around middle", + "OrderedSet sort", + ] + }, + { + "kind": "chart", + "title": "range replaceable", + "tasks": [ + "OrderedSet append", + "OrderedSet append, reserving capacity", + "OrderedSet prepend", + "OrderedSet prepend, reserving capacity", + "OrderedSet random insertions, reserving capacity", + "OrderedSet remove", + "OrderedSet removeLast", + "OrderedSet removeFirst", + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "union with Self", + "tasks": [ + "OrderedSet union with Self (0% overlap)", + "OrderedSet union with Self (25% overlap)", + "OrderedSet union with Self (50% overlap)", + "OrderedSet union with Self (75% overlap)", + "OrderedSet union with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "union with Array", + "tasks": [ + "OrderedSet union with Array (0% overlap)", + "OrderedSet union with Array (25% overlap)", + "OrderedSet union with Array (50% overlap)", + "OrderedSet union with Array (75% overlap)", + "OrderedSet union with Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion with Self", + "tasks": [ + "OrderedSet formUnion with Self (0% overlap)", + "OrderedSet formUnion with Self (25% overlap)", + "OrderedSet formUnion with Self (50% overlap)", + "OrderedSet formUnion with Self (75% overlap)", + "OrderedSet formUnion with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion with Array", + "tasks": [ + "OrderedSet formUnion with Array (0% overlap)", + "OrderedSet formUnion with Array (25% overlap)", + "OrderedSet formUnion with Array (50% overlap)", + "OrderedSet formUnion with Array (75% overlap)", + "OrderedSet formUnion with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "intersection with Self", + "tasks": [ + "OrderedSet intersection with Self (0% overlap)", + "OrderedSet intersection with Self (25% overlap)", + "OrderedSet intersection with Self (50% overlap)", + "OrderedSet intersection with Self (75% overlap)", + "OrderedSet intersection with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "intersection with Array", + "tasks": [ + "OrderedSet intersection with Array (0% overlap)", + "OrderedSet intersection with Array (25% overlap)", + "OrderedSet intersection with Array (50% overlap)", + "OrderedSet intersection with Array (75% overlap)", + "OrderedSet intersection with Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection with Self", + "tasks": [ + "OrderedSet formIntersection with Self (0% overlap)", + "OrderedSet formIntersection with Self (25% overlap)", + "OrderedSet formIntersection with Self (50% overlap)", + "OrderedSet formIntersection with Self (75% overlap)", + "OrderedSet formIntersection with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection with Array", + "tasks": [ + "OrderedSet formIntersection with Array (0% overlap)", + "OrderedSet formIntersection with Array (25% overlap)", + "OrderedSet formIntersection with Array (50% overlap)", + "OrderedSet formIntersection with Array (75% overlap)", + "OrderedSet formIntersection with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "symmetricDifference with Self", + "tasks": [ + "OrderedSet symmetricDifference with Self (0% overlap)", + "OrderedSet symmetricDifference with Self (25% overlap)", + "OrderedSet symmetricDifference with Self (50% overlap)", + "OrderedSet symmetricDifference with Self (75% overlap)", + "OrderedSet symmetricDifference with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "symmetricDifference with Array", + "tasks": [ + "OrderedSet symmetricDifference with Array (0% overlap)", + "OrderedSet symmetricDifference with Array (25% overlap)", + "OrderedSet symmetricDifference with Array (50% overlap)", + "OrderedSet symmetricDifference with Array (75% overlap)", + "OrderedSet symmetricDifference with Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference with Self", + "tasks": [ + "OrderedSet formSymmetricDifference with Self (0% overlap)", + "OrderedSet formSymmetricDifference with Self (25% overlap)", + "OrderedSet formSymmetricDifference with Self (50% overlap)", + "OrderedSet formSymmetricDifference with Self (75% overlap)", + "OrderedSet formSymmetricDifference with Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference with Array", + "tasks": [ + "OrderedSet formSymmetricDifference with Array (0% overlap)", + "OrderedSet formSymmetricDifference with Array (25% overlap)", + "OrderedSet formSymmetricDifference with Array (50% overlap)", + "OrderedSet formSymmetricDifference with Array (75% overlap)", + "OrderedSet formSymmetricDifference with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "subtracting Self", + "tasks": [ + "OrderedSet subtracting Self (0% overlap)", + "OrderedSet subtracting Self (25% overlap)", + "OrderedSet subtracting Self (50% overlap)", + "OrderedSet subtracting Self (75% overlap)", + "OrderedSet subtracting Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtracting Array", + "tasks": [ + "OrderedSet subtracting Array (0% overlap)", + "OrderedSet subtracting Array (25% overlap)", + "OrderedSet subtracting Array (50% overlap)", + "OrderedSet subtracting Array (75% overlap)", + "OrderedSet subtracting Array (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract Self", + "tasks": [ + "OrderedSet subtract Self (0% overlap)", + "OrderedSet subtract Self (25% overlap)", + "OrderedSet subtract Self (50% overlap)", + "OrderedSet subtract Self (75% overlap)", + "OrderedSet subtract Self (100% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract with Array", + "tasks": [ + "OrderedSet subtract Array (0% overlap)", + "OrderedSet subtract Array (25% overlap)", + "OrderedSet subtract Array (50% overlap)", + "OrderedSet subtract Array (75% overlap)", + "OrderedSet subtract Array (100% overlap)", + ] + }, + ] + }, + ] + }, + { + "kind": "group", + "title": "OrderedDictionary", + "contents": [ + { + "kind": "chart", + "title": "operations", + "tasks": [ + "OrderedDictionary init(uniqueKeysWithValues:)", + "OrderedDictionary sequential iteration", + "OrderedDictionary subscript, successful lookups", + "OrderedDictionary subscript, append", + "OrderedDictionary subscript, remove existing", + ] + }, + { + "kind": "chart", + "title": "initializers", + "tasks": [ + "OrderedDictionary init(uniqueKeysWithValues:)", + "OrderedDictionary init(uncheckedUniqueKeysWithValues:)", + "OrderedDictionary init(uncheckedUniqueKeys:values:)" + ] + }, + { + "kind": "chart", + "title": "iteration", + "tasks": [ + "OrderedDictionary sequential iteration", + "OrderedDictionary.Keys sequential iteration", + "OrderedDictionary.Values sequential iteration" + ] + }, + { + "kind": "chart", + "title": "lookups", + "tasks": [ + "OrderedDictionary subscript, successful lookups", + "OrderedDictionary subscript, unsuccessful lookups", + "OrderedDictionary defaulted subscript, successful lookups", + "OrderedDictionary defaulted subscript, unsuccessful lookups", + "OrderedDictionary successful index(forKey:)", + "OrderedDictionary unsuccessful index(forKey:)", + ] + }, + { + "kind": "chart", + "title": "subscript", + "tasks": [ + "OrderedDictionary subscript, successful lookups", + "OrderedDictionary subscript, unsuccessful lookups", + "OrderedDictionary subscript, noop setter", + "OrderedDictionary subscript, set existing", + "OrderedDictionary subscript, _modify", + "OrderedDictionary subscript, append", + "OrderedDictionary subscript, append, reserving capacity", + "OrderedDictionary subscript, remove existing", + "OrderedDictionary subscript, remove missing", + ] + }, + { + "kind": "chart", + "title": "defaulted subscript", + "tasks": [ + "OrderedDictionary defaulted subscript, successful lookups", + "OrderedDictionary defaulted subscript, unsuccessful lookups", + "OrderedDictionary defaulted subscript, _modify existing", + "OrderedDictionary defaulted subscript, _modify missing", + ] + }, + { + "kind": "chart", + "title": "mutations", + "tasks": [ + "OrderedDictionary updateValue(_:forKey:), existing", + "OrderedDictionary subscript, set existing", + "OrderedDictionary subscript, _modify", + "OrderedDictionary defaulted subscript, _modify existing", + "OrderedDictionary random swaps", + "OrderedDictionary partitioning around middle", + "OrderedDictionary sort", + ] + }, + { + "kind": "chart", + "title": "removals", + "tasks": [ + "OrderedDictionary subscript, remove existing", + "OrderedDictionary subscript, remove missing", + "OrderedDictionary removeLast", + "OrderedDictionary removeFirst", + "OrderedDictionary random removals (offset-based)", + "OrderedDictionary random removals (existing keys)", + "OrderedDictionary random removals (missing keys)", + ] + }, + ] + } + ] + }, + { + "kind": "group", + "title": "Against other Swift collections", + "directory": "stdlib", + "contents": [ + { + "kind": "group", + "title": "Deque vs Array", + "contents": [ + { + "kind": "chart", + "title": "init from buffer of integers", + "tasks": [ + "Deque init from unsafe buffer", + "Array init from unsafe buffer" + ] + }, + { + "kind": "chart", + "title": "sequential iteration", + "tasks": [ + "Deque sequential iteration (contiguous)", + "Deque sequential iteration (discontiguous)", + "Array sequential iteration", + ] + }, + { + "kind": "chart", + "title": "random-access offset lookups", + "tasks": [ + "Deque subscript get, random offsets (contiguous)", + "Deque subscript get, random offsets (discontiguous)", + "Array subscript get, random offsets" + ] + }, + { + "kind": "chart", + "title": "mutate through subscript", + "tasks": [ + "Deque mutate through subscript (contiguous)", + "Deque mutate through subscript (discontiguous)", + "Array mutate through subscript" + ] + }, + { + "kind": "chart", + "title": "random swaps", + "tasks": [ + "Deque random swaps (contiguous)", + "Deque random swaps (discontiguous)", + "Array random swaps", + ] + }, + { + "kind": "chart", + "title": "partitioning around middle", + "tasks": [ + "Deque partitioning around middle (contiguous)", + "Deque partitioning around middle (discontiguous)", + "Array partitioning around middle", + ] + }, + { + "kind": "chart", + "title": "sort", + "tasks": [ + "Deque sort (contiguous)", + "Deque sort (discontiguous)", + "Array sort", + ] + }, + { + "kind": "chart", + "title": "append individual integers", + "tasks": [ + "Deque append", + "Deque append, reserving capacity", + "Array append", + "Array append, reserving capacity" + ] + }, + { + "kind": "chart", + "title": "prepend individual integers", + "tasks": [ + "Deque prepend", + "Deque prepend, reserving capacity", + "Array prepend", + "Array prepend, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "random insertions", + "tasks": [ + "Deque random insertions", + "Array random insertions", + ] + }, + { + "kind": "chart", + "title": "removeFirst", + "tasks": [ + "Deque removeFirst (contiguous)", + "Deque removeFirst (discontiguous)", + "Array removeFirst", + ] + }, + { + "kind": "chart", + "title": "removeLast", + "tasks": [ + "Deque removeLast (contiguous)", + "Deque removeLast (discontiguous)", + "Array removeLast", + ] + }, + { + "kind": "chart", + "title": "random removals", + "tasks": [ + "Deque random removals (contiguous)", + "Deque random removals (discontiguous)", + "Array random removals", + ] + }, + ] + }, + { + "kind": "group", + "title": "OrderedSet vs Set", + "contents": [ + { + "kind": "chart", + "title": "init from buffer of integers", + "tasks": [ + "OrderedSet init from unsafe buffer", + "Set init from unsafe buffer", + ] + }, + { + "kind": "chart", + "title": "init from range of integers", + "tasks": [ + "OrderedSet init from range", + "Set init from range", + ] + }, + { + "kind": "chart", + "title": "sequential iteration", + "tasks": [ + "OrderedSet sequential iteration", + "Set sequential iteration", + ] + }, + { + "kind": "chart", + "title": "successful random lookups", + "tasks": [ + "OrderedSet successful contains", + "Set successful contains", + ] + }, + { + "kind": "chart", + "title": "unsuccessful random lookups", + "tasks": [ + "OrderedSet unsuccessful contains", + "Set unsuccessful contains", + ] + }, + { + "kind": "chart", + "title": "insert", + "tasks": [ + "OrderedSet append", + "OrderedSet append, reserving capacity", + "Set insert", + "Set insert, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "remove", + "tasks": [ + "OrderedSet remove", + "Set remove", + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "union (0% overlap)", + "tasks": [ + "OrderedSet union with Self (0% overlap)", + "OrderedSet union with Array (0% overlap)", + "Set union with Self (0% overlap)", + "Set union with Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "union (25% overlap)", + "tasks": [ + "OrderedSet union with Self (25% overlap)", + "OrderedSet union with Array (25% overlap)", + "Set union with Self (25% overlap)", + "Set union with Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "union (50% overlap)", + "tasks": [ + "OrderedSet union with Self (50% overlap)", + "OrderedSet union with Array (50% overlap)", + "Set union with Self (50% overlap)", + "Set union with Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "union (75% overlap)", + "tasks": [ + "OrderedSet union with Self (75% overlap)", + "OrderedSet union with Array (75% overlap)", + "Set union with Self (75% overlap)", + "Set union with Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "union (100% overlap)", + "tasks": [ + "OrderedSet union with Self (100% overlap)", + "OrderedSet union with Array (100% overlap)", + "Set union with Self (100% overlap)", + "Set union with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "formUnion (0% overlap)", + "tasks": [ + "OrderedSet formUnion with Self (0% overlap)", + "OrderedSet formUnion with Array (0% overlap)", + "Set formUnion with Self (0% overlap)", + "Set formUnion with Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion (25% overlap)", + "tasks": [ + "OrderedSet formUnion with Self (25% overlap)", + "OrderedSet formUnion with Array (25% overlap)", + "Set formUnion with Self (25% overlap)", + "Set formUnion with Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion (50% overlap)", + "tasks": [ + "OrderedSet formUnion with Self (50% overlap)", + "OrderedSet formUnion with Array (50% overlap)", + "Set formUnion with Self (50% overlap)", + "Set formUnion with Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion (75% overlap)", + "tasks": [ + "OrderedSet formUnion with Self (75% overlap)", + "OrderedSet formUnion with Array (75% overlap)", + "Set formUnion with Self (75% overlap)", + "Set formUnion with Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "formUnion (100% overlap)", + "tasks": [ + "OrderedSet formUnion with Self (100% overlap)", + "OrderedSet formUnion with Array (100% overlap)", + "Set formUnion with Self (100% overlap)", + "Set formUnion with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "intersection (0% overlap)", + "tasks": [ + "OrderedSet intersection with Self (0% overlap)", + "OrderedSet intersection with Array (0% overlap)", + "Set intersection with Self (0% overlap)", + "Set intersection with Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "intersection (25% overlap)", + "tasks": [ + "OrderedSet intersection with Self (25% overlap)", + "OrderedSet intersection with Array (25% overlap)", + "Set intersection with Self (25% overlap)", + "Set intersection with Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "intersection (50% overlap)", + "tasks": [ + "OrderedSet intersection with Self (50% overlap)", + "OrderedSet intersection with Array (50% overlap)", + "Set intersection with Self (50% overlap)", + "Set intersection with Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "intersection (75% overlap)", + "tasks": [ + "OrderedSet intersection with Self (75% overlap)", + "OrderedSet intersection with Array (75% overlap)", + "Set intersection with Self (75% overlap)", + "Set intersection with Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "intersection (100% overlap)", + "tasks": [ + "OrderedSet intersection with Self (100% overlap)", + "OrderedSet intersection with Array (100% overlap)", + "Set intersection with Self (100% overlap)", + "Set intersection with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "formIntersection (0% overlap)", + "tasks": [ + "OrderedSet formIntersection with Self (0% overlap)", + "OrderedSet formIntersection with Array (0% overlap)", + "Set formIntersection with Self (0% overlap)", + "Set formIntersection with Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection (25% overlap)", + "tasks": [ + "OrderedSet formIntersection with Self (25% overlap)", + "OrderedSet formIntersection with Array (25% overlap)", + "Set formIntersection with Self (25% overlap)", + "Set formIntersection with Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection (50% overlap)", + "tasks": [ + "OrderedSet formIntersection with Self (50% overlap)", + "OrderedSet formIntersection with Array (50% overlap)", + "Set formIntersection with Self (50% overlap)", + "Set formIntersection with Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection (75% overlap)", + "tasks": [ + "OrderedSet formIntersection with Self (75% overlap)", + "OrderedSet formIntersection with Array (75% overlap)", + "Set formIntersection with Self (75% overlap)", + "Set formIntersection with Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "formIntersection (100% overlap)", + "tasks": [ + "OrderedSet formIntersection with Self (100% overlap)", + "OrderedSet formIntersection with Array (100% overlap)", + "Set formIntersection with Self (100% overlap)", + "Set formIntersection with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "symmetricDifference (0% overlap)", + "tasks": [ + "OrderedSet symmetricDifference with Self (0% overlap)", + "OrderedSet symmetricDifference with Array (0% overlap)", + "Set symmetricDifference with Self (0% overlap)", + "Set symmetricDifference with Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "symmetricDifference (25% overlap)", + "tasks": [ + "OrderedSet symmetricDifference with Self (25% overlap)", + "OrderedSet symmetricDifference with Array (25% overlap)", + "Set symmetricDifference with Self (25% overlap)", + "Set symmetricDifference with Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "symmetricDifference (50% overlap)", + "tasks": [ + "OrderedSet symmetricDifference with Self (50% overlap)", + "OrderedSet symmetricDifference with Array (50% overlap)", + "Set symmetricDifference with Self (50% overlap)", + "Set symmetricDifference with Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "symmetricDifference (75% overlap)", + "tasks": [ + "OrderedSet symmetricDifference with Self (75% overlap)", + "OrderedSet symmetricDifference with Array (75% overlap)", + "Set symmetricDifference with Self (75% overlap)", + "Set symmetricDifference with Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "symmetricDifference (100% overlap)", + "tasks": [ + "OrderedSet symmetricDifference with Self (100% overlap)", + "OrderedSet symmetricDifference with Array (100% overlap)", + "Set symmetricDifference with Self (100% overlap)", + "Set symmetricDifference with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "formSymmetricDifference (0% overlap)", + "tasks": [ + "OrderedSet formSymmetricDifference with Self (0% overlap)", + "OrderedSet formSymmetricDifference with Array (0% overlap)", + "Set formSymmetricDifference with Self (0% overlap)", + "Set formSymmetricDifference with Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference (25% overlap)", + "tasks": [ + "OrderedSet formSymmetricDifference with Self (25% overlap)", + "OrderedSet formSymmetricDifference with Array (25% overlap)", + "Set formSymmetricDifference with Self (25% overlap)", + "Set formSymmetricDifference with Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference (50% overlap)", + "tasks": [ + "OrderedSet formSymmetricDifference with Self (50% overlap)", + "OrderedSet formSymmetricDifference with Array (50% overlap)", + "Set formSymmetricDifference with Self (50% overlap)", + "Set formSymmetricDifference with Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference (75% overlap)", + "tasks": [ + "OrderedSet formSymmetricDifference with Self (75% overlap)", + "OrderedSet formSymmetricDifference with Array (75% overlap)", + "Set formSymmetricDifference with Self (75% overlap)", + "Set formSymmetricDifference with Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "formSymmetricDifference (100% overlap)", + "tasks": [ + "OrderedSet formSymmetricDifference with Self (100% overlap)", + "OrderedSet formSymmetricDifference with Array (100% overlap)", + "Set formSymmetricDifference with Self (100% overlap)", + "Set formSymmetricDifference with Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "subtracting (0% overlap)", + "tasks": [ + "OrderedSet subtracting Self (0% overlap)", + "OrderedSet subtracting Array (0% overlap)", + "Set subtracting Self (0% overlap)", + "Set subtracting Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtracting (25% overlap)", + "tasks": [ + "OrderedSet subtracting Self (25% overlap)", + "OrderedSet subtracting Array (25% overlap)", + "Set subtracting Self (25% overlap)", + "Set subtracting Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtracting (50% overlap)", + "tasks": [ + "OrderedSet subtracting Self (50% overlap)", + "OrderedSet subtracting Array (50% overlap)", + "Set subtracting Self (50% overlap)", + "Set subtracting Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtracting (75% overlap)", + "tasks": [ + "OrderedSet subtracting Self (75% overlap)", + "OrderedSet subtracting Array (75% overlap)", + "Set subtracting Self (75% overlap)", + "Set subtracting Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtracting (100% overlap)", + "tasks": [ + "OrderedSet subtracting Self (100% overlap)", + "OrderedSet subtracting Array (100% overlap)", + "Set subtracting Self (100% overlap)", + "Set subtracting Array (100% overlap)", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "subtract (0% overlap)", + "tasks": [ + "OrderedSet subtract Self (0% overlap)", + "OrderedSet subtract Array (0% overlap)", + "Set subtract Self (0% overlap)", + "Set subtract Array (0% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract (25% overlap)", + "tasks": [ + "OrderedSet subtract Self (25% overlap)", + "OrderedSet subtract Array (25% overlap)", + "Set subtract Self (25% overlap)", + "Set subtract Array (25% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract (50% overlap)", + "tasks": [ + "OrderedSet subtract Self (50% overlap)", + "OrderedSet subtract Array (50% overlap)", + "Set subtract Self (50% overlap)", + "Set subtract Array (50% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract (75% overlap)", + "tasks": [ + "OrderedSet subtract Self (75% overlap)", + "OrderedSet subtract Array (75% overlap)", + "Set subtract Self (75% overlap)", + "Set subtract Array (75% overlap)", + ] + }, + { + "kind": "chart", + "title": "subtract (100% overlap)", + "tasks": [ + "OrderedSet subtract Self (100% overlap)", + "OrderedSet subtract Array (100% overlap)", + "Set subtract Self (100% overlap)", + "Set subtract Array (100% overlap)", + ] + }, + ] + }, + ] + }, + { + "kind": "group", + "title": "OrderedDictionary vs Dictionary", + "contents": [ + { + "kind": "chart", + "title": "initializers", + "tasks": [ + "Dictionary init(uniqueKeysWithValues:)", + "OrderedDictionary init(uniqueKeysWithValues:)", + "OrderedDictionary init(uncheckedUniqueKeysWithValues:)", + "OrderedDictionary init(uncheckedUniqueKeys:values:)" + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "iteration", + "tasks": [ + "Dictionary sequential iteration", + "OrderedDictionary sequential iteration", + ] + }, + { + "kind": "chart", + "title": "Keys iteration", + "tasks": [ + "Dictionary.Keys sequential iteration", + "OrderedDictionary.Keys sequential iteration", + ] + }, + { + "kind": "chart", + "title": "Values iteration", + "tasks": [ + "Dictionary.Values sequential iteration", + "OrderedDictionary.Values sequential iteration", + ] + }, + { + "kind": "chart", + "title": "Values iteration", + "tasks": [ + "Dictionary.Values sequential iteration", + "OrderedDictionary.Values sequential iteration", + ] + }, + ] + }, + { + "kind": "chart", + "title": "index(forKey:)", + "tasks": [ + "Dictionary successful index(forKey:)", + "Dictionary unsuccessful index(forKey:)", + "OrderedDictionary successful index(forKey:)", + "OrderedDictionary unsuccessful index(forKey:)", + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "subscript lookups", + "tasks": [ + "Dictionary subscript, successful lookups", + "Dictionary subscript, unsuccessful lookups", + "OrderedDictionary subscript, successful lookups", + "OrderedDictionary subscript, unsuccessful lookups", + ] + }, + { + "kind": "chart", + "title": "subscript setter, simple", + "tasks": [ + "Dictionary subscript, noop setter", + "Dictionary subscript, set existing", + "Dictionary subscript, _modify", + "OrderedDictionary subscript, noop setter", + "OrderedDictionary subscript, set existing", + "OrderedDictionary subscript, _modify", + ] + }, + { + "kind": "chart", + "title": "subscript insert/append", + "tasks": [ + "Dictionary subscript, insert", + "Dictionary subscript, insert, reserving capacity", + "OrderedDictionary subscript, append", + "OrderedDictionary subscript, append, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "subscript remove", + "tasks": [ + "Dictionary subscript, remove existing", + "Dictionary subscript, remove missing", + "OrderedDictionary subscript, remove existing", + "OrderedDictionary subscript, remove missing", + ] + }, + ] + }, + { + "kind": "variants", + "charts": [ + { + "kind": "chart", + "title": "defaulted subscript lookups", + "tasks": [ + "Dictionary defaulted subscript, successful lookups", + "Dictionary defaulted subscript, unsuccessful lookups", + "OrderedDictionary defaulted subscript, successful lookups", + "OrderedDictionary defaulted subscript, unsuccessful lookups", + ] + }, + { + "kind": "chart", + "title": "defaulted subscript mutations", + "tasks": [ + "Dictionary defaulted subscript, _modify existing", + "Dictionary defaulted subscript, _modify missing", + "OrderedDictionary defaulted subscript, _modify existing", + "OrderedDictionary defaulted subscript, _modify missing", + ] + }, + ] + }, + { + "kind": "chart", + "title": "updateValue(_:forKey:)", + "tasks": [ + "Dictionary updateValue(_:forKey:), existing", + "Dictionary updateValue(_:forKey:), insert", + "OrderedDictionary updateValue(_:forKey:), existing", + "OrderedDictionary updateValue(_:forKey:), append", + ] + }, + ] + }, + ] + }, + { + "kind": "group", + "title": "Against containers in the C++ Standard Template Library", + "directory": "stl", + "contents": [ + { + "kind": "chart", + "title": "Hashing", + "tasks": [ + "std::hash", + "custom_intptr_hash (using Swift.Hasher)", + "Hasher.combine on a single buffer of integers", + "Int.hashValue on each value", + ] + }, + { + "kind": "group", + "title": "Array vs std::vector", + "directory": "Array + vector", + "contents": [ + { + "kind": "chart", + "title": "init from buffer of integers", + "tasks": [ + "std::vector constructor from buffer", + "Array init from unsafe buffer", + ] + }, + { + "kind": "chart", + "title": "sequential iteration", + "tasks": [ + "std::vector sequential iteration", + "Array sequential iteration", + ] + }, + { + "kind": "chart", + "title": "random-access offset lookups", + "tasks": [ + "std::vector random-access offset lookups (operator [])", + "std::vector random-access offset lookups (at)", + "Array subscript get, random offsets", + ] + }, + { + "kind": "chart", + "title": "append individual integers", + "tasks": [ + "std::vector push_back", + "std::vector push_back, reserving capacity", + "Array append", + "Array append, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "prepend individual integers", + "tasks": [ + "std::vector insert at front", + "std::vector insert at front, reserving capacity", + "Array prepend", + "Array prepend, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "random insertions", + "tasks": [ + "std::vector random insertions", + "Array random insertions", + ] + }, + { + "kind": "chart", + "title": "removeFirst", + "tasks": [ + "std::vector erase first", + "Array removeFirst", + ] + }, + { + "kind": "chart", + "title": "removeLast", + "tasks": [ + "std::vector pop_back", + "Array removeLast", + ] + }, + { + "kind": "chart", + "title": "random removals", + "tasks": [ + "std::vector random removals", + "Array random removals", + ] + }, + { + "kind": "chart", + "title": "sort", + "tasks": [ + "std::vector sort", + "Array sort", + ] + }, + ] + }, + { + "kind": "group", + "title": "Deque vs std::deque", + "directory": "Deque + deque", + "contents": [ + { + "kind": "chart", + "title": "init from buffer of integers", + "tasks": [ + "std::deque constructor from buffer", + "Deque init from unsafe buffer", + ] + }, + { + "kind": "chart", + "title": "sequential iteration", + "tasks": [ + "std::deque sequential iteration", + "Deque sequential iteration (contiguous)", + "Deque sequential iteration (discontiguous)", + ] + }, + { + "kind": "chart", + "title": "random-access offset lookups", + "tasks": [ + "std::deque random-access offset lookups (operator [])", + "std::deque at, random offsets", + "Deque subscript get, random offsets (contiguous)", + "Deque subscript get, random offsets (discontiguous)", + ] + }, + { + "kind": "chart", + "title": "append individual integers", + "tasks": [ + "std::deque push_back", + "Deque append", + "Deque append, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "prepend individual integers", + "tasks": [ + "std::deque push_front", + "Deque prepend", + "Deque prepend, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "random insertions", + "tasks": [ + "std::deque random insertions", + "Deque random insertions", + ] + }, + { + "kind": "chart", + "title": "removeFirst", + "tasks": [ + "std::deque pop_front", + "Deque removeFirst (contiguous)", + "Deque removeFirst (discontiguous)", + ] + }, + { + "kind": "chart", + "title": "removeLast", + "tasks": [ + "std::deque pop_back", + "Deque removeLast (contiguous)", + "Deque removeLast (discontiguous)", + ] + }, + { + "kind": "chart", + "title": "random removals", + "tasks": [ + "std::deque random removals", + "Deque random removals (contiguous)", + "Deque random removals (discontiguous)", + ] + }, + { + "kind": "chart", + "title": "sort", + "tasks": [ + "std::deque sort", + "Deque sort (contiguous)", + "Deque sort (discontiguous)", + ] + }, + ] + }, + { + "kind": "group", + "title": "Set vs std::unordered_set", + "directory": "Set + unordered_set", + "contents": [ + { + "kind": "chart", + "title": "init from integer range", + "tasks": [ + "std::unordered_set insert from integer range", + "Set init from range", + ] + }, + { + "kind": "chart", + "title": "init from buffer of integers", + "tasks": [ + "std::unordered_set constructor from buffer", + "Set init from unsafe buffer", + ] + }, + { + "kind": "chart", + "title": "sequential iteration", + "tasks": [ + "std::unordered_set sequential iteration", + "Set sequential iteration", + ] + }, + { + "kind": "chart", + "title": "successful lookups", + "tasks": [ + "std::unordered_set successful find", + "Set successful contains", + ] + }, + { + "kind": "chart", + "title": "unsuccessful lookups", + "tasks": [ + "std::unordered_set unsuccessful find", + "Set unsuccessful contains", + ] + }, + { + "kind": "chart", + "title": "random insertions", + "tasks": [ + "std::unordered_set insert", + "std::unordered_set insert, reserving capacity", + "Set insert", + "Set insert, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "random removals", + "tasks": [ + "std::unordered_set erase", + "Set remove", + ] + }, + ] + }, + { + "kind": "group", + "title": "OrderedSet vs std::unordered_set", + "directory": "OrderedSet + unordered_set", + "contents": [ + { + "kind": "chart", + "title": "init from integer range", + "tasks": [ + "std::unordered_set insert from integer range", + "Set init from range", + "OrderedSet init from range", + ] + }, + { + "kind": "chart", + "title": "init from buffer of integers", + "tasks": [ + "std::unordered_set constructor from buffer", + "Set init from unsafe buffer", + "OrderedSet init from unsafe buffer", + ] + }, + { + "kind": "chart", + "title": "sequential iteration", + "tasks": [ + "std::unordered_set sequential iteration", + "Set sequential iteration", + "OrderedSet sequential iteration", + ] + }, + { + "kind": "chart", + "title": "successful lookups", + "tasks": [ + "std::unordered_set successful find", + "OrderedSet successful contains", + "Set successful contains", + ] + }, + { + "kind": "chart", + "title": "unsuccessful lookups", + "tasks": [ + "std::unordered_set unsuccessful find", + "OrderedSet unsuccessful contains", + "Set unsuccessful contains", + ] + }, + { + "kind": "chart", + "title": "insertions", + "tasks": [ + "std::unordered_set insert", + "Set insert", + "OrderedSet append", + ] + }, + { + "kind": "chart", + "title": "insertions, reserving capacity", + "tasks": [ + "std::unordered_set insert, reserving capacity", + "Set insert, reserving capacity", + "OrderedSet append, reserving capacity", + ] + }, + { + "kind": "chart", + "title": "random removals", + "tasks": [ + "std::unordered_set erase", + "Set remove", + "OrderedSet remove", + ] + }, + ] + }, + { + "kind": "group", + "title": "OrderedDictionary vs std::unordered_map", + "directory": "OrderedDictionary + unordered_map", + "contents": [ + { + "kind": "chart", + "title": "initializers", + "tasks": [ + "std::unordered_map insert", + "Dictionary init(uniqueKeysWithValues:)", + "OrderedDictionary init(uniqueKeysWithValues:)", + "OrderedDictionary init(uncheckedUniqueKeysWithValues:)", + "OrderedDictionary init(uncheckedUniqueKeys:values:)", + ] + }, + { + "kind": "chart", + "title": "iteration", + "tasks": [ + "std::unordered_map sequential iteration", + "Dictionary sequential iteration", + "OrderedDictionary sequential iteration", + ] + }, + { + "kind": "chart", + "title": "successful find index", + "tasks": [ + "std::unordered_map successful find", + "OrderedDictionary successful index(forKey:)", + "Dictionary successful index(forKey:)", + "Int.hashValue on each value", + ] + }, + { + "kind": "chart", + "title": "unsuccessful find index", + "tasks": [ + "std::unordered_map unsuccessful find", + "OrderedDictionary unsuccessful index(forKey:)", + "Dictionary unsuccessful index(forKey:)", + "Int.hashValue on each value", + ] + }, + { + "kind": "chart", + "title": "defaulted subscript, existing key", + "tasks": [ + "std::unordered_map subscript, existing key", + "OrderedDictionary defaulted subscript, _modify existing", + "Dictionary defaulted subscript, _modify existing", + "Int.hashValue on each value", + ] + }, + { + "kind": "chart", + "title": "defaulted subscript, new key", + "tasks": [ + "std::unordered_map subscript, new key", + "OrderedDictionary defaulted subscript, _modify missing", + "Dictionary defaulted subscript, _modify missing", + "Int.hashValue on each value", + ] + }, + { + "kind": "chart", + "title": "insert", + "tasks": [ + "std::unordered_map insert", + "OrderedDictionary subscript, append", + "Dictionary subscript, insert", + "Int.hashValue on each value", + ] + }, + { + "kind": "chart", + "title": "insert, reserving capacity", + "tasks": [ + "std::unordered_map insert, reserving capacity", + "OrderedDictionary subscript, append, reserving capacity", + "Dictionary subscript, insert, reserving capacity", + "Int.hashValue on each value", + ] + }, + { + "kind": "chart", + "title": "removing existing elements", + "tasks": [ + "std::unordered_map erase existing", + "OrderedDictionary subscript, remove existing", + "Dictionary subscript, remove existing", + ] + }, + { + "kind": "chart", + "title": "removing missing elements", + "tasks": [ + "std::unordered_map erase missing", + "OrderedDictionary subscript, remove missing", + "Dictionary subscript, remove missing", + ] + }, + ] + }, + ] + }, + ] +} diff --git a/Benchmarks/Benchmarks/Library.swift b/Benchmarks/Benchmarks/Library.swift new file mode 100644 index 00000000..44b6818e --- /dev/null +++ b/Benchmarks/Benchmarks/Library.swift @@ -0,0 +1,20 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import Foundation +import CollectionsBenchmark + +extension Benchmark { + public func loadReferenceLibrary() throws -> ChartLibrary { + let url = Bundle.module.url(forResource: "Library", withExtension: "json")! + return try ChartLibrary.load(from: url) + } +} diff --git a/Benchmarks/Benchmarks/OrderedDictionaryBenchmarks.swift b/Benchmarks/Benchmarks/OrderedDictionaryBenchmarks.swift new file mode 100644 index 00000000..f68c2aa8 --- /dev/null +++ b/Benchmarks/Benchmarks/OrderedDictionaryBenchmarks.swift @@ -0,0 +1,486 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark +import OrderedCollections + +extension Benchmark { + public mutating func addOrderedDictionaryBenchmarks() { + self.add( + title: "OrderedDictionary init(uniqueKeysWithValues:)", + input: [Int].self + ) { input in + let keysAndValues = input.map { ($0, 2 * $0) } + return { timer in + blackHole(OrderedDictionary(uniqueKeysWithValues: keysAndValues)) + } + } + + self.add( + title: "OrderedDictionary init(uncheckedUniqueKeysWithValues:)", + input: [Int].self + ) { input in + let keysAndValues = input.map { ($0, 2 * $0) } + return { timer in + blackHole( + OrderedDictionary(uncheckedUniqueKeysWithValues: keysAndValues)) + } + } + + self.add( + title: "OrderedDictionary init(uncheckedUniqueKeys:values:)", + input: [Int].self + ) { input in + let values = input.map { 2 * $0 } + return { timer in + blackHole( + OrderedDictionary(uncheckedUniqueKeys: input, values: values)) + } + } + + self.add( + title: "OrderedDictionary sequential iteration", + input: [Int].self + ) { input in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, values: input.map { 2 * $0 }) + return { timer in + for item in d { + blackHole(item) + } + } + } + + self.add( + title: "OrderedDictionary.Keys sequential iteration", + input: [Int].self + ) { input in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, values: input.map { 2 * $0 }) + return { timer in + for item in d.keys { + blackHole(item) + } + } + } + + self.add( + title: "OrderedDictionary.Values sequential iteration", + input: [Int].self + ) { input in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, values: input.map { 2 * $0 }) + return { timer in + for item in d.values { + blackHole(item) + } + } + } + + self.add( + title: "OrderedDictionary subscript, successful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, values: input.map { 2 * $0 }) + return { timer in + for i in lookups { + precondition(d[i] == 2 * i) + } + } + } + + self.add( + title: "OrderedDictionary subscript, unsuccessful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, values: input.map { 2 * $0 }) + let c = input.count + return { timer in + for i in lookups { + precondition(d[i + c] == nil) + } + } + } + + self.add( + title: "OrderedDictionary subscript, noop setter", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + let c = input.count + timer.measure { + for i in lookups { + d[i + c] = nil + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary subscript, set existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i] = 0 + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary subscript, _modify", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i]! *= 2 + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.addSimple( + title: "OrderedDictionary subscript, append", + input: [Int].self + ) { input in + var d: OrderedDictionary = [:] + for i in input { + d[i] = 2 * i + } + precondition(d.count == input.count) + blackHole(d) + } + + self.addSimple( + title: "OrderedDictionary subscript, append, reserving capacity", + input: [Int].self + ) { input in + var d: OrderedDictionary = [:] + d.reserveCapacity(input.count) + for i in input { + d[i] = 2 * i + } + precondition(d.count == input.count) + blackHole(d) + } + + self.add( + title: "OrderedDictionary subscript, remove existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i] = nil + } + } + precondition(d.isEmpty) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary subscript, remove missing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + let c = input.count + timer.measure { + for i in lookups { + d[i + c] = nil + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary defaulted subscript, successful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + return { timer in + for i in lookups { + precondition(d[i, default: -1] != -1) + } + } + } + + self.add( + title: "OrderedDictionary defaulted subscript, unsuccessful lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + return { timer in + let c = d.count + for i in lookups { + precondition(d[i + c, default: -1] == -1) + } + } + } + + self.add( + title: "OrderedDictionary defaulted subscript, _modify existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d[i, default: -1] *= 2 + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary defaulted subscript, _modify missing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + let c = input.count + timer.measure { + for i in lookups { + d[c + i, default: -1] *= 2 + } + } + precondition(d.count == 2 * input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary successful index(forKey:)", + input: ([Int], [Int]).self + ) { input, lookups in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, + values: input.map { 2 * $0 }) + return { timer in + for i in lookups { + precondition(d.index(forKey: i) != nil) + } + } + } + + self.add( + title: "OrderedDictionary unsuccessful index(forKey:)", + input: ([Int], [Int]).self + ) { input, lookups in + let d = OrderedDictionary( + uncheckedUniqueKeys: input, + values: input.map { 2 * $0 }) + return { timer in + for i in lookups { + precondition(d.index(forKey: lookups.count + i) == nil) + } + } + } + + self.add( + title: "OrderedDictionary updateValue(_:forKey:), existing", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d.updateValue(0, forKey: i) + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary updateValue(_:forKey:), append", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + d.updateValue(0, forKey: input.count + i) + } + } + precondition(d.count == 2 * input.count) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary random swaps", + input: [Int].self + ) { input in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + var v = 0 + for i in input { + d.swapAt(i, v) + v += 1 + } + } + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary partitioning around middle", + input: [Int].self + ) { input in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + let pivot = input.count / 2 + timer.measure { + let r = d.partition(by: { $0.key >= pivot }) + precondition(r == pivot) + } + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary sort", + input: [Int].self + ) { input in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + d.sort() + } + precondition(d.keys.elementsEqual(0 ..< input.count)) + precondition(d.values.elementsEqual((0 ..< input.count).lazy.map { 2 * $0 })) + } + } + + self.add( + title: "OrderedDictionary removeLast", + input: Int.self + ) { size in + return { timer in + var d = OrderedDictionary(uncheckedUniqueKeys: 0 ..< size, + values: size ..< 2 * size) + timer.measure { + for _ in 0 ..< size { + d.removeLast() + } + } + precondition(d.isEmpty) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary removeFirst", + input: Int.self + ) { size in + return { timer in + var d = OrderedDictionary(uncheckedUniqueKeys: 0 ..< size, + values: size ..< 2 * size) + timer.measure { + for _ in 0 ..< size { + d.removeFirst() + } + } + precondition(d.isEmpty) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary random removals (offset-based)", + input: Insertions.self + ) { insertions in + return { timer in + let insertions = insertions.values + var d = OrderedDictionary(uncheckedUniqueKeys: 0 ..< insertions.count, + values: insertions.count ..< 2 * insertions.count) + timer.measure { + for i in stride(from: insertions.count, to: 0, by: -1) { + d.remove(at: insertions[i - 1]) + } + } + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary random removals (existing keys)", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { ($0, 2 * $0) }) + timer.measure { + for i in lookups { + precondition(d.removeValue(forKey: i) != nil) + } + } + precondition(d.count == 0) + blackHole(d) + } + } + + self.add( + title: "OrderedDictionary random removals (missing keys)", + input: ([Int], [Int]).self + ) { input, lookups in + return { timer in + let c = input.count + var d = OrderedDictionary( + uncheckedUniqueKeysWithValues: input.map { (c + $0, 2 * $0) }) + timer.measure { + for i in lookups { + precondition(d.removeValue(forKey: i) == nil) + } + } + precondition(d.count == input.count) + blackHole(d) + } + } + } +} diff --git a/Benchmarks/Benchmarks/OrderedSetBenchmarks.swift b/Benchmarks/Benchmarks/OrderedSetBenchmarks.swift new file mode 100644 index 00000000..e062ca85 --- /dev/null +++ b/Benchmarks/Benchmarks/OrderedSetBenchmarks.swift @@ -0,0 +1,514 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark +import OrderedCollections + +extension Benchmark { + public mutating func addOrderedSetBenchmarks() { + self.addSimple( + title: "OrderedSet init from range", + input: Int.self + ) { size in + blackHole(OrderedSet(0 ..< size)) + } + + self.addSimple( + title: "OrderedSet init from unsafe buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + blackHole(OrderedSet(buffer)) + } + } + + self.addSimple( + title: "OrderedSet init(uncheckedUniqueElements:) from range", + input: Int.self + ) { size in + blackHole(OrderedSet(0 ..< size)) + } + + self.add( + title: "OrderedSet random-access offset lookups", + input: ([Int], [Int]).self + ) { input, lookups in + let set = OrderedSet(input) + return { timer in + for i in lookups { + blackHole(set[i]) + } + } + } + + self.add( + title: "OrderedSet sequential iteration", + input: [Int].self + ) { input in + let set = OrderedSet(input) + return { timer in + for i in set { + blackHole(i) + } + } + } + + self.add( + title: "OrderedSet successful contains", + input: ([Int], [Int]).self + ) { input, lookups in + let set = OrderedSet(input) + return { timer in + for i in lookups { + precondition(set.contains(i)) + } + } + } + + self.add( + title: "OrderedSet unsuccessful contains", + input: ([Int], [Int]).self + ) { input, lookups in + let set = OrderedSet(input) + let lookups = lookups.map { $0 + input.count } + return { timer in + for i in lookups { + precondition(!set.contains(i)) + } + } + } + + self.add( + title: "OrderedSet random swaps", + input: [Int].self + ) { input in + return { timer in + var set = OrderedSet(0 ..< input.count) + timer.measure { + for i in input.indices { + set.swapAt(i, input[i]) + } + } + blackHole(set) + } + } + + self.add( + title: "OrderedSet partitioning around middle", + input: [Int].self + ) { input in + return { timer in + let pivot = input.count / 2 + var set = OrderedSet(input) + timer.measure { + let r = set.partition(by: { $0 >= pivot }) + precondition(r == pivot) + } + blackHole(set) + } + } + + self.add( + title: "OrderedSet sort", + input: [Int].self + ) { input in + return { timer in + var set = OrderedSet(input) + timer.measure { + set.sort() + } + precondition(set.elementsEqual(0 ..< input.count)) + } + } + + self.addSimple( + title: "OrderedSet append", + input: [Int].self + ) { input in + var set: OrderedSet = [] + for i in input { + set.append(i) + } + precondition(set.count == input.count) + blackHole(set) + } + + self.addSimple( + title: "OrderedSet append, reserving capacity", + input: [Int].self + ) { input in + var set: OrderedSet = [] + set.reserveCapacity(input.count) + for i in input { + set.append(i) + } + precondition(set.count == input.count) + blackHole(set) + } + + self.addSimple( + title: "OrderedSet prepend", + input: [Int].self + ) { input in + var set: OrderedSet = [] + for i in input { + _ = set.insert(i, at: 0) + } + blackHole(set) + } + + self.addSimple( + title: "OrderedSet prepend, reserving capacity", + input: [Int].self + ) { input in + var set: OrderedSet = [] + set.reserveCapacity(input.count) + for i in input { + _ = set.insert(i, at: 0) + } + blackHole(set) + } + + self.add( + title: "OrderedSet random insertions, reserving capacity", + input: Insertions.self + ) { insertions in + return { timer in + let insertions = insertions.values + var set: OrderedSet = [] + set.reserveCapacity(insertions.count) + timer.measure { + for i in insertions.indices { + _ = set.insert(i, at: insertions[i]) + } + } + blackHole(set) + } + } + + self.add( + title: "OrderedSet remove", + input: ([Int], [Int]).self + ) { input, removals in + return { timer in + var set = OrderedSet(input) + timer.measure { + for i in removals { + set.remove(i) + } + } + precondition(set.isEmpty) + blackHole(set) + } + } + + self.add( + title: "OrderedSet removeLast", + input: Int.self + ) { size in + return { timer in + var set = OrderedSet(0 ..< size) + timer.measure { + for _ in 0 ..< size { + set.removeLast() + } + } + precondition(set.isEmpty) + blackHole(set) + } + } + + self.add( + title: "OrderedSet removeFirst", + input: Int.self + ) { size in + return { timer in + var set = OrderedSet(0 ..< size) + timer.measure { + for _ in 0 ..< size { + set.removeFirst() + } + } + precondition(set.isEmpty) + blackHole(set) + } + } + + let overlaps: [(String, (Int) -> Int)] = [ + ("0%", { c in c }), + ("25%", { c in 3 * c / 4 }), + ("50%", { c in c / 2 }), + ("75%", { c in c / 4 }), + ("100%", { c in 0 }), + ] + + // SetAlgebra operations with Self + do { + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet union with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = OrderedSet(start ..< start + input.count) + return { timer in + blackHole(a.union(b)) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet intersection with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = OrderedSet(start ..< start + input.count) + return { timer in + blackHole(a.intersection(b)) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet symmetricDifference with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = OrderedSet(start ..< start + input.count) + return { timer in + blackHole(a.symmetricDifference(b)) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet subtracting Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = OrderedSet(start ..< start + input.count) + return { timer in + blackHole(a.subtracting(b)) + } + } + } + } + + // SetAlgebra operations with Array + do { + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet union with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.union(b)) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet intersection with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.intersection(b)) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet symmetricDifference with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.symmetricDifference(b)) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet subtracting Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = OrderedSet(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.subtracting(b)) + } + } + } + } + + // SetAlgebra mutations with Self + do { + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet formUnion with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = OrderedSet(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.formUnion(b) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet formIntersection with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = OrderedSet(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.formIntersection(b) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet formSymmetricDifference with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = OrderedSet(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.formSymmetricDifference(b) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet subtract Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = OrderedSet(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.subtract(b) + } + blackHole(a) + } + } + } + } + + // SetAlgebra mutations with Array + do { + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet formUnion with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.formUnion(b) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet formIntersection with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.formIntersection(b) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet formSymmetricDifference with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.formSymmetricDifference(b) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "OrderedSet subtract Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = OrderedSet(input) + timer.measure { + a.subtract(b) + } + blackHole(a) + } + } + } + } + + } +} diff --git a/Benchmarks/Benchmarks/SetBenchmarks.swift b/Benchmarks/Benchmarks/SetBenchmarks.swift new file mode 100644 index 00000000..3a853b6a --- /dev/null +++ b/Benchmarks/Benchmarks/SetBenchmarks.swift @@ -0,0 +1,397 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark + +extension Benchmark { + public mutating func addSetBenchmarks() { + self.addSimple( + title: "Int.hashValue on each value", + input: Int.self + ) { size in + for i in 0 ..< size { + blackHole(i.hashValue) + } + } + + self.addSimple( + title: "Hasher.combine on a single buffer of integers", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + var hasher = Hasher() + hasher.combine(bytes: UnsafeRawBufferPointer(buffer)) + blackHole(hasher.finalize()) + } + } + + self.addSimple( + title: "Set init from range", + input: Int.self + ) { size in + blackHole(Set(0 ..< size)) + } + + self.addSimple( + title: "Set init from unsafe buffer", + input: [Int].self + ) { input in + input.withUnsafeBufferPointer { buffer in + blackHole(Set(buffer)) + } + } + + self.add( + title: "Set sequential iteration", + input: Int.self + ) { size in + let set = Set(0 ..< size) + return { timer in + for i in set { + blackHole(i) + } + } + } + + self.add( + title: "Set successful contains", + input: ([Int], [Int]).self + ) { input, lookups in + let set = Set(input) + return { timer in + for i in lookups { + precondition(set.contains(i)) + } + } + } + + self.add( + title: "Set unsuccessful contains", + input: ([Int], [Int]).self + ) { input, lookups in + let set = Set(input) + let lookups = lookups.map { $0 + input.count } + return { timer in + for i in lookups { + precondition(!set.contains(i)) + } + } + } + + self.addSimple( + title: "Set insert", + input: [Int].self + ) { input in + var set: Set = [] + for i in input { + set.insert(i) + } + precondition(set.count == input.count) + blackHole(set) + } + + self.addSimple( + title: "Set insert, reserving capacity", + input: [Int].self + ) { input in + var set: Set = [] + set.reserveCapacity(input.count) + for i in input { + set.insert(i) + } + precondition(set.count == input.count) + blackHole(set) + } + + self.add( + title: "Set remove", + input: ([Int], [Int]).self + ) { input, removals in + return { timer in + var set = Set(input) + for i in removals { + set.remove(i) + } + precondition(set.isEmpty) + blackHole(set) + } + } + + let overlaps: [(String, (Int) -> Int)] = [ + ("0%", { c in c }), + ("25%", { c in 3 * c / 4 }), + ("50%", { c in c / 2 }), + ("75%", { c in c / 4 }), + ("100%", { c in 0 }), + ] + + // SetAlgebra operations with Self + do { + for (percentage, start) in overlaps { + self.add( + title: "Set union with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Set(start ..< start + input.count) + return { timer in + blackHole(a.union(identity(b))) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set intersection with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Set(start ..< start + input.count) + return { timer in + blackHole(a.intersection(identity(b))) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set symmetricDifference with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Set(start ..< start + input.count) + return { timer in + blackHole(a.symmetricDifference(identity(b))) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set subtracting Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Set(start ..< start + input.count) + return { timer in + blackHole(a.subtracting(identity(b))) + } + } + } + } + + // SetAlgebra operations with Array + do { + for (percentage, start) in overlaps { + self.add( + title: "Set union with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.union(identity(b))) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set intersection with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.intersection(identity(b))) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set symmetricDifference with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.symmetricDifference(identity(b))) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set subtracting Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let a = Set(input) + let b = Array(start ..< start + input.count) + return { timer in + blackHole(a.subtracting(identity(b))) + } + } + } + } + + // SetAlgebra mutations with Self + do { + for (percentage, start) in overlaps { + self.add( + title: "Set formUnion with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Set(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.formUnion(identity(b)) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set formIntersection with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Set(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.formIntersection(identity(b)) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set formSymmetricDifference with Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Set(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.formSymmetricDifference(identity(b)) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set subtract Self (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Set(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.subtract(identity(b)) + } + blackHole(a) + } + } + } + } + + // SetAlgebra mutations with Array + do { + for (percentage, start) in overlaps { + self.add( + title: "Set formUnion with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.formUnion(identity(b)) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set formIntersection with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.formIntersection(identity(b)) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set formSymmetricDifference with Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.formSymmetricDifference(identity(b)) + } + blackHole(a) + } + } + } + + for (percentage, start) in overlaps { + self.add( + title: "Set subtract Array (\(percentage) overlap)", + input: [Int].self + ) { input in + let start = start(input.count) + let b = Array(start ..< start + input.count) + return { timer in + var a = Set(input) + timer.measure { + a.subtract(identity(b)) + } + blackHole(a) + } + } + } + } + + } +} diff --git a/Benchmarks/CppBenchmarks/include/DequeBenchmarks.h b/Benchmarks/CppBenchmarks/include/DequeBenchmarks.h new file mode 100644 index 00000000..1aaae6c5 --- /dev/null +++ b/Benchmarks/CppBenchmarks/include/DequeBenchmarks.h @@ -0,0 +1,50 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef CPPBENCHMARKS_DEQUE_BENCHMARKS_H +#define CPPBENCHMARKS_DEQUE_BENCHMARKS_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/// Create a std::deque, populating it with data from the supplied buffer. +/// Returns an opaque pointer to the created instance. +extern void *cpp_deque_create(const intptr_t *start, size_t count); + +/// Destroys a deque previously returned by `cpp_deque_create`. +extern void cpp_deque_destroy(void *ptr); + +extern void cpp_deque_from_int_range(intptr_t count); +extern void cpp_deque_from_int_buffer(const intptr_t *start, size_t count); + +extern void cpp_deque_append_integers(const intptr_t *start, size_t count); +extern void cpp_deque_prepend_integers(const intptr_t *start, size_t count); +extern void cpp_deque_random_insertions(const intptr_t *start, size_t count); + +extern void cpp_deque_iterate(void *ptr); +extern void cpp_deque_lookups_subscript(void *ptr, const intptr_t *start, size_t count); +extern void cpp_deque_lookups_at(void *ptr, const intptr_t *start, size_t count); +extern void cpp_deque_pop_back(void *ptr); +extern void cpp_deque_pop_front(void *ptr); +extern void cpp_deque_random_removals(void *ptr, const intptr_t *start, size_t count); +extern void cpp_deque_sort(void *ptr); + +#ifdef __cplusplus +} +#endif + + +#endif /* CPPBENCHMARKS_DEQUE_BENCHMARKS_H */ diff --git a/Benchmarks/CppBenchmarks/include/Hashing.h b/Benchmarks/CppBenchmarks/include/Hashing.h new file mode 100644 index 00000000..5d85e7b7 --- /dev/null +++ b/Benchmarks/CppBenchmarks/include/Hashing.h @@ -0,0 +1,33 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef CPPBENCHMARKS_HASHING_H +#define CPPBENCHMARKS_HASHING_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +typedef size_t (*cpp_hash_fn)(intptr_t); +extern void cpp_set_hash_fn(cpp_hash_fn fn); + +// Benchmarks +void cpp_hash(const intptr_t *start, size_t count); +void cpp_custom_hash(const intptr_t *start, size_t count); + +#ifdef __cplusplus +} +#endif + +#endif /* CPPBENCHMARKS_HASHING_H */ diff --git a/Benchmarks/CppBenchmarks/include/UnorderedMapBenchmarks.h b/Benchmarks/CppBenchmarks/include/UnorderedMapBenchmarks.h new file mode 100644 index 00000000..e368f79f --- /dev/null +++ b/Benchmarks/CppBenchmarks/include/UnorderedMapBenchmarks.h @@ -0,0 +1,44 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef CPPBENCHMARKS_UNORDERED_MAP_BENCHMARKS_H +#define CPPBENCHMARKS_UNORDERED_MAP_BENCHMARKS_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/// Create a std::unordered_map, populating it with data from the supplied buffer. +/// Returns an opaque pointer to the created instance. +extern void *cpp_unordered_map_create(const intptr_t *start, size_t count); + +/// Destroys an unordered map previously returned by `cpp_unordered_map_create`. +extern void cpp_unordered_map_destroy(void *ptr); + +extern void cpp_unordered_map_iterate(void *ptr); + +extern void cpp_unordered_map_from_int_range(intptr_t count); +extern void cpp_unordered_map_insert_integers(const intptr_t *start, size_t count, bool reserve); + +extern void cpp_unordered_map_lookups(void *ptr, const intptr_t *start, size_t count, bool expectMatch); +extern void cpp_unordered_map_subscript(void *ptr, const intptr_t *start, size_t count); +extern void cpp_unordered_map_removals(void *ptr, const intptr_t *start, size_t count); + +#ifdef __cplusplus +} +#endif + + +#endif /* CPPBENCHMARKS_UNORDERED_MAP_BENCHMARKS_H */ diff --git a/Benchmarks/CppBenchmarks/include/UnorderedSetBenchmarks.h b/Benchmarks/CppBenchmarks/include/UnorderedSetBenchmarks.h new file mode 100644 index 00000000..fb627d44 --- /dev/null +++ b/Benchmarks/CppBenchmarks/include/UnorderedSetBenchmarks.h @@ -0,0 +1,46 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef CPPBENCHMARKS_UNORDERED_SET_BENCHMARKS_H +#define CPPBENCHMARKS_UNORDERED_SET_BENCHMARKS_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +void cpp_hash(const intptr_t *start, size_t count); + +/// Create a std::unordered_set, populating it with data from the supplied buffer. +/// Returns an opaque pointer to the created instance. +extern void *cpp_unordered_set_create(const intptr_t *start, size_t count); + +/// Destroys an unordered set previously returned by `cpp_unordered_set_create`. +extern void cpp_unordered_set_destroy(void *ptr); + +extern void cpp_unordered_set_iterate(void *ptr); +extern void cpp_unordered_set_from_int_range(intptr_t count); +extern void cpp_unordered_set_from_int_buffer(const intptr_t *start, size_t count); + +extern void cpp_unordered_set_insert_integers(const intptr_t *start, size_t count, bool reserve); + +extern void cpp_unordered_set_lookups(void *ptr, const intptr_t *start, size_t count, bool expectMatch); +extern void cpp_unordered_set_removals(void *ptr, const intptr_t *start, size_t count); + +#ifdef __cplusplus +} +#endif + + +#endif /* CPPBENCHMARKS_UNORDERED_SET_BENCHMARKS_H */ diff --git a/Benchmarks/CppBenchmarks/include/VectorBenchmarks.h b/Benchmarks/CppBenchmarks/include/VectorBenchmarks.h new file mode 100644 index 00000000..6a4a99b1 --- /dev/null +++ b/Benchmarks/CppBenchmarks/include/VectorBenchmarks.h @@ -0,0 +1,50 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef CPPBENCHMARKS_VECTOR_BENCHMARKS_H +#define CPPBENCHMARKS_VECTOR_BENCHMARKS_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/// Create a std::vector, populating it with data from the supplied buffer. +/// Returns an opaque pointer to the created instance. +extern void *cpp_vector_create(const intptr_t *start, size_t count); + +/// Destroys a vector previously returned by `cpp_vector_create`. +extern void cpp_vector_destroy(void *ptr); + +extern void cpp_vector_from_int_range(intptr_t count); +extern void cpp_vector_from_int_buffer(const intptr_t *start, size_t count); + +extern void cpp_vector_append_integers(const intptr_t *start, size_t count, bool reserve); +extern void cpp_vector_prepend_integers(const intptr_t *start, size_t count, bool reserve); +extern void cpp_vector_random_insertions(const intptr_t *start, size_t count, bool reserve); + +extern void cpp_vector_iterate(void *ptr); +extern void cpp_vector_lookups_subscript(void *ptr, const intptr_t *start, size_t count); +extern void cpp_vector_lookups_at(void *ptr, const intptr_t *start, size_t count); +extern void cpp_vector_pop_back(void *ptr); +extern void cpp_vector_pop_front(void *ptr); +extern void cpp_vector_random_removals(void *ptr, const intptr_t *start, size_t count); +extern void cpp_vector_sort(void *ptr); + +#ifdef __cplusplus +} +#endif + + +#endif /* CPPBENCHMARKS_VECTOR_BENCHMARKS_H */ diff --git a/Benchmarks/CppBenchmarks/include/module.modulemap b/Benchmarks/CppBenchmarks/include/module.modulemap new file mode 100644 index 00000000..13fe2d39 --- /dev/null +++ b/Benchmarks/CppBenchmarks/include/module.modulemap @@ -0,0 +1,9 @@ +module CppBenchmarks { + header "Hashing.h" + header "VectorBenchmarks.h" + header "DequeBenchmarks.h" + header "UnorderedSetBenchmarks.h" + header "UnorderedMapBenchmarks.h" + export * +} + diff --git a/Benchmarks/CppBenchmarks/src/CustomHash.h b/Benchmarks/CppBenchmarks/src/CustomHash.h new file mode 100644 index 00000000..c8ba3597 --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/CustomHash.h @@ -0,0 +1,31 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef CUSTOMHASH_H +#define CUSTOMHASH_H + +#include +#include + +#include "Hashing.h" + +extern cpp_hash_fn custom_hash_fn; + +struct custom_intptr_hash: public std::unary_function +{ + std::size_t + operator()(intptr_t value) const + { + return static_cast(custom_hash_fn(value)); + } +}; + +#endif /* CUSTOMHASH_H */ diff --git a/Benchmarks/CppBenchmarks/src/DequeBenchmarks.cpp b/Benchmarks/CppBenchmarks/src/DequeBenchmarks.cpp new file mode 100644 index 00000000..dc76acca --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/DequeBenchmarks.cpp @@ -0,0 +1,140 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#include "DequeBenchmarks.h" +#include +#include +#include "utils.h" + +void * +cpp_deque_create(const intptr_t *start, size_t count) +{ + auto deque = new std::deque(start, start + count); + return deque; +} + +void +cpp_deque_destroy(void *ptr) +{ + delete static_cast *>(ptr); +} + +void +cpp_deque_from_int_range(intptr_t count) +{ + auto deque = std::deque(); + for (intptr_t i = 0; i < count; i++) { + deque.push_back(identity(i)); + } + black_hole(&deque); +} + +void +cpp_deque_from_int_buffer(const intptr_t *start, size_t count) +{ + auto deque = std::deque(start, start + count); + black_hole(&deque); +} + +void +cpp_deque_append_integers(const intptr_t *start, size_t count) +{ + auto deque = std::deque(); + auto end = start + count; + for (auto p = start; p != end; ++p) { + deque.push_back(*identity(p)); + } + black_hole(&deque); +} + +void +cpp_deque_prepend_integers(const intptr_t *start, size_t count) +{ + auto deque = std::deque(); + auto end = start + count; + for (auto p = start; p != end; ++p) { + deque.push_front(*identity(p)); + } + black_hole(&deque); +} + +void +cpp_deque_random_insertions(const intptr_t *start, size_t count) +{ + auto deque = std::deque(); + for (intptr_t i = 0; i < count; i++) { + deque.insert(deque.cbegin() + start[i], identity(i)); + } + black_hole(&deque); +} + +void +cpp_deque_iterate(void *ptr) +{ + auto deque = static_cast *>(ptr); + for (auto it = deque->cbegin(); it != deque->cend(); ++it) { + black_hole(*it); + } +} + +void +cpp_deque_lookups_subscript(void *ptr, const intptr_t *start, size_t count) +{ + auto deque = static_cast *>(ptr); + for (auto it = start; it < start + count; ++it) { + black_hole((*deque)[*it]); + } +} + +void +cpp_deque_lookups_at(void *ptr, const intptr_t *start, size_t count) +{ + auto deque = static_cast *>(ptr); + for (auto it = start; it < start + count; ++it) { + black_hole((*deque).at(*it)); + } +} + +void +cpp_deque_pop_back(void *ptr) +{ + auto deque = static_cast *>(ptr); + auto size = deque->size(); + for (int i = 0; i < size; ++i) { + identity(deque)->pop_back(); + } +} + +void +cpp_deque_pop_front(void *ptr) +{ + auto deque = static_cast *>(ptr); + auto size = deque->size(); + for (int i = 0; i < size; ++i) { + identity(deque)->pop_front(); + } +} + +void +cpp_deque_random_removals(void *ptr, const intptr_t *start, size_t count) +{ + auto deque = static_cast *>(ptr); + for (auto it = start; it < start + count; ++it) { + identity(deque)->erase(deque->cbegin() + *it); + } +} + +void +cpp_deque_sort(void *ptr) +{ + auto deque = static_cast *>(ptr); + std::sort(deque->begin(), deque->end()); +} diff --git a/Benchmarks/CppBenchmarks/src/Hashing.cpp b/Benchmarks/CppBenchmarks/src/Hashing.cpp new file mode 100644 index 00000000..cdbac9d6 --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/Hashing.cpp @@ -0,0 +1,39 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#import "Hashing.h" +#import "CustomHash.h" +#import "utils.h" + +cpp_hash_fn custom_hash_fn; + +void +cpp_set_hash_fn(cpp_hash_fn fn) +{ + custom_hash_fn = fn; +} + +void +cpp_hash(const intptr_t *start, size_t count) +{ + for (auto p = start; p < start + count; ++p) { + black_hole(std::hash{}(*p)); + } +} + +void +cpp_custom_hash(const intptr_t *start, size_t count) +{ + for (auto p = start; p < start + count; ++p) { + black_hole(custom_intptr_hash{}(*p)); + } +} + diff --git a/Benchmarks/CppBenchmarks/src/UnorderedMapBenchmarks.cpp b/Benchmarks/CppBenchmarks/src/UnorderedMapBenchmarks.cpp new file mode 100644 index 00000000..17f4f95a --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/UnorderedMapBenchmarks.cpp @@ -0,0 +1,96 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#include "UnorderedMapBenchmarks.h" +#include +#include +#include +#include "CustomHash.h" +#include "utils.h" + +typedef std::unordered_map custom_map; + +void * +cpp_unordered_map_create(const intptr_t *start, size_t count) +{ + auto map = new custom_map(); + for (size_t i = 0; i < count; ++i) { + map->insert({start[i], 2 * start[i]}); + } + return map; +} + +void +cpp_unordered_map_destroy(void *ptr) +{ + delete static_cast(ptr); +} + +void +cpp_unordered_map_from_int_range(intptr_t count) +{ + auto map = custom_map(); + for (intptr_t i = 0; i < count; i++) { + map.insert({identity(i), 2 * i}); + } + black_hole(&map); +} + +void +cpp_unordered_map_insert_integers(const intptr_t *start, size_t count, bool reserve) +{ + auto map = custom_map(); + if (reserve) map.reserve(count); + auto end = start + count; + for (auto p = start; p != end; ++p) { + auto v = *identity(p); + map.insert({ v, 2 * v }); + } + black_hole(&map); +} + +void +cpp_unordered_map_iterate(void *ptr) +{ + auto map = static_cast(ptr); + for (auto it = map->cbegin(); it != map->cend(); ++it) { + black_hole(it->first); + black_hole(it->second); + } +} + +void +cpp_unordered_map_lookups(void *ptr, const intptr_t *start, size_t count, bool expectMatch) +{ + auto map = static_cast(ptr); + for (auto it = start; it < start + count; ++it) { + auto found = map->find(*it) != map->end(); + if (found != expectMatch) { abort(); } + } +} + +void +cpp_unordered_map_subscript(void *ptr, const intptr_t *start, size_t count) +{ + auto map = static_cast(ptr); + for (auto it = start; it < start + count; ++it) { + black_hole((*map)[*it]); + } +} + +void +cpp_unordered_map_removals(void *ptr, const intptr_t *start, size_t count) +{ + auto map = static_cast(ptr); + for (auto it = start; it < start + count; ++it) { + identity(map)->erase(*it); + } +} diff --git a/Benchmarks/CppBenchmarks/src/UnorderedSetBenchmarks.cpp b/Benchmarks/CppBenchmarks/src/UnorderedSetBenchmarks.cpp new file mode 100644 index 00000000..625523c1 --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/UnorderedSetBenchmarks.cpp @@ -0,0 +1,90 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#include "UnorderedSetBenchmarks.h" +#include +#include +#include +#include +#include "CustomHash.h" +#include "utils.h" + +typedef std::unordered_set custom_set; + +void * +cpp_unordered_set_create(const intptr_t *start, size_t count) +{ + auto set = new custom_set(start, start + count); + return set; +} + +void +cpp_unordered_set_destroy(void *ptr) +{ + delete static_cast(ptr); +} + +void +cpp_unordered_set_from_int_range(intptr_t count) +{ + auto set = custom_set(); + for (intptr_t i = 0; i < count; i++) { + set.insert(identity(i)); + } + black_hole(&set); +} + +void +cpp_unordered_set_from_int_buffer(const intptr_t *start, size_t count) +{ + auto set = custom_set(start, start + count); + black_hole(&set); +} + +void +cpp_unordered_set_insert_integers(const intptr_t *start, size_t count, bool reserve) +{ + auto set = custom_set(); + if (reserve) set.reserve(count); + auto end = start + count; + for (auto p = start; p != end; ++p) { + set.insert(*identity(p)); + } + black_hole(&set); +} + +void +cpp_unordered_set_iterate(void *ptr) +{ + auto set = static_cast(ptr); + for (auto it = set->cbegin(); it != set->cend(); ++it) { + black_hole(*it); + } +} + +void +cpp_unordered_set_lookups(void *ptr, const intptr_t *start, size_t count, bool expectMatch) +{ + auto set = static_cast(ptr); + for (auto it = start; it < start + count; ++it) { + auto found = set->find(*it) != set->end(); + if (found != expectMatch) { abort(); } + } +} + +void +cpp_unordered_set_removals(void *ptr, const intptr_t *start, size_t count) +{ + auto set = static_cast(ptr); + for (auto it = start; it < start + count; ++it) { + identity(set)->erase(*it); + } +} diff --git a/Benchmarks/CppBenchmarks/src/VectorBenchmarks.cpp b/Benchmarks/CppBenchmarks/src/VectorBenchmarks.cpp new file mode 100644 index 00000000..cd93965b --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/VectorBenchmarks.cpp @@ -0,0 +1,143 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#include "VectorBenchmarks.h" +#include +#include +#include "utils.h" + +void * +cpp_vector_create(const intptr_t *start, size_t count) +{ + auto vector = new std::vector(start, start + count); + return vector; +} + +void +cpp_vector_destroy(void *ptr) +{ + delete static_cast *>(ptr); +} + +void +cpp_vector_from_int_range(intptr_t count) +{ + auto vector = std::vector(); + for (intptr_t i = 0; i < count; i++) { + vector.push_back(identity(i)); + } + black_hole(&vector); +} + +void +cpp_vector_from_int_buffer(const intptr_t *start, size_t count) +{ + auto vector = std::vector(start, start + count); + black_hole(&vector); +} + +void +cpp_vector_append_integers(const intptr_t *start, size_t count, bool reserve) +{ + auto vector = std::vector(); + if (reserve) vector.reserve(count); + auto end = start + count; + for (auto p = start; p != end; ++p) { + vector.push_back(*identity(p)); + } + black_hole(&vector); +} + +void +cpp_vector_prepend_integers(const intptr_t *start, size_t count, bool reserve) +{ + auto vector = std::vector(); + if (reserve) vector.reserve(count); + auto end = start + count; + for (auto p = start; p != end; ++p) { + vector.insert(vector.cbegin(), *identity(p)); + } + black_hole(&vector); +} + +void +cpp_vector_random_insertions(const intptr_t *start, size_t count, bool reserve) +{ + auto vector = std::vector(); + if (reserve) vector.reserve(count); + for (intptr_t i = 0; i < count; i++) { + vector.insert(vector.cbegin() + start[i], identity(i)); + } + black_hole(&vector); +} + +void +cpp_vector_iterate(void *ptr) +{ + auto vector = static_cast *>(ptr); + for (auto it = vector->cbegin(); it != vector->cend(); ++it) { + black_hole(*it); + } +} + +void +cpp_vector_lookups_subscript(void *ptr, const intptr_t *start, size_t count) +{ + auto vector = static_cast *>(ptr); + for (auto it = start; it < start + count; ++it) { + black_hole((*vector)[*it]); + } +} + +void +cpp_vector_lookups_at(void *ptr, const intptr_t *start, size_t count) +{ + auto vector = static_cast *>(ptr); + for (auto it = start; it < start + count; ++it) { + black_hole((*vector).at(*it)); + } +} + +void +cpp_vector_pop_back(void *ptr) +{ + auto vector = static_cast *>(ptr); + auto size = vector->size(); + for (int i = 0; i < size; ++i) { + identity(vector)->pop_back(); + } +} + +void +cpp_vector_pop_front(void *ptr) +{ + auto vector = static_cast *>(ptr); + auto size = vector->size(); + for (int i = 0; i < size; ++i) { + identity(vector)->erase(vector->cbegin()); + } +} + +void +cpp_vector_random_removals(void *ptr, const intptr_t *start, size_t count) +{ + auto vector = static_cast *>(ptr); + for (auto it = start; it < start + count; ++it) { + identity(vector)->erase(vector->cbegin() + *it); + } +} + +void +cpp_vector_sort(void *ptr) +{ + auto vector = static_cast *>(ptr); + std::sort(vector->begin(), vector->end()); +} diff --git a/Benchmarks/CppBenchmarks/src/utils.cpp b/Benchmarks/CppBenchmarks/src/utils.cpp new file mode 100644 index 00000000..1e2c542c --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/utils.cpp @@ -0,0 +1,42 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#include "utils.h" + +void +black_hole(intptr_t value) +{ + // Do nothing. +} + +void +black_hole(void *value) +{ + // Do nothing. +} + +intptr_t +identity(intptr_t value) +{ + return value; +} + +void * +_identity(void *value) +{ + return value; +} + +const void * +_identity(const void *value) +{ + return value; +} diff --git a/Benchmarks/CppBenchmarks/src/utils.h b/Benchmarks/CppBenchmarks/src/utils.h new file mode 100644 index 00000000..9109a093 --- /dev/null +++ b/Benchmarks/CppBenchmarks/src/utils.h @@ -0,0 +1,38 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#ifndef BLACK_HOLE_H +#define BLACK_HOLE_H + +#include + +// FIXME: Is putting this in a separate compilation unit enough to make +// sure the function call is always emitted? + +extern void black_hole(intptr_t value); +extern void black_hole(void *value); + +extern intptr_t identity(intptr_t value); +extern void *_identity(void *value); +extern const void *_identity(const void *value); + +template +static inline T *identity(T *value) +{ + return static_cast(_identity(value)); +} + +template +static inline const T *identity(const T *value) +{ + return static_cast(_identity(value)); +} +#endif /* BLACK_HOLE_H */ diff --git a/Benchmarks/swift-collections-benchmark/main.swift b/Benchmarks/swift-collections-benchmark/main.swift new file mode 100644 index 00000000..ddfed857 --- /dev/null +++ b/Benchmarks/swift-collections-benchmark/main.swift @@ -0,0 +1,26 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsBenchmark +import Benchmarks + +var benchmark = Benchmark(title: "Collection Benchmarks") +benchmark.addArrayBenchmarks() +benchmark.addSetBenchmarks() +benchmark.addDictionaryBenchmarks() +benchmark.addDequeBenchmarks() +benchmark.addOrderedSetBenchmarks() +benchmark.addOrderedDictionaryBenchmarks() +benchmark.addCppBenchmarks() + +benchmark.chartLibrary = try benchmark.loadReferenceLibrary() + +benchmark.main() diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 00000000..7a84b3bc --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,19 @@ +# This file is a list of the people responsible for ensuring that patches for a +# particular part of Swift are reviewed, either by themselves or by someone else. +# They are also the gatekeepers for their part of Swift, with the final word on +# what goes in or not. +# +# The list is sorted by surname and formatted to allow easy grepping and +# beautification by scripts. The fields are: name (N), email (E), web-address +# (W), PGP key ID and fingerprint (P), description (D), and snail-mail address +# (S). + +# N: Karoy Lorentey +# E: klorentey@apple.com +# D: Everything in swift-collections not covered by someone else + +### + +# The following lines are used by GitHub to automatically recommend reviewers. + +* @lorentey diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..95c80e78 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,38 @@ +# Code of Conduct + +To be a truly great community, Swift.org needs to welcome developers from all walks of life, with different backgrounds, and with a wide range of experience. A diverse and friendly community will have more great ideas, more unique perspectives, and produce more great code. We will work diligently to make the Swift community welcoming to everyone. + +To give clarity of what is expected of our members, this code of conduct is based on [contributor-covenant.org](http://contributor-covenant.org). This document is used across many open source communities, and we think it articulates our values well. + +### Contributor Code of Conduct v1.4 + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language (e.g., prefer non-gendered words like “folks” to “guys”, non-ableist words like “soundness check” to “sanity check”, etc.) +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +This Code of Conduct applies within all project spaces managed by Swift.org, including (but not limited to) source code repositories, bug trackers, web sites, documentation, and online forums. It also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a member of the [Swift Core Team](https://swift.org/community/#community-structure) or by flagging the behavior for moderation (e.g., in the Forums), whether you are the target of that behavior or not. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident. The site of the disputed behavior is usually not an acceptable place to discuss moderation decisions, and moderators may move or remove any such discussion. + +Project maintainers are held to a higher standard, and project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership. +If you disagree with a moderation action, you can appeal to the Core Team (or individual Core Team members) privately. + +This policy is adapted from the Contributor Code of Conduct [version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b4612da5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,11 @@ +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](https://swift.org/LICENSE.txt). + +--- + +Before submitting the pull request, please make sure you have tested your +changes and that they follow the Swift project [guidelines for contributing +code](https://swift.org/contributing/#contributing-code). + diff --git a/Documentation/Deque.md b/Documentation/Deque.md new file mode 100644 index 00000000..e86ea793 --- /dev/null +++ b/Documentation/Deque.md @@ -0,0 +1,93 @@ +# Deque + +A collection implementing a double-ended queue. + +## Declaration + +```swift +import DequeModule + +@frozen struct Deque +``` + +## Overview + +`Deque` (pronounced "deck") implements an ordered random-access +collection that supports efficient insertions and removals from both +ends. + +```swift +var colors: Deque = ["red", "yellow", "blue"] +``` + +Deques implement the same indexing semantics as arrays: they use integer +indices, and the first element of a nonempty deque is always at index zero. +Like arrays, deques conform to `RangeReplaceableCollection`, +`MutableCollection` and `RandomAccessCollection`, providing a familiar +interface for manipulating their contents: + + +```swift +print(colors[1]) // "yellow" +print(colors[3]) // Runtime error: Index out of range + +colors.insert("green", at: 1) +// ["red", "green", "yellow", "blue"] + +colors.remove(at: 2) // "yellow" +// ["red", "green", "blue"] +``` + +Like all variable-size collections on the standard library, `Deque` +implements value semantics: each deque has an independent value that +includes the values of its elements. Modifying one deque does not affect any +others: + +```swift +var copy = deque +copy[1] = "violet" +print(copy) // ["red", "violet", "blue"] +print(deque) // ["red", "green", "blue"] +``` + +This is implemented with the copy-on-write optimization. Multiple copies of +a deque share the same underlying storage until you modify one of the +copies. When that happens, the deque being modified replaces its storage +with a uniquely owned copy of itself, which is then modified in place. + +`Deque` stores its elements in a circular buffer, which allows efficient +insertions and removals at both ends of the collection; however, this comes +at the cost of potentially discontiguous storage. In contrast, `Array` is +(usually) backed by a contiguous buffer, where new data can be efficiently +appended to the end, but inserting at the front is relatively slow, as +existing elements need to be shifted to make room. + +This difference in implementation means that while the interface of a deque +is very similar to an array, the operations have different performance +characteristics. Mutations near the front are expected to be significantly +faster in deques, but arrays may measure slightly faster for general +random-access lookups. + +Deques provide a handful of additional operations that make it easier to +insert and remove elements at the front. This includes queue operations such +as `popFirst` and `prepend`, including the ability to directly prepend a +sequence of elements: + +```swift +colors.append("green") +colors.prepend("orange") +// colors: ["orange", "red", "blue", "yellow", "green"] + +colors.popLast() // "green" +colors.popFirst() // "orange" +// colors: ["red", "blue", "yellow"] + +colors.prepend(contentsOf: ["purple", "teal"]) +// colors: ["purple", "teal", "red", "blue", "yellow"] +``` + +Unlike arrays, deques do not currently provide direct unsafe access to their +underlying storage. They also lack a `capacity` property -- the size of the +storage buffer at any given point is an unstable implementation detail that +should not affect application logic. (However, deques do provide a +`reserveCapacity` method.) diff --git a/Documentation/OrderedDictionary.md b/Documentation/OrderedDictionary.md new file mode 100644 index 00000000..aa56e195 --- /dev/null +++ b/Documentation/OrderedDictionary.md @@ -0,0 +1,224 @@ +# `OrderedDictionary` + +An ordered collection of key-value pairs. + +## Declaration + +```swift +import OrderedCollections + +@frozen struct OrderedDictionary +``` + +## Overview + +Like the standard `Dictionary`, ordered dictionaries use a hash table to +ensure that no two entries have the same keys, and to efficiently look up +values corresponding to specific keys. However, like an `Array` (and +unlike `Dictionary`), ordered dictionaries maintain their elements in a +particular user-specified order, and they support efficient random-access +traversal of their entries. + +`OrderedDictionary` is a useful alternative to `Dictionary` when the order +of elements is important, or when you need to be able to efficiently access +elements at various positions within the collection. + +You can create an ordered dictionary with any key type that conforms to the +`Hashable` protocol. + +```swift +let responses: OrderedDictionary = [ + 200: "OK", + 403: "Access forbidden", + 404: "File not found", + 500: "Internal server error", +] +``` + +### Equality of Ordered Dictionaries + +Two ordered dictionaries are considered equal if they contain the same +elements, and *in the same order*. This matches the concept of equality of +an `Array`, and it is different from the unordered `Dictionary`. + +```swift +let a: OrderedDictionary = [1: "one", 2: "two"] +let b: OrderedDictionary = [2: "two", 1: "one"] +a == b // false +b.swapAt(0, 1) // `b` now has value [1: "one", 2: "two"] +a == b // true +``` + +(`OrderedDictionary` only conforms to `Equatable` when its `Value` is +equatable.) + +### Dictionary Operations + +`OrderedDictionary` provides many of the same operations as `Dictionary`. + +For example, you can look up and add/remove values using the familiar +key-based subscript, returning an optional value: + +```swift +var dictionary: OrderedDictionary = [:] +dictionary["one"] = 1 +dictionary["two"] = 2 +dictionary["three"] // nil +// dictionary is now ["one": 1, "two": 2] +``` + +If a new entry is added using the subscript setter, it gets appended to the +end of the dictionary. (So that by default, the dictionary contains its +elements in the order they were originally inserted.) + +`OrderedDictionary` also implements the variant of this subscript that takes +a default value. Like with `Dictionary`, this is useful when you want to +perform in-place mutations on values: + +```swift +let text = "short string" +var counts: OrderedDictionary = [:] +for character in text { + counts[character, default: 0] += 1 +} +// counts is ["s": 2, "h": 1, "o": 1, +// "r": 2, "t": 2, " ": 1, +// "i": 1, "n": 1, "g": 1] +``` + +If the `Value` type implements reference semantics, or when you need to +perform a series of individual mutations on the values, the closure-based +`modifyValue(forKey:default:_:)` method provides an easier-to-use +alternative to the defaulted key-based subscript. + +```swift +let text = "short string" +var counts: OrderedDictionary = [:] +for character in text { + counts.modifyValue(forKey: character, default: 0) { value in + value += 1 + } +} +// Same result as before +``` + +(This isn't currently available on the regular `Dictionary`.) + +The `Dictionary` type's original `updateValue(_:forKey:)` method is also +available, and so is `index(forKey:)`, grouping/uniquing initializers +(`init(uniqueKeysWithValues:)`, `init(_:uniquingKeysWith:)`, +`init(grouping:by:)`), methods for merging one dictionary with another +(`merge`, `merging`), filtering dictionary entries (`filter(_:)`), +transforming values (`mapValues(_:)`), and a combination of these two +(`compactMapValues(_:)`). + +### Sequence and Collection Operations + +Ordered dictionaries use integer indices representing offsets from the +beginning of the collection. However, to avoid ambiguity between key-based +and indexing subscripts, `OrderedDictionary` doesn't directly conform to +`Collection`. Instead, it only conforms to `Sequence`, and provides a +random-access collection view over its key-value pairs: + +```swift +responses[0] // `nil` (key-based subscript) +responses.elements[0] // `(200, "OK")` (index-based subscript) +``` + +Because ordered dictionaries need to maintain unique keys, neither +`OrderedDictionary` nor its `elements` view can conform to the full +`MutableCollection` or `RangeReplaceableCollection` protocols. However, they +are able to partially implement requirements: they support mutations +that merely change the order of elements, or just remove a subset of +existing members: + +```swift +// Permutation operations from MutableCollection: +func swapAt(_ i: Index, _ j: Index) +func partition(by predicate: (Element) throws -> Bool) -> rethrows Index +func sort() where Element: Comparable +func sort(by predicate: (Element, Element) throws -> Bool) rethrows +func shuffle() +func shuffle(using generator: inout T) + +// Removal operations from RangeReplaceableCollection: +func removeAll(keepingCapacity: Bool = false) +func remove(at index: Index) -> Element +func removeSubrange(_ bounds: Range) +func removeLast() -> Element +func removeLast(_ n: Int) +func removeFirst() -> Element +func removeFirst(_ n: Int) +func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows +``` + +`OrderedDictionary` also implements `reserveCapacity(_)` from +`RangeReplaceableCollection`, to allow for efficient insertion of a known +number of elements. (However, unlike `Array` and `Dictionary`, +`OrderedDictionary` does not provide a `capacity` property.) + +### Keys and Values Views + +Like the standard `Dictionary`, `OrderedDictionary` provides `keys` and +`values` properties that provide lightweight views into the corresponding +parts of the dictionary. + +The `keys` collection is of type `OrderedSet`, containing all the keys +in the original dictionary. + +```swift +let d: OrderedDictionary = [2: "two", 1: "one", 0: "zero"] +d.keys // [2, 1, 0] as OrderedSet +``` + +The `keys` property is read-only, so you cannot mutate the dictionary +through it. However, it returns an ordinary ordered set value, which can be +copied out and then mutated if desired. (Such mutations won't affect the +original dictionary value.) + +The `values` collection is a mutable random-access collection of the values +in the dictionary: + +```swift +d.values // "two", "one", "zero" +d.values[2] = "nada" +// `d` is now [2: "two", 1: "one", 0: "nada"] +d.values.sort() +// `d` is now [2: "nada", 1: "one", 0: "two"] +``` + +Both views store their contents in regular `Array` values, accessible +through their `elements` property. + +## Performance + +Like the standard `Dictionary` type, the performance of hashing operations +in `OrderedDictionary` is highly sensitive to the quality of hashing +implemented by the `Key` type. Failing to correctly implement hashing can +easily lead to unacceptable performance, with the severity of the effect +increasing with the size of the hash table. + +In particular, if a certain set of keys all produce the same hash value, +then hash table lookups regress to searching an element in an unsorted +array, i.e., a linear operation. To ensure hashed collection types exhibit +their target performance, it is important to ensure that such collisions +cannot be induced merely by adding a particular list of keys to the +dictionary. + +The easiest way to achieve this is to make sure `Key` implements hashing +following `Hashable`'s documented best practices. The conformance must +implement the `hash(into:)` requirement, and every bit of information that +is compared in `==` needs to be combined into the supplied `Hasher` value. +When used correctly, `Hasher` produces high-quality, randomly seeded hash +values that prevent repeatable hash collisions. + +When `Key` correctly conforms to `Hashable`, key-based lookups in an ordered +dictionary is expected to take O(1) equality checks on average. Hash +collisions can still occur organically, so the worst-case lookup performance +is technically still O(*n*) (where *n* is the size of the dictionary); +however, long lookup chains are unlikely to occur in practice. + +## Implementation Details + +An ordered dictionary consists of an ordered set of keys, alongside a +regular `Array` value that contains their associated values. diff --git a/Documentation/OrderedSet.md b/Documentation/OrderedSet.md new file mode 100644 index 00000000..3815437e --- /dev/null +++ b/Documentation/OrderedSet.md @@ -0,0 +1,255 @@ +# OrderedSet + +An ordered collection of unique elements. + +## Declaration + +```swift +import OrderedCollections + +@frozen struct OrderedSet +``` + +## Overview + +Similar to the standard `Set`, ordered sets ensure that each element appears +only once in the collection, and they provide efficient tests for +membership. However, like `Array` (and unlike `Set`), ordered sets maintain +their elements in a particular user-specified order, and they support +efficient random-access traversal of their members. + +`OrderedSet` is a useful alternative to `Set` when the order of elements is +important, or when you need to be able to efficiently access elements at +various positions within the collection. It can also be used instead of an +`Array` when each element needs to be unique, or when you need to be able to +quickly determine if a value is a member of the collection. + +You can create an ordered set with any element type that conforms to the +`Hashable` protocol. + +```swift +let buildingMaterials: OrderedSet = ["straw", "sticks", "bricks"] +``` + + +### Equality of Ordered Sets + +Two ordered sets are considered equal if they contain the same elements, and +*in the same order*. This matches the concept of equality of an `Array`, and +it is different from the unordered `Set`. + +```swift +let a: OrderedSet = [1, 2, 3, 4] +let b: OrderedSet = [4, 3, 2, 1] +a == b // false +b.sort() // `b` now has value [1, 2, 3, 4] +a == b // true +``` + +### Set Operations + +`OrderedSet` implements most, but not all, `SetAlgebra` requirements. In +particular, it supports the membership test `contains(_:)` as well as all +high-level set operations such as `union(_:)`, `intersection(_:)` or +`isSubset(of:)`. + +```swift +buildingMaterials.contains("glass") // false +buildingMaterials.intersection(["brick", "straw"]) // ["straw", "brick"] +``` + +Operations that return an ordered set usually preserve the ordering of +elements in their input. For example, in the case of the `intersection` call +above, the ordering of elements in the result is guaranteed to match their +order in the first input set, `buildingMaterials`. + +On the other hand, predicates such as `isSubset(of:)` tend to ignore element +ordering: + +```swift +let moreMaterials: OrderedSet = ["bricks", "glass", "sticks", "straw"] +buildingMaterials.isSubset(of: moreMaterials) // true +``` + +However, `OrderedSet` does not implement `insert(_:)` nor `update(with:)` -- +it provides its own variants for insertion that are more explicit about +where in the collection new elements gets inserted: + +```swift +func insert(_ item: Element, at index: Index) -> (inserted: Bool, index: Int) +func append(_ item: Element) -> (inserted: Bool, index: Int) +func update(at index: Int, with item: Element) -> Element +func updateOrAppend(_ item: Element) -> Element? +``` + +Additionally,`OrderedSet` has an order-sensitive definition of equality (see +above) that is incompatible with `SetAlgebra`'s documented semantic +requirements. Accordingly, `OrderedSet` does not (cannot) itself conform to +`SetAlgebra`. + +### Unordered Set View + +For cases where `SetAlgebra` conformance is desired (such as when passing an +ordered set to a function that is generic over that protocol), `OrderedSet` +provides an efficient *unordered view* of its elements that conforms to +`SetAlgebra`. The unordered view implements the same concept of equality as +the standard `Set`, ignoring element ordering. + +```swift +var a: OrderedSet = [0, 1, 2, 3] +let b: OrderedSet = [3, 2, 1, 0] +a == b // false +a.unordered == b.unordered // true + +func frobnicate(_ set: S) { ... } +frobnicate(a) // error: `OrderedSet` does not conform to `SetAlgebra` +frobnicate(a.unordered) // OK +``` + +The unordered view is mutable. Insertions into it implicitly append new +elements to the end of the collection. + +```swift +buildingMaterials.unordered.insert("glass") // => inserted: true +// buildingMaterials is now ["straw", "sticks", "brick", "glass"] +``` + +Accessing the unordered view is an efficient operation, with constant +(minimal) overhead. Direct mutations of the unordered view (such as the +insertion above) are executed in place when possible. However, as usual with +copy-on-write collections, if you make a copy of the view (such as by +extracting its value into a named variable), the resulting values will share +the same underlying storage, so mutations of either will incur a copy of the +whole set. + +### Sequence and Collection Operations + +Ordered sets are random-access collections. Members are assigned integer +indices, with the first element always being at index `0`: + +```swift +let buildingMaterials: OrderedSet = ["straw", "sticks", "bricks"] +buildingMaterials[1] // "sticks" +buildingMaterials.firstIndex(of: "bricks") // 2 + +for i in 0 ..< buildingMaterials.count { + print("Little piggie #\(i) built a house of \(buildingMaterials[i])") +} +// Little piggie #0 built a house of straw +// Little piggie #1 built a house of sticks +// Little piggie #2 built a house of bricks +``` + +Because `OrderedSet` needs to keep its members unique, it cannot conform to +the full `MutableCollection` or `RangeReplaceableCollection` protocols. +Operations such as `MutableCollection`'s subscript setter or +`RangeReplaceableCollection`'s `replaceSubrange` assume the ability to +insert/replace arbitrary elements in the collection, but allowing that could +lead to duplicate values. + +However, `OrderedSet` is able to partially implement these two protocols; +namely, there is no issue with mutation operations that merely change the +order of elements, or just remove some subset of existing members: + +```swift +// Permutation operations from MutableCollection: +func swapAt(_ i: Int, _ j: Int) +func partition(by predicate: (Element) throws -> Bool) -> rethrows Int +func sort() where Element: Comparable +func sort(by predicate: (Element, Element) throws -> Bool) rethrows +func shuffle() +func shuffle(using generator: inout T) +func reverse() + +// Removal operations from RangeReplaceableCollection: +func removeAll(keepingCapacity: Bool = false) +func remove(at index: Int) -> Element +func removeSubrange(_ bounds: Range) +func removeLast() -> Element +func removeLast(_ n: Int) +func removeFirst() -> Element +func removeFirst(_ n: Int) +func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows +``` + +`OrderedSet` also implements `reserveCapacity(_)` from +`RangeReplaceableCollection`, to allow for efficient insertion of a known +number of elements. (However, unlike `Array` and `Set`, `OrderedSet` does +not provide a `capacity` property.) + +### Accessing The Contents of an Ordered Set as an Array + +In cases where you need to pass the contents of an ordered set to a function +that only takes an array value or (or something that's generic over +`RangeReplaceableCollection` or `MutableCollection`), then the best option +is usually to directly extract the members of the `OrderedSet` as an `Array` +value using its `elements` property. `OrderedSet` uses a standard array +value for element storage, so extracting the array value has minimal +overhead. + +```swift +func pickyFunction(_ items: Array) + +var set: OrderedSet = [0, 1, 2, 3] +pickyFunction(set) // error +pickyFunction(set.elements) // OK +``` + +It is also possible to mutate the set by updating the value of the +`elements` property. This guarantees that direct mutations happen in place +when possible (i.e., without spurious copy-on-write copies). + +However, the set needs to ensure the uniqueness of its members, so every +update to `elements` includes a postprocessing step to detect and remove +duplicates over the entire array. This can be slower than doing the +equivalent updates with direct `OrderedSet` operations, so updating +`elements` is best used in cases where direct implementations aren't +available -- for example, when you need to call a `MutableCollection` +algorithm that isn't directly implemented by `OrderedSet` itself. + +### Performance + +Like the standard `Set` type, the performance of hashing operations in +`OrderedSet` is highly sensitive to the quality of hashing implemented by +the `Element` type. Failing to correctly implement hashing can easily lead +to unacceptable performance, with the severity of the effect increasing with +the size of the hash table. + +In particular, if a certain set of elements all produce the same hash value, +then hash table lookups regress to searching an element in an unsorted +array, i.e., a linear operation. To ensure hashed collection types exhibit +their target performance, it is important to ensure that such collisions +cannot be induced merely by adding a particular list of members to the set. + +The easiest way to achieve this is to make sure `Element` implements hashing +following `Hashable`'s documented best practices. The conformance must +implement the `hash(into:)` requirement, and every bit of information that +is compared in `==` needs to be combined into the supplied `Hasher` value. +When used correctly, `Hasher` produces high-quality, randomly seeded hash +values that prevent repeatable hash collisions. + +When `Element` implements `Hashable` correctly, testing for membership in an +ordered set is expected to take O(1) equality checks on average. Hash +collisions can still occur organically, so the worst-case lookup performance +is technically still O(*n*) (where *n* is the size of the set); however, +long lookup chains are unlikely to occur in practice. + +### Implementation Details + +An `OrderedSet` stores its members in a regular `Array` value (exposed by +the `elements` property). It also maintains a standalone hash table +containing array indices alongside the array; this is used to implement fast +membership tests. The size of the array is limited by the capacity of the +corresponding hash table, so indices stored inside the hash table can be +encoded into fewer bits than a standard `Int` value, leading to a storage +representation that can often be more compact than that of `Set` itself. + +Inserting or removing a single member (or a range of members) needs to +perform the corresponding operation in the storage array, in addition to +renumbering any subsequent members in the hash table. Therefore, these +operations are expected to have performance characteristics similar to an +`Array`: inserting or removing an element to the end of an ordered set is +expected to execute in O(1) operations, while they are expected to take +linear time at the front (or in the middle) of the set. (Note that this is +different to the standard `Set`, where insertions and removals are expected +to take amortized O(1) time.) diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 00000000..61b0c781 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,211 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + +## Runtime Library Exception to the Apache 2.0 License: ## + + + As an exception, if you use this Software to compile your source code and + portions of this Software are embedded into the binary product as a result, + you may redistribute such product without providing attribution as would + otherwise be required by Sections 4(a), 4(b) and 4(d) of the License. diff --git a/Package.resolved b/Package.resolved new file mode 100644 index 00000000..dd55e63a --- /dev/null +++ b/Package.resolved @@ -0,0 +1,25 @@ +{ + "object": { + "pins": [ + { + "package": "swift-argument-parser", + "repositoryURL": "https://github.com/apple/swift-argument-parser", + "state": { + "branch": null, + "revision": "831ed5e860a70e745bc1337830af4786b2576881", + "version": "0.4.1" + } + }, + { + "package": "swift-system", + "repositoryURL": "https://github.com/apple/swift-system", + "state": { + "branch": null, + "revision": "8ffa04c0a0592e6f4f9c30926dedd8fa1c5371f9", + "version": "0.0.1" + } + } + ] + }, + "version": 1 +} diff --git a/Package.swift b/Package.swift new file mode 100644 index 00000000..b53b55dd --- /dev/null +++ b/Package.swift @@ -0,0 +1,141 @@ +// swift-tools-version:5.3 +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import PackageDescription + +// This package recognizes the conditional compilation flags listed below. +// To use enable them, uncomment the corresponding lines or define them +// from the package manager command line: +// +// swift build -Xswiftc -DCOLLECTIONS_INTERNAL_CHECKS +var settings: [SwiftSetting]? = [ + + // Enables internal consistency checks at the end of initializers and + // mutating operations. This can have very significant overhead, so enabling + // this setting invalidates all documented performance guarantees. + // + // This is mostly useful while debugging an issue with the implementation of + // the hash table itself. This setting should never be enabled in production + // code. +// .define("COLLECTIONS_INTERNAL_CHECKS"), + + // Hashing collections provided by this package usually seed their hash + // function with the address of the memory location of their storage, + // to prevent some common hash table merge/copy operations from regressing to + // quadratic behavior. This setting turns off this mechanism, seeding + // the hash function with the table's size instead. + // + // When used in conjunction with the SWIFT_DETERMINISTIC_HASHING environment + // variable, this enables reproducible hashing behavior. + // + // This is mostly useful while debugging an issue with the implementation of + // the hash table itself. This setting should never be enabled in production + // code. +// .define("COLLECTIONS_DETERMINISTIC_HASHING"), + +] + +// Prevent SPM 5.3 from throwing an error on empty settings arrays. +// (This has been fixed in 5.4.) +if settings?.isEmpty == true { settings = nil } + +let package = Package( + name: "swift-collections", + products: [ + .library(name: "Collections", targets: ["Collections"]), + .library(name: "DequeModule", targets: ["DequeModule"]), + .library(name: "OrderedCollections", targets: ["OrderedCollections"]), + .library(name: "UniquedModule", targets: ["UniquedModule"]), + + .executable(name: "swift-collections-benchmark", targets: ["swift-collections-benchmark"]), + ], + dependencies: [ + // This is only used in the benchmark executable target. + .package(url: "https://github.com/apple/swift-collections-benchmark", from: "0.0.1"), + ], + targets: [ + .target( + name: "Collections", + dependencies: [ + "DequeModule", + "OrderedCollections", + ], + path: "Sources/Collections", + swiftSettings: settings), + + // Testing support module + .target( + name: "CollectionsTestSupport", + dependencies: [], + swiftSettings: settings, + linkerSettings: [ + .linkedFramework( + "XCTest", + .when(platforms: [.macOS, .iOS, .watchOS, .tvOS])), + ] + ), + + // Benchmarking + .target( + name: "Benchmarks", + dependencies: [ + .product(name: "CollectionsBenchmark", package: "swift-collections-benchmark"), + "CppBenchmarks", + "Collections", + ], + path: "Benchmarks/Benchmarks", + resources: [ + .copy("Library.json"), + ] + ), + .target( + name: "CppBenchmarks", + path: "Benchmarks/CppBenchmarks" + ), + .target( + name: "swift-collections-benchmark", + dependencies: [ + "Benchmarks", + ], + path: "Benchmarks/swift-collections-benchmark" + ), + + // Deque + .target( + name: "DequeModule", + swiftSettings: settings), + .testTarget( + name: "DequeTests", + dependencies: ["DequeModule", "CollectionsTestSupport"], + swiftSettings: settings), + + // OrderedSet, OrderedDictionary + .target( + name: "OrderedCollections", + swiftSettings: settings), + .testTarget( + name: "OrderedCollectionsTests", + dependencies: ["OrderedCollections", "CollectionsTestSupport"], + swiftSettings: settings), + + // Uniqued + .target( + name: "UniquedModule", + dependencies: ["DequeModule"], + swiftSettings: settings), + .testTarget( + name: "UniquedTests", + dependencies: ["UniquedModule", "CollectionsTestSupport"], + swiftSettings: settings), + ], + cxxLanguageStandard: .cxx1z +) diff --git a/README.md b/README.md new file mode 100644 index 00000000..bb6a7975 --- /dev/null +++ b/README.md @@ -0,0 +1,227 @@ +# Swift Collections + +**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][announcement]. + +[announcement]: https://swift.org/blog/swift-collections + +## Contents + +The package currently provides the following implementations: + +- [`Deque`][Deque], a double-ended queue backed by a ring buffer. Deques are range-replaceable, mutable, random-access collections. + +- [`OrderedSet`][OrderedSet], 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`][OrderedDictionary], an ordered variant of the standard `Dictionary`, providing similar benefits. + +[Deque]: Documentation/Deque.md +[OrderedSet]: Documentation/OrderedSet.md +[OrderedDictionary]: Documentation/OrderedDictionary.md + +Swift Collections uses the same modularization approach as [**Swift Numerics**](https://github.com/apple/swift-numerics): it provides a standalone module for each 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 all of the included modules with a single import statement. + +``` swift +import Collections + +var deque: Deque = ["Ted", "Rebecca"] +deque.prepend("Keeley") +deque.append("Nathan") +print(deque) // ["Keeley", "Ted", "Rebecca", "Nathan"] +``` + +## Project Status + +We think the implementations in this package are robust, but the interfaces provided have not had time to stabilize. Accordingly, while the package is in its pre-1.0 state, from time to time new releases may sometimes include source-breaking changes. We'll try our best to keep such changes to a minimum, though, even during this chaotic initial period. Whenever feasible, we'll mitigate such changes with a multi-release deprecation period. + +Before the 1.0 release, releases containing potentially source-breaking changes will increase the middle version number. The release notes will explain what changed, and how to update your code to work with the new version. + +The implementations in this package have gone through an initial performance optimization pass, but there are lots of work still to be done. Still, we think these implementations are already quite fast enough for production use -- sometimes matching or exceeding the performance of similar constructs in popular prexisting implementations in other languages. + +### Underscored Interfaces + +As customary in Swift, interfaces that are technically declared `public` but begin with an underscore are not considered part of the public interface of this package. We may remove or change them in any release without notice, including minor point releases. (If you have a use case that requires using them, please [submit a Feature Request][feature-request] describing it! We'd like the public interface to be as useful as possible -- preferably without compromising safety or limiting future evolution.) + +[feature-request]: https://github.com/apple/swift-collections/issues/new?assignees=&labels=enhancement&template=FEATURE_REQUEST.md + +### Benchmarks + +The package includes an extensive library of benchmarks in the [Benchmarks](./Benchmarks) directory, driven by a command-line executable target, `swift-collections-benchmark`. These benchmarks, the executable target, and its command-line interface are not considered part of the public interface of the package. As such, new releases may break them without any special ceremony. We do expect the benchmarks will stabilize with time. + +For more information on our benchmarking tool, please see its dedicated package, [**Swift Collections Benchmark**][swift-collections-benchmark]. + +[swift-collections-benchmark]: https://github.com/apple/swift-collections-benchmark + +### Test Support Library + +The package comes with a rich test support library in the [Sources/CollectionsTestSupport](./Sources/CollectionsTestSupport) directory. These were loosely adapted from the contents of the `StdlibUnittest*` modules in the [Swift compiler repository](https://github.com/apple/swift/tree/main/stdlib/private), with some custom additions. + +These components would likely be of interest to the wider Swift community, but they aren't yet stable enough (or documented enough) to publish them. Accordingly, these testing helpers are currently considered implementation details of this package, and are subject to change at whim. + +The test support library currently provides the following functionality: + +- [`AssertionContexts`](./Sources/CollectionsTestSupport/AssertionContexts): Custom test assertions with support for keeping track of nested context information, including stopping execution when the current context matches a particular value. (Useful for debugging combinatorial tests.) + +
+ Click here for a short demonstration + + ```swift + import XCTest + import CollectionsTestSupport + + final class DequeTests: CollectionTestCase { + func test_demo() { + let values = [0, 10, 20, 30, 42, 50, 60] + for i in values.indices { + context.withTrace("i: \(i)") { + expectEqual(values[i], 10 * i) + } + } + } + } + ``` + + ``` + DemoTests.swift:21: error: -[DemoTests.DemoTests test_demo] : XCTAssertEqual failed: ("42") is not equal to ("40") - + Trace: + - i: 4 + ``` + + To debug issues, copy the trace message into a `context.failIfTraceMatches(_:)` invocation and set a breakpoint on test failures. + + ```swift + let values = [0, 10, 20, 30, 42, 50, 60] + for i in values.indices { + context.withTrace("i: \(i)") { + // This will report a test failure before executing the `i == 4` case, + // letting us investigate what's going on. + context.failIfTraceMatches(""" + Trace: + - i: 4 + """) + expectEqual(values[i], 10 * i) + } + } + ``` + +
+ +- [`Combinatorics`](./Sources/CollectionsTestSupport/Combinatorics): Basic support for exhaustive combinatorial testing. This allows us to easily verify that a collection operation works correctly on all possible instances up to a certain size, including behavioral variations such as unique/shared storage. + +
+ Click here for an example + + ```swift + func test_popFirst() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents[...].popFirst() + let actual = deque.popFirst() + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + ``` + +
+ +- [`ConformanceCheckers`](./Sources/CollectionsTestSupport/ConformanceCheckers): A set of generic, semi-automated protocol conformance tests for some Standard Library protocols. These can be used to easily validate the custom protocol conformances provided by this package. These checks aren't (can't be) complete -- but when used correctly, they are able to detect most accidental mistakes. + + We currently have conformance checkers for the following protocols: + + - [`Sequence`](./Sources/CollectionsTestSupport/ConformanceCheckers/CheckSequence.swift) + - [`Collection`](./Sources/CollectionsTestSupport/ConformanceCheckers/CheckCollection.swift) + - [`BidirectionalCollection`](./Sources/CollectionsTestSupport/ConformanceCheckers/CheckBidirectionalCollection.swift) + - [`Equatable`](./Sources/CollectionsTestSupport/ConformanceCheckers/CheckEquatable.swift) + - [`Hashable`](./Sources/CollectionsTestSupport/ConformanceCheckers/CheckHashable.swift) + - [`Comparable`](./Sources/CollectionsTestSupport/ConformanceCheckers/CheckComparable.swift) + +- [`MinimalTypes`](./Sources/CollectionsTestSupport/MinimalTypes): Minimally conforming implementations for standard protocols. These types conform to various standard protocols by implementing the requirements in as narrow-minded way as possible -- sometimes going to extreme lengths to, say, implement collection index invalidation logic in the most unhelpful way possible. + + - [`MinimalSequence`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalSequence.swift) + - [`MinimalCollection`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalCollection.swift) + - [`MinimalBidirectionalCollection`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalBidirectionalCollection.swift) + - [`MinimalRandomAccessCollection`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalRandomAccessCollection.swift) + - [`MinimalMutableRandomAccessCollection`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRandomAccessCollection.swift) + - [`MinimalRangeReplaceableRandomAccessCollection`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalRangeReplaceableRandomAccessCollection.swift) + - [`MinimalMutableRangeReplaceableRandomAccessCollection`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRangeReplaceableRandomAccessCollection.swift) + - [`MinimalIterator`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalIterator.swift) + - [`MinimalIndex`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalIndex.swift) + - [`MinimalEncoder`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalEncoder.swift) + - [`MinimalDecoder`](./Sources/CollectionsTestSupport/MinimalTypes/MinimalDecoder.swift) + +- [`Utilities`](./Sources/CollectionsTestSupport/Utilities): Utility types. Wrapper types for boxed values, a simple deterministic random number generator, and a lifetime tracker for catching simple memory management issues such as memory leaks. (The [Adress Sanitizer][asan] can be used to catch more serious problems.) + +[asan]: https://developer.apple.com/documentation/xcode/diagnosing_memory_thread_and_crash_issues_early?language=objc + + +## Using **Swift Collections** in your project + +To use this package in a SwiftPM project, add the following line to the dependencies in your `Package.swift` file: + +```swift +.package(url: "https://github.com/apple/swift-collections", from: "0.0.1"), +``` + +## Contributing to Swift Collections + +### Asking questions + +We have a dedicated [Swift Collections Forum][forum] where we can ask and answer questions on how to use or work on this package. It's also a great place to discuss its evolution. + +[forum]: https://forums.swift.org/c/related-projects/collections + +### Reporting a bug + +If you find something that looks like a bug, please open a [Bug Report][bugreport]! Fill out as many details as you can. + +### Fixing a bug or making a small improvement + +1. [Submit a PR][PR] with your change. If there is an [existing issue][issues] for the bug you're fixing, please include a reference to it. +2. Make sure to add tests covering whatever changes you are making. + +[PR]: https://github.com/apple/swift-collections/compare +[issues]: https://github.com/apple/swift-collections/issues + +[bugreport]: https://github.com/apple/swift-collections/issues/new?assignees=&labels=bug&template=BUG_REPORT.md + +### Proposing a small enhancement + +1. Raise a [Feature Request][enhancement]. Discuss why it would be important to implement it. +2. Submit a PR with your implementation, participate in the review discussion. +3. When there is a consensus that the feature is desirable, and the implementation works well, it is fully tested and documented, then it will be merged. +4. Rejoice! + +[enhancement]: https://github.com/apple/swift-collections/issues/new?assignees=&labels=enhancement&template=FEATURE_REQUEST.md + +### Proposing the addition of a new data structure + +1. Start a topic on the [forum], explaining why you believe it would be important to implement the data structure. This way we can figure out if it would be right for the package, discuss implementation strategies, and plan to allocate capacity to help. +2. When maintainers agreed to your implementation plan, start work on it, and 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. +3. Participate in the review discussion, and adapt the code accordingly. Sometimes we may need to go through several revisions! This is fine -- it makes the end result that much better. +3. 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. +4. Celebrate! You've achieved something great! + +### Licensing + +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](https://swift.org/LICENSE.txt), a copy of which is [provided in this repository](LICENSE.txt). + +### Code of Conduct + +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](https://swift.org/code-of-conduct/). A copy of this document is [available in this repository][coc]. + +[coc]: CODE_OF_CONDUCT.md + +### Contacting the maintainers + +The current code owner of this package is Karoy Lorentey ([@lorentey](https://github.com/lorentey)). You can contact him [on the Swift forums](https://forums.swift.org/u/lorentey/summary), 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](https://swift.org/community/#community-structure). + diff --git a/Sources/Collections/Collections.swift b/Sources/Collections/Collections.swift new file mode 100644 index 00000000..525b3428 --- /dev/null +++ b/Sources/Collections/Collections.swift @@ -0,0 +1,13 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@_exported import DequeModule +@_exported import OrderedCollections diff --git a/Sources/CollectionsTestSupport/AssertionContexts/Assertions.swift b/Sources/CollectionsTestSupport/AssertionContexts/Assertions.swift new file mode 100644 index 00000000..2172b920 --- /dev/null +++ b/Sources/CollectionsTestSupport/AssertionContexts/Assertions.swift @@ -0,0 +1,390 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +import XCTest + +public func expectFailure( + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + let message = message() + XCTFail( + TestContext.currentTrace(message), + file: file, line: line) + if trapping { + fatalError(message, file: file, line: line) + } +} + +internal func _expectFailure( + _ diagnostic: String, + _ message: () -> String, + trapping: Bool, + file: StaticString, + line: UInt +) { + let message = message() + XCTFail( + TestContext.currentTrace( + """ + \(diagnostic) + \(message) + """), + file: file, line: line) + if trapping { + fatalError(message, file: file, line: line) + } +} + +public func expectTrue( + _ value: Bool, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if value { return } + _expectFailure( + "'\(value)' is not true", + message, trapping: trapping, file: file, line: line) +} + +public func expectFalse( + _ value: Bool, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if !value { return } + _expectFailure( + "'\(value)' is not false", + message, trapping: trapping, file: file, line: line) +} + +public func expectNil( + _ value: Optional, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if value == nil { return } + _expectFailure( + "'\(value!)' is not nil", + message, trapping: trapping, file: file, line: line) +} + +public func expectNotNil( + _ value: Optional, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if value != nil { return } + _expectFailure( + "value is nil", + message, trapping: trapping, file: file, line: line) +} + +public func expectNotNil( + _ value: Optional, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line, + _ handler: (T) throws -> Void = { _ in } +) rethrows { + if let value = value { + try handler(value) + return + } + _expectFailure( + "value is nil", + message, trapping: trapping, file: file, line: line) +} + +public func expectIdentical( + _ left: T?, _ right: T?, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left === right { return } + let l = left.map { "\($0)" } ?? "nil" + let r = right.map { "\($0)" } ?? "nil" + _expectFailure( + "'\(l)' is not identical to '\(r)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectNotIdentical( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left !== right { return } + _expectFailure( + "'\(left)' is identical to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectEquivalent( + _ left: A, _ right: B, + by areEquivalent: (A, B) -> Bool, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if areEquivalent(left, right) { return } + _expectFailure( + "'\(left)' is not equivalent to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectEquivalent( + _ left: A?, _ right: B?, + by areEquivalent: (A, B) -> Bool, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if let left = left, let right = right, areEquivalent(left, right) { return } + let l = left.map { "\($0)" } ?? "nil" + let r = right.map { "\($0)" } ?? "nil" + _expectFailure( + "'\(l)' is not equivalent to '\(r)'", + message, trapping: trapping, file: file, line: line) +} + + +public func expectEqual( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left == right { return } + _expectFailure( + "'\(left)' is not equal to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectEqual( + _ left: T?, _ right: T?, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left == right { return } + let l = left.map { "\($0)" } ?? "nil" + let r = right.map { "\($0)" } ?? "nil" + _expectFailure( + "'\(l)' is not equal to '\(r)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectNotEqual( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left != right { return } + _expectFailure( + "'\(left)' is equal to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectLessThan( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left < right { return } + _expectFailure( + "'\(left)' is not less than '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectLessThanOrEqual( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left <= right { return } + _expectFailure( + "'\(left)' is not less than or equal to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectGreaterThan( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left > right { return } + _expectFailure( + "'\(left)' is not greater than '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectGreaterThanOrEqual( + _ left: T, _ right: T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + if left >= right { return } + _expectFailure( + "'\(left)' is not less than or equal to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +/// Check if `left` and `right` contain equal elements in the same order. +/// Note: `left` and `right` must be restartable sequences. +public func expectEqualElements( + _ left: S1, + _ right: S2, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) where S1.Element == S2.Element, S1.Element: Equatable { + let left = Array(left) + let right = Array(right) + if left.elementsEqual(right) { return } + _expectFailure( + "'\(left)' does not have equal elements to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectEquivalentElements( + _ left: S1, + _ right: S2, + by areEquivalent: (S1.Element, S2.Element) -> Bool, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) { + let left = Array(left) + let right = Array(right) + if left.elementsEqual(right, by: areEquivalent) { return } + _expectFailure( + "'\(left)' does not have equivalent elements to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +/// Check if `left` and `right` contain equal elements in the same order. +/// Note: `left` and `right` must be restartable sequences. +public func expectEqualElements< + S1: Sequence, S2: Sequence, + A: Equatable, B: Equatable +>( + _ left: S1, + _ right: S2, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) where S1.Element == (key: A, value: B), S2.Element == (key: A, value: B) { + let left = Array(left) + let right = Array(right) + if + left.elementsEqual( + right, + by: { $0.key == $1.key && $0.value == $1.value }) + { return } + _expectFailure( + "'\(left)' does not have equal elements to '\(right)'", + message, trapping: trapping, file: file, line: line) +} + +public func expectMonotonicallyIncreasing( + _ items: S, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) where S.Element: Comparable { + let items = Array(items) + var it = items.makeIterator() + guard var prev = it.next() else { return } + while let next = it.next() { + guard prev <= next else { + _expectFailure( + "'\(items)' is not monotonically increasing", + message, trapping: trapping, file: file, line: line) + return + } + prev = next + } +} + +public func expectStrictlyMonotonicallyIncreasing( + _ items: S, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line +) where S.Element: Comparable { + let items = Array(items) + var it = items.makeIterator() + guard var prev = it.next() else { return } + while let next = it.next() { + guard prev < next else { + _expectFailure( + "'\(items)' is not strictly monotonically increasing", + message, trapping: trapping, file: file, line: line) + return + } + prev = next + } +} + +public func expectThrows( + _ expression: @autoclosure () throws -> T, + _ message: @autoclosure () -> String = "", + trapping: Bool = false, + file: StaticString = #file, + line: UInt = #line, + _ errorHandler: (Error) -> Void = { _ in } +) { + do { + let result = try expression() + expectFailure("Expression did not throw" + + (T.self == Void.self ? "" : " (returned '\(result)' instead)"), + trapping: trapping, + file: file, line: line) + } catch { + errorHandler(error) + } +} diff --git a/Sources/CollectionsTestSupport/AssertionContexts/CollectionTestCase.swift b/Sources/CollectionsTestSupport/AssertionContexts/CollectionTestCase.swift new file mode 100644 index 00000000..73d09474 --- /dev/null +++ b/Sources/CollectionsTestSupport/AssertionContexts/CollectionTestCase.swift @@ -0,0 +1,30 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +import XCTest + +open class CollectionTestCase: XCTestCase { + internal var _context: TestContext? + + public var context: TestContext { _context! } + + public override func setUp() { + super.setUp() + _context = TestContext.pushNew() + } + + public override func tearDown() { + super.setUp() + TestContext.pop(context) + _context = nil + } +} diff --git a/Sources/CollectionsTestSupport/AssertionContexts/Combinatorics.swift b/Sources/CollectionsTestSupport/AssertionContexts/Combinatorics.swift new file mode 100644 index 00000000..9da7afc6 --- /dev/null +++ b/Sources/CollectionsTestSupport/AssertionContexts/Combinatorics.swift @@ -0,0 +1,177 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// Run the supplied closure with all values in `items` in a loop, +/// recording the current value in the current test trace stack. +public func withEvery( + _ label: String, + in items: S, + file: StaticString = #file, + line: UInt = #line, + run body: (S.Element) throws -> Void +) rethrows { + let context = TestContext.current + for item in items { + let entry = context.push("\(label): \(item)", file: file, line: line) + var done = false + defer { + context.pop(entry) + if !done { + print(context.currentTrace(title: "Throwing trace")) + } + } + try body(item) + done = true + } +} + +public func withEveryRange( + _ label: String, + in bounds: Range, + file: StaticString = #file, + line: UInt = #line, + run body: (Range) throws -> Void +) rethrows where T.Stride == Int { + let context = TestContext.current + for lowerBound in bounds.lowerBound ... bounds.upperBound { + for upperBound in lowerBound ... bounds.upperBound { + let range = lowerBound ..< upperBound + let entry = context.push("\(label): \(range)", file: file, line: line) + var done = false + defer { + context.pop(entry) + if !done { + print(context.currentTrace(title: "Throwing trace")) + } + } + try body(range) + done = true + } + } +} + +internal func _samples(from items: C) -> [C.Element] { + let c = items.count + guard c > 7 else { return Array(items) } + let offsets = [0, 1, c / 2 - 1, c / 2, c / 2 + 1, c - 2, c - 1] + var offset = 0 + var index = items.startIndex + var result: [C.Element] = [] + result.reserveCapacity(7) + for o in offsets { + items.formIndex(&index, offsetBy: o - offset) + offset = o + result.append(items[index]) + } + return result +} + +/// Run the supplied closure with all values in `items` in a loop, +/// recording the current value in the current test trace stack. +public func withSome( + _ label: String, + in items: C, + file: StaticString = #file, + line: UInt = #line, + run body: (C.Element) throws -> Void +) rethrows { + let context = TestContext.current + for item in _samples(from: items) { + let entry = context.push("\(label): \(item)", file: file, line: line) + var done = false + defer { + context.pop(entry) + if !done { + print(context.currentTrace(title: "Throwing trace")) + } + } + try body(item) + done = true + } +} + +public func withSomeRanges( + _ label: String, + in bounds: Range, + file: StaticString = #file, + line: UInt = #line, + run body: (Range) throws -> Void +) rethrows where T.Stride == Int { + let context = TestContext.current + for lowerBound in _samples(from: bounds) { + for upperBound in _samples(from: lowerBound ... bounds.upperBound) { + let range = lowerBound ..< upperBound + let entry = context.push("\(label): \(range)", file: file, line: line) + var done = false + defer { + context.pop(entry) + if !done { + print(context.currentTrace(title: "Throwing trace")) + } + } + try body(range) + done = true + } + } +} + +/// Utility function for testing mutations with value semantics. +/// +/// Calls `body` with on given collection value, while optionally keeping +/// hidden a hidden copy of it around. Once `body` returns, checks that the copy +/// remain unchanged. +/// +/// - Parameters: +/// - `enabled`: if `false`, then no copies are made -- the values are passed to `body` with no processing. +/// - `value`: The collection value that is being tested. +/// - `body`: A closure performing a mutation on `value`. +public func withHiddenCopies( + if enabled: Bool, + of value: inout S, + file: StaticString = #file, line: UInt = #line, + _ body: (inout S) throws -> R +) rethrows -> R where S.Element: Equatable { + guard enabled else { return try body(&value) } + let copy = value + let expected = Array(value) + let result = try body(&value) + expectEqualElements(copy, expected, file: file, line: line) + return result +} + +/// Utility function for testing mutations with value semantics. +/// +/// Calls `body` with on given collection value, while optionally keeping +/// hidden a hidden copy of it around. Once `body` returns, checks that the copy +/// remain unchanged. +/// +/// - Parameters: +/// - `enabled`: if `false`, then no copies are made -- the values are passed to `body` with no processing. +/// - `value`: The collection value that is being tested. +/// - `body`: A closure performing a mutation on `value`. +public func withHiddenCopies< + S: Sequence, + Key: Equatable, + Value: Equatable, + R +>( + if enabled: Bool, + of value: inout S, + file: StaticString = #file, line: UInt = #line, + _ body: (inout S) throws -> R +) rethrows -> R where S.Element == (key: Key, value: Value) { + guard enabled else { return try body(&value) } + let copy = value + let expected = Array(value) + let result = try body(&value) + expectEqualElements(copy, expected, file: file, line: line) + return result +} diff --git a/Sources/CollectionsTestSupport/AssertionContexts/TestContext.swift b/Sources/CollectionsTestSupport/AssertionContexts/TestContext.swift new file mode 100644 index 00000000..d12ab6db --- /dev/null +++ b/Sources/CollectionsTestSupport/AssertionContexts/TestContext.swift @@ -0,0 +1,259 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest + +public final class TestContext { + internal var _nextStateId = 0 + internal var _nextIndexId = 0 + + /// Stack of labels with associated source positions. + /// Useful for tracking failed cases in combinatorial tests. + internal var _trace: [Entry] = [] + + // FIXME: This ought to be a thread-local variable. + internal static var _current: TestContext? + + public init() {} +} + +extension TestContext { + public static var current: TestContext { + guard let current = _current else { + fatalError("There is no current test context") + } + return current + } + + public static func pushNew() -> TestContext { + let context = TestContext() + push(context) + return context + } + + public static func push(_ context: TestContext) { + precondition(_current == nil, "Can't nest test contexts") + _current = context + } + + public static func pop(_ context: TestContext) { + precondition(_current === context, "Can't pop mismatching context") + _current = nil + } +} + +extension TestContext { + /// An entry in the stack trace. Associates a user-specified label with its associated source position. + public struct Entry: Hashable, CustomStringConvertible { + let label: String + let file: StaticString + let line: UInt + + public init( + label: String, + file: StaticString = #file, + line: UInt = #line + ) { + self.label = label + self.file = file + self.line = line + } + + public var description: String { + "\(label) (\(file):\(line))" + } + + public static func ==(left: Self, right: Self) -> Bool { + left.label == right.label + && left.file.utf8Start == right.file.utf8Start + && left.file.utf8CodeUnitCount == right.file.utf8CodeUnitCount + && left.line == right.line + } + + public func hash(into hasher: inout Hasher) { + hasher.combine(label) + hasher.combine(file.utf8Start) + hasher.combine(file.utf8CodeUnitCount) + hasher.combine(line) + } + } +} + +extension TestContext: Equatable { + public static func ==(left: TestContext, right: TestContext) -> Bool { + return left === right + } +} + +extension TestContext { + internal func nextStateId() -> Int { + defer { _nextStateId += 1 } + return _nextStateId + } + + internal func nextIndexId() -> Int { + defer { _nextIndexId += 1 } + return _nextIndexId + } +} + +extension TestContext { + /// Add the specified trace to the test context trace stack. + /// This call must be paired with a `pop` call with the same value, + /// with no intervening unpopped pushes. + @discardableResult + public func push(_ entry: Entry) -> Entry { + _trace.append(entry) + return entry + } + + /// Add the specified label to the test context trace stack. + /// This call must be paired with a `pop` call with the same value, + /// with no intervening unpopped pushes. + @discardableResult + public func push( + _ label: String, + file: StaticString = #file, + line: UInt = #line + ) -> Entry { + return push(Entry(label: label, file: file, line: line)) + } + + /// Cancel the trace push that returned `trace` and pop the context trace back + /// to the state it was before the push. All pushes since the one that pushed `trace` + /// must have been popped at the time this is called. + public func pop(_ entry: Entry) { + let old = _trace.removeLast() + precondition( + old == entry, + """ + Push/pop pairing violation: top of stack doesn't match expectation. + expected: \(entry) + actual: \(old) + + """) + } + + /// Execute the supplied closure in a new nested trace entry `entry`. + /// Assertion failure messages within the closure will include the specified information to aid with debugging. + public func withTrace( + _ entry: Entry, + _ body: () throws -> R + ) rethrows -> R { + push(entry) + defer { pop(entry) } + return try body() + } + + /// Execute the supplied closure in a new nested trace entry. + /// Assertion failure messages within the closure will include the specified information to aid with debugging. + public func withTrace( + _ label: String, + file: StaticString = #file, + line: UInt = #line, + _ body: () throws -> R + ) rethrows -> R { + let entry = push(label, file: file, line: line) + defer { pop(entry) } + return try body() + } + + /// The current stack of tracing labels with their associated source positions. + public var currentTrace: [Entry] { _trace } + + /// Return a (multi-line) string describing the current trace stack. + /// This string can be used to identify a particular test context, + /// for use in `failIfTraceMatches`. + public func currentTrace( + _ message: String = "", + title: String = "Trace" + ) -> String { + guard !_trace.isEmpty else { + return """ + \(message) + \(title): (empty) + + """ + } + var result = """ + \(message) + \(title): + + """ + for trace in _trace { + result += " - \(trace.label)\n" + } + return result + } + + public static func currentTrace( + _ message: String = "", + title: String = "Trace" + ) -> String { + guard let context = _current else { return message } + return context.currentTrace(message, title: title) + } + + /// Set a breakpoint on this function to stop execution only when `failIfTraceMatches` + /// triggers a test failure. The alternative is to set up a "Test Failure" breakpoint, + /// but if you have lots of test failures, that one might trigger too many times. + @inline(never) + public func debuggerBreak( + _ message: String, + file: StaticString = #file, + line: UInt = #line + ) { + XCTFail(message, file: file, line: line) + } + + /// Call this function to emit a test failure when the current test trace matches + /// the (typically multi-line) string given. By setting a breakpoint on test failures + /// (or on the `debuggerBreak` method above), you can then pause execution to + /// debug the test in that particular context. + /// + /// The string you need to pass to this function can be copy and pasted from + /// the failure message of the `expect` family of assertion methods, or + /// it can be manually generated by calling `currentTrace()` during a debug + /// session. + /// + /// For example, here we trigger a test failure when `count` is 8 and `offset` is 3: + /// + /// func testFoo() { + /// withEvery("count", in: 0 ..< 100) { count in + /// withEvery("offset", in: 0 ... count) { offset in + /// failIfTraceMatches(""" + /// Trace: + /// - count: 8 + /// - offset: 3 + /// """) + /// deque.buggyMethod(...) + /// } + /// } + /// } + /// + public func failIfTraceMatches( + _ expectedTrace: String, + file: StaticString = #file, + line: UInt = #line + ) { + // Filter for lines that match the regex " *- " + let breakOnTrace: [String] = + expectedTrace.split(separator: "\n").compactMap { line in + guard let i = line.firstIndex(where: { $0 != " " }) else { return nil } + guard line[i...].starts(with: "- ") else { return nil } + return String(line[i...].dropFirst(2)) + } + let labels = _trace.map({ $0.label }) + if labels == breakOnTrace { + debuggerBreak(currentTrace(title: "Hit trace"), file: file, line: line) + } + } +} diff --git a/Sources/CollectionsTestSupport/ConformanceCheckers/CheckBidirectionalCollection.swift b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckBidirectionalCollection.swift new file mode 100644 index 00000000..5c14935d --- /dev/null +++ b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckBidirectionalCollection.swift @@ -0,0 +1,147 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +// FIXME: Port all of the collection validation tests from the Swift compiler codebase. + +import XCTest + +extension BidirectionalCollection { + func _indicesByIndexBefore() -> [Index] { + var result: [Index] = [] + var i = endIndex + while i != startIndex { + i = index(before: i) + result.append(i) + } + result.reverse() + return result + } + + func _indicesByFormIndexBefore() -> [Index] { + var result: [Index] = [] + var i = endIndex + while i != startIndex { + formIndex(before: &i) + result.append(i) + } + result.reverse() + return result + } +} + +public func checkBidirectionalCollection( + _ collection: C, + expectedContents: S, + file: StaticString = #file, + line: UInt = #line +) where C.Element: Equatable, S.Element == C.Element { + checkBidirectionalCollection( + collection, + expectedContents: expectedContents, + by: ==, + file: file, + line: line) +} + +public func checkBidirectionalCollection( + _ collection: C, + expectedContents: S, + by areEquivalent: (S.Element, S.Element) -> Bool, + file: StaticString = #file, + line: UInt = #line +) where S.Element == C.Element { + checkSequence( + { collection }, expectedContents: expectedContents, + by: areEquivalent, + file: file, line: line) + _checkCollection( + collection, expectedContents: expectedContents, + by: areEquivalent, + file: file, line: line) + _checkBidirectionalCollection( + collection, expectedContents: expectedContents, + by: areEquivalent, + file: file, line: line) +} + +public func _checkBidirectionalCollection( + _ collection: C, + expectedContents: S, + by areEquivalent: (S.Element, S.Element) -> Bool, + file: StaticString = #file, + line: UInt = #line +) where S.Element == C.Element { + let entry = TestContext.current.push("checkBidirectionalCollection", file: file, line: line) + defer { TestContext.current.pop(entry) } + + let expectedContents = Array(expectedContents) + + // Check that `index(before:)` and `formIndex(before:)` are consistent with `index(after:)`. + let indicesByIndexAfter = collection._indicesByIndexAfter() + let indicesByIndexBefore = collection._indicesByIndexBefore() + let indicesByFormIndexBefore = collection._indicesByFormIndexBefore() + expectEqual(indicesByIndexBefore, indicesByIndexAfter) + expectEqual(indicesByFormIndexBefore, indicesByIndexAfter) + + // Check contents using indexing. + let indexContents1 = indicesByIndexBefore.map { collection[$0] } + expectEquivalentElements( + indexContents1, expectedContents, + by: areEquivalent, + "\(expectedContents)") + let indexContents2 = indicesByFormIndexBefore.map { collection[$0] } + expectEquivalentElements( + indexContents2, expectedContents, + by: areEquivalent, + "\(expectedContents)") + + // Check the Indices associated type + if C.self != C.Indices.self { + checkBidirectionalCollection(collection.indices, expectedContents: indicesByIndexAfter) + } + + var allIndices = indicesByIndexAfter + allIndices.append(collection.endIndex) + + // Check `index(_,offsetBy:)` + for (startOffset, start) in allIndices.enumerated() { + for endOffset in 0 ..< allIndices.count { + let end = collection.index(start, offsetBy: endOffset - startOffset) + expectEqual(end, allIndices[endOffset]) + if endOffset < expectedContents.count { + expectEquivalent( + collection[end], expectedContents[endOffset], + by: areEquivalent) + } + } + } + + // Check `distance(from:to:)` + for i in allIndices.indices { + for j in allIndices.indices { + let d = collection.distance(from: allIndices[i], to: allIndices[j]) + expectEqual(d, j - i) + } + } + + // Check slicing. + for i in 0 ..< allIndices.count { + for j in i ..< allIndices.count { + let range = allIndices[i] ..< allIndices[j] + let slice = collection[range] + expectEqualElements(slice._indicesByIndexBefore(), allIndices[i ..< j]) + expectEqualElements(slice._indicesByFormIndexBefore(), allIndices[i ..< j]) + } + } +} diff --git a/Sources/CollectionsTestSupport/ConformanceCheckers/CheckCollection.swift b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckCollection.swift new file mode 100644 index 00000000..ab9eed1a --- /dev/null +++ b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckCollection.swift @@ -0,0 +1,270 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +// FIXME: Port all of the collection validation tests from the Swift compiler codebase. + +import XCTest + +// FIXME: Port the collection validation tests from the Swift compiler codebase. + +extension Sequence { + func _contentsByIterator() -> [Element] { + var result: [Element] = [] + var it = makeIterator() + while let item = it.next() { + result.append(item) + } + return result + } + + func _contentsByCopyContents(_ count: Int? = nil) -> [Element] { + var it: Iterator? + var result = Array( + unsafeUninitializedCapacity: count ?? self.underestimatedCount + ) { buffer, count in + (it, count) = self._copyContents(initializing: buffer) + } + while let next = it!.next() { + result.append(next) + } + return result + } +} + +extension Collection { + func _indicesByIndexAfter() -> [Index] { + var result: [Index] = [] + var i = startIndex + while i != endIndex { + result.append(i) + i = index(after: i) + } + return result + } + + func _indicesByFormIndexAfter() -> [Index] { + var result: [Index] = [] + var i = startIndex + while i != endIndex { + result.append(i) + formIndex(after: &i) + } + return result + } +} + +public func checkCollection( + _ collection: C, + expectedContents: Expected, + file: StaticString = #file, + line: UInt = #line +) where C.Element: Equatable, Expected.Element == C.Element { + let expectedContents = Array(expectedContents) + + checkCollection( + collection, + expectedContents: expectedContents, + by: ==, + file: file, line: line) + + let indicesByIndexAfter = collection._indicesByIndexAfter() + for item in expectedContents { + if let first = collection._customIndexOfEquatableElement(item) { + expectNotNil(first) { first in + expectEqual(collection[first], item) + let expected = expectedContents.firstIndex(of: item)! + expectEqual(first, indicesByIndexAfter[expected]) + } + } + if let last = collection._customLastIndexOfEquatableElement(item) { + expectNotNil(last) { last in + expectEqual(collection[last], item) + let expected = expectedContents.lastIndex(of: item)! + expectEqual(last, indicesByIndexAfter[expected]) + } + } + } +} + +public func checkCollection( + _ collection: C, + expectedContents: Expected, + by areEquivalent: (C.Element, C.Element) -> Bool, + file: StaticString = #file, + line: UInt = #line +) where Expected.Element == C.Element { + checkSequence( + { collection }, + expectedContents: expectedContents, + by: areEquivalent, + file: file, line: line) + _checkCollection( + collection, + expectedContents: expectedContents, + by: areEquivalent, + file: file, line: line) +} + +public func _checkCollection( + _ collection: C, + expectedContents: Expected, + by areEquivalent: (C.Element, C.Element) -> Bool, + file: StaticString = #file, + line: UInt = #line +) where Expected.Element == C.Element { + let entry = TestContext.current.push("checkCollection", file: file, line: line) + defer { TestContext.current.pop(entry) } + + let expectedContents = Array(expectedContents) + expectEqual(collection.isEmpty, expectedContents.isEmpty) + expectEqual(collection.count, expectedContents.count) + + // Check that `index(after:)` produces the same results as `formIndex(after:)` + let indicesByIndexAfter = collection._indicesByIndexAfter() + let indicesByFormIndexAfter = collection._indicesByFormIndexAfter() + expectEqual(indicesByIndexAfter, indicesByFormIndexAfter) + + // Check contents using the iterator. + expectEquivalentElements( + collection._contentsByIterator(), + expectedContents, + by: areEquivalent) + + // Check _copyContents. + expectEquivalentElements( + collection._contentsByCopyContents(), + expectedContents, + by: areEquivalent) + + // Check contents using indexing. + let indexContents1 = indicesByIndexAfter.map { collection[$0] } + expectEquivalentElements(indexContents1, expectedContents, by: areEquivalent) + let indexContents2 = indicesByFormIndexAfter.map { collection[$0] } + expectEquivalentElements(indexContents2, expectedContents, by: areEquivalent) + + // Check the endIndex. + expectEqual(collection.endIndex, collection.indices.endIndex) + + // Check the Indices associated type + if C.self != C.Indices.self { + checkCollection(collection.indices, expectedContents: indicesByIndexAfter) + } else { + expectEqual(collection.indices.count, collection.count) + expectEqualElements(collection.indices, indicesByIndexAfter) + } + expectEqual(collection.indices.endIndex, collection.endIndex) + + // The sequence of indices must be monotonically increasing. + var allIndices = indicesByIndexAfter + allIndices.append(collection.endIndex) + checkComparable(allIndices, oracle: { .comparing($0, $1) }) + + // Check `index(_,offsetBy:)` + for (offset, start) in allIndices.enumerated() { + for distance in 0 ... indicesByIndexAfter.count - offset { + let end = collection.index(start, offsetBy: distance) + expectEqual(end, allIndices[offset + distance]) + if offset + distance < expectedContents.count { + expectEquivalent(collection[end], expectedContents[offset + distance], + by: areEquivalent) + } + } + } + + // Check `index(_,offsetBy:limitedBy:)` + let limits = + Set([0, allIndices.count - 1, allIndices.count / 2]) + .sorted() + withEvery("limit", in: limits) { limit in + withEvery("i", in: 0 ..< allIndices.count) { i in + let max = allIndices.count - i + (limit >= i ? 2 : 0) + withEvery("delta", in: 0 ..< max) { delta in + let actual = collection.index( + allIndices[i], + offsetBy: delta, + limitedBy: allIndices[limit]) + let j = i + delta + let expected = i > limit || j <= limit ? allIndices[j] : nil + expectEqual(actual, expected) + } + } + } + + // Check `distance(from:to:)` + withEvery("i", in: allIndices.indices) { i in + withEvery("j", in: allIndices.indices) { j in + let d = collection.distance(from: allIndices[i], to: allIndices[j]) + expectEqual(d, j - i) + } + } + + // Check slicing. + withEvery("i", in: 0 ..< allIndices.count) { i in + withEvery("j", in: i ..< allIndices.count) { j in + let range = allIndices[i] ..< allIndices[j] + let slice = collection[range] + expectEqual(slice.count, j - i) + expectEqual(slice.isEmpty, i == j) + expectEqual(slice.startIndex, allIndices[i]) + expectEqual(slice.endIndex, allIndices[j]) + expectEqual(slice.distance(from: allIndices[i], to: allIndices[j]), j - i) + expectEqual(slice.index(allIndices[i], offsetBy: j - i), allIndices[j]) + + expectEqual(slice.index(allIndices[i], offsetBy: j - i, limitedBy: allIndices[j]), + allIndices[j]) + expectEqual(slice.index(allIndices[i], offsetBy: j - i, limitedBy: allIndices[i]), + j - i > 0 ? nil : allIndices[i]) + expectEqual(slice.index(allIndices[i], offsetBy: j - i, limitedBy: allIndices[0]), + i > 0 || j == 0 ? allIndices[j] : nil) + + expectEquivalentElements(slice, expectedContents[i ..< j], + by: areEquivalent) + + expectEquivalentElements( + slice._contentsByIterator(), expectedContents[i ..< j], + by: areEquivalent) + expectEquivalentElements( + slice._contentsByCopyContents(), expectedContents[i ..< j], + by: areEquivalent) + + // Check _copyContents. + let copyContents = collection._contentsByCopyContents() + expectEquivalentElements( + copyContents, expectedContents, + by: areEquivalent) + + expectEqualElements(slice._indicesByIndexAfter(), allIndices[i ..< j]) + expectEqualElements(slice._indicesByFormIndexAfter(), allIndices[i ..< j]) + expectEqualElements(slice.indices, allIndices[i ..< j]) + expectEqualElements(slice.indices._indicesByIndexAfter(), allIndices[i ..< j]) + expectEqualElements(slice.indices._indicesByFormIndexAfter(), allIndices[i ..< j]) + // Check the subsequence iterator. + expectEquivalentElements( + slice, expectedContents[i ..< j], + by: areEquivalent) + // Check the subsequence subscript. + expectEquivalentElements( + allIndices[i ..< j].map { slice[$0] }, expectedContents[i ..< j], + by: areEquivalent) + // Check _copyToContiguousArray. + expectEquivalentElements( + Array(slice), expectedContents[i ..< j], + by: areEquivalent) + // Check slicing of slices. + expectEquivalentElements( + slice[range], expectedContents[i ..< j], + by: areEquivalent) + } + } +} diff --git a/Sources/CollectionsTestSupport/ConformanceCheckers/CheckComparable.swift b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckComparable.swift new file mode 100644 index 00000000..5067b35e --- /dev/null +++ b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckComparable.swift @@ -0,0 +1,176 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibUnittest + +public enum ExpectedComparisonResult: Hashable { + case lt, eq, gt + + public func flip() -> ExpectedComparisonResult { + switch self { + case .lt: + return .gt + case .eq: + return .eq + case .gt: + return .lt + } + } + + public static func comparing(_ left: C, _ right: C) -> Self { + left < right ? .lt + : left > right ? .gt + : .eq + } +} + +extension ExpectedComparisonResult: CustomStringConvertible { + public var description: String { + switch self { + case .lt: + return "<" + case .eq: + return "==" + case .gt: + return ">" + } + } +} + +public func checkComparable( + sortedEquivalenceClasses: [[Instance]], + file: StaticString = #file, line: UInt = #line +) { + let instances = sortedEquivalenceClasses.flatMap { $0 } + // oracle[i] is the index of the equivalence class that contains instances[i]. + let oracle = sortedEquivalenceClasses.indices.flatMap { i in repeatElement(i, count: sortedEquivalenceClasses[i].count) } + checkComparable( + instances, + oracle: { + if oracle[$0] < oracle[$1] { return .lt } + if oracle[$0] > oracle[$1] { return .gt } + return .eq + }, + file: file, line: line) +} + +/// Test that the elements of `instances` satisfy the semantic +/// requirements of `Comparable`, using `oracle` to generate comparison +/// expectations from pairs of positions in `instances`. +public func checkComparable( + _ instances: Instances, + oracle: (Instances.Index, Instances.Index) -> ExpectedComparisonResult, + file: StaticString = #file, line: UInt = #line +) where Instances.Element: Comparable { + checkEquatable(instances, + oracle: { oracle($0, $1) == .eq }, + file: file, line: line) + _checkComparable(instances, oracle: oracle, file: file, line: line) +} + +public func checkComparable( + expected: ExpectedComparisonResult, _ lhs: T, _ rhs: T, + file: StaticString = #file, line: UInt = #line +) { + checkComparable( + [lhs, rhs], + oracle: { [[ .eq, expected], [ expected.flip(), .eq]][$0][$1] }, + file: file, line: line) +} + +/// Same as `checkComparable(_:oracle:file:line:)` but doesn't check +/// `Equatable` conformance. Useful for preventing duplicate testing. +public func _checkComparable( + _ instances: Instances, + oracle: (Instances.Index, Instances.Index) -> ExpectedComparisonResult, + file: StaticString = #file, line: UInt = #line +) where Instances.Element: Comparable { + let entry = TestContext.current.push("checkComparable", file: file, line: line) + defer { TestContext.current.pop(entry) } + for i in instances.indices { + let x = instances[i] + + expectFalse( + x < x, + "found 'x < x' at index \(i): \(String(reflecting: x))") + + expectFalse( + x > x, + "found 'x > x' at index \(i): \(String(reflecting: x))") + + expectTrue(x <= x, + "found 'x <= x' to be false at index \(i): \(String(reflecting: x))") + + expectTrue(x >= x, + "found 'x >= x' to be false at index \(i): \(String(reflecting: x))") + + for j in instances.indices where i != j { + let y = instances[j] + + let expected = oracle(i, j) + + expectEqual( + expected.flip(), oracle(j, i), + """ + bad oracle: missing antisymmetry: + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + expectEqual( + expected == .lt, x < y, + """ + x < y doesn't match oracle + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + expectEqual( + expected != .gt, x <= y, + """ + x <= y doesn't match oracle + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + expectEqual( + expected != .lt, x >= y, + """ + x >= y doesn't match oracle + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + expectEqual( + expected == .gt, x > y, + """ + x > y doesn't match oracle + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + for k in instances.indices { + let expected2 = oracle(j, k) + if expected == expected2 { + expectEqual( + expected, oracle(i, k), + """ + bad oracle: transitivity violation + x (at index \(i)): \(String(reflecting: x)) + y (at index \(j)): \(String(reflecting: y)) + z (at index \(k)): \(String(reflecting: instances[k])) + """) + } + } + } + } +} diff --git a/Sources/CollectionsTestSupport/ConformanceCheckers/CheckEquatable.swift b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckEquatable.swift new file mode 100644 index 00000000..1b58b2e6 --- /dev/null +++ b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckEquatable.swift @@ -0,0 +1,116 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibUnittest + +public func checkEquatable( + equivalenceClasses: [[Instance]], + file: StaticString = #file, + line: UInt = #line +) { + let instances = equivalenceClasses.flatMap { $0 } + let oracle = equivalenceClasses.indices.flatMap { i in repeatElement(i, count: equivalenceClasses[i].count) } + checkEquatable(instances, oracle: { oracle[$0] == oracle[$1] }, file: file, line: line) +} + +public func checkEquatable( + _ instances: C, + oracle: (C.Index, C.Index) -> Bool, + file: StaticString = #file, + line: UInt = #line +) where C.Element: Equatable { + let indices = Array(instances.indices) + checkEquatable( + Array(instances), + oracle: { oracle(indices[$0], indices[$1]) }, + file: file, line: line) +} + +public func checkEquatable( + expectedEqual: Bool, _ lhs: T, _ rhs: T, + file: StaticString = #file, line: UInt = #line +) { + checkEquatable( + [lhs, rhs], + oracle: { expectedEqual || $0 == $1 }, + file: file, line: line) +} + +public func checkEquatable( + _ instances: [Instance], + oracle: (Int, Int) -> Bool, + file: StaticString = #file, + line: UInt = #line +) { + let entry = TestContext.current.push("checkEquatable", file: file, line: line) + defer { TestContext.current.pop(entry) } + // For each index (which corresponds to an instance being tested) track the + // set of equal instances. + var transitivityScoreboard: [Box>] = instances.map { _ in Box([]) } + + for i in instances.indices { + let x = instances[i] + expectTrue(oracle(i, i), + "bad oracle: broken reflexivity at index \(i)") + + for j in instances.indices { + let y = instances[j] + + let expectedXY = oracle(i, j) + expectEqual(oracle(j, i), expectedXY, + "bad oracle: broken symmetry between indices \(i), \(j)") + + let actualXY = (x == y) + expectEqual( + actualXY, expectedXY, + """ + Elements \((expectedXY + ? "expected equal, found not equal" + : "expected not equal, found equal")): + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + // Not-equal is an inverse of equal. + expectNotEqual( + x != y, actualXY, + """ + `!=` returns the same result as `==`: + lhs (at index \(i)): \(String(reflecting: x)) + rhs (at index \(j)): \(String(reflecting: y)) + """) + + // Check transitivity of the predicate represented by the oracle. + // If we are adding the instance `j` into an equivalence set, check that + // it is equal to every other instance in the set. + if expectedXY && i < j && transitivityScoreboard[i].value.insert(j).inserted { + if transitivityScoreboard[i].value.count == 1 { + transitivityScoreboard[i].value.insert(i) + } + for k in transitivityScoreboard[i].value { + expectTrue( + oracle(j, k), + """ + bad oracle: transitivity violation + x (at index \(i)): \(String(reflecting: x)) + y (at index \(j)): \(String(reflecting: y)) + z (at index \(k)): \(String(reflecting: instances[k])) + """) + // No need to check equality between actual values, we will check + // them with the checks above. + } + precondition(transitivityScoreboard[j].value.isEmpty) + transitivityScoreboard[j] = transitivityScoreboard[i] + } + } + } +} diff --git a/Sources/CollectionsTestSupport/ConformanceCheckers/CheckHashable.swift b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckHashable.swift new file mode 100644 index 00000000..e6942c0d --- /dev/null +++ b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckHashable.swift @@ -0,0 +1,124 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibUnittest + +/// Produce an integer hash value for `value` by feeding it to a dedicated +/// `Hasher`. This is always done by calling the `hash(into:)` method. +/// If a non-nil `seed` is given, it is used to perturb the hasher state; +/// this is useful for resolving accidental hash collisions. +private func _hash(_ value: H, seed: Int? = nil) -> Int { + var hasher = Hasher() + if let seed = seed { + hasher.combine(seed) + } + hasher.combine(value) + return hasher.finalize() +} + +/// Test that the elements of `equivalenceClasses` consist of instances that +/// satisfy the semantic requirements of `Hashable`, with each group defining +/// a distinct equivalence class under `==`. +public func checkHashable( + equivalenceClasses: [[Instance]], + file: StaticString = #file, line: UInt = #line +) { + let instances = equivalenceClasses.flatMap { $0 } + // oracle[i] is the index of the equivalence class that contains instances[i]. + let oracle = equivalenceClasses.indices.flatMap { i in repeatElement(i, count: equivalenceClasses[i].count) } + checkHashable( + instances, + equalityOracle: { oracle[$0] == oracle[$1] }, + file: file, line: line) +} + +public func checkHashable( + expectedEqual: Bool, _ lhs: T, _ rhs: T, + file: StaticString = #file, line: UInt = #line +) { + checkHashable( + [lhs, rhs], equalityOracle: { expectedEqual || $0 == $1 }, file: file, line: line) +} + +/// Test that the elements of `instances` satisfy the semantic requirements of +/// `Hashable`, using `equalityOracle` to generate equality and hashing +/// expectations from pairs of positions in `instances`. +public func checkHashable( + _ instances: Instances, + equalityOracle: (Instances.Index, Instances.Index) -> Bool, + file: StaticString = #file, line: UInt = #line +) where Instances.Element: Hashable { + checkEquatable(instances, oracle: equalityOracle, file: file, line: line) + _checkHashable(instances, equalityOracle: equalityOracle, file: file, line: line) +} + +/// Same as `checkHashable(_:equalityOracle:file:line:)` but doesn't check +/// `Equatable` conformance. Useful for preventing duplicate testing. +public func _checkHashable( + _ instances: Instances, + equalityOracle: (Instances.Index, Instances.Index) -> Bool, + file: StaticString = #file, line: UInt = #line +) where Instances.Element: Hashable { + let entry = TestContext.current.push("checkHashable", file: file, line: line) + defer { TestContext.current.pop(entry) } + for i in instances.indices { + let x = instances[i] + for j in instances.indices { + let y = instances[j] + let expected = equalityOracle(i, j) + if expected { + expectEqual( + _hash(x), _hash(y), + """ + hash(into:) expected to match, found to differ: + lhs (at index \(i)): \(x) + rhs (at index \(j)): \(y) + """) + expectEqual( + x.hashValue, y.hashValue, + """ + hashValue expected to match, found to differ + lhs (at index \(i)): \(x) + rhs (at index \(j)): \(y) + """) + expectEqual( + x._rawHashValue(seed: 0), y._rawHashValue(seed: 0), + """ + _rawHashValue(seed:) expected to match, found to differ + lhs (at index \(i)): \(x) + rhs (at index \(j)): \(y) + """) + } else { + // Try a few different seeds; at least one of them should discriminate + // between the hashes. It is extremely unlikely this check will fail + // all ten attempts, unless the type's hash encoding is not unique, + // or unless the hash equality oracle is wrong. + expectTrue( + (0 ..< 10).contains { _hash(x, seed: $0) != _hash(y, seed: $0) }, + """ + hash(into:) expected to differ, found to match + lhs (at index \(i)): \(x) + rhs (at index \(j)): \(y) + """) + expectTrue( + (0 ..< 10).contains { i in + x._rawHashValue(seed: i) != y._rawHashValue(seed: i) + }, + """ + _rawHashValue(seed:) expected to differ, found to match + lhs (at index \(i)): \(x) + rhs (at index \(j)): \(y) + """) + } + } + } +} diff --git a/Sources/CollectionsTestSupport/ConformanceCheckers/CheckSequence.swift b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckSequence.swift new file mode 100644 index 00000000..b46cba71 --- /dev/null +++ b/Sources/CollectionsTestSupport/ConformanceCheckers/CheckSequence.swift @@ -0,0 +1,96 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +// FIXME: Port all of the collection validation tests from the Swift compiler codebase. + +import XCTest + +// FIXME: Port the collection validation tests from the Swift compiler codebase. + +public func checkSequence( + _ sequenceGenerator: () -> S, + expectedContents: Expected, + file: StaticString = #file, + line: UInt = #line +) where S.Element == Expected.Element, S.Element: Equatable { + checkSequence( + sequenceGenerator, + expectedContents: expectedContents, + by: ==, + file: file, + line: line) +} + +public func checkSequence( + _ sequenceGenerator: () -> S, + expectedContents: Expected, + by areEquivalent: (S.Element, S.Element) -> Bool, + file: StaticString = #file, + line: UInt = #line +) where S.Element == Expected.Element { + let entry = TestContext.current.push("checkSequence", file: file, line: line) + defer { TestContext.current.pop(entry) } + + let expectedContents = Array(expectedContents) + + do { + let seq = sequenceGenerator() + let underestimatedCount = seq.underestimatedCount + expectLessThanOrEqual(underestimatedCount, expectedContents.count) + expectGreaterThanOrEqual(underestimatedCount, 0) + } + + // Check contiguous storage. + do { + let seq = sequenceGenerator() + let r: Int? = seq.withContiguousStorageIfAvailable { buffer in + expectEquivalentElements(buffer, expectedContents, by: areEquivalent) + return 42 + } + expectTrue(r == 42 || r == nil) + } + + do { + let seq = sequenceGenerator() + var it = seq.makeIterator() + var i = 0 + while i < expectedContents.count { + expectEquivalent(it.next(), expectedContents[i], by: areEquivalent) + i += 1 + } + expectNil(it.next()) + expectNil(it.next()) + } + + do { + let seq = sequenceGenerator() + let underestimatedCount = seq.underestimatedCount + var state: (it: S.Iterator, count: Int)! + var array = Array( + unsafeUninitializedCapacity: underestimatedCount + ) { buffer, count in + state = seq._copyContents(initializing: buffer) + count = state.count + } + expectEqual(state.count, underestimatedCount) + expectEquivalentElements( + array, + expectedContents[.. { + internal var _core: _MinimalCollectionCore + + public let timesMakeIteratorCalled = ResettableValue(0) + public let timesUnderestimatedCountCalled = ResettableValue(0) + public let timesStartIndexCalled = ResettableValue(0) + public let timesEndIndexCalled = ResettableValue(0) + public let timesRangeChecksCalled = ResettableValue(0) + public let timesIndexAfterCalled = ResettableValue(0) + public let timesIndexBeforeCalled = ResettableValue(0) + public let timesSubscriptCalled = ResettableValue(0) + public let timesRangeSubscriptCalled = ResettableValue(0) + + public init( + _ elements: S, + context: TestContext = TestContext.current, + underestimatedCount: UnderestimatedCountBehavior = .value(0) + ) where S.Element == Element { + self._core = _MinimalCollectionCore(context: context, elements: elements, underestimatedCount: underestimatedCount) + } + + var _context: TestContext { + _core.context + } +} + +extension MinimalBidirectionalCollection: Sequence { + public typealias Iterator = MinimalIterator + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.increment() + return MinimalIterator(_core.elements) + } + + public var underestimatedCount: Int { + timesUnderestimatedCountCalled.increment() + return _core.underestimatedCount + } +} + +extension MinimalBidirectionalCollection: BidirectionalCollection { + public typealias Index = MinimalIndex + public typealias SubSequence = Slice + public typealias Indices = DefaultIndices + + public var startIndex: MinimalIndex { + timesStartIndexCalled.increment() + return _core.startIndex + } + + public var endIndex: MinimalIndex { + timesEndIndexCalled.increment() + return _core.endIndex + } + + public var isEmpty: Bool { + // Pretend this is implemented as `startIndex == endIndex`. + timesStartIndexCalled.increment() + timesEndIndexCalled.increment() + return _core.isEmpty + } + + public var count: Int { + // Pretend this is implemented by counting elements using `index(after:)`. + let result = _core.count + timesIndexAfterCalled.increment(by: result) + return result + } + + public func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(range, bounds: bounds) + } + + public func index(after i: MinimalIndex) -> MinimalIndex { + timesIndexAfterCalled.increment() + return _core.index(after: i) + } + + public func index(before i: MinimalIndex) -> MinimalIndex { + timesIndexBeforeCalled.increment() + return _core.index(before: i) + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) + -> Int { + // Pretend this is implemented by counting elements using `index(after:)`/`index(before:). + let result = _core.distance(from: start, to: end) + if result >= 0 { + timesIndexAfterCalled.increment(by: result) + } else { + timesIndexBeforeCalled.increment(by: -result) + } + return result + } + + public func index(_ i: Index, offsetBy n: Int) -> Index { + // Pretend this is implemented by iterating elements using `index(after:)`/`index(before:)`. + if n >= 0 { + timesIndexAfterCalled.increment(by: n) + } else { + timesIndexBeforeCalled.increment(by: -n) + } + return _core.index(i, offsetBy: n) + } + + public subscript(i: MinimalIndex) -> Element { + timesSubscriptCalled.increment() + return _core[i] + } + + public subscript(bounds: Range) -> SubSequence { + timesRangeSubscriptCalled.increment() + _core.assertValid(bounds) + return Slice(base: self, bounds: bounds) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalCollection.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalCollection.swift new file mode 100644 index 00000000..499397e7 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalCollection.swift @@ -0,0 +1,137 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +/// A minimal implementation of `Collection` with extra checks. +public struct MinimalCollection { + internal var _core: _MinimalCollectionCore + + public let timesMakeIteratorCalled = ResettableValue(0) + public let timesUnderestimatedCountCalled = ResettableValue(0) + public let timesStartIndexCalled = ResettableValue(0) + public let timesEndIndexCalled = ResettableValue(0) + public let timesRangeChecksCalled = ResettableValue(0) + public let timesIndexAfterCalled = ResettableValue(0) + public let timesSubscriptCalled = ResettableValue(0) + public let timesRangeSubscriptCalled = ResettableValue(0) + + public init( + _ elements: S, + context: TestContext = TestContext.current, + underestimatedCount: UnderestimatedCountBehavior = .value(0) + ) where S.Element == Element { + self._core = _MinimalCollectionCore(context: context, elements: elements, underestimatedCount: underestimatedCount) + } + + var _context: TestContext { + _core.context + } +} + +extension MinimalCollection: Sequence { + public typealias Iterator = MinimalIterator + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.increment() + return MinimalIterator(_core.elements) + } + + public var underestimatedCount: Int { + timesUnderestimatedCountCalled.increment() + return _core.underestimatedCount + } +} + +extension MinimalCollection: Collection { + public typealias Index = MinimalIndex + public typealias SubSequence = Slice + public typealias Indices = DefaultIndices + + public var startIndex: MinimalIndex { + timesStartIndexCalled.increment() + return _core.startIndex + } + + public var endIndex: MinimalIndex { + timesEndIndexCalled.increment() + return _core.endIndex + } + + public var isEmpty: Bool { + // Pretend this is implemented as `startIndex == endIndex`. + timesStartIndexCalled.increment() + timesEndIndexCalled.increment() + return _core.isEmpty + } + + public var count: Int { + // Pretend this is implemented by counting elements using `index(after:)`. + let result = _core.count + timesIndexAfterCalled.increment(by: result) + return result + } + + public func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(range, bounds: bounds) + } + + public func index(after i: MinimalIndex) -> MinimalIndex { + timesIndexAfterCalled.increment() + return _core.index(after: i) + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) + -> Int { + // Pretend this is implemented by counting elements using `index(after:)`. + expectTrue( + start <= end, + "Only BidirectionalCollections can have end come before start", + trapping: true) + let result = _core.distance(from: start, to: end) + timesIndexAfterCalled.increment(by: result) + return result + } + + public func index(_ i: Index, offsetBy n: Int) -> Index { + // Pretend this is implemented by iterating elements using `index(after:)`. + expectTrue( + n >= 0, + "Only BidirectionalCollections can be advanced by a negative amount", + trapping: true) + timesIndexAfterCalled.increment(by: n) + return _core.index(i, offsetBy: n) + } + + public subscript(i: MinimalIndex) -> Element { + timesSubscriptCalled.increment() + return _core[i] + } + + public subscript(bounds: Range) -> SubSequence { + timesRangeSubscriptCalled.increment() + _core.assertValid(bounds) + return Slice(base: self, bounds: bounds) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalDecoder.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalDecoder.swift new file mode 100644 index 00000000..11b7aa31 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalDecoder.swift @@ -0,0 +1,756 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +public class MinimalDecoder { + public typealias Value = MinimalEncoder.Value + typealias _Key = MinimalEncoder._Key + + public private(set) var userInfo: [CodingUserInfoKey: Any] + + public init(userInfo: [CodingUserInfoKey: Any] = [:]) { + self.userInfo = userInfo + } + + public func decode(_ input: Value, as type: T.Type) throws -> T { + let decoder = Decoder(base: self, parent: nil, input: input, key: nil) + defer { + decoder.finalize() + } + return try T(from: decoder) + } + + public static func decode(_ input: Value, as type: T.Type) throws -> T { + let decoder = MinimalDecoder() + return try decoder.decode(input, as: T.self) + } +} + +protocol _MinimalDecoderContainer: AnyObject { + var base: MinimalDecoder { get } + var parent: _MinimalDecoderContainer? { get } + var key: CodingKey? { get } + var isValid: Bool { get } + func finalize() +} + +extension _MinimalDecoderContainer { + var codingPath: [CodingKey] { + expectTrue(isValid, "Container isn't valid", trapping: true) + var path: [CodingKey] = [] + var encoder: _MinimalDecoderContainer? = self + while let e = encoder { + if let key = e.key { path.append(key) } + encoder = e.parent + } + path.reverse() + return path + } + + var userInfo: [CodingUserInfoKey: Any] { + expectTrue(isValid, "Container isn't valid", trapping: true) + return base.userInfo + } +} + +extension DecodingError { + internal static func _typeMismatch( + at path: [CodingKey], + expectation: Any.Type, + reality: MinimalDecoder.Value + ) -> DecodingError { + let description = "Expected to decode \(expectation) but found `\(reality.typeDescription))`." + return .typeMismatch(expectation, Context(codingPath: path, debugDescription: description)) + } +} + +extension MinimalDecoder { + final class Decoder { + typealias Value = MinimalEncoder.Value + + unowned let base: MinimalDecoder + unowned let parent: _MinimalDecoderContainer? + let key: CodingKey? + var input: Value + var isValid = true + var pendingContainer: _MinimalDecoderContainer? + + init(base: MinimalDecoder, parent: _MinimalDecoderContainer?, input: Value, key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + self.input = input + } + } +} + +extension MinimalDecoder.Decoder: _MinimalDecoderContainer { + func finalize() { + expectTrue(isValid, "Container isn't valid", trapping: true) + isValid = false + } +} + +extension MinimalDecoder.Decoder: Decoder { + func container(keyedBy type: Key.Type) throws -> KeyedDecodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(pendingContainer, "Cannot extract multiple containers", trapping: true) + guard case let .dictionary(d) = input else { + throw DecodingError._typeMismatch(at: codingPath, expectation: [String: Value].self, reality: input) + } + let keyed = MinimalDecoder.KeyedContainer(base: base, parent: parent, input: d, key: key) + pendingContainer = keyed + return .init(keyed) + } + + func unkeyedContainer() throws -> UnkeyedDecodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(pendingContainer, "Cannot extract multiple containers", trapping: true) + guard case let .array(a) = input else { + throw DecodingError._typeMismatch(at: codingPath, expectation: [Value].self, reality: input) + } + let unkeyed = MinimalDecoder.UnkeyedContainer(base: base, parent: parent, input: a, key: nil) + pendingContainer = unkeyed + return unkeyed + } + + func singleValueContainer() throws -> SingleValueDecodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(pendingContainer, "Cannot extract multiple containers", trapping: true) + let single = MinimalDecoder.SingleValueContainer(base: base, parent: parent, input: input, key: nil) + pendingContainer = single + return single + } +} + +extension MinimalDecoder { + final class KeyedContainer { + typealias Value = MinimalEncoder.Value + + unowned let base: MinimalDecoder + unowned let parent: _MinimalDecoderContainer? + let key: CodingKey? + var input: [String: Value] + var isValid = true + var pendingContainer: AnyObject? + + init(base: MinimalDecoder, parent: _MinimalDecoderContainer?, input: [String: Value], key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + self.input = input + } + + func commitPendingContainer() { + expectTrue(self.isValid, "Container isn't valid", trapping: true) + guard let c = pendingContainer else { return } + self.pendingContainer = nil + let container = c as! _MinimalDecoderContainer + container.finalize() + } + } +} + +extension MinimalDecoder.KeyedContainer: _MinimalDecoderContainer { + func finalize() { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + isValid = false + } +} + +extension MinimalDecoder.KeyedContainer: KeyedDecodingContainerProtocol { + var allKeys: [Key] { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + return input.keys.compactMap { Key(stringValue: $0) } + } + + func contains(_ key: Key) -> Bool { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + return input[key.stringValue] != nil + } + + func _decode(key: Key) throws -> Value { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + guard let value = input[key.stringValue] else { + let context = DecodingError.Context( + codingPath: codingPath + [key], + debugDescription: "Key not found (\"\(key.stringValue)\")") + throw DecodingError.keyNotFound(key, context) + } + return value + } + + func _decode(_ type: T.Type, forKey key: Key, _ extract: (Value) -> T?) throws -> T { + let value = try _decode(key: key) + guard let v = extract(value) else { + throw DecodingError._typeMismatch(at: codingPath + [key], expectation: T.self, reality: value) + } + return v + } + + func decodeNil(forKey key: Key) throws -> Bool { + let value = try _decode(key: key) + return value == .null + } + + func decode(_ type: Bool.Type, forKey key: Key) throws -> Bool { + try _decode(type, forKey: key) { input in + guard case let .bool(v) = input else { return nil } + return v + } + } + + func decode(_ type: Int.Type, forKey key: Key) throws -> Int { + try _decode(type, forKey: key) { input in + guard case let .int(v) = input else { return nil } + return v + } + } + + func decode(_ type: Int8.Type, forKey key: Key) throws -> Int8 { + try _decode(type, forKey: key) { input in + guard case let .int8(v) = input else { return nil } + return v + } + } + + func decode(_ type: Int16.Type, forKey key: Key) throws -> Int16 { + try _decode(type, forKey: key) { input in + guard case let .int16(v) = input else { return nil } + return v + } + } + + func decode(_ type: Int32.Type, forKey key: Key) throws -> Int32 { + try _decode(type, forKey: key) { input in + guard case let .int32(v) = input else { return nil } + return v + } + } + + func decode(_ type: Int64.Type, forKey key: Key) throws -> Int64 { + try _decode(type, forKey: key) { input in + guard case let .int64(v) = input else { return nil } + return v + } + } + + func decode(_ type: UInt.Type, forKey key: Key) throws -> UInt { + try _decode(type, forKey: key) { input in + guard case let .uint(v) = input else { return nil } + return v + } + } + + func decode(_ type: UInt8.Type, forKey key: Key) throws -> UInt8 { + try _decode(type, forKey: key) { input in + guard case let .uint8(v) = input else { return nil } + return v + } + } + + func decode(_ type: UInt16.Type, forKey key: Key) throws -> UInt16 { + try _decode(type, forKey: key) { input in + guard case let .uint16(v) = input else { return nil } + return v + } + } + + func decode(_ type: UInt32.Type, forKey key: Key) throws -> UInt32 { + try _decode(type, forKey: key) { input in + guard case let .uint32(v) = input else { return nil } + return v + } + } + + func decode(_ type: UInt64.Type, forKey key: Key) throws -> UInt64 { + try _decode(type, forKey: key) { input in + guard case let .uint64(v) = input else { return nil } + return v + } + } + + func decode(_ type: String.Type, forKey key: Key) throws -> String { + try _decode(type, forKey: key) { input in + guard case let .string(v) = input else { return nil } + return v + } + } + + func decode(_ type: Double.Type, forKey key: Key) throws -> Double { + try _decode(type, forKey: key) { input in + guard case let .double(v) = input else { return nil } + return v + } + } + + func decode(_ type: Float.Type, forKey key: Key) throws -> Float { + try _decode(type, forKey: key) { input in + guard case let .float(v) = input else { return nil } + return v + } + } + + func decode(_ type: T.Type, forKey key: Key) throws -> T { + let value = try _decode(key: key) + let decoder = MinimalDecoder.Decoder(base: base, parent: self, input: value, key: key) + pendingContainer = decoder + defer { + expectIdentical(pendingContainer, decoder, trapping: true) + commitPendingContainer() + } + return try T(from: decoder) + } + + func nestedContainer( + keyedBy type: NestedKey.Type, + forKey key: Key + ) throws -> KeyedDecodingContainer { + let value = try _decode(key: key) + guard case let .dictionary(v) = value else { + throw DecodingError._typeMismatch(at: codingPath + [key], + expectation: [String: Value].self, + reality: value) + } + let nested = MinimalDecoder.KeyedContainer(base: base, parent: self, input: v, key: key) + pendingContainer = nested + return .init(nested) + } + + func nestedUnkeyedContainer(forKey key: Key) throws -> UnkeyedDecodingContainer { + let value = try _decode(key: key) + guard case let .array(v) = value else { + throw DecodingError._typeMismatch(at: codingPath + [key], + expectation: [String: Value].self, + reality: value) + } + let nested = MinimalDecoder.UnkeyedContainer(base: base, parent: self, input: v, key: key) + pendingContainer = nested + return nested + } + + func superDecoder() throws -> Decoder { + let value = try _decode(key: MinimalDecoder._Key.super) + let nested = MinimalDecoder.Decoder(base: base, parent: self, input: value, key: key) + pendingContainer = nested + return nested + } + + func superDecoder(forKey key: Key) throws -> Decoder { + let value = try _decode(key: key) + let nested = MinimalDecoder.Decoder(base: base, parent: self, input: value, key: key) + pendingContainer = nested + return nested + } +} + +extension MinimalDecoder { + class UnkeyedContainer { + typealias Value = MinimalEncoder.Value + + unowned let base: MinimalDecoder + unowned let parent: _MinimalDecoderContainer? + let key: CodingKey? + var input: [Value] + var isValid = true + var pendingContainer: AnyObject? + var index: Int = 0 + + init(base: MinimalDecoder, parent: _MinimalDecoderContainer?, input: [Value], key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + self.input = input + } + + func commitPendingContainer() { + expectTrue(self.isValid, "Container isn't valid", trapping: true) + guard let c = pendingContainer else { return } + self.pendingContainer = nil + let container = c as! _MinimalDecoderContainer + container.finalize() + } + } +} + +extension MinimalDecoder.UnkeyedContainer: _MinimalDecoderContainer { + func finalize() { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + isValid = false + } +} + +extension MinimalDecoder.UnkeyedContainer: UnkeyedDecodingContainer { + typealias _Key = MinimalDecoder._Key + + var count: Int? { + expectTrue(isValid, "Container isn't valid", trapping: true) + return input.count + } + + var isAtEnd: Bool { + expectTrue(isValid, "Container isn't valid", trapping: true) + return index == input.count + } + + var currentIndex: Int { + expectTrue(isValid, "Container isn't valid", trapping: true) + return index + } + + func _decodeNext(_ type: T.Type) throws -> Value { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + guard index < input.count else { + let context = DecodingError.Context( + codingPath: codingPath + [_Key(index)], + debugDescription: "Unkeyed container is at end") + throw DecodingError.valueNotFound(T.self, context) + } + let value = input[index] + index += 1 + return value + } + + func _decodeNext(_ type: T.Type = T.self, _ extract: (Value) -> T?) throws -> T { + let value = try _decodeNext(type) + guard let v = extract(value) else { + throw DecodingError._typeMismatch(at: codingPath + [_Key(index - 1)], + expectation: T.self, + reality: value) + } + return v + } + + + func decodeNil() throws -> Bool { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + guard index < input.count else { + let context = DecodingError.Context( + codingPath: codingPath + [_Key(index)], + debugDescription: "Unkeyed container is at end") + throw DecodingError.valueNotFound(Any?.self, context) + } + let value = input[index] + guard value == .null else { return false } + index += 1 + return true + } + + func decode(_ type: Bool.Type) throws -> Bool { + try _decodeNext() { value in + guard case let .bool(v) = value else { return nil } + return v + } + } + + func decode(_ type: Float.Type) throws -> Float { + try _decodeNext() { value in + guard case let .float(v) = value else { return nil } + return v + } + } + + func decode(_ type: Double.Type) throws -> Double { + try _decodeNext() { value in + guard case let .double(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int.Type) throws -> Int { + try _decodeNext() { value in + guard case let .int(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int8.Type) throws -> Int8 { + try _decodeNext() { value in + guard case let .int8(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int16.Type) throws -> Int16 { + try _decodeNext() { value in + guard case let .int16(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int32.Type) throws -> Int32 { + try _decodeNext() { value in + guard case let .int32(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int64.Type) throws -> Int64 { + try _decodeNext() { value in + guard case let .int64(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt.Type) throws -> UInt { + try _decodeNext() { value in + guard case let .uint(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt8.Type) throws -> UInt8 { + try _decodeNext() { value in + guard case let .uint8(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt16.Type) throws -> UInt16 { + try _decodeNext() { value in + guard case let .uint16(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt32.Type) throws -> UInt32 { + try _decodeNext() { value in + guard case let .uint32(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt64.Type) throws -> UInt64 { + try _decodeNext() { value in + guard case let .uint64(v) = value else { return nil } + return v + } + } + + func decode(_ type: String.Type) throws -> String { + try _decodeNext() { value in + guard case let .string(v) = value else { return nil } + return v + } + } + + func decode(_ type: T.Type) throws -> T { + let key = _Key(index) + let value = try _decodeNext(T.self) + let decoder = MinimalDecoder.Decoder(base: base, parent: self, input: value, key: key) + pendingContainer = decoder + defer { + expectIdentical(pendingContainer, decoder, trapping: true) + commitPendingContainer() + } + return try T(from: decoder) + } + + func nestedContainer( + keyedBy type: NestedKey.Type + ) throws -> KeyedDecodingContainer { + let key = _Key(index) + let value = try _decodeNext([String: Value].self) + guard case let .dictionary(v) = value else { + throw DecodingError._typeMismatch(at: codingPath + [key], + expectation: [String: Value].self, + reality: value) + } + let nested = MinimalDecoder.KeyedContainer(base: base, parent: parent, input: v, key: key) + pendingContainer = nested + return .init(nested) + } + + func nestedUnkeyedContainer() throws -> UnkeyedDecodingContainer { + let key = _Key(index) + let value = try _decodeNext([Value].self) + guard case let .array(v) = value else { + throw DecodingError._typeMismatch(at: codingPath + [key], + expectation: [Value].self, + reality: value) + } + let nested = MinimalDecoder.UnkeyedContainer(base: base, parent: parent, input: v, key: key) + pendingContainer = nested + return nested + } + + func superDecoder() throws -> Decoder { + let key = _Key(index) + let value = try _decodeNext(Any.self) + let nested = MinimalDecoder.Decoder(base: base, parent: self, input: value, key: key) + pendingContainer = nested + return nested + } +} + +extension MinimalDecoder { + class SingleValueContainer { + typealias Value = MinimalEncoder.Value + + unowned let base: MinimalDecoder + unowned let parent: _MinimalDecoderContainer? + let key: CodingKey? + var input: Value + var isValid = true + var done = false + + init(base: MinimalDecoder, parent: _MinimalDecoderContainer?, input: Value, key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + self.input = input + } + } +} + +extension MinimalDecoder.SingleValueContainer: _MinimalDecoderContainer { + func finalize() { + expectTrue(isValid, "Container isn't valid") + isValid = false + } +} + +extension MinimalDecoder.SingleValueContainer: SingleValueDecodingContainer { + func _decodeNext(_ type: T.Type = T.self, _ extract: (Value) -> T?) throws -> T { + expectTrue(isValid, "Container isn't valid") + expectFalse(done, "Cannot decode multiple values from a single-value container") + guard let v = extract(input) else { + throw DecodingError._typeMismatch(at: codingPath, + expectation: T.self, + reality: input) + } + done = true + return v + } + + func decodeNil() -> Bool { + expectTrue(isValid, "Container isn't valid") + expectFalse(done, "Cannot decode multiple values from a single-value container") + guard input == .null else { return false } + done = true + return true + } + + func decode(_ type: Bool.Type) throws -> Bool { + try _decodeNext { value in + guard case let .bool(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int.Type) throws -> Int { + try _decodeNext { value in + guard case let .int(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int8.Type) throws -> Int8 { + try _decodeNext { value in + guard case let .int8(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int16.Type) throws -> Int16 { + try _decodeNext { value in + guard case let .int16(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int32.Type) throws -> Int32 { + try _decodeNext { value in + guard case let .int32(v) = value else { return nil } + return v + } + } + + func decode(_ type: Int64.Type) throws -> Int64 { + try _decodeNext { value in + guard case let .int64(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt.Type) throws -> UInt { + try _decodeNext { value in + guard case let .uint(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt8.Type) throws -> UInt8 { + try _decodeNext { value in + guard case let .uint8(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt16.Type) throws -> UInt16 { + try _decodeNext { value in + guard case let .uint16(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt32.Type) throws -> UInt32 { + try _decodeNext { value in + guard case let .uint32(v) = value else { return nil } + return v + } + } + + func decode(_ type: UInt64.Type) throws -> UInt64 { + try _decodeNext { value in + guard case let .uint64(v) = value else { return nil } + return v + } + } + + func decode(_ type: Float.Type) throws -> Float { + try _decodeNext { value in + guard case let .float(v) = value else { return nil } + return v + } + } + + func decode(_ type: Double.Type) throws -> Double { + try _decodeNext { value in + guard case let .double(v) = value else { return nil } + return v + } + } + + func decode(_ type: String.Type) throws -> String { + try _decodeNext { value in + guard case let .string(v) = value else { return nil } + return v + } + } + + func decode(_ type: T.Type) throws -> T { + expectTrue(isValid, "Container isn't valid") + expectFalse(done, "Cannot decode multiple values from a single-value container") + let decoder = MinimalDecoder.Decoder(base: base, parent: self, input: input, key: nil) + defer { + done = true + decoder.finalize() + } + return try T(from: decoder) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalEncoder.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalEncoder.swift new file mode 100644 index 00000000..d48061a6 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalEncoder.swift @@ -0,0 +1,716 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// A Plist-style encoder that attempts to enforce a strict interpretation of +/// the `Encodable` protocol requirements. The encoded value is of an enum type +/// that exactly reflects the values encoded, allowing easy matching of +/// actual vs expected outputs. +/// +/// This encoder verifies that `encoder(to:)` implementations do not keep +/// containers alive beyond their expected lifetime. +/// +/// FIXME: Fix error reporting. We ought to throw errors instead of trapping +/// on validation problems, and we should include context information to help +/// isolating the problem. +public class MinimalEncoder { + public enum Value: Hashable { + case null + case bool(Bool) + case int(Int) + case int8(Int8) + case int16(Int16) + case int32(Int32) + case int64(Int64) + case uint(UInt) + case uint8(UInt8) + case uint16(UInt16) + case uint32(UInt32) + case uint64(UInt64) + case float(Float) + case double(Double) + case string(String) + case array([Value]) + case dictionary([String: Value]) + } + + var userInfo: [CodingUserInfoKey: Any] + + public init(userInfo: [CodingUserInfoKey: Any] = [:]) { + self.userInfo = userInfo + } + + public func encode(_ value: T) throws -> Value { + let encoder = Encoder(base: self, parent: nil, key: nil) + return try encoder._encode(value, key: nil) + } + + public static func encode(_ value: T) throws -> Value { + let base = MinimalEncoder() + return try base.encode(value) + } +} + +extension MinimalEncoder { + struct _Key: CodingKey { + var stringValue: String + var intValue: Int? + + static let `super` = Self("super") + + init(_ string: String) { + self.stringValue = string + self.intValue = nil + } + + init(_ index: Int) { + self.stringValue = "Index \(index)" + self.intValue = index + } + + init?(stringValue: String) { + self.init(stringValue) + } + + init?(intValue: Int) { + self.init(intValue) + } + } +} + +extension MinimalEncoder.Value: CustomStringConvertible { + func _description(prefix: String, indent: String) -> String { + switch self { + case .null: return ".null" + case .bool(let v): return ".bool(\(v))" + case .int(let v): return ".int(\(v))" + case .int8(let v): return ".int8(\(v))" + case .int16(let v): return ".int16(\(v))" + case .int32(let v): return ".int32(\(v))" + case .int64(let v): return ".int64(\(v))" + case .uint(let v): return ".uint(\(v))" + case .uint8(let v): return ".uint8(\(v))" + case .uint16(let v): return ".uint16(\(v))" + case .uint32(let v): return ".uint32(\(v))" + case .uint64(let v): return ".uint64(\(v))" + case .float(let v): return ".float(\(v))" + case .double(let v): return ".double(\(v))" + case .string(let v): return ".string(\(String(reflecting: v)))" + case .array(let value): + if value.count == 0 { return ".array([])" } + var result = ".array([\n" + for v in value { + result += prefix + result += indent + result += v._description(prefix: prefix + indent, indent: indent) + result += ",\n" + } + result += prefix + "])" + return result + case .dictionary(let value): + if value.count == 0 { return ".dictionary([:])" } + var result = ".dictionary([\n" + for (k, v) in value.sorted(by: { $0.key < $1.key }) { + result += prefix + result += indent + result += String(reflecting: k) + result += ": " + result += v._description(prefix: prefix + indent, indent: indent) + result += ",\n" + } + result += prefix + "])" + return result + } + } + + public var description: String { + self._description(prefix: "", indent: " ") + } +} + +extension MinimalDecoder.Value { + public var typeDescription: String { + switch self { + case .null: return ".null" + case .bool(_): return ".bool" + case .int(_): return ".int" + case .int8(_): return ".int8" + case .int16(_): return ".int16" + case .int32(_): return ".int32" + case .int64(_): return ".int64" + case .uint(_): return ".uint" + case .uint8(_): return ".uint8" + case .uint16(_): return ".uint16" + case .uint32(_): return ".uint32" + case .uint64(_): return ".uint64" + case .float(_): return ".float" + case .double(_): return ".double" + case .string(_): return ".string" + case .array(_): return ".array" + case .dictionary(_): return ".dictionary" + } + } +} + +protocol _MinimalEncoderContainer: AnyObject { + var base: MinimalEncoder { get } + var parent: _MinimalEncoderContainer? { get } + var key: CodingKey? { get } + var isValid: Bool { get } + func finalize() -> MinimalEncoder.Value? +} + +extension _MinimalEncoderContainer { + var codingPath: [CodingKey] { + expectTrue(isValid, "Container isn't valid", trapping: true) + var path: [CodingKey] = [] + var encoder: _MinimalEncoderContainer? = self + while let e = encoder { + if let key = e.key { path.append(key) } + encoder = e.parent + } + path.reverse() + return path + } + + func _encode(_ value: T, key: CodingKey?) throws -> MinimalEncoder.Value { + expectTrue(isValid, "Container isn't valid", trapping: true) + var encoder = MinimalEncoder.Encoder(base: base, parent: self, key: key) + try value.encode(to: encoder) + expectTrue(isKnownUniquelyReferenced(&encoder), "\(T.self).encode(to:) retained its encoder", trapping: true) + guard let result = encoder.finalize() else { + preconditionFailure("\(T.self).encode(to:) failed to encode anything") + } + return result + } +} + +extension MinimalEncoder { + final class Encoder { + unowned let base: MinimalEncoder + unowned let parent: _MinimalEncoderContainer? + let key: CodingKey? + var container: _MinimalEncoderContainer? + var isValid = true + + init(base: MinimalEncoder, parent: _MinimalEncoderContainer?, key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + } + } +} + +extension MinimalEncoder.Encoder: _MinimalEncoderContainer { + func finalize() -> MinimalEncoder.Value? { + expectTrue(isValid, "Container isn't valid", trapping: true) + let value = container?.finalize() + isValid = false + return value + } +} + +extension MinimalEncoder.Encoder: Encoder { + var userInfo: [CodingUserInfoKey: Any] { base.userInfo } + + func container( + keyedBy type: Key.Type + ) -> KeyedEncodingContainer { + expectTrue(isValid, "Encoder isn't valid", trapping: true) + expectNil(container, "Cannot extract multiple containers", trapping: true) + let keyed = MinimalEncoder.KeyedContainer(base: base, parent: self, key: nil) + self.container = keyed + return .init(keyed) + } + + func unkeyedContainer() -> UnkeyedEncodingContainer { + expectTrue(isValid, "Encoder isn't valid", trapping: true) + expectNil(container, "Cannot extract multiple containers", trapping: true) + let unkeyed = MinimalEncoder.UnkeyedContainer(base: base, parent: self, key: nil) + self.container = unkeyed + return unkeyed + } + + func singleValueContainer() -> SingleValueEncodingContainer { + expectTrue(isValid, "Encoder isn't valid", trapping: true) + expectNil(container, "Cannot extract multiple containers", trapping: true) + let single = MinimalEncoder.SingleValueContainer(base: base, parent: self, key: nil) + self.container = single + return single + } +} + + +extension MinimalEncoder { + final class KeyedContainer { + unowned let base: MinimalEncoder + unowned let parent: _MinimalEncoderContainer? + var key: CodingKey? + var values: [String: Value] = [:] + var isValid = true + var pendingContainer: AnyObject? + + init(base: MinimalEncoder, parent: _MinimalEncoderContainer?, key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + } + + func commitPendingContainer() { + expectTrue(self.isValid, "Container isn't valid", trapping: true) + guard var c = pendingContainer else { return } + self.pendingContainer = nil + expectTrue(isKnownUniquelyReferenced(&c), "Container was retained", trapping: true) + let container = c as! _MinimalEncoderContainer + let key = container.key! + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + guard let v = container.finalize() else { preconditionFailure("Container remained empty")} + values[key.stringValue] = v + } + } +} + +extension MinimalEncoder.KeyedContainer: _MinimalEncoderContainer { + func finalize() -> MinimalEncoder.Value? { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + isValid = false + return .dictionary(values) + } +} + +extension MinimalEncoder.KeyedContainer: KeyedEncodingContainerProtocol { + + func encodeNil(forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .null + } + func encode(_ value: Bool, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .bool(value) + } + func encode(_ value: Int, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .int(value) + } + func encode(_ value: Int8, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .int8(value) + } + func encode(_ value: Int16, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .int16(value) + } + func encode(_ value: Int32, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .int32(value) + } + func encode(_ value: Int64, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .int64(value) + } + func encode(_ value: UInt, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .uint(value) + } + func encode(_ value: UInt8, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .uint8(value) + } + func encode(_ value: UInt16, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .uint16(value) + } + func encode(_ value: UInt32, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .uint32(value) + } + func encode(_ value: UInt64, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .uint64(value) + } + func encode(_ value: Float, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .float(value) + } + func encode(_ value: Double, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .double(value) + } + func encode(_ value: String, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = .string(value) + } + func encode(_ value: T, forKey key: Key) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + values[key.stringValue] = try _encode(value, key: key) + } + func nestedContainer( + keyedBy keyType: NestedKey.Type, + forKey key: Key + ) -> KeyedEncodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + let keyed = MinimalEncoder.KeyedContainer(base: base, parent: self, key: key) + pendingContainer = keyed + return .init(keyed) + } + + func nestedUnkeyedContainer(forKey key: Key) -> UnkeyedEncodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key.stringValue) has already been encoded", trapping: true) + let unkeyed = MinimalEncoder.UnkeyedContainer(base: base, parent: self, key: key) + pendingContainer = unkeyed + return unkeyed + } + + func superEncoder() -> Encoder { + let key = MinimalEncoder._Key.super + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key) has already been encoded", trapping: true) + let sup = MinimalEncoder.Encoder(base: base, parent: self, key: key) + pendingContainer = sup + return sup + } + + func superEncoder(forKey key: Key) -> Encoder { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + expectNil(values[key.stringValue], "Key \(key) has already been encoded", trapping: true) + let sup = MinimalEncoder.Encoder(base: base, parent: self, key: key) + pendingContainer = sup + return sup + } +} + + +extension MinimalEncoder { + final class UnkeyedContainer { + unowned let base: MinimalEncoder + unowned let parent: _MinimalEncoderContainer? + let key: CodingKey? + var values: [Value] = [] + var isValid = true + var pendingContainer: AnyObject? + + init(base: MinimalEncoder, parent: _MinimalEncoderContainer?, key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + } + + func commitPendingContainer() { + expectTrue(self.isValid, "Container isn't valid", trapping: true) + guard var c = pendingContainer else { return } + self.pendingContainer = nil + expectTrue(isKnownUniquelyReferenced(&c), "Container was retained", trapping: true) + let container = c as! _MinimalEncoderContainer + guard let v = container.finalize() else { preconditionFailure("Container remained empty")} + values.append(v) + } + } +} + +extension MinimalEncoder.UnkeyedContainer: _MinimalEncoderContainer { + func finalize() -> MinimalEncoder.Value? { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + isValid = false + return .array(values) + } +} + +extension MinimalEncoder.UnkeyedContainer: UnkeyedEncodingContainer { + var count: Int { + values.count + } + + func encodeNil() throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.null) + } + + func encode(_ value: Bool) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.bool(value)) + } + + func encode(_ value: Int) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.int(value)) + } + + func encode(_ value: Int8) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.int8(value)) + } + + func encode(_ value: Int16) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.int16(value)) + } + + func encode(_ value: Int32) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.int32(value)) + } + + func encode(_ value: Int64) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.int64(value)) + } + + func encode(_ value: UInt) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.uint(value)) + } + + func encode(_ value: UInt8) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.uint8(value)) + } + + func encode(_ value: UInt16) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.uint16(value)) + } + + func encode(_ value: UInt32) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.uint32(value)) + } + + func encode(_ value: UInt64) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.uint64(value)) + } + + func encode(_ value: Float) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.float(value)) + } + + func encode(_ value: Double) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.double(value)) + } + + func encode(_ value: String) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(.string(value)) + } + + func encode(_ value: T) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + values.append(try _encode(value, key: key)) + } + + func nestedContainer( + keyedBy keyType: NestedKey.Type + ) -> KeyedEncodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + let keyed = MinimalEncoder.KeyedContainer( + base: base, + parent: self, + key: MinimalEncoder._Key(count)) + pendingContainer = keyed + return .init(keyed) + } + + func nestedUnkeyedContainer() -> UnkeyedEncodingContainer { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + let unkeyed = MinimalEncoder.UnkeyedContainer(base: base, parent: self, key: MinimalEncoder._Key(count)) + pendingContainer = unkeyed + return unkeyed + } + + func superEncoder() -> Encoder { + expectTrue(isValid, "Container isn't valid", trapping: true) + commitPendingContainer() + let sup = MinimalEncoder.Encoder(base: base, parent: self, key: MinimalEncoder._Key(count)) + pendingContainer = sup + return sup + } +} + +extension MinimalEncoder { + final class SingleValueContainer { + unowned let base: MinimalEncoder + unowned let parent: _MinimalEncoderContainer? + let key: CodingKey? + var value: Value? + var isValid = true + + init(base: MinimalEncoder, parent: _MinimalEncoderContainer?, key: CodingKey?) { + self.base = base + self.parent = parent + self.key = key + } + } +} + +extension MinimalEncoder.SingleValueContainer: _MinimalEncoderContainer { + func finalize() -> MinimalEncoder.Value? { + expectTrue(isValid, "Container isn't valid", trapping: true) + isValid = false + return value + } +} + +extension MinimalEncoder.SingleValueContainer: SingleValueEncodingContainer { + func encodeNil() throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .null + } + + func encode(_ value: Bool) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .bool(value) + } + + func encode(_ value: Int) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .int(value) + } + + func encode(_ value: Int8) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .int8(value) + } + + func encode(_ value: Int16) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .int16(value) + } + + func encode(_ value: Int32) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .int32(value) + } + + func encode(_ value: Int64) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .int64(value) + } + + func encode(_ value: UInt) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .uint(value) + } + + func encode(_ value: UInt8) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .uint8(value) + } + + func encode(_ value: UInt16) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .uint16(value) + } + + func encode(_ value: UInt32) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .uint32(value) + } + + func encode(_ value: UInt64) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .uint64(value) + } + + func encode(_ value: Float) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .float(value) + } + + func encode(_ value: Double) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .double(value) + } + + func encode(_ value: String) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = .string(value) + } + + func encode(_ value: T) throws { + expectTrue(isValid, "Container isn't valid", trapping: true) + expectNil(self.value, "Cannot encode multiple values into a single-value container", trapping: true) + self.value = try _encode(value, key: nil) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalIndex.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalIndex.swift new file mode 100644 index 00000000..032b6904 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalIndex.swift @@ -0,0 +1,59 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibUnittest + +import XCTest + +public struct MinimalIndex { + internal let _state: _CollectionState + internal let _id: Int + internal var _offset: Int + + internal init(state: _CollectionState, offset: Int) { + _state = state + _id = state.context.nextIndexId() + _offset = offset + precondition(_offset >= 0 && _offset <= state.count) + } + + public var offset: Int { _offset } + public var context: TestContext { _state.context } +} + +extension MinimalIndex: Equatable { + public static func == (left: Self, right: Self) -> Bool { + left._assertCompatible(with: right) + return left._offset == right._offset + } +} + +extension MinimalIndex: Comparable { + public static func < (left: Self, right: Self) -> Bool { + left._assertCompatible(with: right) + return left._offset < right._offset + } +} + +extension MinimalIndex: CustomStringConvertible { + public var description: String { + return "MinimalIndex(offset: \(_offset), state: \(_state.id))" + } +} + +extension MinimalIndex { + func _assertCompatible(with other: Self) { + if self._state === other._state { return } + expectTrue(self._state.isValidIndex(other), "Invalid index", trapping: true) + expectTrue(other._state.isValidIndex(self), "Invalid index", trapping: true) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalIterator.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalIterator.swift new file mode 100644 index 00000000..32a6734a --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalIterator.swift @@ -0,0 +1,54 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +/// State shared by all iterators of a MinimalSequence instance. +internal class _MinimalIteratorSharedState { + internal init(_ data: [Element]) { + self.data = data + } + + internal let data: [Element] + internal var i: Int = 0 + internal var underestimatedCount: Int = 0 + + public func next() -> Element? { + if i == data.count { + return nil + } + defer { i += 1 } + return data[i] + } +} + +/// An iterator that implements the IteratorProtocol contract in the most +/// narrow way possible. +public struct MinimalIterator: IteratorProtocol { + internal let _sharedState: _MinimalIteratorSharedState + + public init(_ s: S) where S.Element == Element { + self._sharedState = _MinimalIteratorSharedState(Array(s)) + } + + public init(_ data: [Element]) { + self._sharedState = _MinimalIteratorSharedState(data) + } + + internal init(_ _sharedState: _MinimalIteratorSharedState) { + self._sharedState = _sharedState + } + + public func next() -> Element? { + _sharedState.next() + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRandomAccessCollection.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRandomAccessCollection.swift new file mode 100644 index 00000000..4d2656f8 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRandomAccessCollection.swift @@ -0,0 +1,182 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +/// A minimal implementation of `RandomAccessCollection & MutableCollection` with extra checks. +public struct MinimalMutableRandomAccessCollection { + internal var _core: _MinimalCollectionCore + + public let timesMakeIteratorCalled = ResettableValue(0) + public let timesUnderestimatedCountCalled = ResettableValue(0) + public let timesRangeChecksCalled = ResettableValue(0) + public let timesIndexNavigationCalled = ResettableValue(0) + public let timesSubscriptGetterCalled = ResettableValue(0) + public let timesSubscriptSetterCalled = ResettableValue(0) + public let timesRangeSubscriptGetterCalled = ResettableValue(0) + public let timesRangeSubscriptSetterCalled = ResettableValue(0) + public let timesSwapCalled = ResettableValue(0) + public let timesPartitionCalled = ResettableValue(0) + + public init( + _ elements: S, + context: TestContext = TestContext.current, + underestimatedCount: UnderestimatedCountBehavior = .value(0) + ) where S.Element == Element { + self._core = _MinimalCollectionCore(context: context, elements: elements, underestimatedCount: underestimatedCount) + } + + var _context: TestContext { + _core.context + } +} + +extension MinimalMutableRandomAccessCollection: Sequence { + public typealias Iterator = MinimalIterator + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.increment() + return MinimalIterator(_core.elements) + } + + public var underestimatedCount: Int { + timesUnderestimatedCountCalled.increment() + return _core.underestimatedCount + } +} + +extension MinimalMutableRandomAccessCollection: RandomAccessCollection { + public typealias Index = MinimalIndex + public typealias SubSequence = Slice + public typealias Indices = DefaultIndices + + public var startIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.startIndex + } + + public var endIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.endIndex + } + + public var isEmpty: Bool { + timesIndexNavigationCalled.increment() + return _core.isEmpty + } + + public var count: Int { + timesIndexNavigationCalled.increment() + return _core.count + } + + public func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(range, bounds: bounds) + } + + public func index(after i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(after: i) + } + + public func index(before i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(before: i) + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) + -> Int { + timesIndexNavigationCalled.increment() + return _core.distance(from: start, to: end) + } + + public func index(_ i: Index, offsetBy n: Int) -> Index { + timesIndexNavigationCalled.increment() + return _core.index(i, offsetBy: n) + } + + public subscript(i: MinimalIndex) -> Element { + get { + timesSubscriptGetterCalled.increment() + return _core[i] + } + set { + timesSubscriptSetterCalled.increment() + _core[i] = newValue + } + } + + public subscript(bounds: Range) -> SubSequence { + get { + timesRangeSubscriptGetterCalled.increment() + _core.assertValid(bounds) + return Slice(base: self, bounds: bounds) + } + set { + timesRangeSubscriptSetterCalled.increment() + _core.assertValid(bounds) + expectEqual(bounds.upperBound._offset - bounds.lowerBound._offset, + newValue.endIndex._offset - newValue.startIndex._offset, + "Range assignment cannot change number of elements in MutableCollection") + _core.elements[bounds.lowerBound._offset ..< bounds.upperBound._offset] = + Self._coreSlice(from: newValue) + // Don't invalidate indices. + } + } + + static func _coreSlice(from slice: SubSequence) -> ArraySlice { + slice.base._core.assertValid(slice.startIndex ..< slice.endIndex) + return slice.base._core.elements[slice.startIndex._offset ..< slice.endIndex._offset] + } +} + +extension MinimalMutableRandomAccessCollection: MutableCollection { + public mutating func partition( + by belongsInSecondPartition: (Element) throws -> Bool + ) rethrows -> Index { + timesPartitionCalled.increment() + let pivot = try _core.elements.partition(by: belongsInSecondPartition) + return _core.index(at: pivot) + } + + public mutating func swapAt(_ i: Index, _ j: Index) { + _core.assertValidIndexBeforeEnd(i) + _core.assertValidIndexBeforeEnd(j) + timesSwapCalled.increment() + _core.elements.swapAt(i._offset, j._offset) + // Don't invalidate indices. + } + + public mutating func _withUnsafeMutableBufferPointerIfSupported( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + return nil + } + + public mutating func withContiguousMutableStorageIfAvailable( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + return nil + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRangeReplaceableRandomAccessCollection.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRangeReplaceableRandomAccessCollection.swift new file mode 100644 index 00000000..1f70e13e --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalMutableRangeReplaceableRandomAccessCollection.swift @@ -0,0 +1,249 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +/// A minimal implementation of `RandomAccessCollection & MutableCollection & RangeReplaceableCollection` with extra checks. +public struct MinimalMutableRangeReplaceableRandomAccessCollection { + internal var _core: _MinimalCollectionCore + + public let timesMakeIteratorCalled = ResettableValue(0) + public let timesUnderestimatedCountCalled = ResettableValue(0) + public let timesRangeChecksCalled = ResettableValue(0) + public let timesIndexNavigationCalled = ResettableValue(0) + public let timesSubscriptGetterCalled = ResettableValue(0) + public let timesSubscriptSetterCalled = ResettableValue(0) + public let timesRangeSubscriptGetterCalled = ResettableValue(0) + public let timesRangeSubscriptSetterCalled = ResettableValue(0) + public let timesSwapCalled = ResettableValue(0) + public let timesPartitionCalled = ResettableValue(0) + + public init( + _ elements: S, + context: TestContext = TestContext.current, + underestimatedCount: UnderestimatedCountBehavior = .value(0) + ) where S.Element == Element { + self._core = _MinimalCollectionCore(context: context, elements: elements, underestimatedCount: underestimatedCount) + } + + var _context: TestContext { + _core.context + } +} + +extension MinimalMutableRangeReplaceableRandomAccessCollection: Sequence { + public typealias Iterator = MinimalIterator + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.increment() + return MinimalIterator(_core.elements) + } + + public var underestimatedCount: Int { + timesUnderestimatedCountCalled.increment() + return _core.underestimatedCount + } +} + +extension MinimalMutableRangeReplaceableRandomAccessCollection: RandomAccessCollection { + public typealias Index = MinimalIndex + public typealias SubSequence = Slice + public typealias Indices = DefaultIndices + + public var startIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.startIndex + } + + public var endIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.endIndex + } + + public var isEmpty: Bool { + timesIndexNavigationCalled.increment() + return _core.isEmpty + } + + public var count: Int { + timesIndexNavigationCalled.increment() + return _core.count + } + + public func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(range, bounds: bounds) + } + + public func index(after i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(after: i) + } + + public func index(before i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(before: i) + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) + -> Int { + timesIndexNavigationCalled.increment() + return _core.distance(from: start, to: end) + } + + public func index(_ i: Index, offsetBy n: Int) -> Index { + timesIndexNavigationCalled.increment() + return _core.index(i, offsetBy: n) + } + + public subscript(i: MinimalIndex) -> Element { + get { + timesSubscriptGetterCalled.increment() + return _core[i] + } + set { + timesSubscriptSetterCalled.increment() + _core[i] = newValue + } + } + + public subscript(bounds: Range) -> SubSequence { + get { + timesRangeSubscriptGetterCalled.increment() + _core.assertValid(bounds) + return Slice(base: self, bounds: bounds) + } + set { + timesRangeSubscriptSetterCalled.increment() + _core.assertValid(bounds) + _core.elements[bounds.lowerBound._offset ..< bounds.upperBound._offset] = + Self._coreSlice(from: newValue) + // Don't invalidate indices. + } + } + + static func _coreSlice(from slice: SubSequence) -> ArraySlice { + slice.base._core.assertValid(slice.startIndex ..< slice.endIndex) + return slice.base._core.elements[slice.startIndex._offset ..< slice.endIndex._offset] + } +} + +extension MinimalMutableRangeReplaceableRandomAccessCollection: MutableCollection { + public mutating func partition( + by belongsInSecondPartition: (Element) throws -> Bool + ) rethrows -> Index { + timesPartitionCalled.increment() + let pivot = try _core.elements.partition(by: belongsInSecondPartition) + return _core.index(at: pivot) + } + + public mutating func swapAt(_ i: Index, _ j: Index) { + _core.assertValidIndexBeforeEnd(i) + _core.assertValidIndexBeforeEnd(j) + timesSwapCalled.increment() + _core.elements.swapAt(i._offset, j._offset) + // Don't invalidate indices. + } + + public mutating func _withUnsafeMutableBufferPointerIfSupported( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + return nil + } + + public mutating func withContiguousMutableStorageIfAvailable( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + return nil + } +} + +extension MinimalMutableRangeReplaceableRandomAccessCollection: RangeReplaceableCollection { + public init() { + self.init([]) + } + + public mutating func replaceSubrange( + _ subrange: Range, + with newElements: C + ) where C.Element == Element { + _core.replaceSubrange(subrange, with: newElements) + } + + public mutating func reserveCapacity(_ n: Int) { + _core.reserveCapacity(minimumCapacity: n) + } + + public init(_ elements: S) where S.Element == Element { + self.init(elements, context: TestContext.current) + } + + public mutating func append(_ newElement: Element) { + _core.append(newElement) + } + + public mutating func append( + contentsOf newElements: S + ) where S.Element == Element { + _core.append(contentsOf: newElements) + } + + public mutating func insert(_ newElement: Element, at i: Index) { + _core.insert(newElement, at: i) + } + + @discardableResult + public mutating func remove(at i: Index) -> Element { + return _core.remove(at: i) + } + + public mutating func removeSubrange(_ bounds: Range) { + _core.removeSubrange(bounds) + } + + public mutating func _customRemoveLast() -> Element? { + return _core._customRemoveLast() + } + + public mutating func _customRemoveLast(_ n: Int) -> Bool { + return _core._customRemoveLast(n) + } + + @discardableResult + public mutating func removeFirst() -> Element { + return _core.removeFirst() + } + + public mutating func removeFirst(_ n: Int) { + _core.removeFirst(n) + } + + public mutating func removeAll(keepingCapacity keepCapacity: Bool) { + _core.removeAll(keepingCapacity: keepCapacity) + } + + public mutating func removeAll( + where shouldBeRemoved: (Element) throws -> Bool) rethrows { + try _core.removeAll(where: shouldBeRemoved) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalRandomAccessCollection.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalRandomAccessCollection.swift new file mode 100644 index 00000000..773011e4 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalRandomAccessCollection.swift @@ -0,0 +1,125 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +/// A minimal implementation of `RandomAccessCollection` with extra checks. +public struct MinimalRandomAccessCollection { + internal var _core: _MinimalCollectionCore + + public let timesMakeIteratorCalled = ResettableValue(0) + public let timesUnderestimatedCountCalled = ResettableValue(0) + public let timesRangeChecksCalled = ResettableValue(0) + public let timesIndexNavigationCalled = ResettableValue(0) + public let timesSubscriptCalled = ResettableValue(0) + public let timesRangeSubscriptCalled = ResettableValue(0) + + public init( + _ elements: S, + context: TestContext = TestContext.current, + underestimatedCount: UnderestimatedCountBehavior = .value(0) + ) where S.Element == Element { + self._core = _MinimalCollectionCore(context: context, elements: elements, underestimatedCount: underestimatedCount) + } + + var _context: TestContext { + _core.context + } +} + +extension MinimalRandomAccessCollection: Sequence { + public typealias Iterator = MinimalIterator + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.increment() + return MinimalIterator(_core.elements) + } + + public var underestimatedCount: Int { + timesUnderestimatedCountCalled.increment() + return _core.underestimatedCount + } +} + +extension MinimalRandomAccessCollection: RandomAccessCollection { + public typealias Index = MinimalIndex + public typealias SubSequence = Slice + public typealias Indices = DefaultIndices + + public var startIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.startIndex + } + + public var endIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.endIndex + } + + public var isEmpty: Bool { + timesIndexNavigationCalled.increment() + return _core.isEmpty + } + + public var count: Int { + timesIndexNavigationCalled.increment() + return _core.count + } + + public func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(range, bounds: bounds) + } + + public func index(after i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(after: i) + } + + public func index(before i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(before: i) + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) + -> Int { + timesIndexNavigationCalled.increment() + return _core.distance(from: start, to: end) + } + + public func index(_ i: Index, offsetBy n: Int) -> Index { + timesIndexNavigationCalled.increment() + return _core.index(i, offsetBy: n) + } + + public subscript(i: MinimalIndex) -> Element { + timesSubscriptCalled.increment() + return _core[i] + } + + public subscript(bounds: Range) -> SubSequence { + timesRangeSubscriptCalled.increment() + _core.assertValid(bounds) + return Slice(base: self, bounds: bounds) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalRangeReplaceableRandomAccessCollection.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalRangeReplaceableRandomAccessCollection.swift new file mode 100644 index 00000000..88905b17 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalRangeReplaceableRandomAccessCollection.swift @@ -0,0 +1,204 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +/// A minimal implementation of `RandomAccessCollection & RangeReplaceableCollection` with extra checks. +public struct MinimalRangeReplaceableRandomAccessCollection { + internal var _core: _MinimalCollectionCore + + public let timesMakeIteratorCalled = ResettableValue(0) + public let timesUnderestimatedCountCalled = ResettableValue(0) + public let timesRangeChecksCalled = ResettableValue(0) + public let timesIndexNavigationCalled = ResettableValue(0) + public let timesSubscriptGetterCalled = ResettableValue(0) + public let timesSubscriptSetterCalled = ResettableValue(0) + public let timesRangeSubscriptGetterCalled = ResettableValue(0) + public let timesRangeSubscriptSetterCalled = ResettableValue(0) + public let timesSwapCalled = ResettableValue(0) + public let timesPartitionCalled = ResettableValue(0) + + public init( + _ elements: S, + context: TestContext = TestContext.current, + underestimatedCount: UnderestimatedCountBehavior = .value(0) + ) where S.Element == Element { + self._core = _MinimalCollectionCore(context: context, elements: elements, underestimatedCount: underestimatedCount) + } + + var _context: TestContext { + _core.context + } +} + +extension MinimalRangeReplaceableRandomAccessCollection: Sequence { + public typealias Iterator = MinimalIterator + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.increment() + return MinimalIterator(_core.elements) + } + + public var underestimatedCount: Int { + timesUnderestimatedCountCalled.increment() + return _core.underestimatedCount + } +} + +extension MinimalRangeReplaceableRandomAccessCollection: RandomAccessCollection { + public typealias Index = MinimalIndex + public typealias SubSequence = Slice + public typealias Indices = DefaultIndices + + public var startIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.startIndex + } + + public var endIndex: MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.endIndex + } + + public var isEmpty: Bool { + timesIndexNavigationCalled.increment() + return _core.isEmpty + } + + public var count: Int { + timesIndexNavigationCalled.increment() + return _core.count + } + + public func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + timesRangeChecksCalled.increment() + _core._failEarlyRangeCheck(range, bounds: bounds) + } + + public func index(after i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(after: i) + } + + public func index(before i: MinimalIndex) -> MinimalIndex { + timesIndexNavigationCalled.increment() + return _core.index(before: i) + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) + -> Int { + timesIndexNavigationCalled.increment() + return _core.distance(from: start, to: end) + } + + public func index(_ i: Index, offsetBy n: Int) -> Index { + timesIndexNavigationCalled.increment() + return _core.index(i, offsetBy: n) + } + + public subscript(i: MinimalIndex) -> Element { + timesSubscriptGetterCalled.increment() + return _core[i] + } + + public subscript(bounds: Range) -> SubSequence { + timesRangeSubscriptGetterCalled.increment() + _core.assertValid(bounds) + return Slice(base: self, bounds: bounds) + } + + static func _coreSlice(from slice: SubSequence) -> ArraySlice { + slice.base._core.assertValid(slice.startIndex ..< slice.endIndex) + return slice.base._core.elements[slice.startIndex._offset ..< slice.endIndex._offset] + } +} + +extension MinimalRangeReplaceableRandomAccessCollection: RangeReplaceableCollection { + public init() { + self.init([]) + } + + public mutating func replaceSubrange( + _ subrange: Range, + with newElements: C + ) where C.Element == Element { + _core.replaceSubrange(subrange, with: newElements) + } + + public mutating func reserveCapacity(_ n: Int) { + _core.reserveCapacity(minimumCapacity: n) + } + + public init(_ elements: S) where S.Element == Element { + self.init(elements, context: TestContext.current) + } + + public mutating func append(_ newElement: Element) { + _core.append(newElement) + } + + public mutating func append( + contentsOf newElements: S + ) where S.Element == Element { + _core.append(contentsOf: newElements) + } + + public mutating func insert(_ newElement: Element, at i: Index) { + _core.insert(newElement, at: i) + } + + @discardableResult + public mutating func remove(at i: Index) -> Element { + return _core.remove(at: i) + } + + public mutating func removeSubrange(_ bounds: Range) { + _core.removeSubrange(bounds) + } + + public mutating func _customRemoveLast() -> Element? { + return _core._customRemoveLast() + } + + public mutating func _customRemoveLast(_ n: Int) -> Bool { + return _core._customRemoveLast(n) + } + + @discardableResult + public mutating func removeFirst() -> Element { + return _core.removeFirst() + } + + public mutating func removeFirst(_ n: Int) { + _core.removeFirst(n) + } + + public mutating func removeAll(keepingCapacity keepCapacity: Bool) { + _core.removeAll(keepingCapacity: keepCapacity) + } + + public mutating func removeAll( + where shouldBeRemoved: (Element) throws -> Bool) rethrows { + try _core.removeAll(where: shouldBeRemoved) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/MinimalSequence.swift b/Sources/CollectionsTestSupport/MinimalTypes/MinimalSequence.swift new file mode 100644 index 00000000..be5a0cf8 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/MinimalSequence.swift @@ -0,0 +1,96 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +public enum UnderestimatedCountBehavior { + /// Return the actual number of elements. + case precise + + /// Return the actual number of elements divided by 2. + case half + + /// Return an overestimated count. Useful to test how algorithms reserve + /// memory. + case overestimate + + /// Return the provided value. + case value(Int) + + func value(forCount count: Int) -> Int { + switch self { + case .precise: + return count + case .half: + return count / 2 + case .overestimate: + return count * 3 + 5 + case .value(let count): + return count + } + } +} + +/// A Sequence that implements the protocol contract in the most +/// narrow way possible. +/// +/// This sequence is consumed when its generator is advanced. +public struct MinimalSequence: Sequence, CustomDebugStringConvertible { + public let timesMakeIteratorCalled = ResettableValue(0) + + internal let _sharedState: _MinimalIteratorSharedState + internal let _isContiguous: Bool + + public init( + elements: S, + underestimatedCount: UnderestimatedCountBehavior = .value(0), + isContiguous: Bool = false + ) where S.Element == T { + let data = Array(elements) + self._sharedState = _MinimalIteratorSharedState(data) + self._isContiguous = isContiguous + switch underestimatedCount { + case .precise: + self._sharedState.underestimatedCount = data.count + + case .half: + self._sharedState.underestimatedCount = data.count / 2 + + case .overestimate: + self._sharedState.underestimatedCount = data.count * 3 + 5 + + case .value(let count): + self._sharedState.underestimatedCount = count + } + } + + public func makeIterator() -> MinimalIterator { + timesMakeIteratorCalled.value += 1 + return MinimalIterator(_sharedState) + } + + public var underestimatedCount: Int { + return Swift.max(0, self._sharedState.underestimatedCount - self._sharedState.i) + } + + public var debugDescription: String { + return "MinimalSequence(\(_sharedState.data[_sharedState.i...]))" + } + + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + guard _isContiguous else { return nil } + return try _sharedState.data[_sharedState.i...] + .withContiguousStorageIfAvailable(body) + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/ResettableValue.swift b/Sources/CollectionsTestSupport/MinimalTypes/ResettableValue.swift new file mode 100644 index 00000000..aebb0c96 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/ResettableValue.swift @@ -0,0 +1,37 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibUnittest + +public class ResettableValue { + public init(_ value: Value) { + self.defaultValue = value + self.value = value + } + + public func reset() { + value = defaultValue + } + + public let defaultValue: Value + public var value: Value +} + +extension ResettableValue where Value: Strideable { + public func increment(by delta: Value.Stride = 1) { + value = value.advanced(by: delta) + } +} + +extension ResettableValue: CustomStringConvertible { + public var description: String { "\(value)" } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/StringConvertibleValue.swift b/Sources/CollectionsTestSupport/MinimalTypes/StringConvertibleValue.swift new file mode 100644 index 00000000..b4e524be --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/StringConvertibleValue.swift @@ -0,0 +1,34 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +public struct StringConvertibleValue { + public var value: Int + public init(_ value: Int) { self.value = value } +} + +extension StringConvertibleValue: ExpressibleByIntegerLiteral { + public init(integerLiteral value: Int) { + self.init(value) + } +} + +extension StringConvertibleValue: CustomStringConvertible { + public var description: String { + "description(\(value))" + } +} + +extension StringConvertibleValue: CustomDebugStringConvertible { + public var debugDescription: String { + "debugDescription(\(value))" + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/_CollectionState.swift b/Sources/CollectionsTestSupport/MinimalTypes/_CollectionState.swift new file mode 100644 index 00000000..fcb05959 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/_CollectionState.swift @@ -0,0 +1,241 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +// Loosely adapted from https://github.com/apple/swift/tree/main/stdlib/private/StdlibCollectionUnittest + +final class _CollectionState { + /// The collection context in which this state belongs. + let context: TestContext + /// The unique identifier of this state within its context. + let id: Int + /// The state from which this instance spawned. + private(set) var parent: _CollectionState? + private(set) var count: Int + private(set) var strategy: IndexInvalidationStrategy + /// The identifier of the state in which each currently valid index first became valid. + /// (Note: the end index is tracked separately, in `endIndexValidity`. + /// The identifier tracked here is guaranteed to match one of the states on the `parent` chain. + private var indexValidity: [Int] + /// The identitifer of the state in which the current endIndex first became valid. + private var endIndexValidity: Int + + enum IndexInvalidationStrategy: Hashable { + case allIndices + case afterChange + } + + + init( + context: TestContext, + parent: _CollectionState?, + count: Int, + strategy: IndexInvalidationStrategy = .allIndices, + indexValidity: [Int], + endIndexValidity: Int + ) { + self.context = context + self.id = context.nextStateId() + self.parent = parent + self.count = count + self.strategy = strategy + self.indexValidity = indexValidity + self.endIndexValidity = endIndexValidity + } + + init( + context: TestContext, + parent: _CollectionState?, + count: Int, + strategy: IndexInvalidationStrategy = .allIndices + ) { + self.context = context + self.parent = parent + self.id = context.nextStateId() + self.count = count + self.strategy = strategy + switch strategy { + case .allIndices: + self.indexValidity = [] + self.endIndexValidity = 0 + case .afterChange: + self.indexValidity = Array(repeatElement(id, count: count)) + self.endIndexValidity = id + } + } + + deinit { + // Prevent stack overflow for long parent chains. + var node = self + while isKnownUniquelyReferenced(&node.parent) { + let p = node.parent! + node.parent = nil + node = p + } + } + + func spawnChild() -> _CollectionState { + _CollectionState( + context: context, + parent: self, + count: count, + strategy: strategy, + indexValidity: indexValidity, + endIndexValidity: endIndexValidity) + } +} + +extension _CollectionState: Equatable { + public static func == (left: _CollectionState, right: _CollectionState) -> Bool { + return left.id == right.id + } +} + +extension _CollectionState: Hashable { + public func hash(into hasher: inout Hasher) { + hasher.combine(id) + } +} + +extension _CollectionState { + func isValidIndex(_ index: MinimalIndex) -> Bool { + if index._state === self { return true } + guard index._state.context == context else { return false } + guard index._offset >= 0 && index._offset <= count else { return false } + switch strategy { + case .allIndices: + guard index._state.id == self.id else { return false } + case .afterChange: + if index._offset < count { + guard index._state.id == indexValidity[index._offset] else { return false } + } else { + guard index._state.id == endIndexValidity else { return false } + } + } + return true + } +} + +extension _CollectionState { + internal subscript(validityAt offset: Int) -> Int { + get { + switch strategy { + case .allIndices: + return id + case .afterChange: + precondition(offset >= 0) + if offset > count { + return id + } + if offset == count { + return endIndexValidity + } + return indexValidity[offset] + } + } + set { + precondition(strategy == .allIndices, "Cannot invalidate individual indices") + precondition(offset >= 0 && offset <= count) + if offset == count { + endIndexValidity = newValue + } else { + indexValidity[offset] = newValue + } + } + } +} + +extension _CollectionState { + func insert(count: Int, at offset: Int) { + precondition(count >= 0 && offset >= 0 && offset <= self.count) + guard count > 0 else { return } + self.count += count + switch strategy { + case .allIndices: + // Do nothing + break + case .afterChange: + let rest = offset ..< indexValidity.count + self.indexValidity.replaceSubrange(rest, with: repeatElement(id, count: rest.count + count)) + self.endIndexValidity = self.id + assert(indexValidity.count == self.count) + } + } + + func remove(_ range: Range) { + remove(count: range.upperBound._offset - range.lowerBound._offset, + at: range.lowerBound._offset) + } + + func remove(count: Int, at offset: Int) { + precondition(count >= 0 && offset >= 0 && offset + count <= self.count) + guard count > 0 else { return } + switch strategy { + case .allIndices: + self.count -= count + case .afterChange: + let rest = offset ..< self.count + self.indexValidity.replaceSubrange(rest, with: repeatElement(id, count: rest.count - count)) + self.endIndexValidity = self.id + self.count -= count + assert(indexValidity.count == self.count) + } + } + + func replace(_ range: Range, with newCount: Int) { + replace(oldCount: range.upperBound._offset - range.lowerBound._offset, + at: range.lowerBound._offset, + with: newCount) + } + + func replace(oldCount: Int, at offset: Int, with newCount: Int) { + precondition(oldCount >= 0 && offset >= 0 && newCount >= 0) + precondition(offset + oldCount <= self.count) + guard oldCount > 0 || newCount > 0 else { return } + switch strategy { + case .allIndices: + self.count += newCount - oldCount + case .afterChange: + let rest = offset ..< self.count + self.indexValidity.replaceSubrange( + rest, + with: repeatElement(id, count: rest.count + newCount - oldCount)) + self.endIndexValidity = self.id + self.count += newCount - oldCount + assert(indexValidity.count == self.count) + } + } + + func replaceAll() { + switch strategy { + case .allIndices: + // Do nothing + break + case .afterChange: + self.indexValidity = Array(repeating: id, count: count) + self.endIndexValidity = id + assert(indexValidity.count == self.count) + } + } + + func reset(count: Int) { + self.count = count + switch strategy { + case .allIndices: + // Do nothing + break + case .afterChange: + self.indexValidity = Array(repeating: id, count: count) + self.endIndexValidity = id + assert(indexValidity.count == self.count) + } + } +} diff --git a/Sources/CollectionsTestSupport/MinimalTypes/_MinimalCollectionCore.swift b/Sources/CollectionsTestSupport/MinimalTypes/_MinimalCollectionCore.swift new file mode 100644 index 00000000..4bdc7c63 --- /dev/null +++ b/Sources/CollectionsTestSupport/MinimalTypes/_MinimalCollectionCore.swift @@ -0,0 +1,349 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +struct _MinimalCollectionCore { + var state: _CollectionState + var elements: [Element] + var underestimatedCount: Int + + public init( + context: TestContext, + elements: S, + underestimatedCount: UnderestimatedCountBehavior? = nil + ) where S.Element == Element { + self.init(context: context, elements: Array(elements), underestimatedCount: underestimatedCount) + } + + public init( + context: TestContext, + elements: [Element], + underestimatedCount: UnderestimatedCountBehavior? = nil + ) { + self.state = _CollectionState(context: context, parent: nil, count: elements.count) + self.elements = elements + self.underestimatedCount = underestimatedCount?.value(forCount: elements.count) ?? elements.count + } + + var context: TestContext { state.context } +} + +extension _MinimalCollectionCore { + var startIndex: MinimalIndex { + MinimalIndex(state: state, offset: 0) + } + + var endIndex: MinimalIndex { + MinimalIndex(state: state, offset: count) + } + + var count: Int { + elements.count + } + + var isEmpty: Bool { + elements.isEmpty + } +} + +extension _MinimalCollectionCore { + mutating func ensureUniqueState() { + if !isKnownUniquelyReferenced(&state) { + state = state.spawnChild() + } + } +} + +// MARK: Index validation + +extension _MinimalCollectionCore { + internal func index(at offset: Int) -> MinimalIndex { + return MinimalIndex(state: state, offset: offset) + } + + func isValidIndex(_ index: MinimalIndex) -> Bool { + state.isValidIndex(index) + } + + func assertValidIndex( + _ index: MinimalIndex, + _ message: @autoclosure () -> String = "Invalid index", + file: StaticString = #file, + line: UInt = #line + ) { + expectTrue(isValidIndex(index), + message(), trapping: true, + file: file, line: line) + } + + func assertValidIndexBeforeEnd( + _ index: MinimalIndex, + _ message: @autoclosure () -> String = "Invalid index", + file: StaticString = #file, + line: UInt = #line + ) { + expectTrue(isValidIndex(index), + message(), trapping: true, + file: file, line: line) + + expectTrue(index._offset != elements.count, + message(), trapping: true, + file: file, line: line) + } + + func assertValid( + _ range: Range, + message: @autoclosure () -> String = "Invalid index range", + file: StaticString = #file, + line: UInt = #line + ) { + assertValidIndex(range.lowerBound, message()) + assertValidIndex(range.upperBound, message()) + } +} + +// MARK: Index navigation + +extension _MinimalCollectionCore { + func index(after index: MinimalIndex) -> MinimalIndex { + assertValidIndex(index) + expectTrue(index._offset < count, + "Can't advance beyond endIndex", + trapping: true) + return self.index(at: index._offset + 1) + } + + func index(before index: MinimalIndex) -> MinimalIndex { + assertValidIndex(index) + expectTrue(index._offset > 0, + "Can't advance before startIndex", + trapping: true) + return self.index(at: index._offset - 1) + } + + func formIndex(after index: inout MinimalIndex) { + assertValidIndex(index) + expectTrue(index._offset < count, + "Can't advance beyond endIndex", + trapping: true) + index._offset += 1 + } + + func formIndex(before index: inout MinimalIndex) { + assertValidIndex(index) + expectTrue(index._offset > 0, + "Can't advance before startIndex", + trapping: true) + index._offset -= 1 + } + + public func distance(from start: MinimalIndex, to end: MinimalIndex) -> Int { + assertValidIndex(start) + assertValidIndex(end) + return end._offset - start._offset + } + + public func index( + _ index: MinimalIndex, + offsetBy n: Int + ) -> MinimalIndex { + assertValidIndex(index) + expectTrue(index._offset + n >= 0, + "Can't advance before startIndex", + trapping: true) + expectTrue(index._offset + n <= count, + "Can't advance after endIndex", + trapping: true) + return self.index(at: index._offset + n) + } + + func _failEarlyRangeCheck( + _ index: MinimalIndex, + bounds: Range + ) { + assertValidIndex(index) + assertValid(bounds) + expectLessThanOrEqual( + bounds.lowerBound._offset, index._offset, + "Index out of bounds", trapping: true) + expectLessThan( + index._offset, bounds.upperBound._offset, + "Index out of bounds", trapping: true) + } + + public func _failEarlyRangeCheck( + _ range: Range, + bounds: Range + ) { + assertValid(range) + assertValid(bounds) + expectLessThanOrEqual( + bounds.lowerBound._offset, range.lowerBound._offset, + "Index range out of bounds", trapping: true) + expectLessThanOrEqual( + range.upperBound._offset, bounds.upperBound._offset, + "Index range out of bounds", trapping: true) + } + + func _count(of range: Range) -> Int { + range.upperBound._offset - range.lowerBound._offset + } +} + +// MARK: Mutations + +extension _MinimalCollectionCore { + subscript(index: MinimalIndex) -> Element { + get { + assertValidIndexBeforeEnd(index) + return elements[index._offset] + } + set { + assertValidIndexBeforeEnd(index) + elements[index._offset] = newValue + // MutableCollection requires that the subscript setter + // not invalidate any indices. + } + } + + mutating func replaceSubrange( + _ subrange: Range, + with newElements: C + ) where C.Element == Element { + assertValid(subrange) + elements.replaceSubrange( + subrange.lowerBound._offset ..< subrange.upperBound._offset, + with: newElements) + + ensureUniqueState() + state.replace(subrange, with: newElements.count) + } + + mutating func reserveCapacity(minimumCapacity: Int) { + elements.reserveCapacity(minimumCapacity) + state.replaceAll() + } + + mutating func append(_ item: Element) { + elements.append(item) + ensureUniqueState() + state.insert(count: 1, at: state.count) + } + + mutating func append( + contentsOf newElements: S + ) where S.Element == Element { + elements.append(contentsOf: newElements) + ensureUniqueState() + state.insert(count: elements.count - state.count, at: state.count) + } + + mutating func insert( + _ newElement: Element, + at index: MinimalIndex + ) { + assertValidIndex(index) + elements.insert(newElement, at: index._offset) + ensureUniqueState() + state.insert(count: 1, at: index._offset) + } + + mutating func insert( + contentsOf newElements: C, + at index: MinimalIndex + ) where C.Element == Element { + assertValidIndex(index) + elements.insert(contentsOf: newElements, at: index._offset) + ensureUniqueState() + state.insert(count: newElements.count, at: index._offset) + } + + mutating func remove(at index: MinimalIndex) -> Element { + assertValidIndexBeforeEnd(index) + ensureUniqueState() + state.remove(count: 1, at: index._offset) + return elements.remove(at: index._offset) + } + + mutating func removeSubrange(_ bounds: Range) { + assertValid(bounds) + elements.removeSubrange(bounds.lowerBound._offset ..< bounds.upperBound._offset) + ensureUniqueState() + state.remove(count: _count(of: bounds), at: bounds.lowerBound._offset) + } + + mutating func removeFirst() -> Element { + expectTrue( + count > 0, + "Can't remove first element of an empty collection", + trapping: true) + ensureUniqueState() + state.remove(count: 1, at: 0) + return elements.removeFirst() + } + + mutating func removeFirst(_ n: Int) { + expectTrue( + n >= 0, + "Can't remove a negative number of elements", + trapping: true) + expectTrue( + n <= count, + "Can't remove more elements than there are in the collection", + trapping: true) + ensureUniqueState() + state.remove(count: n, at: 0) + elements.removeFirst(n) + } + + public mutating func _customRemoveLast() -> Element? { + expectTrue( + !isEmpty, + "Can't remove last element of an empty collection", + trapping: true) + ensureUniqueState() + state.remove(count: 1, at: state.count) + return elements.removeLast() + } + + public mutating func _customRemoveLast(_ n: Int) -> Bool { + expectTrue( + n >= 0, + "Can't remove a negative number of elements", + trapping: true) + expectTrue( + count >= n, + "Can't remove more elements than there are in the collection", + trapping: true) + elements.removeLast(n) + ensureUniqueState() + state.remove(count: n, at: state.count - n) + return true + } + + + mutating func removeAll(keepingCapacity keepCapacity: Bool) { + elements.removeAll(keepingCapacity: keepCapacity) + ensureUniqueState() + state.remove(count: state.count, at: 0) + } + + mutating func removeAll( + where shouldBeRemoved: (Element) throws -> Bool + ) rethrows { + defer { + ensureUniqueState() + state.reset(count: elements.count) + } + try elements.removeAll(where: shouldBeRemoved) + } +} + diff --git a/Sources/CollectionsTestSupport/Utilities/Box.swift b/Sources/CollectionsTestSupport/Utilities/Box.swift new file mode 100644 index 00000000..15cae71f --- /dev/null +++ b/Sources/CollectionsTestSupport/Utilities/Box.swift @@ -0,0 +1,16 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +public final class Box { + public init(_ value: T) { self.value = value } + public var value: T +} diff --git a/Sources/CollectionsTestSupport/Utilities/HashableBox.swift b/Sources/CollectionsTestSupport/Utilities/HashableBox.swift new file mode 100644 index 00000000..ed2388e5 --- /dev/null +++ b/Sources/CollectionsTestSupport/Utilities/HashableBox.swift @@ -0,0 +1,24 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +public final class HashableBox: Hashable { + public init(_ value: T) { self.value = value } + public var value: T + + public static func ==(left: HashableBox, right: HashableBox) -> Bool { + left.value == right.value + } + + public func hash(into hasher: inout Hasher) { + hasher.combine(value) + } +} diff --git a/Sources/CollectionsTestSupport/Utilities/LifetimeTracked.swift b/Sources/CollectionsTestSupport/Utilities/LifetimeTracked.swift new file mode 100644 index 00000000..a53b5795 --- /dev/null +++ b/Sources/CollectionsTestSupport/Utilities/LifetimeTracked.swift @@ -0,0 +1,77 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +/// A type that tracks the number of live instances. +/// +/// `LifetimeTracked` conforms to `CustomStringConvertible`, and conditionally +/// conforms to `Equatable`, `Hashable` and `Comparable` when its payload does. +/// +/// `LifetimeTracked` is useful to check for leaks in algorithms and data +/// structures. The easiest way to produce instances is to use the +/// `withLifetimeTracking` function: +/// +/// class FooTests: XCTestCase { +/// func testFoo() { +/// withLifetimeTracking([1, 2, 3]) { instances in +/// _ = instances.sorted(by: >) +/// } +/// } +/// } +public class LifetimeTracked { + public let tracker: LifetimeTracker + internal var serialNumber: Int = 0 + public let payload: Payload + + public init(_ payload: Payload, for tracker: LifetimeTracker) { + tracker.instances += 1 + tracker._nextSerialNumber += 1 + self.tracker = tracker + self.serialNumber = tracker._nextSerialNumber + self.payload = payload + } + + deinit { + precondition(serialNumber != 0, "Double deinit") + tracker.instances -= 1 + serialNumber = -serialNumber + } +} + +extension LifetimeTracked: CustomStringConvertible { + public var description: String { + return "\(payload)" + } +} + +extension LifetimeTracked: Equatable where Payload: Equatable { + public static func == (left: LifetimeTracked, right: LifetimeTracked) -> Bool { + return left.payload == right.payload + } +} + +extension LifetimeTracked: Hashable where Payload: Hashable { + public func hash(into hasher: inout Hasher) { + hasher.combine(payload) + } +} + +extension LifetimeTracked: Comparable where Payload: Comparable { + public static func < (left: LifetimeTracked, right: LifetimeTracked) -> Bool { + return left.payload < right.payload + } +} + +extension LifetimeTracked: Encodable where Payload: Encodable { + public func encode(to encoder: Encoder) throws { + try payload.encode(to: encoder) + } +} diff --git a/Sources/CollectionsTestSupport/Utilities/LifetimeTracker.swift b/Sources/CollectionsTestSupport/Utilities/LifetimeTracker.swift new file mode 100644 index 00000000..e920a675 --- /dev/null +++ b/Sources/CollectionsTestSupport/Utilities/LifetimeTracker.swift @@ -0,0 +1,54 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift.org open source project +// +// Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors +// +//===----------------------------------------------------------------------===// + +/// Tracks the life times of `LifetimeTracked` instances, providing a method +/// to validate checkpoints where no instances should exist. +/// +/// - Note: `LifetimeTracker` is not designed for multithreaded use. Trying to +/// instantiate or deinitialize instances belonging to the same tracker +/// from multiple concurrent threads (or reentrantly) will lead to +/// exclusivity violations and therefore undefined behavior. +public class LifetimeTracker { + public internal(set) var instances = 0 + var _nextSerialNumber = 0 + + public init() {} + + deinit { + check() + } + + public func check(file: StaticString = #file, line: UInt = #line) { + expectEqual(instances, 0, + "Potential leak of \(instances) objects", + file: file, line: line) + } + + public func instance(for payload: Payload) -> LifetimeTracked { + LifetimeTracked(payload, for: self) + } + + public func instances(for items: S) -> [LifetimeTracked] { + return items.map { LifetimeTracked($0, for: self) } + } +} + +@inlinable +public func withLifetimeTracking( + file: StaticString = #file, + line: UInt = #line, + _ body: (LifetimeTracker) throws -> R +) rethrows -> R { + let tracker = LifetimeTracker() + defer { tracker.check(file: file, line: line) } + return try body(tracker) +} diff --git a/Sources/CollectionsTestSupport/Utilities/SeedableRandomNumberGenerator.swift b/Sources/CollectionsTestSupport/Utilities/SeedableRandomNumberGenerator.swift new file mode 100644 index 00000000..f09b89eb --- /dev/null +++ b/Sources/CollectionsTestSupport/Utilities/SeedableRandomNumberGenerator.swift @@ -0,0 +1,40 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +public struct RepeatableRandomNumberGenerator: RandomNumberGenerator { + // This uses the same linear congruential generator as rand48. + // FIXME: Replace with something better. + internal static let _m: UInt64 = 1 << 48 + internal static let _a: UInt64 = 25214903917 + internal static let _c: UInt64 = 11 + + internal var _state: UInt64 + + public init(seed: Int) { + self.init(seed: UInt64(truncatingIfNeeded: seed)) + } + + public init(seed: UInt64) { + // Perturb the seed a little so that the sequence doesn't start with a + // zero value in the common case of seed == 0. (Using a zero seed is a + // rather silly thing to do, but it's the easy thing.) + _state = seed ^ 0x536f52616e646f6d // "SoRandom" + } + + private mutating func _next() -> UInt64 { + _state = (Self._a &* _state &+ Self._c) & (Self._m - 1) + return _state &>> 16 + } + + public mutating func next() -> UInt64 { + return (_next() &<< 32) | _next() + } +} diff --git a/Sources/DequeModule/Deque+Codable.swift b/Sources/DequeModule/Deque+Codable.swift new file mode 100644 index 00000000..2d98587c --- /dev/null +++ b/Sources/DequeModule/Deque+Codable.swift @@ -0,0 +1,49 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: Encodable where Element: Encodable { + /// Encodes the elements of this deque into the given encoder in an unkeyed + /// container. + /// + /// This function throws an error if any values are invalid for the given + /// encoder's format. + /// + /// - Parameter encoder: The encoder to write data to. + @inlinable + public func encode(to encoder: Encoder) throws { + var container = encoder.unkeyedContainer() + for element in self { + try container.encode(element) + } + } +} + +extension Deque: Decodable where Element: Decodable { + /// Creates a new deque by decoding from the given decoder. + /// + /// This initializer throws an error if reading from the decoder fails, or + /// if the data read is corrupted or otherwise invalid. + /// + /// - Parameter decoder: The decoder to read data from. + @inlinable + public init(from decoder: Decoder) throws { + self.init() + + var container = try decoder.unkeyedContainer() + if let count = container.count { + self.reserveCapacity(count) + } + while !container.isAtEnd { + let element = try container.decode(Element.self) + self.append(element) + } + } +} diff --git a/Sources/DequeModule/Deque+CustomDebugStringConvertible.swift b/Sources/DequeModule/Deque+CustomDebugStringConvertible.swift new file mode 100644 index 00000000..5a8e258f --- /dev/null +++ b/Sources/DequeModule/Deque+CustomDebugStringConvertible.swift @@ -0,0 +1,28 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: CustomDebugStringConvertible { + /// A textual representation of this instance, suitable for debugging. + public var debugDescription: String { + var result = "Deque<\(Element.self)>([" + var first = true + for item in self { + if first { + first = false + } else { + result += ", " + } + debugPrint(item, terminator: "", to: &result) + } + result += "])" + return result + } +} diff --git a/Sources/DequeModule/Deque+CustomReflectable.swift b/Sources/DequeModule/Deque+CustomReflectable.swift new file mode 100644 index 00000000..df919856 --- /dev/null +++ b/Sources/DequeModule/Deque+CustomReflectable.swift @@ -0,0 +1,17 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: CustomReflectable { + /// The custom mirror for this instance. + public var customMirror: Mirror { + Mirror(self, unlabeledChildren: self, displayStyle: .collection) + } +} diff --git a/Sources/DequeModule/Deque+CustomStringConvertible.swift b/Sources/DequeModule/Deque+CustomStringConvertible.swift new file mode 100644 index 00000000..915c339b --- /dev/null +++ b/Sources/DequeModule/Deque+CustomStringConvertible.swift @@ -0,0 +1,28 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: CustomStringConvertible { + /// A textual representation of this instance. + public var description: String { + var result = "[" + var first = true + for item in self { + if first { + first = false + } else { + result += ", " + } + print(item, terminator: "", to: &result) + } + result += "]" + return result + } +} diff --git a/Sources/DequeModule/Deque+Equatable.swift b/Sources/DequeModule/Deque+Equatable.swift new file mode 100644 index 00000000..f71403e7 --- /dev/null +++ b/Sources/DequeModule/Deque+Equatable.swift @@ -0,0 +1,22 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: Equatable where Element: Equatable { + /// Returns a Boolean value indicating whether two values are equal. Two + /// deques are considered equal if they contain the same elements in the same + /// order. + /// + /// - Complexity: O(`min(left.count, right.count)`) + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + return left.elementsEqual(right) + } +} diff --git a/Sources/DequeModule/Deque+ExpressibleByArrayLiteral.swift b/Sources/DequeModule/Deque+ExpressibleByArrayLiteral.swift new file mode 100644 index 00000000..54b6e917 --- /dev/null +++ b/Sources/DequeModule/Deque+ExpressibleByArrayLiteral.swift @@ -0,0 +1,27 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: ExpressibleByArrayLiteral { + /// Creates a new deque from the contents of an array literal. + /// + /// Do not call this initializer directly. It is used by the compiler when + /// you use an array literal. Instead, create a new set using an array + /// literal as its value by enclosing a comma-separated list of values in + /// square brackets. You can use an array literal anywhere a set is expected + /// by the type context. + /// + /// - Parameter elements: A variadic list of elements of the new set. + @inlinable + @inline(__always) + public init(arrayLiteral elements: Element...) { + self.init(elements) + } +} diff --git a/Sources/DequeModule/Deque+Extras.swift b/Sources/DequeModule/Deque+Extras.swift new file mode 100644 index 00000000..9b7edbba --- /dev/null +++ b/Sources/DequeModule/Deque+Extras.swift @@ -0,0 +1,180 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque { + /// Creates a deque with the specified capacity, then calls the given + /// closure with a buffer covering the array's uninitialized memory. + /// + /// Inside the closure, set the `initializedCount` parameter to the number of + /// elements that are initialized by the closure. The memory in the range + /// `buffer[0.., inout Int) throws -> Void + ) rethrows { + self._storage = .init(minimumCapacity: capacity) + try _storage.update { handle in + handle.startSlot = .zero + var count = 0 + var buffer = handle.mutableBuffer(for: .zero ..< _Slot(at: capacity)) + defer { + precondition(count <= capacity, + "Initialized count set to greater than specified capacity") + let b = handle.mutableBuffer(for: .zero ..< _Slot(at: capacity)) + precondition(buffer.baseAddress == b.baseAddress && buffer.count == b.count, + "Initializer relocated Deque storage") + handle.count = count + } + try initializer(&buffer, &count) + } + } +} + +extension Deque { + /// Removes and returns the first element of this deque, if it exists. + /// + /// - Returns: The first element of the original collection if the collection + /// isn't empty; otherwise, `nil`. + /// + /// - Complexity: O(1) when this instance has a unique reference to its + /// underlying storage; O(`count`) otherwise. + @inlinable + public mutating func popFirst() -> Element? { + // FIXME: Add this to the stdlib on BidirectionalCollection + // where Self == Self.SubSequence + guard count > 0 else { return nil } + _storage.ensureUnique() + return _storage.update { + $0.uncheckedRemoveFirst() + } + } + + // Note: `popLast` is implemented by the stdlib as a + // `RangeReplaceableCollection` extension, defined in terms of + // `_customRemoveLast`. + + + /// Adds a new element at the front of the deque. + /// + /// Use this method to append a single element to the front of a deque. + /// + /// var numbers: Deque = [1, 2, 3, 4, 5] + /// numbers.prepend(100) + /// print(numbers) + /// // Prints "[100, 1, 2, 3, 4, 5]" + /// + /// Because deques increase their allocated capacity using an exponential + /// strategy, prepending a single element to a deque is an O(1) operation when + /// averaged over many calls to the `prepend(_:)` method. When a deque has + /// additional capacity and is not sharing its storage with another instance, + /// prepending an element is O(1). When a deque needs to reallocate storage + /// before prepending or its storage is shared with another copy, prepending + /// is O(`count`). + /// + /// - Parameter newElement: The element to prepend to the deque. + /// + /// - Complexity: Amortized O(1). + /// + /// - SeeAlso: `append(_:)` + @inlinable + public mutating func prepend(_ newElement: Element) { + _storage.ensureUnique(minimumCapacity: count + 1) + return _storage.update { + $0.uncheckedPrepend(newElement) + } + } + + /// Adds the elements of a collection to the front of the deque. + /// + /// Use this method to prepend the elements of a collection to the front of + /// this deque. This example prepends the elements of a `Range` instance + /// to a deque of integers. + /// + /// var numbers: Deque = [1, 2, 3, 4, 5] + /// numbers.prepend(contentsOf: 10...15) + /// print(numbers) + /// // Prints "[10, 11, 12, 13, 14, 15, 1, 2, 3, 4, 5]" + /// + /// - Parameter newElements: The elements to prepend to the deque. + /// + /// - Complexity: Amortized O(`newElements.count`). + /// + /// - SeeAlso: `append(contentsOf:)` + @inlinable + public mutating func prepend(contentsOf newElements: C) where C.Element == Element { + let done: Void? = newElements.withContiguousStorageIfAvailable { source in + _storage.ensureUnique(minimumCapacity: count + source.count) + _storage.update { $0.uncheckedPrepend(contentsOf: source) } + } + guard done == nil else { return } + + let c = newElements.count + guard c > 0 else { return } + _storage.ensureUnique(minimumCapacity: count + c) + _storage.update { target in + let gaps = target.availableSegments().suffix(c) + gaps.initialize(from: newElements) + target.count += c + target.startSlot = target.slot(target.startSlot, offsetBy: -c) + } + } + + /// Adds the elements of a sequence to the front of the deque. + /// + /// Use this method to prepend the elements of a sequence to the front of this + /// deque. This example prepends the elements of a `Range` instance to a + /// deque of integers. + /// + /// var numbers: Deque = [1, 2, 3, 4, 5] + /// numbers.prepend(contentsOf: 10...15) + /// print(numbers) + /// // Prints "[10, 11, 12, 13, 14, 15, 1, 2, 3, 4, 5]" + /// + /// - Parameter newElements: The elements to prepend to the deque. + /// + /// - Complexity: Amortized O(`newElements.count`). + /// + /// - SeeAlso: `append(contentsOf:)` + @inlinable + public mutating func prepend(contentsOf newElements: S) where S.Element == Element { + let originalCount = self.count + self.append(contentsOf: newElements) + let newCount = self.count + let c = newCount - originalCount + _storage.update { target in + target.startSlot = target.slot(forOffset: originalCount) + target.count = target.capacity + target.closeGap(offsets: c ..< c + (target.capacity - newCount)) + assert(target.count == newCount) + } + } +} diff --git a/Sources/DequeModule/Deque+Hashable.swift b/Sources/DequeModule/Deque+Hashable.swift new file mode 100644 index 00000000..de050c90 --- /dev/null +++ b/Sources/DequeModule/Deque+Hashable.swift @@ -0,0 +1,24 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: Hashable where Element: Hashable { + /// Hashes the essential components of this value by feeding them into the + /// given hasher. + /// + /// Complexity: O(`count`) + @inlinable + public func hash(into hasher: inout Hasher) { + hasher.combine(count) // discriminator + for element in self { + hasher.combine(element) + } + } +} diff --git a/Sources/DequeModule/Deque+MutableCollection.swift b/Sources/DequeModule/Deque+MutableCollection.swift new file mode 100644 index 00000000..0e670c3d --- /dev/null +++ b/Sources/DequeModule/Deque+MutableCollection.swift @@ -0,0 +1,83 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: MutableCollection { + /// Exchanges the values at the specified indices of the collection. + /// + /// Both parameters must be valid indices of the collection and not equal to + /// `endIndex`. Passing the same index as both `i` and `j` has no effect. + /// + /// - Parameters: + /// - i: The index of the first value to swap. + /// - j: The index of the second value to swap. + /// + /// - Complexity: O(1) when this instance has a unique reference to its + /// underlying storage; O(`count`) otherwise. + @inlinable + public mutating func swapAt(_ i: Index, _ j: Index) { + precondition(i >= 0 && i < count, "Index out of bounds") + precondition(j >= 0 && j < count, "Index out of bounds") + _storage.ensureUnique() + _storage.update { handle in + let slot1 = handle.slot(forOffset: i) + let slot2 = handle.slot(forOffset: j) + handle.mutableBuffer.swapAt(slot1.position, slot2.position) + } + } + + // FIXME: Implement `partition(by:)` by making storage contiguous, + // and partitioning that. + + /// Call `body(b)`, where `b` is an unsafe buffer pointer to the deque's + /// mutable contiguous storage. If the deque's contents aren't stored + /// contiguously, `body` is not called and `nil` is returned. The supplied + /// buffer pointer is only valid for the duration of the call. + /// + /// Often, the optimizer can eliminate bounds- and uniqueness-checks within an + /// algorithm, but when that fails, invoking the same algorithm on the unsafe + /// buffer supplied to `body` lets you trade safety for speed. + /// + /// - Parameters: + /// - body: The function to invoke. + /// + /// - Returns: The value returned by `body`, or `nil` if `body` wasn't called. + /// + /// - Complexity: O(1) when this instance has a unique reference to its + /// underlying storage; O(`count`) otherwise. (Not counting the call to + /// `body`.) + @inlinable + public mutating func withContiguousMutableStorageIfAvailable( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + _storage.ensureUnique() + return try _storage.update { handle in + let endSlot = handle.startSlot.advanced(by: handle.count) + guard endSlot.position <= handle.capacity else { + // FIXME: Rotate storage such that it becomes contiguous. + return nil + } + let original = handle.mutableBuffer(for: handle.startSlot ..< endSlot) + var extract = original + defer { + precondition(extract.baseAddress == original.baseAddress && extract.count == original.count, + "Closure must not replace the provided buffer") + } + return try body(&extract) + } + } + + @inlinable + public mutating func _withUnsafeMutableBufferPointerIfSupported( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + return try withContiguousMutableStorageIfAvailable(body) + } +} diff --git a/Sources/DequeModule/Deque+RandomAccessCollection.swift b/Sources/DequeModule/Deque+RandomAccessCollection.swift new file mode 100644 index 00000000..e21ad4e0 --- /dev/null +++ b/Sources/DequeModule/Deque+RandomAccessCollection.swift @@ -0,0 +1,243 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: RandomAccessCollection { + public typealias Index = Int + public typealias SubSequence = Slice + + /// The number of elements in the deque. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var count: Int { _storage.count } + + /// The position of the first element in a nonempty deque. + /// + /// For an instance of `Deque`, `startIndex` is always zero. If the deque is + /// empty, `startIndex` is equal to `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var startIndex: Index { 0 } + + /// The deque’s “past the end” position—that is, the position one greater than + /// the last valid subscript argument. + /// + /// For an instance of `Deque`, `endIndex` is always equal to its `count`. If + /// the deque is empty, `endIndex` is equal to `startIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var endIndex: Index { count } + + /// Returns the position immediately after the given index. + /// + /// - Parameter `i`: A valid index of the deque. `i` must be less than + /// `endIndex`. + /// + /// - Returns: The next valid index immediately after `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(after i: Index) -> Index { + // Note: Like `Array`, index manipulation methods on deques don't trap on + // invalid indices. (Indices are still validated on element access.) + return i + 1 + } + + /// Replaces the given index with its successor. + /// + /// - Parameter `i`: A valid index of the deque. `i` must be less than + /// `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(after i: inout Index) { + // Note: Like `Array`, index manipulation methods on deques + // don't trap on invalid indices. + // (Indices are still validated on element access.) + i += 1 + } + + /// Returns the position immediately before the given index. + /// + /// - Parameter `i`: A valid index of the deque. `i` must be greater than + /// `startIndex`. + /// + /// - Returns: The preceding valid index immediately before `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(before i: Index) -> Index { + // Note: Like `Array`, index manipulation methods on deques don't trap on + // invalid indices. (Indices are still validated on element access.) + return i - 1 + } + + /// Replaces the given index with its predecessor. + /// + /// - Parameter `i`: A valid index of the deque. `i` must be greater than `startIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(before i: inout Index) { + // Note: Like `Array`, index manipulation methods on deques don't trap on + // invalid indices. (Indices are still validated on element access.) + i -= 1 + } + + /// Returns an index that is the specified distance from the given index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection. + /// + /// - Parameters: + /// - i: A valid index of the deque. + /// - `distance`: The distance by which to offset `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`. If `distance` + /// is positive, this is the same value as the result of `distance` calls + /// to `index(after:)`. If `distance` is negative, this is the same value + /// as the result of `abs(distance)` calls to `index(before:)`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(_ i: Index, offsetBy distance: Int) -> Index { + // Note: Like `Array`, index manipulation methods on deques don't trap on + // invalid indices. (Indices are still validated on element access.) + return i + distance + } + + /// Returns an index that is the specified distance from the given index, + /// unless that distance is beyond a given limiting index. + /// + /// - Parameters: + /// - i: A valid index of the array. + /// - distance: The distance to offset `i`. + /// - limit: A valid index of the deque to use as a limit. + /// If `distance > 0`, then `limit` has no effect it is less than `i`. + /// Likewise, if `distance < 0`, then `limit` has no effect if it is + /// greater than `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`, unless that + /// index would be beyond `limit` in the direction of movement. In that + /// case, the method returns `nil`. + /// + /// - Complexity: O(1) + @inlinable + public func index( + _ i: Int, + offsetBy distance: Int, + limitedBy limit: Int + ) -> Int? { + // Note: Like `Array`, index manipulation methods on deques + // don't trap on invalid indices. + // (Indices are still validated on element access.) + let l = limit - i + if distance > 0 ? l >= 0 && l < distance : l <= 0 && distance < l { + return nil + } + return i + distance + } + + + /// Returns the distance between two indices. + /// + /// - Parameters: + /// - start: A valid index of the collection. + /// - end: Another valid index of the collection. + /// + /// - Returns: The distance between `start` and `end`. If `end` is equal to + /// `start`, the result is zero. Otherwise the result is positive if `end` + /// is greater than `start`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func distance(from start: Index, to end: Index) -> Int { + // Note: Like `Array`, index manipulation method on deques + // don't trap on invalid indices. + // (Indices are still validated on element access.) + return end - start + } + + /// Accesses the element at the specified position. + /// + /// - Parameters: + /// - index: The position of the element to access. `index` must be greater + /// than or equal to `startIndex` and less than `endIndex`. + /// + /// - Complexity: Reading an element from a deque is O(1). Writing is O(1) + /// unless the deque’s storage is shared with another deque, in which case + /// writing is O(`count`). + @inlinable + public subscript(index: Index) -> Element { + get { + precondition(index >= 0 && index < count, "Index out of bounds") + return _storage.read { $0.ptr(at: $0.slot(forOffset: index)).pointee } + } + set { + precondition(index >= 0 && index < count, "Index out of bounds") + _storage.ensureUnique() + _storage.update { handle in + let slot = handle.slot(forOffset: index) + handle.ptr(at: slot).pointee = newValue + } + } + _modify { + precondition(index >= 0 && index < count, "Index out of bounds") + _storage.ensureUnique() + // We technically aren't supposed to escape storage pointers out of a + // managed buffer, so we escape a `(slot, value)` pair instead, leaving + // the corresponding slot temporarily uninitialized. + var (slot, value) = _storage.update { handle -> (_Slot, Element) in + let slot = handle.slot(forOffset: index) + return (slot, handle.ptr(at: slot).move()) + } + defer { + _storage.update { handle in + handle.ptr(at: slot).initialize(to: value) + } + } + yield &value + } + } + + /// Accesses a contiguous subrange of the deque's elements. + /// + /// - Parameters: + /// - bounds: A range of the deque's indices. The bounds of the range must + /// be valid indices of the deque (including the `endIndex`). + /// + /// The accessed slice uses the same indices for the same elements as the + /// original collection. + @inlinable + public subscript(bounds: Range) -> Slice { + get { + precondition(bounds.lowerBound >= 0 && bounds.upperBound <= count, + "Invalid bounds") + return Slice(base: self, bounds: bounds) + } + set(source) { + precondition(bounds.lowerBound >= 0 && bounds.upperBound <= count, + "Invalid bounds") + self.replaceSubrange(bounds, with: source) + } + } +} diff --git a/Sources/DequeModule/Deque+RangeReplaceableCollection.swift b/Sources/DequeModule/Deque+RangeReplaceableCollection.swift new file mode 100644 index 00000000..0bde464b --- /dev/null +++ b/Sources/DequeModule/Deque+RangeReplaceableCollection.swift @@ -0,0 +1,437 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: RangeReplaceableCollection { + /// Creates a new, empty deque. + /// + /// This is equivalent to initializing with an empty array literal. + /// For example: + /// + /// let deque1 = Deque() + /// print(deque1.isEmpty) // true + /// + /// let deque2: Deque = [] + /// print(deque2.isEmpty) // true + /// + /// - Complexity: O(1) + @inlinable + public init() { + _storage = _Storage() + } + + /// Replaces a range of elements with the elements in the specified + /// collection. + /// + /// This method has the effect of removing the specified range of elements + /// from the deque and inserting the new elements at the same location. The + /// number of new elements need not match the number of elements being + /// removed. + /// + /// - Parameters: + /// - subrange: The subrange of the deque to replace. The bounds of the + /// subrange must be valid indices of the deque (including the + /// `endIndex`). + /// - newElements: The new elements to add to the deque. + /// + /// - Complexity: O(`self.count + newElements.count`). If the operation needs + /// to change the size of the deque, it minimizes the number of existing + /// items that need to be moved by shifting elements either before or after + /// `subrange`. + @inlinable + public mutating func replaceSubrange( + _ subrange: Range, + with newElements: __owned C + ) where C.Element == Element { + precondition(subrange.lowerBound >= 0 && subrange.upperBound <= count, "Index range out of bounds") + let removalCount = subrange.count + let insertionCount = newElements.count + let deltaCount = insertionCount - removalCount + _storage.ensureUnique(minimumCapacity: count + deltaCount) + + let replacementCount = Swift.min(removalCount, insertionCount) + let targetCut = subrange.lowerBound + replacementCount + let sourceCut = newElements.index(newElements.startIndex, offsetBy: replacementCount) + + _storage.update { target in + target.uncheckedReplaceInPlace( + inOffsets: subrange.lowerBound ..< targetCut, + with: newElements[.. 0 { + target.uncheckedInsert( + contentsOf: newElements[sourceCut...], + count: deltaCount, + atOffset: targetCut) + } + } + } + + /// Reserves enough space to store the specified number of elements. + /// + /// If you are adding a known number of elements to a deque, use this method + /// to avoid multiple reallocations. It ensures that the deque has unique + /// storage, with space allocated for at least the requested number of + /// elements. + /// + /// - Parameters: + /// - minimumCapacity: The requested number of elements to store. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func reserveCapacity(_ minimumCapacity: Int) { + _storage.ensureUnique(minimumCapacity: minimumCapacity, linearGrowth: true) + } + + /// Creates a new deque containing the specified number of a single, repeated + /// value. + /// + /// - Parameters: + /// - repeatedValue: The element to repeat. + /// - count: The number of times to repeat the element. `count` must be zero + /// or greater. + /// + /// - Complexity: O(`count`) + @inlinable + public init(repeating repeatedValue: Element, count: Int) { + precondition(count >= 0) + self.init(minimumCapacity: count) + _storage.update { handle in + assert(handle.startSlot == .zero) + if count > 0 { + handle.ptr(at: .zero).initialize(repeating: repeatedValue, count: count) + } + handle.count = count + } + } + + /// Creates a deque containing the elements of a sequence. + /// + /// - Parameters: + /// - elements: The sequence of elements to turn into a deque. + /// + /// - Complexity: O(*n*), where *n* is the number of elements in the sequence. + @inlinable + public init(_ elements: S) where S.Element == Element { + self.init() + self.append(contentsOf: elements) + } + + /// Creates a deque containing the elements of a collection. + /// + /// - Parameters: + /// - elements: The collection of elements to turn into a deque. + /// + /// - Complexity: O(`elements.count`) + @inlinable + public init(_ elements: C) where C.Element == Element { + let c = elements.count + guard c > 0 else { _storage = _Storage(); return } + self._storage = _Storage(minimumCapacity: c) + _storage.update { handle in + assert(handle.startSlot == .zero) + let target = handle.mutableBuffer(for: .zero ..< _Slot(at: c)) + let done: Void? = elements.withContiguousStorageIfAvailable { source in + target._initialize(from: source) + } + if done == nil { + target._initialize(from: elements) + } + handle.count = c + } + } + + /// Adds a new element at the end of the deque. + /// + /// Use this method to append a single element to the end of a deque. + /// + /// var numbers: Deque = [1, 2, 3, 4, 5] + /// numbers.append(100) + /// print(numbers) + /// // Prints "[1, 2, 3, 4, 5, 100]" + /// + /// Because deques increase their allocated capacity using an exponential + /// strategy, appending a single element to a deque is an O(1) operation when + /// averaged over many calls to the `append(_:)` method. When a deque has + /// additional capacity and is not sharing its storage with another instance, + /// appending an element is O(1). When a deque needs to reallocate storage + /// before prepending or its storage is shared with another copy, appending is + /// O(`count`). + /// + /// - Parameters: + /// - newElement: The element to append to the deque. + /// + /// - Complexity: Amortized O(1) + /// + /// - SeeAlso: `prepend(_:)` + @inlinable + public mutating func append(_ newElement: Element) { + _storage.ensureUnique(minimumCapacity: count + 1) + _storage.update { + $0.uncheckedAppend(newElement) + } + } + + /// Adds the elements of a sequence to the end of the deque. + /// + /// Use this method to append the elements of a sequence to the front of this + /// deque. This example appends the elements of a `Range` instance to a + /// deque of integers. + /// + /// var numbers: Deque = [1, 2, 3, 4, 5] + /// numbers.append(contentsOf: 10...15) + /// print(numbers) + /// // Prints "[1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15]" + /// + /// - Parameter newElements: The elements to append to the deque. + /// + /// - Complexity: Amortized O(`newElements.count`). + @inlinable + public mutating func append(contentsOf newElements: S) where S.Element == Element { + let done: Void? = newElements.withContiguousStorageIfAvailable { source in + _storage.ensureUnique(minimumCapacity: count + source.count) + _storage.update { $0.uncheckedAppend(contentsOf: source) } + } + if done != nil { + return + } + + let underestimatedCount = newElements.underestimatedCount + reserveCapacity(count + underestimatedCount) + var it: S.Iterator = _storage.update { target in + let gaps = target.availableSegments() + let (it, copied) = gaps.initialize(fromSequencePrefix: newElements) + target.count += copied + return it + } + while let next = it.next() { + _storage.ensureUnique(minimumCapacity: count + 1) + _storage.update { target in + target.uncheckedAppend(next) + let gaps = target.availableSegments() + target.count += gaps.initialize(fromPrefixOf: &it) + } + } + } + + /// Adds the elements of a collection to the end of the deque. + /// + /// Use this method to append the elements of a collection to the front of + /// this deque. This example appends the elements of a `Range` instance + /// to a deque of integers. + /// + /// var numbers: Deque = [1, 2, 3, 4, 5] + /// numbers.append(contentsOf: 10...15) + /// print(numbers) + /// // Prints "[1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15]" + /// + /// - Parameter newElements: The elements to append to the deque. + /// + /// - Complexity: Amortized O(`newElements.count`). + @inlinable + public mutating func append(contentsOf newElements: C) where C.Element == Element { + let done: Void? = newElements.withContiguousStorageIfAvailable { source in + _storage.ensureUnique(minimumCapacity: count + source.count) + _storage.update { $0.uncheckedAppend(contentsOf: source) } + } + guard done == nil else { return } + + let c = newElements.count + guard c > 0 else { return } + reserveCapacity(count + c) + _storage.update { target in + let gaps = target.availableSegments().prefix(c) + gaps.initialize(from: newElements) + target.count += c + } + } + + /// Inserts a new element at the specified position. + /// + /// The new element is inserted before the element currently at the specified + /// index. If you pass the deque’s `endIndex` as the `index` parameter, the + /// new element is appended to the deque. + /// + /// - Parameters: + /// - newElement: The new element to insert into the deque. + /// - index: The position at which to insert the new element. `index` must + /// be a valid index of the deque (including `endIndex`). + /// + /// - Complexity: O(`count`). The operation shifts existing elements either + /// towards the beginning or the end of the deque to minimize the number of + /// elements that need to be moved. When inserting at the start or the end, + /// this reduces the complexity to amortized O(1). + @inlinable + public mutating func insert(_ newElement: Element, at index: Index) { + precondition(index >= 0 && index <= count, + "Can't insert element at invalid index") + _storage.ensureUnique(minimumCapacity: count + 1) + _storage.update { target in + if index == 0 { + target.uncheckedPrepend(newElement) + return + } + if index == count { + target.uncheckedAppend(newElement) + return + } + let gap = target.openGap(ofSize: 1, atOffset: index) + assert(gap.first.count == 1) + gap.first.baseAddress!.initialize(to: newElement) + } + } + + /// Inserts the elements of a collection into the deque at the specified + /// position. + /// + /// The new elements are inserted before the element currently at the + /// specified index. If you pass the deque's `endIndex` property as the + /// `index` parameter, the new elements are appended to the deque. + /// + /// - Parameters: + /// - newElements: The new elements to insert into the deque. + /// - index: The position at which to insert the new elements. `index` must + /// be a valid index of the deque (including `endIndex`). + /// + /// - Complexity: O(`count + newElements.count`). The operation shifts + /// existing elements either towards the beginning or the end of the deque + /// to minimize the number of elements that need to be moved. When + /// inserting at the start or the end, this reduces the complexity to + /// amortized O(1). + @inlinable + public mutating func insert( + contentsOf newElements: __owned C, at index: Index + ) where C.Element == Element { + precondition(index >= 0 && index <= count, + "Can't insert elements at an invalid index") + let newCount = newElements.count + _storage.ensureUnique(minimumCapacity: count + newCount) + _storage.update { target in + target.uncheckedInsert(contentsOf: newElements, count: newCount, atOffset: index) + } + } + + /// Removes and returns the element at the specified position. + /// + /// To close the resulting gap, all elements following the specified position + /// are (logically) moved up by one index position. (Internally, the deque may + /// actually decide to shift previous elements forward instead to minimize the + /// number of elements that need to be moved.) + /// + /// - Parameters: + /// - index: The position of the element to remove. `index` must be a valid + /// index of the array. + /// + /// - Returns: The element originally at the specified index. + /// + /// - Complexity: O(`count`). Removing elements from the start or end of the + /// deque costs O(1) if the deque's storage isn't shared. + @inlinable + @discardableResult + public mutating func remove(at index: Index) -> Element { + precondition(index >= 0 && index < self.count, "Index out of bounds") + // FIXME: Implement storage shrinking + _storage.ensureUnique() + return _storage.update { target in + // FIXME: Add direct implementation & see if it makes a difference + let result = self[index] + target.uncheckedRemove(offsets: index ..< index + 1) + return result + } + } + + /// Removes the elements in the specified subrange from the deque. + + /// All elements following the specified range are (logically) moved up to + /// close the resulting gap. (Internally, the deque may actually decide to + /// shift previous elements forward instead to minimize the number of elements + /// that need to be moved.) + /// + /// - Parameters: + /// - bounds: The range of the collection to be removed. The bounds of the + /// range must be valid indices of the collection. + /// + /// - Complexity: O(`count`). Removing elements from the start or end of the + /// deque costs O(`bounds.count`) if the deque's storage isn't shared. + @inlinable + public mutating func removeSubrange(_ bounds: Range) { + precondition(bounds.lowerBound >= 0 && bounds.upperBound <= self.count, + "Index range out of bounds") + _storage.ensureUnique() + _storage.update { $0.uncheckedRemove(offsets: bounds) } + } + + @inlinable + public mutating func _customRemoveLast() -> Element? { + precondition(!isEmpty, "Cannot remove last element of an empty Deque") + _storage.ensureUnique() + return _storage.update { $0.uncheckedRemoveLast() } + } + + @inlinable + public mutating func _customRemoveLast(_ n: Int) -> Bool { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the Collection") + _storage.ensureUnique() + _storage.update { $0.uncheckedRemoveLast(n) } + return true + } + + /// Removes and returns the first element of the deque. + /// + /// The collection must not be empty. + /// + /// - Returns: The removed element. + /// + /// - Complexity: O(1) if the underlying storage isn't shared; otherwise + /// O(`count`). + @inlinable + @discardableResult + public mutating func removeFirst() -> Element { + precondition(!isEmpty, "Cannot remove first element of an empty Deque") + _storage.ensureUnique() + return _storage.update { $0.uncheckedRemoveFirst() } + } + + /// Removes the specified number of elements from the beginning of the deque. + /// + /// - Parameter n: The number of elements to remove from the deque. `n` must + /// be greater than or equal to zero and must not exceed the number of + /// elements in the deque. + /// + /// - Complexity: O(`n`) if the underlying storage isn't shared; otherwise + /// O(`count`). + @inlinable + public mutating func removeFirst(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the Collection") + _storage.ensureUnique() + return _storage.update { $0.uncheckedRemoveFirst(n) } + } + + /// Removes all elements from the deque. + /// + /// - Parameter keepCapacity: Pass true to keep the existing storage capacity + /// of the deque after removing its elements. The default value is false. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll(keepingCapacity keepCapacity: Bool = false) { + if keepCapacity { + _storage.ensureUnique() + _storage.update { $0.uncheckedRemoveAll() } + } else { + self = Deque() + } + } +} diff --git a/Sources/DequeModule/Deque+Sequence.swift b/Sources/DequeModule/Deque+Sequence.swift new file mode 100644 index 00000000..e05fc977 --- /dev/null +++ b/Sources/DequeModule/Deque+Sequence.swift @@ -0,0 +1,160 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque: Sequence { + // Implementation note: we could also use the default `IndexingIterator` here. + // This custom implementation performs direct storage access to eliminate any + // and all index validation overhead. It also optimizes away repeated + // conversions from indices to storage slots. + + /// An iterator over the members of a deque. + public struct Iterator: IteratorProtocol { + @usableFromInline + internal var _storage: Deque._Storage + + @usableFromInline + internal var _nextSlot: _Slot + + @usableFromInline + internal var _endSlot: _Slot + + @inlinable + internal init(_storage: Deque._Storage, start: _Slot, end: _Slot) { + self._storage = _storage + self._nextSlot = start + self._endSlot = end + } + + @inlinable + internal init(_base: Deque) { + self = _base._storage.read { handle in + let start = handle.startSlot + let end = Swift.min(start.advanced(by: handle.count), handle.limSlot) + return Self(_storage: _base._storage, start: start, end: end) + } + } + + @inlinable + internal init(_base: Deque, from index: Index) { + assert(index <= _base.count) + self = _base._storage.read { handle in + let start = handle.slot(forOffset: index) + if index == _base.count { + return Self(_storage: _base._storage, start: start, end: start) + } + var end = handle.endSlot + if start >= end { end = handle.limSlot } + return Self(_storage: _base._storage, start: start, end: end) + } + } + + @inlinable + @inline(never) + internal mutating func _swapSegment() -> Bool { + assert(_nextSlot == _endSlot) + return _storage.read { handle in + let end = handle.endSlot + if end == .zero || end == _nextSlot { + return false + } + _endSlot = end + _nextSlot = .zero + return true + } + } + + /// Advances to the next element and returns it, or `nil` if no next element + /// exists. + /// + /// Once `nil` has been returned, all subsequent calls return `nil`. + @inlinable + public mutating func next() -> Element? { + if _nextSlot == _endSlot { + guard _swapSegment() else { return nil } + } + assert(_nextSlot < _endSlot) + let slot = _nextSlot + _nextSlot = _nextSlot.advanced(by: 1) + return _storage.read { handle in + return handle.ptr(at: slot).pointee + } + } + } + + /// Returns an iterator over the elements of the deque. + /// + /// - Complexity: O(1) + @inlinable + public func makeIterator() -> Iterator { + Iterator(_base: self) + } + + @inlinable + public __consuming func _copyToContiguousArray() -> ContiguousArray { + ContiguousArray(unsafeUninitializedCapacity: count) { target, count in + _storage.read { source in + let segments = source.segments() + let c = segments.first.count + target[.. + ) -> (Iterator, UnsafeMutableBufferPointer.Index) { + _storage.read { source in + let segments = source.segments() + let c1 = Swift.min(segments.first.count, target.count) + target[.. c1, let second = segments.second else { + return (Iterator(_base: self, from: c1), c1) + } + let c2 = Swift.min(second.count, target.count - c1) + target[c1 ..< c1 + c2]._rebased()._initialize(from: second.prefix(c2)._rebased()) + return (Iterator(_base: self, from: c1 + c2), c1 + c2) + } + } + + /// Call `body(b)`, where `b` is an unsafe buffer pointer to the deque's + /// contiguous storage, if available. If the deque's contents aren't stored + /// contiguously, `body` is not called and `nil` is returned. The supplied + /// buffer pointer is only valid for the duration of the call. + /// + /// Often, the optimizer can eliminate bounds- and uniqueness-checks within an + /// algorithm, but when that fails, invoking the same algorithm on the unsafe + /// buffer supplied to `body` lets you trade safety for speed. + /// + /// - Parameters: + /// - body: The function to invoke. + /// + /// - Returns: The value returned by `body`, or `nil` if `body` wasn't called. + /// + /// - Complexity: O(1) when this instance has a unique reference to its + /// underlying storage; O(`count`) otherwise. + @inlinable + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + return try _storage.read { handle in + let endSlot = handle.startSlot.advanced(by: handle.count) + guard endSlot.position <= handle.capacity else { return nil } + return try body(handle.buffer(for: handle.startSlot ..< endSlot)) + } + } +} diff --git a/Sources/DequeModule/Deque+Testing.swift b/Sources/DequeModule/Deque+Testing.swift new file mode 100644 index 00000000..00692981 --- /dev/null +++ b/Sources/DequeModule/Deque+Testing.swift @@ -0,0 +1,76 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// This file contains exported but non-public entry points to support clear box +// testing. + +extension Deque { + /// The maximum number of elements this deque is currently able to store + /// without reallocating its storage buffer. + /// + /// This information isn't exposed as public, as the returned value isn't + /// guaranteed to be stable, and may even differ between equal deques, + /// violating value semantics. + /// + /// This property isn't intended to be used outside of `Deque`'s own test + /// target. + @_spi(Testing) + public var _capacity: Int { + _storage.capacity + } + + /// The number of the storage slot in this deque that holds the first element. + /// (Or would hold it after an insertion in case the deque is currently + /// empty.) + /// + /// This property isn't intended to be used outside of `Deque`'s own test + /// target. + @_spi(Testing) + public var _startSlot: Int { + _storage.startSlot.position + } + + /// Constructs a deque instance of the specified contents and layout. Exposed + /// as public to allow exhaustive input/output tests for `Deque`'s members. + /// This isn't intended to be used outside of `Deque`'s own test target. + @_spi(Testing) + public init( + _capacity capacity: Int, + startSlot: Int, + contents: S + ) where S.Element == Element { + let contents = ContiguousArray(contents) + precondition(capacity >= 0) + precondition(startSlot >= 0 && (startSlot < capacity || (capacity == 0 && startSlot == 0))) + precondition(contents.count <= capacity) + let startSlot = _Slot(at: startSlot) + let buffer = _DequeBuffer.create(minimumCapacity: capacity) { _ in + _DequeBufferHeader(capacity: capacity, count: contents.count, startSlot: startSlot) + } + let storage = Deque._Storage(unsafeDowncast(buffer, to: _DequeBuffer.self)) + if contents.count > 0 { + contents.withUnsafeBufferPointer { source in + storage.update { target in + let segments = target.mutableSegments() + let c = segments.first.count + segments.first._initialize(from: source.prefix(c)._rebased()) + if let second = segments.second { + second._initialize(from: source.dropFirst(c)._rebased()) + } + } + } + } + self.init(_storage: storage) + assert(self._capacity == capacity) + assert(self._startSlot == startSlot.position) + assert(self.count == contents.count) + } +} diff --git a/Sources/DequeModule/Deque._Storage.swift b/Sources/DequeModule/Deque._Storage.swift new file mode 100644 index 00000000..4953872e --- /dev/null +++ b/Sources/DequeModule/Deque._Storage.swift @@ -0,0 +1,208 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque { + @usableFromInline + struct _Storage { + @usableFromInline + internal typealias _Buffer = ManagedBufferPointer<_DequeBufferHeader, Element> + + @usableFromInline + internal var _buffer: _Buffer + + @inlinable + @inline(__always) + internal init(_buffer: _Buffer) { + self._buffer = _buffer + } + } +} + +extension Deque._Storage: CustomStringConvertible { + @usableFromInline + internal var description: String { + "Deque<\(Element.self)>._Storage\(_buffer.header)" + } +} + +extension Deque._Storage { + @inlinable + internal init() { + self.init(_buffer: _Buffer(unsafeBufferObject: _emptyDequeStorage)) + } + + @inlinable + internal init(_ object: _DequeBuffer) { + self.init(_buffer: _Buffer(unsafeBufferObject: object)) + } + + @inlinable + internal init(minimumCapacity: Int) { + let object = _DequeBuffer.create( + minimumCapacity: minimumCapacity, + makingHeaderWith: { object in + _DequeBufferHeader(capacity: object.capacity, count: 0, startSlot: .zero) + }) + self.init(_buffer: _Buffer(unsafeBufferObject: object)) + } +} + +extension Deque._Storage { + #if COLLECTIONS_INTERNAL_CHECKS + @usableFromInline @inline(never) @_effects(releasenone) + internal func _checkInvariants() { + _buffer.withUnsafeMutablePointerToHeader { $0.pointee._checkInvariants() } + } + #else + @inlinable @inline(__always) + internal func _checkInvariants() {} + #endif // COLLECTIONS_INTERNAL_CHECKS +} + +extension Deque._Storage { + @inlinable + @inline(__always) + internal var identity: AnyObject { _buffer.buffer } + + + @inlinable + @inline(__always) + internal var capacity: Int { + _buffer.withUnsafeMutablePointerToHeader { $0.pointee.capacity } + } + + @inlinable + @inline(__always) + internal var count: Int { + _buffer.withUnsafeMutablePointerToHeader { $0.pointee.count } + } + + @inlinable + @inline(__always) + internal var startSlot: _DequeSlot { + _buffer.withUnsafeMutablePointerToHeader { $0.pointee.startSlot + } + } +} + +extension Deque._Storage { + @usableFromInline + internal typealias Index = Int + + @usableFromInline + internal typealias _UnsafeHandle = Deque._UnsafeHandle + + @inlinable + @inline(__always) + internal func read(_ body: (_UnsafeHandle) throws -> R) rethrows -> R { + try _buffer.withUnsafeMutablePointers { header, elements in + let handle = _UnsafeHandle(header: header, + elements: elements, + isMutable: false) + return try body(handle) + } + } + + @inlinable + @inline(__always) + internal func update(_ body: (_UnsafeHandle) throws -> R) rethrows -> R { + try _buffer.withUnsafeMutablePointers { header, elements in + let handle = _UnsafeHandle(header: header, + elements: elements, + isMutable: true) + return try body(handle) + } + } +} + +extension Deque._Storage { + /// Return a boolean indicating whether this storage instance is known to have + /// a single unique reference. If this method returns true, then it is safe to + /// perform in-place mutations on the deque. + @inlinable + @inline(__always) + internal mutating func isUnique() -> Bool { + _buffer.isUniqueReference() + } + + /// Ensure that this storage refers to a uniquely held buffer by copying + /// elements if necessary. + @inlinable + @inline(__always) + internal mutating func ensureUnique() { + if isUnique() { return } + self._makeUniqueCopy() + } + + @inlinable + @inline(never) + internal mutating func _makeUniqueCopy() { + self = self.read { $0.copyElements() } + } + + /// The growth factor to use to increase storage size to make place for an + /// insertion. + @inlinable + @inline(__always) + internal static var growthFactor: Double { 1.5 } + + @usableFromInline + internal func _growCapacity( + to minimumCapacity: Int, + linearly: Bool + ) -> Int { + if linearly { return Swift.max(capacity, minimumCapacity) } + return Swift.max(Int((Self.growthFactor * Double(capacity)).rounded(.up)), + minimumCapacity) + } + + /// Ensure that we have a uniquely referenced buffer with enough space to + /// store at least `minimumCapacity` elements. + /// + /// - Parameter minimumCapacity: The minimum number of elements the buffer + /// needs to be able to hold on return. + /// + /// - Parameter linearGrowth: If true, then don't use an exponential growth + /// factor when reallocating the buffer -- just allocate space for the + /// requested number of elements + @inlinable + @inline(__always) + internal mutating func ensureUnique( + minimumCapacity: Int, + linearGrowth: Bool = false + ) { + let unique = isUnique() + if _slowPath(capacity < minimumCapacity || !unique) { + _ensureUnique(minimumCapacity: minimumCapacity, linearGrowth: linearGrowth) + } + } + + @inlinable + internal mutating func _ensureUnique( + minimumCapacity: Int, + linearGrowth: Bool + ) { + if capacity >= minimumCapacity { + assert(!self.isUnique()) + self = self.read { $0.copyElements() } + } else if isUnique() { + let minimumCapacity = _growCapacity(to: minimumCapacity, linearly: linearGrowth) + self = self.update { source in + source.moveElements(minimumCapacity: minimumCapacity) + } + } else { + let minimumCapacity = _growCapacity(to: minimumCapacity, linearly: linearGrowth) + self = self.read { source in + source.copyElements(minimumCapacity: minimumCapacity) + } + } + } +} diff --git a/Sources/DequeModule/Deque._UnsafeHandle.swift b/Sources/DequeModule/Deque._UnsafeHandle.swift new file mode 100644 index 00000000..ffa633d6 --- /dev/null +++ b/Sources/DequeModule/Deque._UnsafeHandle.swift @@ -0,0 +1,822 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Deque { + @usableFromInline + internal struct _UnsafeHandle { + @usableFromInline + let _header: UnsafeMutablePointer<_DequeBufferHeader> + @usableFromInline + let _elements: UnsafeMutablePointer + #if DEBUG + @usableFromInline + let _isMutable: Bool + #endif + + @inlinable + @inline(__always) + init( + header: UnsafeMutablePointer<_DequeBufferHeader>, + elements: UnsafeMutablePointer, + isMutable: Bool + ) { + self._header = header + self._elements = elements + #if DEBUG + self._isMutable = isMutable + #endif + } + } +} + +extension Deque._UnsafeHandle { + @inlinable + @inline(__always) + func assertMutable() { + #if DEBUG + assert(_isMutable) + #endif + } +} + +extension Deque._UnsafeHandle { + @usableFromInline + internal typealias Slot = _DequeSlot + + @inlinable + @inline(__always) + var header: _DequeBufferHeader { + _header.pointee + } + + @inlinable + @inline(__always) + var capacity: Int { + _header.pointee.capacity + } + + @inlinable + @inline(__always) + var count: Int { + get { _header.pointee.count } + nonmutating set { _header.pointee.count = newValue } + } + + @inlinable + @inline(__always) + var startSlot: Slot { + get { _header.pointee.startSlot } + nonmutating set { _header.pointee.startSlot = newValue } + } + + @inlinable + @inline(__always) + func ptr(at slot: Slot) -> UnsafeMutablePointer { + assert(slot.position >= 0 && slot.position <= capacity) + return _elements + slot.position + } +} + +extension Deque._UnsafeHandle { + @inlinable + @inline(__always) + var mutableBuffer: UnsafeMutableBufferPointer { + assertMutable() + return .init(start: _elements, count: _header.pointee.capacity) + } + + @inlinable + internal func buffer(for range: Range) -> UnsafeBufferPointer { + assert(range.upperBound.position <= capacity) + return .init(start: _elements + range.lowerBound.position, count: range._count) + } + + @inlinable + @inline(__always) + internal func mutableBuffer(for range: Range) -> UnsafeMutableBufferPointer { + assertMutable() + return .init(mutating: buffer(for: range)) + } +} + +extension Deque._UnsafeHandle { + /// The slot immediately following the last valid one. (`endSlot` refers to + /// the valid slot corresponding to `endIndex`, which is a different thing + /// entirely.) + @inlinable + @inline(__always) + internal var limSlot: Slot { + Slot(at: capacity) + } + + @inlinable + internal func slot(after slot: Slot) -> Slot { + assert(slot.position < capacity) + let position = slot.position + 1 + if position >= capacity { + return Slot(at: 0) + } + return Slot(at: position) + } + + @inlinable + internal func slot(before slot: Slot) -> Slot { + assert(slot.position < capacity) + if slot.position == 0 { return Slot(at: capacity - 1) } + return Slot(at: slot.position - 1) + } + + @inlinable + internal func slot(_ slot: Slot, offsetBy delta: Int) -> Slot { + assert(slot.position <= capacity) + let position = slot.position + delta + if delta >= 0 { + if position >= capacity { return Slot(at: position - capacity) } + } else { + if position < 0 { return Slot(at: position + capacity) } + } + return Slot(at: position) + } + + @inlinable + @inline(__always) + internal var endSlot: Slot { + slot(startSlot, offsetBy: count) + } + + /// Return the storage slot corresponding to the specified offset, which may + /// or may not address an existing element. + @inlinable + internal func slot(forOffset offset: Int) -> Slot { + assert(offset >= 0) + assert(offset <= capacity) // Not `count`! + + // Note: The use of wrapping addition/subscription is justified here by the + // fact that `offset` is guaranteed to fall in the range `0 ..< capacity`. + // Eliminating the overflow checks leads to a measurable speedup for + // random-access subscript operations. (Up to 2x on some microbenchmarks.) + let position = startSlot.position &+ offset + guard position < capacity else { return Slot(at: position &- capacity) } + return Slot(at: position) + } +} + +extension Deque._UnsafeHandle { + @inlinable + internal func segments() -> _UnsafeWrappedBuffer { + let wrap = capacity - startSlot.position + if count <= wrap { + return .init(start: ptr(at: startSlot), count: count) + } + return .init(first: ptr(at: startSlot), count: wrap, + second: ptr(at: .zero), count: count - wrap) + } + + @inlinable + internal func segments( + forOffsets offsets: Range + ) -> _UnsafeWrappedBuffer { + assert(offsets.lowerBound >= 0 && offsets.upperBound <= count) + let lower = slot(forOffset: offsets.lowerBound) + let upper = slot(forOffset: offsets.upperBound) + if offsets.count == 0 || lower < upper { + return .init(start: ptr(at: lower), count: offsets.count) + } + return .init(first: ptr(at: lower), count: capacity - lower.position, + second: ptr(at: .zero), count: upper.position) + } + + @inlinable + @inline(__always) + internal func mutableSegments() -> _UnsafeMutableWrappedBuffer { + assertMutable() + return .init(mutating: segments()) + } + + @inlinable + @inline(__always) + internal func mutableSegments( + forOffsets range: Range + ) -> _UnsafeMutableWrappedBuffer { + assertMutable() + return .init(mutating: segments(forOffsets: range)) + } +} + +extension Deque._UnsafeHandle { + @inlinable + internal func availableSegments() -> _UnsafeMutableWrappedBuffer { + assertMutable() + let endSlot = self.endSlot + guard count < capacity else { return .init(start: ptr(at: endSlot), count: 0) } + if endSlot < startSlot { return .init(mutableBuffer(for: endSlot ..< startSlot)) } + return .init(mutableBuffer(for: endSlot ..< limSlot), + mutableBuffer(for: .zero ..< startSlot)) + } +} + + + +extension Deque._UnsafeHandle { + @inlinable + @discardableResult + func initialize( + at start: Slot, + from source: UnsafeBufferPointer + ) -> Slot { + assert(start.position + source.count <= capacity) + guard source.count > 0 else { return start } + ptr(at: start).initialize(from: source.baseAddress!, count: source.count) + return Slot(at: start.position + source.count) + } + + @inlinable + @inline(__always) + @discardableResult + func moveInitialize( + at start: Slot, + from source: UnsafeMutableBufferPointer + ) -> Slot { + assert(start.position + source.count <= capacity) + guard source.count > 0 else { return start } + ptr(at: start).moveInitialize(from: source.baseAddress!, count: source.count) + return Slot(at: start.position + source.count) + } + + @inlinable + @inline(__always) + @discardableResult + public func move( + from source: Slot, + to target: Slot, + count: Int + ) -> (source: Slot, target: Slot) { + assert(count >= 0) + assert(source.position + count <= self.capacity) + assert(target.position + count <= self.capacity) + guard count > 0 else { return (source, target) } + ptr(at: target).moveInitialize(from: ptr(at: source), count: count) + return (slot(source, offsetBy: count), slot(target, offsetBy: count)) + } +} + + + +extension Deque._UnsafeHandle { + /// Copy elements into a new storage instance without changing capacity or + /// layout. + @inlinable + internal func copyElements() -> Deque._Storage { + let object = _DequeBuffer.create( + minimumCapacity: capacity, + makingHeaderWith: { _ in header }) + let result = Deque._Storage(_buffer: ManagedBufferPointer(unsafeBufferObject: object)) + guard self.count > 0 else { return result } + result.update { target in + let source = self.segments() + target.initialize(at: startSlot, from: source.first) + if let second = source.second { + target.initialize(at: .zero, from: second) + } + } + return result + } + + /// Copy elements into a new storage instance with the specified minimum + /// capacity. + @inlinable + internal func copyElements(minimumCapacity: Int) -> Deque._Storage { + assert(minimumCapacity >= count) + let object = _DequeBuffer.create( + minimumCapacity: minimumCapacity, + makingHeaderWith: { + _DequeBufferHeader( + capacity: $0.capacity, + count: count, + startSlot: .zero) + }) + let result = Deque._Storage(_buffer: ManagedBufferPointer(unsafeBufferObject: object)) + guard count > 0 else { return result } + result.update { target in + assert(target.count == count && target.startSlot.position == 0) + let source = self.segments() + let next = target.initialize(at: .zero, from: source.first) + if let second = source.second { + target.initialize(at: next, from: second) + } + } + return result + } + + /// Move elements into a new storage instance with the specified minimum + /// capacity. Existing indices in `self` won't necessarily be valid in the + /// result. `self` is left empty. + @inlinable + internal func moveElements(minimumCapacity: Int) -> Deque._Storage { + assertMutable() + let count = self.count + assert(minimumCapacity >= count) + let object = _DequeBuffer.create( + minimumCapacity: minimumCapacity, + makingHeaderWith: { + _DequeBufferHeader( + capacity: $0.capacity, + count: count, + startSlot: .zero) + }) + let result = Deque._Storage(_buffer: ManagedBufferPointer(unsafeBufferObject: object)) + guard count > 0 else { return result } + result.update { target in + let source = self.mutableSegments() + let next = target.moveInitialize(at: .zero, from: source.first) + if let second = source.second { + target.moveInitialize(at: next, from: second) + } + } + self.count = 0 + return result + } +} + +extension Deque._UnsafeHandle { + @inlinable + internal func withUnsafeSegment( + startingAt start: Int, + maximumCount: Int?, + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> (end: Int, result: R) { + assert(start <= count) + guard start < count else { + return try (count, body(UnsafeBufferPointer(start: nil, count: 0))) + } + let endSlot = self.endSlot + + let segmentStart = self.slot(forOffset: start) + let segmentEnd = segmentStart < endSlot ? endSlot : limSlot + let count = Swift.min(maximumCount ?? Int.max, segmentEnd.position - segmentStart.position) + let result = try body(UnsafeBufferPointer(start: ptr(at: segmentStart), count: count)) + return (start + count, result) + } +} + +// MARK: Replacement + +extension Deque._UnsafeHandle { + /// Replace the elements in `range` with `newElements`. The deque's count must + /// not change as a result of calling this function. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + @inlinable + internal func uncheckedReplaceInPlace( + inOffsets range: Range, + with newElements: C + ) where C.Element == Element { + assertMutable() + assert(range.upperBound <= count) + assert(newElements.count == range.count) + guard !range.isEmpty else { return } + let target = mutableSegments(forOffsets: range) + target.assign(from: newElements) + } +} + +// MARK: Appending + +extension Deque._UnsafeHandle { + /// Append `element` to this buffer. The buffer must have enough free capacity + /// to insert one new element. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + @inlinable + internal func uncheckedAppend(_ element: Element) { + assertMutable() + assert(count < capacity) + ptr(at: endSlot).initialize(to: element) + count += 1 + } + + /// Append the contents of `source` to this buffer. The buffer must have + /// enough free capacity to insert the new elements. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + @inlinable + internal func uncheckedAppend(contentsOf source: UnsafeBufferPointer) { + assertMutable() + assert(count + source.count <= capacity) + guard source.count > 0 else { return } + let c = self.count + count += source.count + let gap = mutableSegments(forOffsets: c ..< count) + gap.initialize(from: source) + } +} + +// MARK: Prepending + +extension Deque._UnsafeHandle { + @inlinable + internal func uncheckedPrepend(_ element: Element) { + assertMutable() + assert(count < capacity) + let slot = self.slot(before: startSlot) + ptr(at: slot).initialize(to: element) + startSlot = slot + count += 1 + } + + /// Prepend the contents of `source` to this buffer. The buffer must have + /// enough free capacity to insert the new elements. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + @inlinable + internal func uncheckedPrepend(contentsOf source: UnsafeBufferPointer) { + assertMutable() + assert(count + source.count <= capacity) + guard source.count > 0 else { return } + let oldStart = startSlot + let newStart = self.slot(startSlot, offsetBy: -source.count) + startSlot = newStart + count += source.count + + let gap = mutableWrappedBuffer(between: newStart, and: oldStart) + gap.initialize(from: source) + } +} + +// MARK: Insertion + +extension Deque._UnsafeHandle { + /// Insert all elements from `newElements` into this deque, starting at + /// `offset`. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + /// + /// - Parameter newElements: The elements to insert. + /// - Parameter newCount: Must be equal to `newElements.count`. Used to + /// prevent calling `count` more than once. + /// - Parameter offset: The desired offset from the start at which to place + /// the first element. + @inlinable + internal func uncheckedInsert( + contentsOf newElements: __owned C, + count newCount: Int, + atOffset offset: Int + ) where C.Element == Element { + assertMutable() + assert(offset <= count) + assert(newElements.count == newCount) + guard newCount > 0 else { return } + let gap = openGap(ofSize: newCount, atOffset: offset) + gap.initialize(from: newElements) + } + + @inlinable + internal func mutableWrappedBuffer( + between start: Slot, + and end: Slot + ) -> _UnsafeMutableWrappedBuffer { + assert(start.position <= capacity) + assert(end.position <= capacity) + if start < end { + return .init(start: ptr(at: start), count: end.position - start.position) + } + return .init( + first: ptr(at: start), count: capacity - start.position, + second: ptr(at: .zero), count: end.position) + } + + /// Slide elements around so that there is a gap of uninitialized slots of + /// size `gapSize` starting at `offset`, and return a (potentially wrapped) + /// buffer holding the newly inserted slots. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + /// + /// - Parameter gapSize: The number of uninitialized slots to create. + /// - Parameter offset: The offset from the start at which the uninitialized + /// slots should start. + @inlinable + internal func openGap( + ofSize gapSize: Int, + atOffset offset: Int + ) -> _UnsafeMutableWrappedBuffer { + assertMutable() + assert(offset >= 0 && offset <= self.count) + assert(self.count + gapSize <= capacity) + assert(gapSize > 0) + + let headCount = offset + let tailCount = count - offset + if tailCount <= headCount { + // Open the gap by sliding elements to the right. + + let originalEnd = self.slot(startSlot, offsetBy: count) + let newEnd = self.slot(startSlot, offsetBy: count + gapSize) + let gapStart = self.slot(forOffset: offset) + let gapEnd = self.slot(gapStart, offsetBy: gapSize) + + let sourceIsContiguous = gapStart <= originalEnd.orIfZero(capacity) + let targetIsContiguous = gapEnd <= newEnd.orIfZero(capacity) + + if sourceIsContiguous && targetIsContiguous { + // No need to deal with wrapping; we just need to slide + // elements after the gap. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) ....ABCDE̲F̲G̲H..... EFG̲H̲.̲........ABCD .̲.......ABCDEFGH̲.̲ + // 1) ....ABCD.̲.̲.̲EFGH.. EF.̲.̲.̲GH......ABCD .̲H......ABCDEFG.̲.̲ + move(from: gapStart, to: gapEnd, count: tailCount) + } else if targetIsContiguous { + // The gap itself will be wrapped. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) E̲FGH.........ABC̲D̲ + // 1) .̲..EFGH......ABC̲D̲ + // 2) .̲CDEFGH......AB.̲.̲ + assert(startSlot > originalEnd.orIfZero(capacity)) + move(from: .zero, to: Slot.zero.advanced(by: gapSize), count: originalEnd.position) + move(from: gapStart, to: gapEnd, count: capacity - gapStart.position) + } else if sourceIsContiguous { + // Opening the gap pushes subsequent elements across the wrap. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) ........ABC̲D̲E̲FGH. + // 1) GH......ABC̲D̲E̲F... + // 2) GH......AB.̲.̲.̲CDEF + move(from: limSlot.advanced(by: -gapSize), to: .zero, count: newEnd.position) + move(from: gapStart, to: gapEnd, count: tailCount - newEnd.position) + } else { + // The rest of the items are wrapped, and will remain so. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) GH.........AB̲C̲D̲EF + // 1) ...GH......AB̲C̲D̲EF + // 2) DEFGH......AB̲C̲.̲.. + // 3) DEFGH......A.̲.̲.̲BC + move(from: .zero, to: Slot.zero.advanced(by: gapSize), count: originalEnd.position) + move(from: limSlot.advanced(by: -gapSize), to: .zero, count: gapSize) + move(from: gapStart, to: gapEnd, count: tailCount - gapSize - originalEnd.position) + } + count += gapSize + return mutableWrappedBuffer(between: gapStart, and: gapEnd.orIfZero(capacity)) + } + + // Open the gap by sliding elements to the left. + + let originalStart = self.startSlot + let newStart = self.slot(originalStart, offsetBy: -gapSize) + let gapEnd = self.slot(forOffset: offset) + let gapStart = self.slot(gapEnd, offsetBy: -gapSize) + + let sourceIsContiguous = originalStart <= gapEnd.orIfZero(capacity) + let targetIsContiguous = newStart <= gapStart.orIfZero(capacity) + + if sourceIsContiguous && targetIsContiguous { + // No need to deal with any wrapping. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) ....A̲B̲C̲DEFGH... GH.........̲A̲B̲CDEF .̲A̲B̲CDEFGH.......̲.̲ + // 1) .ABC.̲.̲.̲DEFGH... GH......AB.̲.̲.̲CDEF .̲.̲.̲CDEFGH....AB.̲.̲ + move(from: originalStart, to: newStart, count: headCount) + } else if targetIsContiguous { + // The gap itself will be wrapped. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) C̲D̲EFGH.........A̲B̲ + // 1) C̲D̲EFGH.....AB...̲.̲ + // 2) .̲.̲EFGH.....ABCD.̲.̲ + assert(originalStart >= newStart) + move(from: originalStart, to: newStart, count: capacity - originalStart.position) + move(from: .zero, to: limSlot.advanced(by: -gapSize), count: gapEnd.position) + } else if sourceIsContiguous { + // Opening the gap pushes preceding elements across the wrap. + + // Illustrated steps: (underscores mark eventual gap position) + // + // 0) .AB̲C̲D̲EFGH......... + // 1) ...̲C̲D̲EFGH.......AB + // 2) CD.̲.̲.̲EFGH.......AB + move(from: originalStart, to: newStart, count: capacity - newStart.position) + move(from: Slot.zero.advanced(by: gapSize), to: .zero, count: gapStart.position) + } else { + // The preceding of the items are wrapped, and will remain so. + + // Illustrated steps: (underscores mark eventual gap position) + // 0) CD̲E̲F̲GHIJKL.........AB + // 1) CD̲E̲F̲GHIJKL......AB... + // 2) ..̲.̲F̲GHIJKL......ABCDE + // 3) F.̲.̲.̲GHIJKL......ABCDE + move(from: originalStart, to: newStart, count: capacity - originalStart.position) + move(from: .zero, to: limSlot.advanced(by: -gapSize), count: gapSize) + move(from: Slot.zero.advanced(by: gapSize), to: .zero, count: gapStart.position) + } + startSlot = newStart + count += gapSize + return mutableWrappedBuffer(between: gapStart, and: gapEnd.orIfZero(capacity)) + } +} + +// MARK: Removal + +extension Deque._UnsafeHandle { + @inlinable + internal func uncheckedRemoveFirst() -> Element { + assertMutable() + assert(count > 0) + let result = ptr(at: startSlot).move() + startSlot = slot(after: startSlot) + count -= 1 + return result + } + + @inlinable + internal func uncheckedRemoveLast() -> Element { + assertMutable() + assert(count > 0) + let slot = self.slot(forOffset: count - 1) + let result = ptr(at: slot).move() + count -= 1 + return result + } + + @inlinable + internal func uncheckedRemoveFirst(_ n: Int) { + assertMutable() + assert(count >= n) + guard n > 0 else { return } + let target = mutableSegments(forOffsets: 0 ..< n) + target.deinitialize() + startSlot = slot(startSlot, offsetBy: n) + count -= n + } + + @inlinable + internal func uncheckedRemoveLast(_ n: Int) { + assertMutable() + assert(count >= n) + guard n > 0 else { return } + let target = mutableSegments(forOffsets: count - n ..< count) + target.deinitialize() + count -= n + } + + /// Remove all elements stored in this instance, deinitializing their storage. + /// + /// This method does not ensure that the storage buffer is uniquely + /// referenced. + @inlinable + internal func uncheckedRemoveAll() { + assertMutable() + guard count > 0 else { return } + let target = mutableSegments() + target.deinitialize() + count = 0 + startSlot = .zero + } + + /// Remove all elements in `bounds`, deinitializing their storage and sliding + /// remaining elements to close the resulting gap. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + @inlinable + internal func uncheckedRemove(offsets bounds: Range) { + assertMutable() + assert(bounds.lowerBound >= 0 && bounds.upperBound <= self.count) + + // Deinitialize elements in `bounds`. + mutableSegments(forOffsets: bounds).deinitialize() + closeGap(offsets: bounds) + } + + /// Close the gap of already uninitialized elements in `bounds`, sliding + /// elements outside of the gap to eliminate it. + /// + /// This function does not validate its input arguments in release builds. Nor + /// does it ensure that the storage buffer is uniquely referenced. + @inlinable + internal func closeGap(offsets bounds: Range) { + assertMutable() + assert(bounds.lowerBound >= 0 && bounds.upperBound <= self.count) + let gapSize = bounds.count + guard gapSize > 0 else { return } + + let gapStart = self.slot(forOffset: bounds.lowerBound) + let gapEnd = self.slot(forOffset: bounds.upperBound) + + let headCount = bounds.lowerBound + let tailCount = count - bounds.upperBound + + if headCount >= tailCount { + // Close the gap by sliding elements to the left. + let originalEnd = endSlot + let newEnd = self.slot(forOffset: count - gapSize) + + let sourceIsContiguous = gapEnd < originalEnd.orIfZero(capacity) + let targetIsContiguous = gapStart <= newEnd.orIfZero(capacity) + if tailCount == 0 { + // No need to move any elements. + } else if sourceIsContiguous && targetIsContiguous { + // No need to deal with wrapping. + + // 0) ....ABCD.̲.̲.̲EFGH.. EF.̲.̲.̲GH........ABCD .̲.̲.̲E..........ABCD.̲.̲ .̲.̲.̲EF........ABCD .̲.̲.̲DE.......ABC + // 1) ....ABCDE̲F̲G̲H..... EFG̲H̲.̲..........ABCD .̲.̲.̲...........ABCDE̲.̲ E̲F̲.̲..........ABCD D̲E̲.̲.........ABC + move(from: gapEnd, to: gapStart, count: tailCount) + } else if sourceIsContiguous { + // The gap lies across the wrap from the subsequent elements. + + // 0) .̲.̲.̲EFGH.......ABCD.̲.̲ EFGH.......ABCD.̲.̲.̲ + // 1) .̲.̲.̲..GH.......ABCDE̲F̲ ..GH.......ABCDE̲F̲G̲ + // 2) G̲H̲.̲...........ABCDE̲F̲ GH.........ABCDE̲F̲G̲ + let c = capacity - gapStart.position + assert(tailCount > c) + let next = move(from: gapEnd, to: gapStart, count: c) + move(from: next.source, to: .zero, count: tailCount - c) + } else if targetIsContiguous { + // We need to move elements across a wrap, but the wrap will + // disappear when we're done. + + // 0) HI....ABCDE.̲.̲.̲FG + // 1) HI....ABCDEF̲G̲.̲.. + // 2) ......ABCDEF̲G̲H̲I. + let next = move(from: gapEnd, to: gapStart, count: capacity - gapEnd.position) + move(from: .zero, to: next.target, count: originalEnd.position) + } else { + // We need to move elements across a wrap that won't go away. + + // 0) HIJKL....ABCDE.̲.̲.̲FG + // 1) HIJKL....ABCDEF̲G̲.̲.. + // 2) ...KL....ABCDEF̲G̲H̲IJ + // 3) KL.......ABCDEF̲G̲H̲IJ + var next = move(from: gapEnd, to: gapStart, count: capacity - gapEnd.position) + next = move(from: .zero, to: next.target, count: gapSize) + move(from: next.source, to: .zero, count: newEnd.position) + } + count -= gapSize + } else { + // Close the gap by sliding elements to the right. + let originalStart = startSlot + let newStart = slot(startSlot, offsetBy: gapSize) + + let sourceIsContiguous = originalStart < gapStart.orIfZero(capacity) + let targetIsContiguous = newStart <= gapEnd.orIfZero(capacity) + + if headCount == 0 { + // No need to move any elements. + } else if sourceIsContiguous && targetIsContiguous { + // No need to deal with wrapping. + + // 0) ....ABCD.̲.̲.̲EFGH..... EFGH........AB.̲.̲.̲CD .̲.̲.̲CDEFGH.......AB.̲.̲ DEFGH.......ABC.̲.̲ + // 1) .......AB̲C̲D̲EFGH..... EFGH...........̲A̲B̲CD .̲A̲B̲CDEFGH..........̲.̲ DEFGH.........AB̲C̲ ABCDEFGH........̲.̲.̲ + move(from: originalStart, to: newStart, count: headCount) + } else if sourceIsContiguous { + // The gap lies across the wrap from the preceding elements. + + // 0) .̲.̲DEFGH.......ABC.̲.̲ .̲.̲.̲EFGH.......ABCD + // 1) B̲C̲DEFGH.......A...̲.̲ B̲C̲D̲DEFGH......A... + // 2) B̲C̲DEFGH...........̲A̲ B̲C̲D̲DEFGH.........A + move(from: limSlot.advanced(by: -gapSize), to: .zero, count: gapEnd.position) + move(from: startSlot, to: newStart, count: headCount - gapEnd.position) + } else if targetIsContiguous { + // We need to move elements across a wrap, but the wrap will + // disappear when we're done. + + // 0) CD.̲.̲.̲EFGHI.....AB + // 1) ...̲C̲D̲EFGHI.....AB + // 1) .AB̲C̲D̲EFGHI....... + move(from: .zero, to: gapEnd.advanced(by: -gapStart.position), count: gapStart.position) + move(from: startSlot, to: newStart, count: headCount - gapStart.position) + } else { + // We need to move elements across a wrap that won't go away. + // 0) FG.̲.̲.̲HIJKLMNO....ABCDE + // 1) ...̲F̲G̲HIJKLMNO....ABCDE + // 2) CDE̲F̲G̲HIJKLMNO....AB... + // 3) CDE̲F̲G̲HIJKLMNO.......AB + move(from: .zero, to: Slot.zero.advanced(by: gapSize), count: gapStart.position) + move(from: limSlot.advanced(by: -gapSize), to: .zero, count: gapSize) + move(from: startSlot, to: newStart, count: headCount - gapEnd.position) + } + startSlot = newStart + count -= gapSize + } + } +} diff --git a/Sources/DequeModule/Deque.swift b/Sources/DequeModule/Deque.swift new file mode 100644 index 00000000..51d8643f --- /dev/null +++ b/Sources/DequeModule/Deque.swift @@ -0,0 +1,105 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// A collection implementing a double-ended queue. `Deque` (pronounced "deck") +/// implements an ordered random-access collection that supports efficient +/// insertions and removals from both ends. +/// +/// var colors: Deque = ["red", "yellow", "blue"] +/// +/// Deques implement the same indexing semantics as arrays: they use integer +/// indices, and the first element of a nonempty deque is always at index zero. +/// Like arrays, deques conform to `RangeReplaceableCollection`, +/// `MutableCollection` and `RandomAccessCollection`, providing a familiar +/// interface for manipulating their contents: +/// +/// print(colors[1]) // "yellow" +/// print(colors[3]) // Runtime error: Index out of range +/// +/// colors.insert("green", at: 1) +/// // ["red", "green", "yellow", "blue"] +/// +/// colors.remove(at: 2) // "yellow" +/// // ["red", "green", "blue"] +/// +/// Like all variable-size collections on the standard library, `Deque` +/// implements value semantics: each deque has an independent value that +/// includes the values of its elements. Modifying one deque does not affect any +/// others: +/// +/// var copy = deque +/// copy[1] = "violet" +/// print(copy) // ["red", "violet", "blue"] +/// print(deque) // ["red", "green", "blue"] +/// +/// This is implemented with the copy-on-write optimization. Multiple copies of +/// a deque share the same underlying storage until you modify one of the +/// copies. When that happens, the deque being modified replaces its storage +/// with a uniquely owned copy of itself, which is then modified in place. +/// +/// `Deque` stores its elements in a circular buffer, which allows efficient +/// insertions and removals at both ends of the collection; however, this comes +/// at the cost of potentially discontiguous storage. In contrast, `Array` is +/// (usually) backed by a contiguous buffer, where new data can be efficiently +/// appended to the end, but inserting at the front is relatively slow, as +/// existing elements need to be shifted to make room. +/// +/// This difference in implementation means that while the interface of a deque +/// is very similar to an array, the operations have different performance +/// characteristics. Mutations near the front are expected to be significantly +/// faster in deques, but arrays may measure slightly faster for general +/// random-access lookups. +/// +/// Deques provide a handful of additional operations that make it easier to +/// insert and remove elements at the front. This includes queue operations such +/// as `popFirst` and `prepend`, including the ability to directly prepend a +/// sequence of elements: +/// +/// colors.append("green") +/// colors.prepend("orange") +/// // colors: ["orange", "red", "blue", "yellow", "green"] +/// +/// colors.popLast() // "green" +/// colors.popFirst() // "orange" +/// // colors: ["red", "blue", "yellow"] +/// +/// colors.prepend(contentsOf: ["purple", "teal"]) +/// // colors: ["purple", "teal", "red", "blue", "yellow"] +/// +/// Unlike arrays, deques do not currently provide direct unsafe access to their +/// underlying storage. They also lack a `capacity` property -- the size of the +/// storage buffer at any given point is an unstable implementation detail that +/// should not affect application logic. (However, deques do provide a +/// `reserveCapacity` method.) +@frozen +public struct Deque { + @usableFromInline + internal typealias _Slot = _DequeSlot + + @usableFromInline + internal var _storage: _Storage + + @inlinable + internal init(_storage: _Storage) { + self._storage = _storage + } + + /// Creates and empty deque with preallocated space for at least the specified + /// number of elements. + /// + /// - Parameter minimumCapacity: The minimum number of elements that the + /// newly created deque should be able to store without reallocating its + /// storage buffer. + @inlinable + public init(minimumCapacity: Int) { + self._storage = _Storage(minimumCapacity: minimumCapacity) + } +} diff --git a/Sources/DequeModule/UnsafeMutableBufferPointer+Utilities.swift b/Sources/DequeModule/UnsafeMutableBufferPointer+Utilities.swift new file mode 100644 index 00000000..95b2635a --- /dev/null +++ b/Sources/DequeModule/UnsafeMutableBufferPointer+Utilities.swift @@ -0,0 +1,65 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Collection { + @inlinable + @inline(__always) + internal func _rebased() -> UnsafeBufferPointer + where Self == UnsafeBufferPointer.SubSequence { + .init(rebasing: self) + } +} + +extension Collection { + @inlinable + @inline(__always) + internal func _rebased() -> UnsafeMutableBufferPointer + where Self == UnsafeMutableBufferPointer.SubSequence { + .init(rebasing: self) + } +} + +extension UnsafeMutableBufferPointer { + @inlinable + @inline(__always) + internal func _initialize(from source: UnsafeBufferPointer) { + assert(source.count == count) + guard source.count > 0 else { return } + baseAddress!.initialize(from: source.baseAddress!, count: source.count) + } + + @inlinable + @inline(__always) + internal func _initialize( + from elements: C + ) where C.Element == Element { + assert(elements.count == count) + var (it, copied) = elements._copyContents(initializing: self) + precondition(copied == count) + precondition(it.next() == nil) + } + + @inlinable + @inline(__always) + internal func _deinitializeAll() { + guard count > 0 else { return } + baseAddress!.deinitialize(count: count) + } + + @inlinable + internal func _assign( + from replacement: C + ) where C.Element == Element { + guard self.count > 0 else { return } + self[0 ..< count]._rebased()._deinitializeAll() + _initialize(from: replacement) + } +} diff --git a/Sources/DequeModule/_DequeBuffer.swift b/Sources/DequeModule/_DequeBuffer.swift new file mode 100644 index 00000000..d2ce22d2 --- /dev/null +++ b/Sources/DequeModule/_DequeBuffer.swift @@ -0,0 +1,51 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@usableFromInline +internal class _DequeBuffer: ManagedBuffer<_DequeBufferHeader, Element> { + @inlinable + deinit { + let storage = Deque._Storage(self) + storage.update { handle in + } + self.withUnsafeMutablePointers { header, elements in + header.pointee._checkInvariants() + + let capacity = header.pointee.capacity + let count = header.pointee.count + let startSlot = header.pointee.startSlot + + if startSlot.position + count <= capacity { + (elements + startSlot.position).deinitialize(count: count) + } else { + let firstRegion = capacity - startSlot.position + (elements + startSlot.position).deinitialize(count: firstRegion) + elements.deinitialize(count: count - firstRegion) + } + } + } +} + +extension _DequeBuffer: CustomStringConvertible { + @usableFromInline + internal var description: String { + withUnsafeMutablePointerToHeader { "_DequeStorage<\(Element.self)>\($0.pointee)" } + } +} + +/// The type-punned empty singleton storage instance. +@usableFromInline +internal let _emptyDequeStorage = _DequeBuffer.create( + minimumCapacity: 0, + makingHeaderWith: { _ in + _DequeBufferHeader(capacity: 0, count: 0, startSlot: .init(at: 0)) + }) + diff --git a/Sources/DequeModule/_DequeBufferHeader.swift b/Sources/DequeModule/_DequeBufferHeader.swift new file mode 100644 index 00000000..37c0ff9c --- /dev/null +++ b/Sources/DequeModule/_DequeBufferHeader.swift @@ -0,0 +1,49 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@usableFromInline +internal struct _DequeBufferHeader { + @usableFromInline + var capacity: Int + + @usableFromInline + var count: Int + + @usableFromInline + var startSlot: _DequeSlot + + @usableFromInline + init(capacity: Int, count: Int, startSlot: _DequeSlot) { + self.capacity = capacity + self.count = count + self.startSlot = startSlot + _checkInvariants() + } + + #if COLLECTIONS_INTERNAL_CHECKS + @usableFromInline @inline(never) @_effects(releasenone) + internal func _checkInvariants() { + precondition(capacity >= 0) + precondition(count >= 0 && count <= capacity) + precondition(startSlot.position >= 0 && startSlot.position <= capacity) + } + #else + @inlinable @inline(__always) + internal func _checkInvariants() {} + #endif // COLLECTIONS_INTERNAL_CHECKS +} + +extension _DequeBufferHeader: CustomStringConvertible { + @usableFromInline + internal var description: String { + "(capacity: \(capacity), count: \(count), startSlot: \(startSlot))" + } +} diff --git a/Sources/DequeModule/_DequeSlot.swift b/Sources/DequeModule/_DequeSlot.swift new file mode 100644 index 00000000..321c2f87 --- /dev/null +++ b/Sources/DequeModule/_DequeSlot.swift @@ -0,0 +1,72 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@usableFromInline +@frozen +internal struct _DequeSlot { + @usableFromInline + internal var position: Int + + @inlinable + @inline(__always) + init(at position: Int) { + assert(position >= 0) + self.position = position + } +} + +extension _DequeSlot { + @inlinable + @inline(__always) + internal static var zero: Self { Self(at: 0) } + + @inlinable + @inline(__always) + internal func advanced(by delta: Int) -> Self { + Self(at: position &+ delta) + } + + @inlinable + @inline(__always) + internal func orIfZero(_ value: Int) -> Self { + guard position > 0 else { return Self(at: value) } + return self + } +} + +extension _DequeSlot: CustomStringConvertible { + @usableFromInline + internal var description: String { + "@\(position)" + } +} + +extension _DequeSlot: Equatable { + @inlinable + @inline(__always) + static func ==(left: Self, right: Self) -> Bool { + left.position == right.position + } +} + +extension _DequeSlot: Comparable { + @inlinable + @inline(__always) + static func <(left: Self, right: Self) -> Bool { + left.position < right.position + } +} + +extension Range where Bound == _DequeSlot { + @inlinable + @inline(__always) + internal var _count: Int { upperBound.position - lowerBound.position } +} diff --git a/Sources/DequeModule/_UnsafeWrappedBuffer.swift b/Sources/DequeModule/_UnsafeWrappedBuffer.swift new file mode 100644 index 00000000..0424403e --- /dev/null +++ b/Sources/DequeModule/_UnsafeWrappedBuffer.swift @@ -0,0 +1,215 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@usableFromInline +internal struct _UnsafeWrappedBuffer { + @usableFromInline + internal let first: UnsafeBufferPointer + + @usableFromInline + internal let second: UnsafeBufferPointer? + + @inlinable + @inline(__always) + internal init( + _ first: UnsafeBufferPointer, + _ second: UnsafeBufferPointer? = nil + ) { + self.first = first + self.second = second + assert(first.count > 0 || second == nil) + } + + @inlinable + internal init( + start: UnsafePointer, + count: Int + ) { + self.init(UnsafeBufferPointer(start: start, count: count)) + } + + @inlinable + internal init( + first start1: UnsafePointer, + count count1: Int, + second start2: UnsafePointer, + count count2: Int + ) { + self.init(UnsafeBufferPointer(start: start1, count: count1), + UnsafeBufferPointer(start: start2, count: count2)) + } + + @inlinable + internal var count: Int { first.count + (second?.count ?? 0) } +} + +@usableFromInline +internal struct _UnsafeMutableWrappedBuffer { + @usableFromInline + internal let first: UnsafeMutableBufferPointer + + @usableFromInline + internal let second: UnsafeMutableBufferPointer? + + @inlinable + @inline(__always) + internal init( + _ first: UnsafeMutableBufferPointer, + _ second: UnsafeMutableBufferPointer? = nil + ) { + self.first = first + self.second = second?.count == 0 ? nil : second + assert(first.count > 0 || second == nil) + } + + @inlinable + @inline(__always) + internal init( + start: UnsafeMutablePointer, + count: Int + ) { + self.init(UnsafeMutableBufferPointer(start: start, count: count)) + } + + @inlinable + @inline(__always) + internal init( + first start1: UnsafeMutablePointer, + count count1: Int, + second start2: UnsafeMutablePointer, + count count2: Int + ) { + self.init(UnsafeMutableBufferPointer(start: start1, count: count1), + UnsafeMutableBufferPointer(start: start2, count: count2)) + } + + @inlinable + @inline(__always) + internal init(mutating buffer: _UnsafeWrappedBuffer) { + self.init(.init(mutating: buffer.first), + buffer.second.map { .init(mutating: $0) }) + } +} + +extension _UnsafeMutableWrappedBuffer { + @inlinable + @inline(__always) + internal var count: Int { first.count + (second?.count ?? 0) } + + @inlinable + internal func prefix(_ n: Int) -> Self { + assert(n >= 0) + if n >= self.count { + return self + } + if n <= first.count { + return Self(first.prefix(n)._rebased()) + } + return Self(first, second!.prefix(n - first.count)._rebased()) + } + + @inlinable + internal func suffix(_ n: Int) -> Self { + assert(n >= 0) + if n >= self.count { + return self + } + guard let second = second else { + return Self(first.suffix(n)._rebased()) + } + if n <= second.count { + return Self(second.suffix(n)._rebased()) + } + return Self(first.suffix(n - second.count)._rebased(), second) + } +} + +extension _UnsafeMutableWrappedBuffer { + @inlinable + internal func deinitialize() { + first._deinitializeAll() + second?._deinitializeAll() + } + + @inlinable + @discardableResult + internal func initialize( + fromPrefixOf iterator: inout I + ) -> Int + where I.Element == Element { + var copied = 0 + var gap = first + var wrapped = false + while true { + if copied == gap.count { + guard !wrapped, let second = second, second.count > 0 else { break } + gap = second + copied = 0 + wrapped = true + } + guard let next = iterator.next() else { break } + (gap.baseAddress! + copied).initialize(to: next) + copied += 1 + } + return wrapped ? first.count + copied : copied + } + + @inlinable + internal func initialize( + fromSequencePrefix elements: __owned S + ) -> (iterator: S.Iterator, count: Int) + where S.Element == Element { + guard second == nil || first.count >= elements.underestimatedCount else { + var it = elements.makeIterator() + let copied = initialize(fromPrefixOf: &it) + return (it, copied) + } + // Note: Array._copyContents traps when not given enough space, so we + // need to check if we have enough contiguous space available above. + // + // FIXME: Add suppport for segmented (a.k.a. piecewise contiguous) + // collections to the stdlib. + var (it, copied) = elements._copyContents(initializing: first) + if copied == first.count, let second = second { + var i = 0 + while i < second.count { + guard let next = it.next() else { break } + (second.baseAddress! + i).initialize(to: next) + i += 1 + } + copied += i + } + return (it, copied) + } + + @inlinable + internal func initialize( + from elements: __owned C + ) where C.Element == Element { + assert(self.count == elements.count) + if let second = second { + let wrap = elements.index(elements.startIndex, offsetBy: first.count) + first._initialize(from: elements[..( + from elements: C + ) where C.Element == Element { + assert(elements.count == self.count) + deinitialize() + initialize(from: elements) + } +} diff --git a/Sources/OrderedCollections/HashTable/_HashTable+Bucket.swift b/Sources/OrderedCollections/HashTable/_HashTable+Bucket.swift new file mode 100644 index 00000000..b912fe83 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable+Bucket.swift @@ -0,0 +1,37 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension _HashTable { + /// Identifies a particular bucket within a hash table by its offset. + /// Having a dedicated wrapper type for this prevents passing a bucket number + /// to a function that expects a word index, or vice versa. + @usableFromInline + @frozen + internal struct Bucket { + /// The distance of this bucket from the first bucket in the hash table. + @usableFromInline + internal var offset: Int + + @inlinable + @inline(__always) + internal init(offset: Int) { + assert(offset >= 0) + self.offset = offset + } + } +} + +extension _HashTable.Bucket: Equatable { + @_transparent + public static func == (left: Self, right: Self) -> Bool { + left.offset == right.offset + } +} diff --git a/Sources/OrderedCollections/HashTable/_HashTable+BucketIterator.swift b/Sources/OrderedCollections/HashTable/_HashTable+BucketIterator.swift new file mode 100644 index 00000000..c4a62485 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable+BucketIterator.swift @@ -0,0 +1,265 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension _HashTable { + /// An iterator construct for visiting a chain of buckets within the hash + /// table. This is a convenient tool for implementing linear probing. + /// + /// Beyond merely providing bucket values, bucket iterators can also tell + /// you their current oposition within the hash table, and (for mutable hash + /// tables) they allow you update the value of the currently visited bucket. + /// (This is useful when implementing simple insertions, for example.) + /// + /// The bucket iterator caches some bucket contents, so if you are looping + /// over an iterator you must be careful to only modify hash table contents + /// through the iterator itself. + /// + /// - Warning: Like `UnsafeHandle`, `BucketIterator` does not have + /// ownership of its underlying storage buffer. You must not escape + /// iterator values outside the closure call that produced the original + /// hash table. + @usableFromInline + internal struct BucketIterator { + @usableFromInline + internal typealias Bucket = _HashTable.Bucket + + /// The hash table we are iterating over. + internal let _hashTable: _UnsafeHashTable + + /// The current position within the hash table. + @usableFromInline + internal var _currentBucket: Bucket + + /// The raw bucket value corresponding to `_currentBucket`. + internal var _currentRawValue: UInt64 + + /// Remaining bits not yet processed from the last word read. + internal var _nextBits: UInt64 + + /// Count of usable bits in `_nextBits`. (They start at bit 0.) + internal var _remainingBitCount: Int + + internal var _wrappedAround = false + + /// Create a new iterator starting at the specified bucket. + @_effects(releasenone) + @usableFromInline + internal init(hashTable: _UnsafeHashTable, startingAt bucket: Bucket) { + assert(hashTable.scale >= _HashTable.minimumScale) + assert(bucket.offset >= 0 && bucket.offset < hashTable.bucketCount) + self._hashTable = hashTable + self._currentBucket = bucket + (self._currentRawValue, self._nextBits, self._remainingBitCount) + = hashTable._startIterator(bucket: bucket) + } + } +} + +extension _HashTable.UnsafeHandle { + @usableFromInline + internal typealias BucketIterator = _HashTable.BucketIterator + + @_effects(releasenone) + @inlinable + @inline(__always) + internal func idealBucket(forHashValue hashValue: Int) -> Bucket { + return Bucket(offset: hashValue & (bucketCount - 1)) + } + + @inlinable + @inline(__always) + internal func idealBucket(for element: Element) -> Bucket { + let hashValue = element._rawHashValue(seed: seed) + return idealBucket(forHashValue: hashValue) + } + + /// Return a bucket iterator for the chain starting at the bucket corresponding + /// to the specified value. + @inlinable + @inline(__always) + internal func bucketIterator(for element: Element) -> BucketIterator { + let bucket = idealBucket(for: element) + return bucketIterator(startingAt: bucket) + } + + /// Return a bucket iterator for the chain starting at the specified bucket. + @inlinable + @inline(__always) + internal func bucketIterator(startingAt bucket: Bucket) -> BucketIterator { + BucketIterator(hashTable: self, startingAt: bucket) + } + + @usableFromInline + @_effects(releasenone) + internal func startFind( + _ startBucket: Bucket + ) -> (iterator: BucketIterator, currentValue: Int?) { + let iterator = bucketIterator(startingAt: startBucket) + return (iterator, iterator.currentValue) + } + + @_effects(readonly) + @usableFromInline + internal func _startIterator( + bucket: Bucket + ) -> (currentBits: UInt64, nextBits: UInt64, remainingBitCount: Int) { + // The `scale == 5` case is special because the last word is only half filled there, + // which is why the code below needs to special case it. + // (For all scales > 5, the last bucket ends exactly on a word boundary.) + + var (word, bit) = self.position(of: bucket) + if bit + scale <= 64 { + // We're in luck, the current bucket is stored entirely within one word. + let w = self[word: word] + let currentRawValue = (w &>> bit) & bucketMask + let c = (scale == 5 && word == wordCount - 1 ? 32 : 64) + let remainingBitCount = c - (bit + scale) + let nextBits = (remainingBitCount == 0 ? 0 : w &>> (bit + scale)) + assert(remainingBitCount >= 0) + assert(bit < c) + return (currentRawValue, nextBits, remainingBitCount) + } else { + // We need to read two words. + assert(scale != 5 || word < wordCount - 1) + assert(bit > 0) + let w1 = self[word: word] + word = self.word(after: word) + let w2 = self[word: word] + let currentRawValue = ((w1 &>> bit) | (w2 &<< (64 - bit))) & bucketMask + let overhang = scale - (64 - bit) + let nextBits = w2 &>> overhang + let c = (scale == 5 && word == wordCount - 1 ? 32 : 64) + let remainingBitCount = c - overhang + return (currentRawValue, nextBits, remainingBitCount) + } + } +} + +extension _HashTable.BucketIterator { + /// The scale of the hash table. A table of scale *n* holds 2^*n* buckets, + /// each of which contain an *n*-bit value. + @inline(__always) + internal var _scale: Int { _hashTable.scale } + + /// The current position within the hash table. + @inlinable + @inline(__always) + internal var currentBucket: Bucket { _currentBucket } + + @usableFromInline + internal var isOccupied: Bool { + @_effects(readonly) + @inline(__always) + get { + _currentRawValue != 0 + } + } + + /// The value of the bucket at the current position in the hash table. + /// Setting this property overwrites the bucket value. + /// + /// A nil value indicates an empty bucket. + @usableFromInline + internal var currentValue: Int? { + @inline(__always) + @_effects(readonly) + get { _hashTable._value(forBucketContents: _currentRawValue) } + @_effects(releasenone) + set { + _hashTable.assertMutable() + let v = _hashTable._bucketContents(for: newValue) + let pattern = v ^ _currentRawValue + + assert(_currentBucket.offset < _hashTable.bucketCount) + let (word, bit) = _hashTable.position(of: _currentBucket) + _hashTable[word: word] ^= pattern &<< bit + let extractedBits = 64 - bit + if extractedBits < _scale { + let word2 = _hashTable.word(after: word) + _hashTable[word: word2] ^= pattern &>> extractedBits + } + _currentRawValue = v + } + } + + /// Advance this iterator to the next bucket within the hash table. + /// The buckets form a cycle, so the last bucket is logically followed + /// by the first. Therefore, the iterator never runs out of buckets -- + /// you must devise some way to guarantee to stop iterating. + /// + /// In the typical case, you stop iterating buckets when you find the + /// element you're looking for, or when you run across an empty bucket + /// (terminating the chain with a negative lookup result). + /// + /// To catch mistakes (and corrupt tables), `advance` traps the second + /// time it needs to wrap around to the beginning of the table. + @usableFromInline + @_effects(releasenone) + internal mutating func advance() { + // Advance to next bucket, checking for wraparound condition. + _currentBucket.offset &+= 1 + if _currentBucket.offset == _hashTable.bucketCount { + guard !_wrappedAround else { + // Prevent wasting battery in an infinite loop if a hash table + // somehow becomes corrupt. + fatalError("Hash table has no unoccupied buckets") + } + _wrappedAround = true + _currentBucket.offset = 0 + } + + // If we have loaded enough bits, eat them and return. + if _remainingBitCount >= _scale { + _currentRawValue = _nextBits & _hashTable.bucketMask + _nextBits &>>= _scale + _remainingBitCount -= _scale + return + } + + // Load the next batch of bits. + var word = _hashTable.position(of: _currentBucket).word + if _remainingBitCount != 0 { + word = _hashTable.word(after: word) + } + let c = (_hashTable.scale == 5 && word == _hashTable.wordCount - 1 ? 32 : 64) + let w = _hashTable[word: word] + _currentRawValue = (_nextBits | (w &<< _remainingBitCount)) & _hashTable.bucketMask + _nextBits = w &>> (_scale - _remainingBitCount) + _remainingBitCount = c - (_scale - _remainingBitCount) + } + + @usableFromInline + @_effects(releasenone) + internal mutating func findNext() -> Int? { + advance() + return currentValue + } + + /// Advance this iterator until it points to an occupied bucket with the + /// specified value, or an unoccupied bucket -- whichever comes first. + @inlinable + @_effects(releasenone) + internal mutating func advance(until expected: Int) { + while isOccupied && currentValue != expected { + advance() + } + } + + /// Advance this iterator until it points to an unoccupied bucket. + /// Useful when inserting an element that we know isn't already in the table. + @inlinable + @_effects(releasenone) + internal mutating func advanceToNextUnoccupiedBucket() { + while isOccupied { + advance() + } + } +} diff --git a/Sources/OrderedCollections/HashTable/_HashTable+Constants.swift b/Sources/OrderedCollections/HashTable/_HashTable+Constants.swift new file mode 100644 index 00000000..84ef2dd5 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable+Constants.swift @@ -0,0 +1,97 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension _HashTable { + /// The minimum hash table scale. + @usableFromInline + @inline(__always) + internal static var minimumScale: Int { + @_effects(readnone) + get { + 5 + } + } + + /// The maximum hash table scale. + @usableFromInline + @inline(__always) + internal static var maximumScale: Int { + @_effects(readnone) + get { + Swift.min(Int.bitWidth, 56) + } + } + + /// The maximum number of items for which we do not create a hash table. + @usableFromInline + @inline(__always) + internal static var maximumUnhashedCount: Int { + @_effects(readnone) + get { + (1 &<< (minimumScale - 1)) - 1 + } + } + + /// The maximum hash table load factor. + @inline(__always) + internal static var maximumLoadFactor: Double { 3 / 4 } + + /// The minimum hash table load factor. + @inline(__always) + internal static var minimumLoadFactor: Double { 1 / 4 } + + /// The maximum number of items that can be held in a hash table of the given scale. + @usableFromInline + @_effects(readnone) + internal static func minimumCapacity(forScale scale: Int) -> Int { + guard scale >= minimumScale else { return 0 } + let bucketCount = 1 &<< scale + return Int(Double(bucketCount) * minimumLoadFactor) + } + + /// The maximum number of items that can be held in a hash table of the given scale. + @usableFromInline + @_effects(readnone) + internal static func maximumCapacity(forScale scale: Int) -> Int { + guard scale >= minimumScale else { return maximumUnhashedCount } + let bucketCount = 1 &<< scale + return Int(Double(bucketCount) * maximumLoadFactor) + } + + /// The minimum hash table scale that can hold the specified number of elements. + @usableFromInline + @_effects(readnone) + internal static func scale(forCapacity capacity: Int) -> Int { + guard capacity > maximumUnhashedCount else { return 0 } + let capacity = Swift.max(capacity, 1) + // Calculate the minimum number of entries we need to allocate to satisfy + // the maximum load factor. `capacity + 1` below ensures that we always + // leave at least one hole. + let minimumEntries = Swift.max( + Int((Double(capacity) / maximumLoadFactor).rounded(.up)), + capacity + 1) + // The actual number of entries we need to allocate is the lowest power of + // two greater than or equal to the minimum entry count. Calculate its + // exponent. + let scale = (Swift.max(minimumEntries, 2) - 1)._binaryLogarithm() + 1 + assert(scale >= minimumScale && scale < Int.bitWidth) + // The scale is the exponent corresponding to the bucket count. + assert(self.maximumCapacity(forScale: scale) >= capacity) + return scale + } + + /// The count of 64-bit words that a hash table of the specified scale + /// will need to have in its storage. + internal static func wordCount(forScale scale: Int) -> Int { + ((scale &<< scale) + 63) / 64 + } +} + diff --git a/Sources/OrderedCollections/HashTable/_HashTable+CustomStringConvertible.swift b/Sources/OrderedCollections/HashTable/_HashTable+CustomStringConvertible.swift new file mode 100644 index 00000000..2c466312 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable+CustomStringConvertible.swift @@ -0,0 +1,61 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// These are primarily for debugging. + +extension _HashTable.Header: CustomStringConvertible { + @usableFromInline + internal var _description: String { + "(scale: \(scale), reservedScale: \(reservedScale), bias: \(bias), seed: \(String(seed, radix: 16)))" + } + + @usableFromInline + internal var description: String { + "_HashTable.Header\(_description)" + } +} + +extension _HashTable.UnsafeHandle: CustomStringConvertible { + internal func _description(type: String) -> String { + var d = """ + \(type)\(_header.pointee._description) + load factor: \(debugLoadFactor()) + """ + if bucketCount < 128 { + d += "\n " + d += debugContents() + .lazy + .map { $0 == nil ? "_" : "\($0!)" } + .joined(separator: " ") + } + return d + } + + @usableFromInline + internal var description: String { + _description(type: "_HashTable.UnsafeHandle") + } +} + +extension _HashTable: CustomStringConvertible { + @usableFromInline + internal var description: String { + read { $0._description(type: "_HashTable") } + } +} + +extension _HashTable.Storage: CustomStringConvertible { + @usableFromInline + internal var description: String { + _HashTable(self).read { $0._description(type: "_HashTable.Storage") } + } +} + diff --git a/Sources/OrderedCollections/HashTable/_HashTable+Testing.swift b/Sources/OrderedCollections/HashTable/_HashTable+Testing.swift new file mode 100644 index 00000000..f27006fa --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable+Testing.swift @@ -0,0 +1,63 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension _HashTable.Bucket: CustomStringConvertible { + public var description: String { "Bucket(@\(offset))"} +} + +extension _UnsafeHashTable { + internal func debugOccupiedCount() -> Int { + var count = 0 + var it = bucketIterator(startingAt: Bucket(offset: 0)) + repeat { + if it.isOccupied { + count += 1 + } + it.advance() + } while it.currentBucket.offset != 0 + return count + } + + internal func debugLoadFactor() -> Double { + return Double(debugOccupiedCount()) / Double(bucketCount) + } + + internal func debugContents() -> [Int?] { + var result: [Int?] = [] + result.reserveCapacity(bucketCount) + var it = bucketIterator(startingAt: Bucket(offset: 0)) + repeat { + result.append(it.currentValue) + it.advance() + } while it.currentBucket.offset != 0 + return result + } +} + +extension _UnsafeHashTable.BucketIterator: CustomStringConvertible { + @usableFromInline + var description: String { + func pad(_ s: String, to length: Int, by padding: Character = " ") -> String { + let c = s.count + guard c < length else { return s } + return String(repeating: padding, count: length - c) + s + } + let offset = pad(String(_currentBucket.offset), to: 4) + let value: String + if let v = currentValue { + value = pad(String(v), to: 4) + } else { + value = " nil" + } + let remainingBits = pad(String(_nextBits, radix: 2), to: _remainingBitCount, by: "0") + return "BucketIterator(scale: \(_scale), bucket: \(offset), value: \(value), bits: \(remainingBits) (\(_remainingBitCount) bits))" + } +} diff --git a/Sources/OrderedCollections/HashTable/_HashTable+UnsafeHandle.swift b/Sources/OrderedCollections/HashTable/_HashTable+UnsafeHandle.swift new file mode 100644 index 00000000..ba8efcb4 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable+UnsafeHandle.swift @@ -0,0 +1,542 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@usableFromInline +internal typealias _UnsafeHashTable = _HashTable.UnsafeHandle + +extension _HashTable { + /// A non-owning handle to hash table storage, implementing higher-level + /// table operations. + /// + /// - Warning: `_UnsafeHashTable` values do not have ownership of their + /// underlying storage buffer. You must not escape these handles outside + /// the closure call that produced them. + @usableFromInline + @frozen + internal struct UnsafeHandle { + @usableFromInline + internal typealias Bucket = _HashTable.Bucket + + /// A pointer to the table header. + @usableFromInline + internal var _header: UnsafeMutablePointer
+ + /// A pointer to bucket storage. + @usableFromInline + internal var _buckets: UnsafeMutablePointer + + #if DEBUG + /// True when this handle does not support table mutations. + /// (This is only checked in debug builds.) + @usableFromInline + internal let _readonly: Bool + #endif + + /// Initialize a new hash table handle for storage at the supplied locations. + @inlinable + @inline(__always) + internal init( + header: UnsafeMutablePointer
, + buckets: UnsafeMutablePointer, + readonly: Bool + ) { + self._header = header + self._buckets = buckets + #if DEBUG + self._readonly = readonly + #endif + } + + /// Check that this handle supports mutating operations. + /// Every member that mutates table data must start by calling this function. + /// This helps preventing COW violations. + /// + /// Note that this is a noop in release builds. + @inlinable + @inline(__always) + func assertMutable() { + #if DEBUG + assert(!_readonly, "Attempt to mutate a hash table through a read-only handle") + #endif + } + } +} + +extension _HashTable.UnsafeHandle { + /// The scale of the hash table. A table of scale *n* holds 2^*n* buckets, + /// each of which contain an *n*-bit value. + @inlinable + @inline(__always) + internal var scale: Int { _header.pointee.scale } + + /// The scale corresponding to the last call to `reserveCapacity`. + /// We store this to make sure we don't shrink the table below its reserved size. + @inlinable + @inline(__always) + internal var reservedScale: Int { _header.pointee.reservedScale } + + /// The hasher seed to use within this hash table. + @inlinable + @inline(__always) + internal var seed: Int { _header.pointee.seed } + + /// A bias value that needs to be added to buckets to convert them into offsets + /// into element storage. (This allows O(1) insertions at the front when the + /// underlying storage supports it.) + @inlinable + @inline(__always) + internal var bias: Int { + get { _header.pointee.bias } + nonmutating set { _header.pointee.bias = newValue } + } + + /// The number of buckets within this hash table. This is always a power of two. + @inlinable + @inline(__always) + internal var bucketCount: Int { 1 &<< scale } + + @inlinable + @inline(__always) + internal var bucketMask: UInt64 { UInt64(truncatingIfNeeded: bucketCount) - 1 } + + /// The number of bits used to store all the buckets in this hash table. + /// Each bucket holds a value that is `scale` bits wide. + @inlinable + @inline(__always) + internal var bitCount: Int { scale &<< scale } + + /// The number of 64-bit words that are available in the storage buffer, + /// rounded up to the nearest whole number if necessary. + @inlinable + @inline(__always) + internal var wordCount: Int { (bitCount + UInt64.bitWidth - 1) / UInt64.bitWidth } + + /// The maximum number of items that can fit into this table. + @inlinable + @inline(__always) + internal var capacity: Int { _HashTable.maximumCapacity(forScale: scale) } + + /// Return the bucket logically following `bucket` in this hash table. + /// The buckets form a cycle, so the last bucket is logically followed by the first. + @inlinable + @inline(__always) + func bucket(after bucket: Bucket) -> Bucket { + var offset = bucket.offset + 1 + if offset == bucketCount { + offset = 0 + } + return Bucket(offset: offset) + } + + /// Return the bucket logically preceding `bucket` in this hash table. + /// The buckets form a cycle, so the first bucket is logically preceded by the last. + @inlinable + @inline(__always) + func bucket(before bucket: Bucket) -> Bucket { + let offset = (bucket.offset == 0 ? bucketCount : bucket.offset) - 1 + return Bucket(offset: offset) + } + + /// Return the index of the word logically following `word` in this hash table. + /// The buckets form a cycle, so the last word is logically followed by the first. + /// + /// Note that the last word may be only partially filled if `scale` is less than 6. + @inlinable + @inline(__always) + func word(after word: Int) -> Int { + var result = word + 1 + if result == wordCount { + result = 0 + } + return result + } + + /// Return the index of the word logically preceding `word` in this hash table. + /// The buckets form a cycle, so the first word is logically preceded by the first. + /// + /// Note that the last word may be only partially filled if `scale` is less than 6. + @inlinable + @inline(__always) + func word(before word: Int) -> Int { + if word == 0 { + return wordCount - 1 + } + return word - 1 + } + + /// Return the index of the 64-bit storage word that holds the first bit + /// corresponding to `bucket`, along with its bit position within the word. + @inlinable + internal func position(of bucket: Bucket) -> (word: Int, bit: Int) { + let start = bucket.offset &* scale + return (start &>> 6, start & 0x3F) + } +} + +extension _HashTable.UnsafeHandle { + /// Decode and return the logical value corresponding to the specified bucket value. + /// + /// The nil value is represented by an all-zero bit pattern. + /// Other values are stored as the complement of the lowest `scale` bits + /// after taking `bias` into account. + /// The range of representable values is `0 ..< bucketCount - 1`. + /// (Note that the value `bucketCount - 1` is missing from this range, as its + /// encoding is used for `nil`. This isn't an issue, because the maximum load + /// factor guarantees that the hash table will never be completely full.) + @inlinable + func _value(forBucketContents bucketContents: UInt64) -> Int? { + let mask = bucketMask + assert(bucketContents <= mask) + guard bucketContents != 0 else { return nil } + let v = (bucketContents ^ mask) &+ UInt64(truncatingIfNeeded: bias) + return Int(truncatingIfNeeded: v >= mask ? v - mask : v) + } + + /// Encodes the specified logical value into a `scale`-bit bit pattern suitable + /// for storing into a bucket. + /// + /// The nil value is represented by an all-zero bit pattern. + /// Other values are stored as the complement of their lowest `scale` bits. + /// The range of representable values is `0 ..< bucketCount - 1`. + /// (Note that the value `bucketCount - 1` is missing from this range, as it + /// its encoding is used for `nil`. This isn't an issue, because the maximum + /// load factor guarantees that the hash table will never be completely full.) + @inlinable + func _bucketContents(for value: Int?) -> UInt64 { + guard var value = value else { return 0 } + let mask = Int(truncatingIfNeeded: bucketMask) + assert(value >= 0 && value < mask) + value &-= bias + if value < 0 { value += mask } + assert(value >= 0 && value < mask) + return UInt64(truncatingIfNeeded: value ^ mask) + } + + @inlinable + subscript(word word: Int) -> UInt64 { + @inline(__always) get { + assert(word >= 0 && word < bucketCount) + return _buckets[word] + } + @inline(__always) nonmutating set { + assert(word >= 0 && word < bucketCount) + assertMutable() + _buckets[word] = newValue + } + } + + @inlinable + subscript(raw bucket: Bucket) -> UInt64 { + get { + assert(bucket.offset < bucketCount) + let (word, bit) = position(of: bucket) + var value = self[word: word] &>> bit + let extractedBits = 64 - bit + if extractedBits < scale { + let word2 = self.word(after: word) + value &= (1 &<< extractedBits) - 1 + value |= self[word: word2] &<< extractedBits + } + return value & bucketMask + } + nonmutating set { + assertMutable() + assert(bucket.offset < bucketCount) + let mask = bucketMask + assert(newValue <= mask) + let (word, bit) = position(of: bucket) + self[word: word] &= ~(mask &<< bit) + self[word: word] |= newValue &<< bit + let extractedBits = 64 - bit + if extractedBits < scale { + let word2 = self.word(after: word) + self[word: word2] &= ~((1 &<< (scale - extractedBits)) - 1) + self[word: word2] |= newValue &>> extractedBits + } + } + } + + @inlinable + @inline(__always) + func isOccupied(_ bucket: Bucket) -> Bool { + self[raw: bucket] != 0 + } + + /// Return or update the current value stored in the specified bucket. + /// A nil value indicates that the bucket is empty. + @inlinable + internal subscript(bucket: Bucket) -> Int? { + get { + let contents = self[raw: bucket] + return _value(forBucketContents: contents) + } + nonmutating set { + assertMutable() + let v = _bucketContents(for: newValue) + self[raw: bucket] = v + } + } +} + +extension _UnsafeHashTable { + @inlinable + internal func _find( + _ item: Base.Element, + in elements: Base + ) -> (index: Int?, bucket: Bucket) + where Base.Element: Hashable { + let start = idealBucket(for: item) + var (iterator, value) = startFind(start) + while let index = value { + if elements[_offset: index] == item { + return (index, iterator.currentBucket) + } + value = iterator.findNext() + } + return (nil, iterator.currentBucket) + } +} + +extension _UnsafeHashTable { + @usableFromInline + internal func firstOccupiedBucketInChain(with bucket: Bucket) -> Bucket { + var bucket = bucket + repeat { + bucket = self.bucket(before: bucket) + } while isOccupied(bucket) + return self.bucket(after: bucket) + } + + @inlinable + internal func delete( + bucket: Bucket, + hashValueGenerator: (Int, Int) -> Int // (offset, seed) -> hashValue + ) { + assertMutable() + var it = bucketIterator(startingAt: bucket) + assert(it.isOccupied) + it.advance() + guard it.isOccupied else { + // Fast path: Don't get the start bucket when there's nothing to do. + self[bucket] = nil + return + } + // If we've put a hole in the middle of a collision chain, some element after + // the hole may belong where the new hole is. + + // Find the first bucket in the collision chain that contains the entry we've just deleted. + let start = firstOccupiedBucketInChain(with: bucket) + var hole = bucket + + while it.isOccupied { + let hash = hashValueGenerator(it.currentValue!, seed) + let candidate = idealBucket(forHashValue: hash) + + // Does this element belong between start and hole? We need two + // separate tests depending on whether [start, hole] wraps around the + // end of the storage. + let c0 = candidate.offset >= start.offset + let c1 = candidate.offset <= hole.offset + if start.offset <= hole.offset ? (c0 && c1) : (c0 || c1) { + // Fill the hole. Here we are mutating table contents behind the back of + // the iterator; this is okay since we know we are never going to revisit + // `hole` with it. + self[hole] = it.currentValue + hole = it.currentBucket + } + it.advance() + } + self[hole] = nil + } +} + +extension _UnsafeHashTable { + @inlinable + internal func adjustContents( + preparingForInsertionOfElementAtOffset offset: Int, + in elements: Base + ) where Base.Element: Hashable { + assertMutable() + let index = elements._index(at: offset) + if offset < elements.count / 2 { + self.bias += 1 + if offset <= capacity / 3 { + var i = 1 + for item in elements[..= offset { + it.currentValue = value + 1 + } + it.advance() + } while it.currentBucket.offset != 0 + } + } + } +} + +extension _UnsafeHashTable { + @inlinable + @inline(__always) + internal func adjustContents( + preparingForRemovalOf index: Base.Index, + in elements: Base + ) where Base.Element: Hashable { + let next = elements.index(after: index) + adjustContents(preparingForRemovalOf: index ..< next, in: elements) + } + + @inlinable + internal func adjustContents( + preparingForRemovalOf bounds: Range, + in elements: Base + ) where Base.Element: Hashable { + assertMutable() + let startOffset = elements._offset(of: bounds.lowerBound) + let endOffset = elements._offset(of: bounds.upperBound) + let c = endOffset - startOffset + guard c > 0 else { return } + let remainingCount = elements.count - c + + if startOffset >= remainingCount / 2 { + let tailCount = elements.count - endOffset + if tailCount < capacity / 3 { + var i = endOffset + for item in elements[bounds.upperBound...] { + var it = self.bucketIterator(for: item) + it.advance(until: i) + it.currentValue = i - c + i += 1 + } + } else { + var it = bucketIterator(startingAt: Bucket(offset: 0)) + repeat { + if let value = it.currentValue { + if value >= endOffset { + it.currentValue = value - c + } else { + assert(value < startOffset) + } + } + it.advance() + } while it.currentBucket.offset != 0 + } + } else { + if startOffset < capacity / 3 { + var i = 0 + for item in elements[..= endOffset) + } + } + it.advance() + } while it.currentBucket.offset != 0 + } + self.bias -= c + } + } +} + +extension _UnsafeHashTable { + @usableFromInline + internal func clear() { + assertMutable() + _buckets.assign(repeating: 0, count: wordCount) + } +} + +extension _UnsafeHashTable { + /// Fill an empty hash table by populating it with data from `elements`. + /// + /// - Parameter elements: A random-access collection for which this table is being generated. + @inlinable + internal func fill( + uncheckedUniqueElements elements: C + ) where C.Element: Hashable { + assertMutable() + assert(elements.count <= capacity) + // Iterate over elements and insert their offset into the hash table. + var offset = 0 + for index in elements.indices { + // Find the insertion position. We know that we're inserting a new item, + // so there is no need to compare it with any of the existing ones. + var it = bucketIterator(for: elements[index]) + it.advanceToNextUnoccupiedBucket() + it.currentValue = offset + offset += 1 + } + } + + /// Fill an empty hash table by populating it with data from `elements`. + /// + /// - Parameter elements: A random-access collection for which this table is being generated. + /// - Parameter stoppingOnFirstDuplicateValue: If true, check for duplicate values and stop inserting items when one is found. + /// - Returns: `(success, index)` where `success` is a boolean value indicating that every value in `elements` was successfully inserted. A false success indicates that duplicate elements have been found; in this case `index` points to the first duplicate value; otherwise `index` is set to `elements.endIndex`. + @inlinable + internal func fill( + untilFirstDuplicateIn elements: C + ) -> (success: Bool, end: C.Index) + where C.Element: Hashable { + assertMutable() + assert(elements.count <= capacity) + // Iterate over elements and insert their offset into the hash table. + var offset = 0 + for index in elements.indices { + // Find the insertion position. We know that we're inserting a new item, + // so there is no need to compare it with any of the existing ones. + var it = bucketIterator(for: elements[index]) + while let offset = it.currentValue { + guard elements[_offset: offset] != elements[index] else { + return (false, index) + } + it.advance() + } + it.currentValue = offset + offset += 1 + } + return (true, elements.endIndex) + } +} diff --git a/Sources/OrderedCollections/HashTable/_HashTable.swift b/Sources/OrderedCollections/HashTable/_HashTable.swift new file mode 100644 index 00000000..7faa5344 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_HashTable.swift @@ -0,0 +1,201 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +@usableFromInline +@frozen +internal struct _HashTable { + @usableFromInline + internal var _storage: Storage + + @inlinable + @inline(__always) + internal init(_ storage: Storage) { + _storage = storage + } +} + +extension _HashTable { + /// A class holding hash table storage for a `OrderedSet` collection. + /// Values in the hash table are offsets into separate element storage, so + /// this class doesn't need to be generic over `OrderedSet`'s `Element` type. + @usableFromInline + internal final class Storage + : ManagedBuffer + {} +} + +extension _HashTable { + /// Allocate a new empty hash table buffer of the specified scale. + @usableFromInline + @_effects(releasenone) + internal init(scale: Int, reservedScale: Int = 0) { + assert(scale >= Self.minimumScale && scale <= Self.maximumScale) + let wordCount = Self.wordCount(forScale: scale) + let storage = Storage.create( + minimumCapacity: wordCount, + makingHeaderWith: { object in + #if COLLECTIONS_DETERMINISTIC_HASHING + let seed = scale << 6 + #else + let seed = Int(bitPattern: Unmanaged.passUnretained(object).toOpaque()) + #endif + return Header(scale: scale, reservedScale: reservedScale, seed: seed) + }) + storage.withUnsafeMutablePointerToElements { elements in + elements.initialize(repeating: 0, count: wordCount) + } + self.init(unsafeDowncast(storage, to: Storage.self)) + } + + /// Populate a new hash table with data from `elements`. + /// + /// - Parameter scale: The desired hash table scale or nil to use the minimum scale that satisfies invariants. + /// - Parameter reservedScale: The reserved scale to remember in the returned storage. + /// - Parameter duplicates: The strategy to use to handle duplicate items. + /// - Returns: `(storage, index)` where `storage` is a storage instance. The contents of `storage` reflects all elements in `contents[contents.startIndex ..< index]`. `index` is usually `contents.endIndex`, except when the function was asked to reject duplicates, in which case `index` addresses the first duplicate element in `contents` (if any). + @inlinable + @inline(never) + @_effects(releasenone) + static func create( + uncheckedUniqueElements elements: C, + scale: Int? = nil, + reservedScale: Int = 0 + ) -> _HashTable? + where C.Element: Hashable { + let minScale = Self.scale(forCapacity: elements.count) + let scale = Swift.max(Swift.max(scale ?? 0, minScale), + reservedScale) + if scale < Self.minimumScale { return nil } + let hashTable = Self(scale: scale, reservedScale: reservedScale) + hashTable.update { handle in + handle.fill(uncheckedUniqueElements: elements) + } + return hashTable + } + + /// Populate a new hash table with data from `elements`. + /// + /// - Parameter scale: The desired hash table scale or nil to use the minimum scale that satisfies invariants. + /// - Parameter reservedScale: The reserved scale to remember in the returned storage. + /// - Parameter duplicates: The strategy to use to handle duplicate items. + /// - Returns: `(storage, index)` where `storage` is a storage instance. The contents of `storage` reflects all elements in `contents[contents.startIndex ..< index]`. `index` is usually `contents.endIndex`, except when the function was asked to reject duplicates, in which case `index` addresses the first duplicate element in `contents` (if any). + @inlinable + @inline(never) + @_effects(releasenone) + static func create( + untilFirstDuplicateIn elements: C, + scale: Int? = nil, + reservedScale: Int = 0 + ) -> (hashTable: _HashTable?, end: C.Index) + where C.Element: Hashable { + let minScale = Self.scale(forCapacity: elements.count) + let scale = Swift.max(Swift.max(scale ?? 0, minScale), + reservedScale) + if scale < Self.minimumScale { + // Don't hash anything. + if elements.count < 2 { return (nil, elements.endIndex) } + var temp: [C.Element] = [] + temp.reserveCapacity(elements.count) + for i in elements.indices { + let item = elements[i] + guard !temp.contains(item) else { return (nil, i) } + temp.append(item) + } + return (nil, elements.endIndex) + } + let hashTable = Self(scale: scale, reservedScale: reservedScale) + let (_, index) = hashTable.update { handle in + handle.fill(untilFirstDuplicateIn: elements) + } + return (hashTable, index) + } + + /// Create and return a new copy of this instance. The result has the same + /// scale and seed, and contains the exact same bucket data as the original instance. + @usableFromInline + @_effects(releasenone) + internal func copy() -> _HashTable { + self.read { handle in + let wordCount = handle.wordCount + let new = Storage.create( + minimumCapacity: wordCount, + makingHeaderWith: { _ in handle._header.pointee }) + new.withUnsafeMutablePointerToElements { elements in + elements.initialize(from: handle._buckets, count: wordCount) + } + return Self(unsafeDowncast(new, to: Storage.self)) + } + } +} + + + +extension _HashTable { + /// Call `body` with a hash table handle suitable for read-only use. + /// + /// - Warning: The handle supplied to `body` is only valid for the duration of + /// the closure call. The closure must not escape it outside the call. + @inlinable + @inline(__always) + internal func read(_ body: (_UnsafeHashTable) throws -> R) rethrows -> R { + try _storage.withUnsafeMutablePointers { header, elements in + let handle = _UnsafeHashTable(header: header, buckets: elements, readonly: true) + return try body(handle) + } + } + + /// Call `body` with a hash table handle suitable for mutating use. + /// + /// - Warning: The handle supplied to `body` is only valid for the duration of + /// the closure call. The closure must not escape it outside the call. + @inlinable + @inline(__always) + internal func update(_ body: (_UnsafeHashTable) throws -> R) rethrows -> R { + try _storage.withUnsafeMutablePointers { header, elements in + let handle = _UnsafeHashTable(header: header, buckets: elements, readonly: false) + return try body(handle) + } + } +} + +extension _HashTable { + @inlinable + internal var header: Header { + get { _storage.header } + nonmutating _modify { yield &_storage.header } + } + + @inlinable + internal var capacity: Int { + _storage.header.capacity + } + + @inlinable + internal var minimumCapacity: Int { + if scale == reservedScale { return 0 } + return Self.minimumCapacity(forScale: scale) + } + + @inlinable + internal var scale: Int { + _storage.header.scale + } + + @inlinable + internal var reservedScale: Int { + _storage.header.reservedScale + } + + @inlinable + internal var bias: Int { + _storage.header.bias + } +} diff --git a/Sources/OrderedCollections/HashTable/_Hashtable+Header.swift b/Sources/OrderedCollections/HashTable/_Hashtable+Header.swift new file mode 100644 index 00000000..93ceb246 --- /dev/null +++ b/Sources/OrderedCollections/HashTable/_Hashtable+Header.swift @@ -0,0 +1,99 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension _HashTable { + /// The storage header for hash table buffers. + /// + /// Note that we don't store the number of items currently in the table; + /// that information can be easily retrieved from the element storage. + @usableFromInline + internal struct Header { + /// We are packing the scale data into the lower bits of the seed & bias + /// to saves a bit of space that would be otherwise taken up by padding. + /// + /// Layout: + /// + /// 63 6 5 0 + /// ├──────────────────────────────────────────────┼────────┤ + /// │ seed │ scale │ + /// └──────────────────────────────────────────────┴────────┘ + /// 63 6 5 0 + /// ├──────────────────────────────────────────────┼────────┤ + /// │ bias │ rsvd │ + /// └──────────────────────────────────────────────┴────────┘ + @usableFromInline + var _scaleAndSeed: UInt64 + @usableFromInline + var _reservedScaleAndBias: UInt64 + + init(scale: Int, reservedScale: Int, seed: Int) { + assert(scale >= _HashTable.minimumScale && scale <= _HashTable.maximumScale) + assert(reservedScale >= 0 && reservedScale <= _HashTable.maximumScale) + _scaleAndSeed = UInt64(truncatingIfNeeded: seed) << (Swift.max(UInt64.bitWidth - Int.bitWidth, 6)) + _scaleAndSeed &= ~0x3F + _scaleAndSeed |= UInt64(truncatingIfNeeded: scale) + _reservedScaleAndBias = UInt64(truncatingIfNeeded: reservedScale) + assert(self.scale == scale) + assert(self.reservedScale == reservedScale) + assert(self.bias == 0) + } + + /// The scale of the hash table. A table of scale *n* holds 2^*n* buckets, + /// each of which contain an *n*-bit value. + @inlinable + @inline(__always) + var scale: Int { Int(_scaleAndSeed & 0x3F) } + + /// The scale corresponding to the last call to `reserveCapacity`. + /// We remember this here to make sure we don't shrink the table below its reserved size. + @inlinable + var reservedScale: Int { + @inline(__always) + get { Int(_reservedScaleAndBias & 0x3F) } + set { + assert(newValue >= 0 && newValue < 64) + _reservedScaleAndBias &= ~0x3F + _reservedScaleAndBias |= UInt64(truncatingIfNeeded: newValue) & 0x3F + } + } + + /// The hasher seed to use within this hash table. + @inlinable + @inline(__always) + var seed: Int { + Int(truncatingIfNeeded: _scaleAndSeed) + } + + /// A bias value that needs to be added to buckets to convert them into offsets + /// into element storage. (This allows O(1) insertions at the front when the + /// underlying storage supports it.) + @inlinable + var bias: Int { + @inline(__always) + get { Int(truncatingIfNeeded: _reservedScaleAndBias) &>> 6 } + set { + let limit = (1 &<< scale) - 1 + var bias = newValue + if bias < 0 { bias += limit } + if bias >= limit { bias -= limit } + assert(bias >= 0 && bias < limit) + _reservedScaleAndBias &= 0x3F + _reservedScaleAndBias |= UInt64(truncatingIfNeeded: bias) &<< 6 + assert(self.bias >= 0 && self.bias < limit) + } + } + + /// The maximum number of items that can fit into this table. + @inlinable + @inline(__always) + var capacity: Int { _HashTable.maximumCapacity(forScale: scale) } + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Codable.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Codable.swift new file mode 100644 index 00000000..153ff45c --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Codable.swift @@ -0,0 +1,76 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: Encodable where Key: Encodable, Value: Encodable { + /// Encodes the contents of this dictionary into the given encoder. + /// + /// The dictionary's contents are encoded as alternating key-value pairs in + /// an unkeyed container. + /// + /// This function throws an error if any values are invalid for the given + /// encoder's format. + /// + /// - Note: Unlike the standard `Dictionary` type, ordered dictionaries + /// always encode in an unkeyed container, because `Codable`'s keyed + /// containers do not guarantee that they preserve the ordering of the + /// items they contain. (And in popular encoding formats, keyed containers + /// tend to map to unordered data structures -- e.g., JSON's "object" + /// construct is explicitly unordered.) + /// + /// - Parameter encoder: The encoder to write data to. + @inlinable + public func encode(to encoder: Encoder) throws { + // Encode contents as an array of alternating key-value pairs. + var container = encoder.unkeyedContainer() + for (key, value) in self { + try container.encode(key) + try container.encode(value) + } + } +} + +extension OrderedDictionary: Decodable where Key: Decodable, Value: Decodable { + /// Creates a new dictionary by decoding from the given decoder. + /// + /// This initializer throws an error if reading from the decoder fails, or + /// if the decoded contents are corrupt (such as they contain duplicate values). + /// + /// - Parameter decoder: The decoder to read data from. + @inlinable + public init(from decoder: Decoder) throws { + // We expect to be encoded as an array of alternating key-value pairs. + var container = try decoder.unkeyedContainer() + + self.init() + while !container.isAtEnd { + let key = try container.decode(Key.self) + let (index, bucket) = self._keys._find(key) + guard index == nil else { + let context = DecodingError.Context( + codingPath: container.codingPath, + debugDescription: "Duplicate key at offset \(container.currentIndex - 1)") + throw DecodingError.dataCorrupted(context) + } + + guard !container.isAtEnd else { + throw DecodingError.dataCorrupted( + DecodingError.Context( + codingPath: container.codingPath, + debugDescription: "Unkeyed container reached end before value in key-value pair" + ) + ) + } + let value = try container.decode(Value.self) + _keys._appendNew(key, in: bucket) + _values.append(value) + } + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomDebugStringConvertible.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomDebugStringConvertible.swift new file mode 100644 index 00000000..4bc122a3 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomDebugStringConvertible.swift @@ -0,0 +1,44 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: CustomDebugStringConvertible { + /// A textual representation of this instance, suitable for debugging. + public var debugDescription: String { + _debugDescription(typeName: _debugTypeName()) + } + + internal func _debugTypeName() -> String { + "OrderedDictionary<\(Key.self), \(Value.self)>" + } + + internal func _debugDescription(typeName: String) -> String { + var result = "\(typeName)(" + if isEmpty { + result += "[:]" + } else { + result += "[" + var first = true + for (key, value) in self { + if first { + first = false + } else { + result += ", " + } + debugPrint(key, terminator: "", to: &result) + result += ": " + debugPrint(value, terminator: "", to: &result) + } + result += "]" + } + result += ")" + return result + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomReflectable.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomReflectable.swift new file mode 100644 index 00000000..82a5d37c --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomReflectable.swift @@ -0,0 +1,17 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: CustomReflectable { + /// The custom mirror for this instance. + public var customMirror: Mirror { + Mirror(self, unlabeledChildren: self.elements, displayStyle: .dictionary) + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomStringConvertible.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomStringConvertible.swift new file mode 100644 index 00000000..eb40ebab --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+CustomStringConvertible.swift @@ -0,0 +1,29 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: CustomStringConvertible { + /// A textual representation of this instance. + public var description: String { + if isEmpty { return "[:]" } + var result = "[" + var first = true + for (key, value) in self { + if first { + first = false + } else { + result += ", " + } + result += "\(key): \(value)" + } + result += "]" + return result + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Elements+SubSequence.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Elements+SubSequence.swift new file mode 100644 index 00000000..542defb3 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Elements+SubSequence.swift @@ -0,0 +1,329 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary.Elements { + /// A collection that represents a contiguous slice of an ordered dictionary. + /// + /// Ordered dictionary slices are random access collections that + /// support efficient key-based lookups. + @frozen + public struct SubSequence { + @usableFromInline + internal var _base: OrderedDictionary + @usableFromInline + internal var _bounds: Range + + @inlinable + @inline(__always) + internal init(_base: OrderedDictionary, bounds: Range) { + self._base = _base + self._bounds = bounds + } + } +} + +extension OrderedDictionary.Elements.SubSequence { + /// A read-only collection view containing the keys in this slice. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var keys: OrderedSet.SubSequence { + _base._keys[_bounds] + } + + /// A read-only collection view containing the values in this slice. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var values: OrderedDictionary.Values.SubSequence { + _base.values[_bounds] + } +} + +extension OrderedDictionary.Elements.SubSequence { + /// Returns the index for the given key. + /// + /// If the given key is found in the dictionary, this method returns an index + /// into the dictionary that corresponds with the key-value pair. + /// + /// let countryCodes: OrderedDictionary = ["BR": "Brazil", "GH": "Ghana", "JP": "Japan"] + /// let index = countryCodes.index(forKey: "JP") + /// + /// print("Country code for \(countryCodes[index!].value): '\(countryCodes[index!].key)'.") + /// // Prints "Country code for Japan: 'JP'." + /// + /// - Parameter key: The key to find in the dictionary. + /// + /// - Returns: The index for `key` and its associated value if `key` is in + /// the dictionary; otherwise, `nil`. + /// + /// - Complexity: Expected to be O(1) on average, if `Key` implements + /// high-quality hashing. + @inlinable + public func index(forKey key: Key) -> Int? { + guard let index = _base.index(forKey: key) else { return nil } + guard _bounds.contains(index) else { return nil } + return index + } +} + +extension OrderedDictionary.Elements.SubSequence: Sequence { + // A type representing the collection’s elements. + public typealias Element = OrderedDictionary.Element + + /// The type that allows iteration over the collection's elements. + @frozen + public struct Iterator: IteratorProtocol { + @usableFromInline + internal var _base: OrderedDictionary + + @usableFromInline + internal var _end: Int + + @usableFromInline + internal var _index: Int + + @inlinable + @inline(__always) + internal init(_ base: OrderedDictionary.Elements.SubSequence) { + self._base = base._base + self._end = base._bounds.upperBound + self._index = base._bounds.lowerBound + } + + /// Advances to the next element and returns it, or `nil` if no next + /// element exists. + /// + /// - Complexity: O(1) + @inlinable + public mutating func next() -> Element? { + guard _index < _end else { return nil } + defer { _index += 1 } + return (_base._keys[_index], _base._values[_index]) + } + } + + /// Returns an iterator over the elements of this dictionary slice. + @inlinable + @inline(__always) + public func makeIterator() -> Iterator { + Iterator(self) + } +} + +extension OrderedDictionary.Elements.SubSequence: RandomAccessCollection { + /// The index type for an ordered dictionary: `Int`. + /// + /// The indices are integer offsets from the start of the original + /// (unsliced) collection. + public typealias Index = Int + + /// The type that represents the indices that are valid for subscripting an + /// ordered dictionary, in ascending order. + public typealias Indices = Range + + /// Ordered dictionary subsequences are self-slicing. + public typealias SubSequence = Self + + /// The position of the first element in a nonempty ordered dictionary slice. + /// + /// Note that instances of `OrderedDictionary.SubSequence` generally + /// don't have a `startIndex` with an offset of zero. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var startIndex: Int { _bounds.lowerBound } + + /// The "past the end" position---that is, the position one greater + /// than the last valid subscript argument. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var endIndex: Int { _bounds.upperBound } + + /// The indices that are valid for subscripting the collection, + /// in ascending order. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var indices: Range { _bounds } + + /// Returns the position immediately after the given index. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the dictionary. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately after `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(after i: Int) -> Int { i + 1 } + + /// Returns the position immediately before the given index. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the dictionary. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately before `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(before i: Int) -> Int { i - 1 } + + /// Replaces the given index with its successor. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the dictionary. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(after i: inout Int) { i += 1 } + + /// Replaces the given index with its predecessor. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the dictionary. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(before i: inout Int) { i -= 1 } + + /// Returns an index that is the specified distance from the given index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, or the returned value will not be a valid index. + /// + /// - Parameters: + /// - i: A valid index of the dictionary. + /// - distance: The distance to offset `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`. If `distance` + /// is positive, this is the same value as the result of `distance` calls to + /// `index(after:)`. If `distance` is negative, this is the same value as + /// the result of `abs(distance)` calls to `index(before:)`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(_ i: Int, offsetBy distance: Int) -> Int { + i + distance + } + + /// Returns an index that is the specified distance from the given index, + /// unless that distance is beyond a given limiting index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, unless the index passed as `limit` prevents offsetting + /// beyond those bounds. (Otherwise the returned value won't be a valid index + /// in the set.) + /// + /// - Parameters: + /// - i: A valid index of the dictionary. + /// - distance: The distance to offset `i`. + /// - limit: A valid index of the collection to use as a limit. If + /// `distance > 0`, `limit` has no effect if it is less than `i`. + /// Likewise, if `distance < 0`, `limit` has no effect if it is greater + /// than `i`. + /// - Returns: An index offset by `distance` from the index `i`, unless that + /// index would be beyond `limit` in the direction of movement. In that + /// case, the method returns `nil`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index( + _ i: Int, + offsetBy distance: Int, + limitedBy limit: Int + ) -> Int? { + _base._values.index(i, offsetBy: distance, limitedBy: limit) + } + + /// Returns the distance between two indices. + /// + /// - Parameters: + /// - start: A valid index of the collection. + /// - end: Another valid index of the collection. If `end` is equal to + /// `start`, the result is zero. + /// + /// - Returns: The distance between `start` and `end`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func distance(from start: Int, to end: Int) -> Int { + end - start + } + + /// Accesses the element at the specified position. + /// + /// - Parameter index: The position of the element to access. `index` must be + /// greater than or equal to `startIndex` and less than `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + public subscript(position: Int) -> Element { + precondition(_bounds.contains(position), "Index out of range") + return _base[offset: position] + } + + /// Accesses a contiguous subrange of the dictionary's elements. + /// + /// The returned `Subsequence` instance uses the same indices for the same + /// elements as the original dictionary. In particular, that slice, unlike an + /// `OrderedDictionary`, may have a nonzero `startIndex.offset` and an + /// `endIndex.offset` that is not equal to `count`. Always use the slice's + /// `startIndex` and `endIndex` properties instead of assuming that its + /// indices start or end at a particular value. + /// + /// - Parameter bounds: A range of valid indices in the dictionary. + /// + /// - Complexity: O(1) + @inlinable + public subscript(bounds: Range) -> SubSequence { + precondition( + bounds.lowerBound >= _bounds.lowerBound + && bounds.upperBound <= _bounds.upperBound, + "Index out of range") + return Self(_base: _base, bounds: bounds) + } + + /// A Boolean value indicating whether the collection is empty. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var isEmpty: Bool { _bounds.isEmpty } + + /// The number of elements in the dictionary. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var count: Int { _bounds.count } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Elements.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Elements.swift new file mode 100644 index 00000000..51cdd286 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Elements.swift @@ -0,0 +1,652 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary { + /// A view of the contents of an ordered dictionary as a random-access + /// collection. + @frozen + public struct Elements { + @usableFromInline + internal var _base: OrderedDictionary + + @inlinable + @inline(__always) + internal init(_base: OrderedDictionary) { + self._base = _base + } + } +} + +extension OrderedDictionary { + /// A view of the contents of this dictionary as a random-access collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var elements: Elements { + get { + Elements(_base: self) + } + _modify { + var elements = Elements(_base: self) + self = Self() + defer { self = elements._base } + yield &elements + } + } +} + +extension OrderedDictionary.Elements { + /// A read-only collection view containing the keys in this collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var keys: OrderedSet { + _base._keys + } + + /// A mutable collection view containing the values in this collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var values: OrderedDictionary.Values { + get { + _base.values + } + _modify { + var values = OrderedDictionary.Values(_base: _base) + self = Self(_base: .init()) + defer { self._base = values._base } + yield &values + } + } +} + +extension OrderedDictionary.Elements { + /// Returns the index for the given key. + /// + /// If the given key is found in the dictionary, this method returns an index + /// into the dictionary that corresponds with the key-value pair. + /// + /// let countryCodes: OrderedDictionary = ["BR": "Brazil", "GH": "Ghana", "JP": "Japan"] + /// let index = countryCodes.index(forKey: "JP") + /// + /// print("Country code for \(countryCodes[index!].value): '\(countryCodes[index!].key)'.") + /// // Prints "Country code for Japan: 'JP'." + /// + /// - Parameter key: The key to find in the dictionary. + /// + /// - Returns: The index for `key` and its associated value if `key` is in + /// the dictionary; otherwise, `nil`. + /// + /// - Complexity: Expected to be O(1) on average, if `Key` implements + /// high-quality hashing. + @inlinable + public func index(forKey key: Key) -> Int? { + _base.index(forKey: key) + } +} + +extension OrderedDictionary.Elements: Sequence { + /// The element type of the collection. + public typealias Element = (key: Key, value: Value) + + @inlinable + public var underestimatedCount: Int { _base.count } + + @inlinable + public func makeIterator() -> OrderedDictionary.Iterator { + _base.makeIterator() + } +} + +extension OrderedDictionary.Elements: RandomAccessCollection { + /// The index type for an ordered dictionary: `Int`. + /// + /// Indices in `Elements` are integer offsets from the start of the + /// collection. + public typealias Index = Int + + /// The type that represents the indices that are valid for subscripting the + /// `Elements` collection, in ascending order. + public typealias Indices = Range + + /// The position of the first element in a nonempty dictionary. + /// + /// For an instance of `OrderedDictionary.Elements`, `startIndex` is always + /// zero. If the dictionary is empty, `startIndex` is equal to `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var startIndex: Int { 0 } + + /// The collection's "past the end" position---that is, the position one + /// greater than the last valid subscript argument. + /// + /// In `OrderedDictionary.Elements`, `endIndex` always equals the count of + /// elements. If the dictionary is empty, `endIndex` is equal to `startIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var endIndex: Int { _base.count } + + /// Returns the position immediately after the given index. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately after `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(after i: Index) -> Index { i + 1 } + + /// Returns the position immediately before the given index. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately before `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(before i: Index) -> Index { i - 1 } + + /// Replaces the given index with its successor. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(after i: inout Index) { i += 1 } + + /// Replaces the given index with its predecessor. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(before i: inout Index) { i -= 1 } + + /// Returns an index that is the specified distance from the given index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, or the returned value will not be a valid index. + /// + /// - Parameters: + /// - i: A valid index of the collection. + /// - distance: The distance to offset `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`. If `distance` + /// is positive, this is the same value as the result of `distance` calls to + /// `index(after:)`. If `distance` is negative, this is the same value as + /// the result of `abs(distance)` calls to `index(before:)`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(_ i: Index, offsetBy distance: Int) -> Index { + i + distance + } + + /// Returns an index that is the specified distance from the given index, + /// unless that distance is beyond a given limiting index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, unless the index passed as `limit` prevents offsetting + /// beyond those bounds. (Otherwise the returned value won't be a valid index + /// in the collection.) + /// + /// - Parameters: + /// - i: A valid index of the collection. + /// - distance: The distance to offset `i`. + /// - limit: A valid index of the collection to use as a limit. If + /// `distance > 0`, `limit` has no effect if it is less than `i`. + /// Likewise, if `distance < 0`, `limit` has no effect if it is greater + /// than `i`. + /// - Returns: An index offset by `distance` from the index `i`, unless that + /// index would be beyond `limit` in the direction of movement. In that + /// case, the method returns `nil`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index( + _ i: Index, + offsetBy distance: Int, + limitedBy limit: Index + ) -> Index? { + _base._values.index(i, offsetBy: distance, limitedBy: limit) + } + + /// Returns the distance between two indices. + /// + /// - Parameters: + /// - start: A valid index of the collection. + /// - end: Another valid index of the collection. If `end` is equal to + /// `start`, the result is zero. + /// + /// - Returns: The distance between `start` and `end`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func distance(from start: Index, to end: Index) -> Int { + end - start + } + + /// Accesses the element at the specified position. This can be used to + /// perform in-place mutations on dictionary values. + /// + /// - Parameter index: The position of the element to access. `index` must be + /// greater than or equal to `startIndex` and less than `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public subscript(position: Index) -> Element { + (_base._keys[position], _base._values[position]) + } + + /// Accesses a contiguous subrange of the dictionary's elements. + /// + /// The returned `Subsequence` instance uses the same indices for the same + /// elements as the original collection. In particular, the slice, unlike an + /// `Elements`, may have a nonzero `startIndex` and an `endIndex` that is not + /// equal to `count`. Always use the slice's `startIndex` and `endIndex` + /// properties instead of assuming that its indices start or end at a + /// particular value. + /// + /// - Parameter bounds: A range of valid indices in the collection. + /// + /// - Complexity: O(1) + public subscript(bounds: Range) -> SubSequence { + _failEarlyRangeCheck(bounds, bounds: startIndex ..< endIndex) + return SubSequence(_base: _base, bounds: bounds) + } + + /// A Boolean value indicating whether the collection is empty. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var isEmpty: Bool { _base.isEmpty } + + /// The number of elements in the dictionary. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var count: Int { _base.count } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ index: Int, bounds: Range) { + _base._values._failEarlyRangeCheck(index, bounds: bounds) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ index: Index, bounds: ClosedRange) { + _base._values._failEarlyRangeCheck(index, bounds: bounds) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ range: Range, bounds: Range) { + _base._values._failEarlyRangeCheck(range, bounds: bounds) + } +} + +extension OrderedDictionary.Elements: CustomStringConvertible { + public var description: String { + _base.description + } +} + +extension OrderedDictionary.Elements: CustomDebugStringConvertible { + public var debugDescription: String { + _base._debugDescription( + typeName: "OrderedDictionary<\(Key.self), \(Value.self)>.Elements") + } +} + +extension OrderedDictionary.Elements: CustomReflectable { + public var customMirror: Mirror { + Mirror(self, unlabeledChildren: self, displayStyle: .collection) + } +} + +extension OrderedDictionary.Elements: Equatable where Value: Equatable { + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + left._base == right._base + } +} + +extension OrderedDictionary.Elements: Hashable where Value: Hashable { + @inlinable + public func hash(into hasher: inout Hasher) { + _base.hash(into: &hasher) + } +} + +// MARK: Partial `MutableCollection` + +extension OrderedDictionary.Elements { + /// Exchanges the key-value pairs at the specified indices of the dictionary. + /// + /// Both parameters must be valid indices below `endIndex`. Passing the same + /// index as both `i` and `j` has no effect. + /// + /// - Parameters: + /// - i: The index of the first value to swap. + /// - j: The index of the second value to swap. + /// + /// - Complexity: O(1) when the dictionary's storage isn't shared with another + /// value; O(`count`) otherwise. + @inlinable + @inline(__always) + public mutating func swapAt(_ i: Index, _ j: Index) { + _base.swapAt(i, j) + } + + /// Reorders the elements of the dictionary such that all the elements that + /// match the given predicate are after all the elements that don't match. + /// + /// After partitioning a collection, there is a pivot index `p` where + /// no element before `p` satisfies the `belongsInSecondPartition` + /// predicate and every element at or after `p` satisfies + /// `belongsInSecondPartition`. + /// + /// - Parameter belongsInSecondPartition: A predicate used to partition + /// the collection. All elements satisfying this predicate are ordered + /// after all elements not satisfying it. + /// - Returns: The index of the first element in the reordered collection + /// that matches `belongsInSecondPartition`. If no elements in the + /// collection match `belongsInSecondPartition`, the returned index is + /// equal to the collection's `endIndex`. + /// + /// - Complexity: O(`count`) + @inlinable + @inline(__always) + public mutating func partition( + by belongsInSecondPartition: (Element) throws -> Bool + ) rethrows -> Index { + try _base.partition(by: belongsInSecondPartition) + } +} + +extension OrderedDictionary.Elements { + /// Sorts the collection in place, using the given predicate as the + /// comparison between elements. + /// + /// When you want to sort a collection of elements that don't conform to + /// the `Comparable` protocol, pass a closure to this method that returns + /// `true` when the first element should be ordered before the second. + /// + /// Alternatively, use this method to sort a collection of elements that do + /// conform to `Comparable` when you want the sort to be descending instead + /// of ascending. Pass the greater-than operator (`>`) operator as the + /// predicate. + /// + /// `areInIncreasingOrder` must be a *strict weak ordering* over the + /// elements. That is, for any elements `a`, `b`, and `c`, the following + /// conditions must hold: + /// + /// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity) + /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are + /// both `true`, then `areInIncreasingOrder(a, c)` is also `true`. + /// (Transitive comparability) + /// - Two elements are *incomparable* if neither is ordered before the other + /// according to the predicate. If `a` and `b` are incomparable, and `b` + /// and `c` are incomparable, then `a` and `c` are also incomparable. + /// (Transitive incomparability) + /// + /// The sorting algorithm is not guaranteed to be stable. A stable sort + /// preserves the relative order of elements for which + /// `areInIncreasingOrder` does not establish an order. + /// + /// - Parameter areInIncreasingOrder: A predicate that returns `true` if its + /// first argument should be ordered before its second argument; + /// otherwise, `false`. If `areInIncreasingOrder` throws an error during + /// the sort, the elements may be in a different order, but none will be + /// lost. + /// + /// - Complexity: O(*n* log *n*), where *n* is the length of the collection. + @inlinable + @inline(__always) + public mutating func sort( + by areInIncreasingOrder: (Element, Element) throws -> Bool + ) rethrows { + try _base.sort(by: areInIncreasingOrder) + } +} + +extension OrderedDictionary.Elements where Key: Comparable { + /// Sorts the dictionary in place. + /// + /// You can sort an ordered dictionary of keys that conform to the + /// `Comparable` protocol by calling this method. The key-value pairs are + /// sorted in ascending order. (`Value` doesn't need to conform to + /// `Comparable` because the keys are guaranteed to be unique.) + /// + /// The sorting algorithm is not guaranteed to be stable. A stable sort + /// preserves the relative order of elements that compare equal. + /// + /// - Complexity: O(*n* log *n*), where *n* is the length of the collection. + @inlinable + @inline(__always) + public mutating func sort() { + _base.sort() + } +} + +extension OrderedDictionary.Elements { + /// Shuffles the collection in place. + /// + /// Use the `shuffle()` method to randomly reorder the elements of an ordered + /// dictionary. + /// + /// This method is equivalent to calling `shuffle(using:)`, passing in the + /// system's default random generator. + /// + /// - Complexity: O(*n*), where *n* is the length of the collection. + @inlinable + public mutating func shuffle() { + _base.shuffle() + } + + /// Shuffles the collection in place, using the given generator as a source + /// for randomness. + /// + /// You use this method to randomize the elements of a collection when you + /// are using a custom random number generator. For example, you can use the + /// `shuffle(using:)` method to randomly reorder the elements of an array. + /// + /// - Parameter generator: The random number generator to use when shuffling + /// the collection. + /// + /// - Complexity: O(*n*), where *n* is the length of the collection. + /// + /// - Note: The algorithm used to shuffle a collection may change in a future + /// version of Swift. If you're passing a generator that results in the + /// same shuffled order each time you run your program, that sequence may + /// change when your program is compiled using a different version of + /// Swift. + @inlinable + public mutating func shuffle( + using generator: inout T + ) { + _base.shuffle(using: &generator) + } +} + +extension OrderedDictionary.Elements { + /// Reverses the elements of the ordered dictionary in place. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func reverse() { + _base.reverse() + } +} + +// MARK: Partial `RangeReplaceableCollection` + +extension OrderedDictionary.Elements { + /// Removes all members from the dictionary. + /// + /// - Parameter keepingCapacity: If `true`, the dictionary's storage capacity + /// is preserved; if `false`, the underlying storage is released. The + /// default is `false`. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll(keepingCapacity keepCapacity: Bool = false) { + _base.removeAll(keepingCapacity: keepCapacity) + } + + /// Removes and returns the element at the specified position. + /// + /// All the elements following the specified position are moved to close the + /// resulting gap. + /// + /// - Parameter index: The position of the element to remove. `index` must be + /// a valid index of the collection that is not equal to the collection's + /// end index. + /// + /// - Returns: The removed element. + /// + /// - Complexity: O(`count`) + @inlinable + @discardableResult + public mutating func remove(at index: Int) -> Element { + _base.remove(at: index) + } + + /// Removes the specified subrange of elements from the collection. + /// + /// All the elements following the specified subrange are moved to close the + /// resulting gap. + /// + /// - Parameter bounds: The subrange of the collection to remove. The bounds + /// of the range must be valid indices of the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeSubrange(_ bounds: Range) { + _base.removeSubrange(bounds) + } + + /// Removes the specified subrange of elements from the collection. + /// + /// All the elements following the specified subrange are moved to close the + /// resulting gap. + /// + /// - Parameter bounds: The subrange of the collection to remove. The bounds + /// of the range must be valid indices of the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeSubrange( + _ bounds: R + ) where R.Bound == Int { + _base.removeSubrange(bounds) + } + + + /// Removes the last element of a non-empty dictionary. + /// + /// - Complexity: Expected to be O(`1`) on average, if `Element` implements + /// high-quality hashing. + @inlinable + @discardableResult + public mutating func removeLast() -> Element { + _base.removeLast() + } + + /// Removes the last `n` element of the dictionary. + /// + /// - Parameter n: The number of elements to remove from the collection. + /// `n` must be greater than or equal to zero and must not exceed the + /// number of elements in the collection. + /// + /// - Complexity: Expected to be O(`n`) on average, if `Element` implements + /// high-quality hashing. + @inlinable + public mutating func removeLast(_ n: Int) { + _base.removeLast(n) + } + + /// Removes the first element of a non-empty dictionary. + /// + /// The members following the removed key-value pair need to be moved to close + /// the resulting gaps in the storage arrays. + /// + /// - Complexity: O(`count`). + @inlinable + @discardableResult + public mutating func removeFirst() -> Element { + _base.removeFirst() + } + + /// Removes the first `n` elements of the dictionary. + /// + /// The members following the removed items need to be moved to close the + /// resulting gaps in the storage arrays. + /// + /// - Parameter n: The number of elements to remove from the collection. + /// `n` must be greater than or equal to zero and must not exceed the + /// number of elements in the set. + /// + /// - Complexity: O(`count`). + @inlinable + public mutating func removeFirst(_ n: Int) { + _base.removeFirst(n) + } + + /// Removes all the elements that satisfy the given predicate. + /// + /// Use this method to remove every element in a collection that meets + /// particular criteria. The order of the remaining elements is preserved. + /// + /// - Parameter shouldBeRemoved: A closure that takes an element of the + /// dictionary as its argument and returns a Boolean value indicating + /// whether the element should be removed from the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll( + where shouldBeRemoved: (Self.Element) throws -> Bool + ) rethrows { + try _base.removeAll(where: shouldBeRemoved) + } +} + diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Equatable.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Equatable.swift new file mode 100644 index 00000000..93ed08c6 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Equatable.swift @@ -0,0 +1,23 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: Equatable where Value: Equatable { + /// Returns a Boolean value indicating whether two values are equal. + /// + /// Two ordered dictionaries are considered equal if they contain the same + /// key-value pairs, in the same order. + /// + /// - Complexity: O(`min(left.count, right.count)`) + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + left._keys == right._keys && left._values == right._values + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+ExpressibleByDictionaryLiteral.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+ExpressibleByDictionaryLiteral.swift new file mode 100644 index 00000000..91f11600 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+ExpressibleByDictionaryLiteral.swift @@ -0,0 +1,34 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: ExpressibleByDictionaryLiteral { + /// Creates a new ordered dictionary from the contents of a dictionary + /// literal. + /// + /// Duplicate elements in the literal are allowed, but the resulting + /// set will only contain the first occurrence of each. + /// + /// Do not call this initializer directly. It is used by the compiler when you + /// use a dictionary literal. Instead, create a new ordered dictionary using a + /// dictionary literal as its value by enclosing a comma-separated list of + /// values in square brackets. You can use an array literal anywhere a set is + /// expected by the type context. + /// + /// - Parameter elements: A variadic list of key-value pairs for the new + /// dictionary. + /// + /// - Complexity: O(`elements.count`) if `Key` implements + /// high-quality hashing. + @inlinable + public init(dictionaryLiteral elements: (Key, Value)...) { + self.init(uniqueKeysWithValues: elements) + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Hashable.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Hashable.swift new file mode 100644 index 00000000..40375df8 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Hashable.swift @@ -0,0 +1,25 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: Hashable where Value: Hashable { + /// Hashes the essential components of this value by feeding them into the + /// given hasher. + /// + /// Complexity: O(`count`) + @inlinable + public func hash(into hasher: inout Hasher) { + hasher.combine(count) // Discriminator + for (key, value) in self { + hasher.combine(key) + hasher.combine(value) + } + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Initializers.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Initializers.swift new file mode 100644 index 00000000..1d27adaa --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Initializers.swift @@ -0,0 +1,407 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary { + /// Creates an empty dictionary. + /// + /// This initializer is equivalent to initializing with an empty dictionary + /// literal. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public init() { + self._keys = OrderedSet() + self._values = [] + } + + /// Creates an empty dictionary with preallocated space for at least the + /// specified number of elements. + /// + /// Use this initializer to avoid intermediate reallocations of a dictionary's + /// storage buffer when you know in advance how many elements you'll insert + /// into it after creation. + /// + /// If you have a good idea of the expected working size of the dictionary, + /// calling this initializer with `persistent` set to true can sometimes + /// improve performance by eliminating churn due to repeated rehashings when + /// the dictionary temporarily shrinks below its regular size. You can cancel + /// any capacity you've previously reserved by persistently reserving a + /// capacity of zero. (This also shrinks the hash table to the ideal size for + /// its current number elements.) + /// + /// - Parameter minimumCapacity: The minimum number of elements that the newly + /// created dictionary should be able to store without reallocating its + /// storage. + /// + /// - Parameter persistent: If set to true, prevent removals from shrinking + /// storage below the specified capacity. By default, removals are allowed + /// to shrink storage below any previously reserved capacity. + /// + /// - Complexity: O(`minimumCapacity`) + @inlinable + @inline(__always) + public init(minimumCapacity: Int, persistent: Bool = false) { + self._keys = OrderedSet(minimumCapacity: minimumCapacity, persistent: persistent) + self._values = [] + _values.reserveCapacity(minimumCapacity) + } +} + +extension OrderedDictionary { + /// Creates a new dictionary from the key-value pairs in the given sequence. + /// + /// You use this initializer to create a dictionary when you have a sequence + /// of key-value tuples with unique keys. Passing a sequence with duplicate + /// keys to this initializer results in a runtime error. If your + /// sequence might have duplicate keys, use the + /// `Dictionary(_:uniquingKeysWith:)` initializer instead. + /// + /// - Parameter keysAndValues: A sequence of key-value pairs to use for + /// the new dictionary. Every key in `keysAndValues` must be unique. + /// + /// - Returns: A new dictionary initialized with the elements of + /// `keysAndValues`. + /// + /// - Precondition: The sequence must not have duplicate keys. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count if + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + public init( + uniqueKeysWithValues keysAndValues: S + ) where S.Element == (key: Key, value: Value) { + if S.self == Dictionary.self { + self.init(_uncheckedUniqueKeysWithValues: keysAndValues) + return + } + self.init() + reserveCapacity(keysAndValues.underestimatedCount) + for (key, value) in keysAndValues { + guard _keys._append(key).inserted else { + preconditionFailure("Duplicate key: '\(key)'") + } + _values.append(value) + } + } + + /// Creates a new dictionary from the key-value pairs in the given sequence. + /// + /// You use this initializer to create a dictionary when you have a sequence + /// of key-value tuples with unique keys. Passing a sequence with duplicate + /// keys to this initializer results in a runtime error. If your + /// sequence might have duplicate keys, use the + /// `Dictionary(_:uniquingKeysWith:)` initializer instead. + /// + /// - Parameter keysAndValues: A sequence of key-value pairs to use for + /// the new dictionary. Every key in `keysAndValues` must be unique. + /// + /// - Returns: A new dictionary initialized with the elements of + /// `keysAndValues`. + /// + /// - Precondition: The sequence must not have duplicate keys. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count if + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + public init( + uniqueKeysWithValues keysAndValues: S + ) where S.Element == (Key, Value) { + self.init() + reserveCapacity(keysAndValues.underestimatedCount) + for (key, value) in keysAndValues { + guard _keys._append(key).inserted else { + preconditionFailure("Duplicate key: '\(key)'") + } + _values.append(value) + } + } +} + +extension OrderedDictionary { + /// Creates a new dictionary from separate sequences of keys and values. + /// + /// You use this initializer to create a dictionary when you have two + /// sequences with unique keys and their associated values, respectively. + /// Passing a `keys` sequence with duplicate keys to this initializer results + /// in a runtime error. + /// + /// - Parameter keys: A sequence of unique keys. + /// + /// - Parameter values: A sequence of values associated with items in `keys`. + /// + /// - Returns: A new dictionary initialized with the data in + /// `keys` and `values`. + /// + /// - Precondition: The sequence must not have duplicate keys, and `keys` and + /// `values` must contain an equal number of elements. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count if + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + public init( + uniqueKeys keys: Keys, + values: Values + ) where Keys.Element == Key, Values.Element == Value { + let keys = ContiguousArray(keys) + let values = ContiguousArray(values) + precondition(keys.count == values.count, + "Mismatching element counts between keys and values") + self._keys = .init(keys) + self._values = values + precondition(_keys.count == _values.count, "Duplicate keys") + _checkInvariants() + } +} + +extension OrderedDictionary { + /// Creates a new dictionary from the key-value pairs in the given sequence, + /// using a combining closure to determine the value for any duplicate keys. + /// + /// You use this initializer to create a dictionary when you have a sequence + /// of key-value tuples that might have duplicate keys. As the dictionary is + /// built, the initializer calls the `combine` closure with the current and + /// new values for any duplicate keys. Pass a closure as `combine` that + /// returns the value to use in the resulting dictionary: The closure can + /// choose between the two values, combine them to produce a new value, or + /// even throw an error. + /// + /// let pairsWithDuplicateKeys = [("a", 1), ("b", 2), ("a", 3), ("b", 4)] + /// + /// let firstValues = OrderedDictionary( + /// pairsWithDuplicateKeys, + /// uniquingKeysWith: { (first, _) in first }) + /// // ["a": 1, "b": 2] + /// + /// let lastValues = OrderedDictionary( + /// pairsWithDuplicateKeys, + /// uniquingKeysWith: { (_, last) in last }) + /// // ["a": 3, "b": 4] + /// + /// - Parameters: + /// - keysAndValues: A sequence of key-value pairs to use for the new + /// dictionary. + /// - combine: A closure that is called with the values for any duplicate + /// keys that are encountered. The closure returns the desired value for + /// the final dictionary. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count of + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + @inline(__always) + public init( + _ keysAndValues: S, + uniquingKeysWith combine: (Value, Value) throws -> Value + ) rethrows where S.Element == (key: Key, value: Value) { + self.init() + try self.merge(keysAndValues, uniquingKeysWith: combine) + } + + /// Creates a new dictionary from the key-value pairs in the given sequence, + /// using a combining closure to determine the value for any duplicate keys. + /// + /// You use this initializer to create a dictionary when you have a sequence + /// of key-value tuples that might have duplicate keys. As the dictionary is + /// built, the initializer calls the `combine` closure with the current and + /// new values for any duplicate keys. Pass a closure as `combine` that + /// returns the value to use in the resulting dictionary: The closure can + /// choose between the two values, combine them to produce a new value, or + /// even throw an error. + /// + /// let pairsWithDuplicateKeys = [("a", 1), ("b", 2), ("a", 3), ("b", 4)] + /// + /// let firstValues = OrderedDictionary( + /// pairsWithDuplicateKeys, + /// uniquingKeysWith: { (first, _) in first }) + /// // ["a": 1, "b": 2] + /// + /// let lastValues = OrderedDictionary( + /// pairsWithDuplicateKeys, + /// uniquingKeysWith: { (_, last) in last }) + /// // ["a": 3, "b": 4] + /// + /// - Parameters: + /// - keysAndValues: A sequence of key-value pairs to use for the new + /// dictionary. + /// - combine: A closure that is called with the values for any duplicate + /// keys that are encountered. The closure returns the desired value for + /// the final dictionary. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count of + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + @inline(__always) + public init( + _ keysAndValues: S, + uniquingKeysWith combine: (Value, Value) throws -> Value + ) rethrows where S.Element == (Key, Value) { + self.init() + try self.merge(keysAndValues, uniquingKeysWith: combine) + } +} + +extension OrderedDictionary { + /// Creates a new dictionary whose keys are the groupings returned by the + /// given closure and whose values are arrays of the elements that returned + /// each key. + /// + /// The arrays in the "values" position of the new dictionary each contain at + /// least one element, with the elements in the same order as the source + /// sequence. + /// + /// The following example declares an array of names, and then creates a + /// dictionary from that array by grouping the names by first letter: + /// + /// let students = ["Kofi", "Abena", "Efua", "Kweku", "Akosua"] + /// let studentsByLetter = OrderedDictionary(grouping: students, by: { $0.first! }) + /// // ["K": ["Kofi", "Kweku"], "A": ["Abena", "Akosua"], "E": ["Efua"]] + /// + /// The new `studentsByLetter` dictionary has three entries, with students' + /// names grouped by the keys `"E"`, `"K"`, and `"A"`. + /// + /// - Parameters: + /// - values: A sequence of values to group into a dictionary. + /// - keyForValue: A closure that returns a key for each element in + /// `values`. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count of + /// values, if `Key` implements high-quality hashing. + @inlinable + public init( + grouping values: S, + by keyForValue: (S.Element) throws -> Key + ) rethrows where Value: RangeReplaceableCollection, Value.Element == S.Element { + self.init() + for value in values { + let key = try keyForValue(value) + self.modifyValue(forKey: key, default: Value()) { array in + array.append(value) + } + } + } +} + +extension OrderedDictionary { + @inlinable + internal init( + _uncheckedUniqueKeysWithValues keysAndValues: S + ) where S.Element == (key: Key, value: Value) { + self.init() + reserveCapacity(keysAndValues.underestimatedCount) + for (key, value) in keysAndValues { + _keys._appendNew(key) + _values.append(value) + } + } + + /// Creates a new dictionary from the key-value pairs in the given sequence, + /// which must not contain duplicate keys. + /// + /// In optimized builds, this initializer does not verify that the keys are + /// actually unique. This makes creating the dictionary somewhat faster if you + /// know for sure that the elements are unique (e.g., because they come from + /// another collection with guaranteed-unique members, such as a + /// `Dictionary`). However, if you accidentally call this initializer with + /// duplicate members, it can return a corrupt dictionary value that may be + /// difficult to debug. + /// + /// - Parameter keysAndValues: A sequence of key-value pairs to use for + /// the new dictionary. Every key in `keysAndValues` must be unique. + /// + /// - Returns: A new dictionary initialized with the elements of + /// `keysAndValues`. + /// + /// - Precondition: The sequence must not have duplicate keys. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count if + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + public init( + uncheckedUniqueKeysWithValues keysAndValues: S + ) where S.Element == (key: Key, value: Value) { +#if DEBUG + self.init(uniqueKeysWithValues: keysAndValues) +#else + self.init(_uncheckedUniqueKeysWithValues: keysAndValues) +#endif + } + + /// Creates a new dictionary from the key-value pairs in the given sequence, + /// which must not contain duplicate keys. + /// + /// In optimized builds, this initializer does not verify that the keys are + /// actually unique. This makes creating the dictionary somewhat faster if you + /// know for sure that the elements are unique (e.g., because they come from + /// another collection with guaranteed-unique members, such as a + /// `Dictionary`). However, if you accidentally call this initializer with + /// duplicate members, it can return a corrupt dictionary value that may be + /// difficult to debug. + /// + /// - Parameter keysAndValues: A sequence of key-value pairs to use for + /// the new dictionary. Every key in `keysAndValues` must be unique. + /// + /// - Returns: A new dictionary initialized with the elements of + /// `keysAndValues`. + /// + /// - Precondition: The sequence must not have duplicate keys. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count if + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + public init( + uncheckedUniqueKeysWithValues keysAndValues: S + ) where S.Element == (Key, Value) { + // Add tuple labels + let keysAndValues = keysAndValues.lazy.map { (key: $0.0, value: $0.1) } + self.init(uncheckedUniqueKeysWithValues: keysAndValues) + } +} + +extension OrderedDictionary { + /// Creates a new dictionary from separate sequences of unique keys and + /// associated values. + /// + /// In optimized builds, this initializer does not verify that the keys are + /// actually unique. This makes creating the dictionary somewhat faster if you + /// know for sure that the elements are unique (e.g., because they come from + /// another collection with guaranteed-unique members, such as a + /// `Dictionary`). However, if you accidentally call this initializer with + /// duplicate members, it can return a corrupt dictionary value that may be + /// difficult to debug. + /// + /// - Parameter keys: A sequence of unique keys. + /// + /// - Parameter values: A sequence of values associated with items in `keys`. + /// + /// - Returns: A new dictionary initialized with the data in + /// `keys` and `values`. + /// + /// - Precondition: The sequence must not have duplicate keys, and `keys` and + /// `values` must contain an equal number of elements. + /// + /// - Complexity: Expected O(*n*) on average, where *n* is the count if + /// key-value pairs, if `Key` implements high-quality hashing. + @inlinable + @inline(__always) + public init( + uncheckedUniqueKeys keys: Keys, + values: Values + ) where Keys.Element == Key, Values.Element == Value { +#if DEBUG + self.init(uniqueKeys: keys, values: values) +#else + self._keys = .init(uncheckedUniqueElements: keys) + self._values = .init(values) + precondition(_keys.count == _values.count) + _checkInvariants() +#endif + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Invariants.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Invariants.swift new file mode 100644 index 00000000..87cc5ff0 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Invariants.swift @@ -0,0 +1,23 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary { + #if COLLECTIONS_INTERNAL_CHECKS + @inline(never) @_effects(releasenone) + public func _checkInvariants() { + precondition(_keys.count == _values.count) + _keys.__unstable._checkInvariants() + } + #else + @inline(__always) @inlinable + public func _checkInvariants() {} + #endif // COLLECTIONS_INTERNAL_CHECKS +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift new file mode 100644 index 00000000..0deba75c --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift @@ -0,0 +1,191 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary { + /// Exchanges the key-value pairs at the specified indices of the dictionary. + /// + /// Both parameters must be valid indices below `endIndex`. Passing the same + /// index as both `i` and `j` has no effect. + /// + /// - Parameters: + /// - i: The index of the first value to swap. + /// - j: The index of the second value to swap. + /// + /// - Complexity: O(1) when the dictionary's storage isn't shared with another + /// value; O(`count`) otherwise. + @inlinable + public mutating func swapAt(_ i: Index, _ j: Index) { + _keys.swapAt(i, j) + _values.swapAt(i, j) + } + + /// Reorders the elements of the dictionary such that all the elements that + /// match the given predicate are after all the elements that don't match. + /// + /// After partitioning a collection, there is a pivot index `p` where + /// no element before `p` satisfies the `belongsInSecondPartition` + /// predicate and every element at or after `p` satisfies + /// `belongsInSecondPartition`. + /// + /// - Parameter belongsInSecondPartition: A predicate used to partition + /// the collection. All elements satisfying this predicate are ordered + /// after all elements not satisfying it. + /// - Returns: The index of the first element in the reordered collection + /// that matches `belongsInSecondPartition`. If no elements in the + /// collection match `belongsInSecondPartition`, the returned index is + /// equal to the collection's `endIndex`. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func partition( + by belongsInSecondPartition: (Element) throws -> Bool + ) rethrows -> Index { + let pivot = try _values.withUnsafeMutableBufferPointer { values in + try _keys._partition(values: values, by: belongsInSecondPartition) + } + return pivot + } +} + +extension OrderedDictionary { + /// Sorts the collection in place, using the given predicate as the + /// comparison between elements. + /// + /// When you want to sort a collection of elements that don't conform to + /// the `Comparable` protocol, pass a closure to this method that returns + /// `true` when the first element should be ordered before the second. + /// + /// Alternatively, use this method to sort a collection of elements that do + /// conform to `Comparable` when you want the sort to be descending instead + /// of ascending. Pass the greater-than operator (`>`) operator as the + /// predicate. + /// + /// `areInIncreasingOrder` must be a *strict weak ordering* over the + /// elements. That is, for any elements `a`, `b`, and `c`, the following + /// conditions must hold: + /// + /// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity) + /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are + /// both `true`, then `areInIncreasingOrder(a, c)` is also `true`. + /// (Transitive comparability) + /// - Two elements are *incomparable* if neither is ordered before the other + /// according to the predicate. If `a` and `b` are incomparable, and `b` + /// and `c` are incomparable, then `a` and `c` are also incomparable. + /// (Transitive incomparability) + /// + /// The sorting algorithm is not guaranteed to be stable. A stable sort + /// preserves the relative order of elements for which + /// `areInIncreasingOrder` does not establish an order. + /// + /// - Parameter areInIncreasingOrder: A predicate that returns `true` if its + /// first argument should be ordered before its second argument; + /// otherwise, `false`. If `areInIncreasingOrder` throws an error during + /// the sort, the elements may be in a different order, but none will be + /// lost. + /// + /// - Complexity: O(*n* log *n*), where *n* is the length of the collection. + @inlinable + public mutating func sort( + by areInIncreasingOrder: (Element, Element) throws -> Bool + ) rethrows { + // FIXME: Implement in-place sorting. + let temp = try self.sorted(by: areInIncreasingOrder) + precondition(temp.count == self.count) + temp.withUnsafeBufferPointer { source in + _keys = OrderedSet(uncheckedUniqueElements: source.lazy.map { $0.key }) + _values = ContiguousArray(source.lazy.map { $0.value }) + } + } +} + +extension OrderedDictionary where Key: Comparable { + /// Sorts the dictionary in place. + /// + /// You can sort an ordered dictionary of keys that conform to the + /// `Comparable` protocol by calling this method. The key-value pairs are + /// sorted in ascending order. (`Value` doesn't need to conform to + /// `Comparable` because the keys are guaranteed to be unique.) + /// + /// The sorting algorithm is not guaranteed to be stable. A stable sort + /// preserves the relative order of elements that compare equal. + /// + /// - Complexity: O(*n* log *n*), where *n* is the length of the collection. + @inlinable + public mutating func sort() { + sort { $0.key < $1.key } + } +} + +extension OrderedDictionary { + /// Shuffles the collection in place. + /// + /// Use the `shuffle()` method to randomly reorder the elements of an ordered + /// dictionary. + /// + /// This method is equivalent to calling `shuffle(using:)`, passing in the + /// system's default random generator. + /// + /// - Complexity: O(*n*), where *n* is the length of the collection. + @inlinable + public mutating func shuffle() { + var generator = SystemRandomNumberGenerator() + shuffle(using: &generator) + } + + /// Shuffles the collection in place, using the given generator as a source + /// for randomness. + /// + /// You use this method to randomize the elements of a collection when you + /// are using a custom random number generator. For example, you can use the + /// `shuffle(using:)` method to randomly reorder the elements of an array. + /// + /// - Parameter generator: The random number generator to use when shuffling + /// the collection. + /// + /// - Complexity: O(*n*), where *n* is the length of the collection. + /// + /// - Note: The algorithm used to shuffle a collection may change in a future + /// version of Swift. If you're passing a generator that results in the + /// same shuffled order each time you run your program, that sequence may + /// change when your program is compiled using a different version of + /// Swift. + @inlinable + public mutating func shuffle( + using generator: inout T + ) { + guard count > 1 else { return } + var keys = self._keys.elements + var values = self._values + self = [:] + var amount = keys.count + var current = 0 + while amount > 1 { + let random = Int.random(in: 0 ..< amount, using: &generator) + amount -= 1 + keys.swapAt(current, current + random) + values.swapAt(current, current + random) + current += 1 + } + self = OrderedDictionary(uncheckedUniqueKeys: keys, values: values) + } +} + +extension OrderedDictionary { + /// Reverses the elements of the ordered dictionary in place. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func reverse() { + _keys.reverse() + _values.reverse() + } +} + diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial RangeReplaceableCollection.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial RangeReplaceableCollection.swift new file mode 100644 index 00000000..af52aa35 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial RangeReplaceableCollection.swift @@ -0,0 +1,183 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// The parts of RangeReplaceableCollection that OrderedDictionary is able to implement. + +extension OrderedDictionary { + /// Reserves enough space to store the specified number of elements. + /// + /// This method ensures that the dictionary has unique, mutable, contiguous + /// storage, with space allocated for at least the requested number of + /// elements. + /// + /// If you are adding a known number of elements to a dictionary, call this + /// method once before the first insertion to avoid multiple reallocations. + /// + /// Do not call this method in a loop -- it does not use an exponential + /// allocation strategy, so doing that can result in quadratic instead of + /// linear performance. + /// + /// - Parameter minimumCapacity: The minimum number of elements that the + /// dictionary should be able to store without reallocating its storage. + /// + /// - Complexity: O(`max(count, minimumCapacity)`) + @inlinable + public mutating func reserveCapacity(_ minimumCapacity: Int) { + self._keys.reserveCapacity(minimumCapacity) + self._values.reserveCapacity(minimumCapacity) + } + + /// Removes all members from the dictionary. + /// + /// - Parameter keepingCapacity: If `true`, the dictionary's storage capacity + /// is preserved; if `false`, the underlying storage is released. The + /// default is `false`. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll(keepingCapacity keepCapacity: Bool = false) { + _keys.removeAll(keepingCapacity: keepCapacity) + _values.removeAll(keepingCapacity: keepCapacity) + } + + /// Removes and returns the element at the specified position. + /// + /// All the elements following the specified position are moved to close the + /// resulting gap. + /// + /// - Parameter index: The position of the element to remove. `index` must be + /// a valid index of the collection that is not equal to the collection's + /// end index. + /// + /// - Returns: The removed element. + /// + /// - Complexity: O(`count`) + @inlinable + @discardableResult + public mutating func remove(at index: Int) -> Element { + let key = _keys.remove(at: index) + let value = _values.remove(at: index) + return (key, value) + } + + /// Removes the specified subrange of elements from the collection. + /// + /// All the elements following the specified subrange are moved to close the + /// resulting gap. + /// + /// - Parameter bounds: The subrange of the collection to remove. The bounds + /// of the range must be valid indices of the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeSubrange(_ bounds: Range) { + _keys.removeSubrange(bounds) + _values.removeSubrange(bounds) + } + + /// Removes the specified subrange of elements from the collection. + /// + /// All the elements following the specified subrange are moved to close the + /// resulting gap. + /// + /// - Parameter bounds: The subrange of the collection to remove. The bounds + /// of the range must be valid indices of the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeSubrange( + _ bounds: R + ) where R.Bound == Int { + removeSubrange(bounds.relative(to: elements)) + } + + + /// Removes the last element of a non-empty dictionary. + /// + /// - Complexity: Expected to be O(`1`) on average, if `Element` implements + /// high-quality hashing. + @inlinable + @discardableResult + public mutating func removeLast() -> Element { + precondition(!isEmpty, "Cannot remove last element of an empty collection") + return remove(at: count - 1) + } + + /// Removes the last `n` element of the dictionary. + /// + /// - Parameter n: The number of elements to remove from the collection. + /// `n` must be greater than or equal to zero and must not exceed the + /// number of elements in the collection. + /// + /// - Complexity: Expected to be O(`n`) on average, if `Element` implements + /// high-quality hashing. + @inlinable + public mutating func removeLast(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the collection") + _keys.removeLast(n) + _values.removeLast(n) + } + + /// Removes the first element of a non-empty dictionary. + /// + /// The members following the removed key-value pair need to be moved to close + /// the resulting gaps in the storage arrays. + /// + /// - Complexity: O(`count`). + @inlinable + @discardableResult + public mutating func removeFirst() -> Element { + precondition(!isEmpty, "Cannot remove first element of an empty collection") + return remove(at: 0) + } + + /// Removes the first `n` elements of the dictionary. + /// + /// The members following the removed items need to be moved to close the + /// resulting gaps in the storage arrays. + /// + /// - Parameter n: The number of elements to remove from the collection. + /// `n` must be greater than or equal to zero and must not exceed the + /// number of elements in the set. + /// + /// - Complexity: O(`count`). + @inlinable + public mutating func removeFirst(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the collection") + _keys.removeFirst(n) + _values.removeFirst(n) + } + + /// Removes all the elements that satisfy the given predicate. + /// + /// Use this method to remove every element in a collection that meets + /// particular criteria. The order of the remaining elements is preserved. + /// + /// - Parameter shouldBeRemoved: A closure that takes an element of the + /// dictionary as its argument and returns a Boolean value indicating + /// whether the element should be removed from the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll( + where shouldBeRemoved: (Self.Element) throws -> Bool + ) rethrows { + let pivot = try _values.withUnsafeMutableBufferPointer { values in + try _keys._halfStablePartition( + values: values, + by: shouldBeRemoved) + } + removeSubrange(pivot...) + } +} + diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Sequence.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Sequence.swift new file mode 100644 index 00000000..2e5c5593 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Sequence.swift @@ -0,0 +1,63 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary: Sequence { + /// The element type of a dictionary: a tuple containing an individual + /// key-value pair. + public typealias Element = (key: Key, value: Value) + + /// The type that allows iteration over an ordered dictionary's elements. + @frozen + public struct Iterator: IteratorProtocol { + @usableFromInline + internal let _base: OrderedDictionary + + @usableFromInline + internal var _position: Int + + @inlinable + @inline(__always) + internal init(_base: OrderedDictionary) { + self._base = _base + self._position = 0 + } + + /// Advances to the next element and returns it, or nil if no next + /// element exists. + /// + /// - Complexity: O(1) + @inlinable + public mutating func next() -> Element? { + guard _position < _base._values.count else { return nil } + let result = (_base._keys[_position], _base._values[_position]) + _position += 1 + return result + } + } + + /// The number of elements in the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var underestimatedCount: Int { + count + } + + /// Returns an iterator over the elements of this collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func makeIterator() -> Iterator { + Iterator(_base: self) + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Values.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Values.swift new file mode 100644 index 00000000..88a046e2 --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Values.swift @@ -0,0 +1,380 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedDictionary { + /// A view of an ordered dictionary's values as a standalone collection. + @frozen + public struct Values { + @usableFromInline + internal var _base: OrderedDictionary + + @inlinable + @inline(__always) + internal init(_base: OrderedDictionary) { + self._base = _base + } + } +} + +extension OrderedDictionary.Values { + /// A read-only view of the contents of this collection as an array value. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var elements: Array { + Array(_base._values) + } +} + +extension OrderedDictionary.Values { + /// Calls a closure with a pointer to the collection's contiguous storage. + /// + /// Often, the optimizer can eliminate bounds checks within a collection + /// algorithm, but when that fails, invoking the same algorithm on the + /// buffer pointer passed into your closure lets you trade safety for speed. + /// + /// The pointer passed as an argument to `body` is valid only during the + /// execution of `withUnsafeBufferPointer(_:)`. Do not store or return the + /// pointer for later use. + /// + /// - Parameter body: A closure with an `UnsafeBufferPointer` parameter that + /// points to the contiguous storage for the collection. If `body` has a + /// return value, that value is also used as the return value for the + /// `withUnsafeBufferPointer(_:)` method. The pointer argument is valid only + /// for the duration of the method's execution. + /// + /// - Returns: The return value, if any, of the `body` closure parameter. + /// + /// - Complexity: O(1) (not counting the closure call) + @inlinable + @inline(__always) + public func withUnsafeBufferPointer( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R { + try _base._values.withUnsafeBufferPointer(body) + } + + /// Calls the given closure with a pointer to the collection's mutable + /// contiguous storage. + /// + /// Often, the optimizer can eliminate bounds checks within a collection + /// algorithm, but when that fails, invoking the same algorithm on the buffer + /// pointer passed into your closure lets you trade safety for speed. + /// + /// The pointer passed as an argument to `body` is valid only during the + /// execution of `withUnsafeMutableBufferPointer(_:)`. Do not store or return + /// the pointer for later use. + /// + /// - Parameter body: A closure with an `UnsafeMutableBufferPointer` parameter + /// that points to the contiguous storage for the collection. If `body` has + /// a return value, that value is also used as the return value for the + /// `withUnsafeMutableBufferPointer(_:)` method. The pointer argument is + /// valid only for the duration of the method's execution. + /// + /// - Returns: The return value, if any, of the `body` closure parameter. + /// + /// - Complexity: O(1) (not counting the closure call) + @inlinable + @inline(__always) + public mutating func withUnsafeMutableBufferPointer( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R { + try _base._values.withUnsafeMutableBufferPointer(body) + } +} + +extension OrderedDictionary.Values: Sequence { + /// The element type of the collection. + public typealias Element = Value + + /// The type that allows iteration over the collection's elements. + public typealias Iterator = IndexingIterator +} + +extension OrderedDictionary.Values: RandomAccessCollection { + /// The index type for a dictionary's values view, `Int`. + /// + /// Indices in `Values` are integer offsets from the start of the collection. + public typealias Index = Int + + /// The type that represents the indices that are valid for subscripting the + /// `Values` collection, in ascending order. + public typealias Indices = Range + + /// The position of the first element in a nonempty dictionary. + /// + /// For an instance of `OrderedDictionary.Values`, `startIndex` is always + /// zero. If the dictionary is empty, `startIndex` is equal to `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var startIndex: Int { 0 } + + /// The collection's "past the end" position---that is, the position one + /// greater than the last valid subscript argument. + /// + /// In `OrderedDictionary.Values`, `endIndex` always equals the count of + /// elements. If the dictionary is empty, `endIndex` is equal to `startIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var endIndex: Int { _base._values.count } + + /// Returns the position immediately after the given index. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately after `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(after i: Index) -> Index { i + 1 } + + /// Returns the position immediately before the given index. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately before `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(before i: Index) -> Index { i - 1 } + + /// Replaces the given index with its successor. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(after i: inout Index) { i += 1 } + + /// Replaces the given index with its predecessor. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the collection. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(before i: inout Index) { i -= 1 } + + /// Returns an index that is the specified distance from the given index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, or the returned value will not be a valid index. + /// + /// - Parameters: + /// - i: A valid index of the collection. + /// - distance: The distance to offset `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`. If `distance` + /// is positive, this is the same value as the result of `distance` calls to + /// `index(after:)`. If `distance` is negative, this is the same value as + /// the result of `abs(distance)` calls to `index(before:)`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(_ i: Index, offsetBy distance: Int) -> Index { + i + distance + } + + /// Returns an index that is the specified distance from the given index, + /// unless that distance is beyond a given limiting index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, unless the index passed as `limit` prevents offsetting + /// beyond those bounds. (Otherwise the returned value won't be a valid index + /// in the collection.) + /// + /// - Parameters: + /// - i: A valid index of the collection. + /// - distance: The distance to offset `i`. + /// - limit: A valid index of the collection to use as a limit. If + /// `distance > 0`, `limit` has no effect if it is less than `i`. + /// Likewise, if `distance < 0`, `limit` has no effect if it is greater + /// than `i`. + /// - Returns: An index offset by `distance` from the index `i`, unless that + /// index would be beyond `limit` in the direction of movement. In that + /// case, the method returns `nil`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index( + _ i: Index, + offsetBy distance: Int, + limitedBy limit: Index + ) -> Index? { + _base._values.index(i, offsetBy: distance, limitedBy: limit) + } + + /// Returns the distance between two indices. + /// + /// - Parameters: + /// - start: A valid index of the collection. + /// - end: Another valid index of the collection. If `end` is equal to + /// `start`, the result is zero. + /// + /// - Returns: The distance between `start` and `end`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func distance(from start: Index, to end: Index) -> Int { + end - start + } + + /// Call `body(p)`, where `p` is a buffer pointer to the collection’s + /// contiguous storage. `OrderedDictionary.Values` values always have + /// contiguous storage. + /// + /// - Parameter body: A function to call. The function must not escape its + /// unsafe buffer pointer argument. + /// + /// - Returns: The value returned by `body`. + /// + /// - Complexity: O(1) (ignoring time spent in `body`) + @inlinable + @inline(__always) + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + try _base._values.withUnsafeBufferPointer(body) + } +} + +extension OrderedDictionary.Values: MutableCollection { + /// Accesses the element at the specified position. This can be used to + /// perform in-place mutations on dictionary values. + /// + /// - Parameter index: The position of the element to access. `index` must be + /// greater than or equal to `startIndex` and less than `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public subscript(position: Index) -> Value { + get { + _base._values[position] + } + _modify { + yield &_base._values[position] + } + } + + /// Exchanges the values at the specified indices of the collection. (Leaving + /// their associated keys in the underlying dictionary at their original + /// position.) + /// + /// Both parameters must be valid indices below `endIndex`. Passing the same + /// index as both `i` and `j` has no effect. + /// + /// - Parameters: + /// - i: The index of the first value to swap. + /// - j: The index of the second value to swap. + /// + /// - Complexity: O(1) when the dictionary's storage isn't shared with another + /// value; O(`count`) otherwise. + @inlinable + @inline(__always) + public mutating func swapAt(_ i: Int, _ j: Int) { + _base._values.swapAt(i, j) + } + + /// Reorders the elements of the collection such that all the elements that + /// match the given predicate are after all the elements that don't match. + /// + /// This operation does not reorder the keys of the underlying dictionary, + /// just their associated values. + /// + /// After partitioning a collection, there is a pivot index `p` where + /// no element before `p` satisfies the `belongsInSecondPartition` + /// predicate and every element at or after `p` satisfies + /// `belongsInSecondPartition`. + /// + /// - Parameter belongsInSecondPartition: A predicate used to partition + /// the collection. All elements satisfying this predicate are ordered + /// after all elements not satisfying it. + /// - Returns: The index of the first element in the reordered collection + /// that matches `belongsInSecondPartition`. If no elements in the + /// collection match `belongsInSecondPartition`, the returned index is + /// equal to the collection's `endIndex`. + /// + /// - Complexity: O(`count`) + @inlinable + @inline(__always) + public mutating func partition( + by belongsInSecondPartition: (Value) throws -> Bool + ) rethrows -> Int { + try _base._values.partition(by: belongsInSecondPartition) + } + + /// Call `body(b)`, where `b` is an unsafe buffer pointer to the collection's + /// mutable contiguous storage. `OrderedDictionary.Values` always stores its + /// elements in contiguous storage. + /// + /// The supplied buffer pointer is only valid for the duration of the call. + /// + /// Often, the optimizer can eliminate bounds- and uniqueness-checks within an + /// algorithm, but when that fails, invoking the same algorithm on the unsafe + /// buffer supplied to `body` lets you trade safety for speed. + /// + /// - Parameters: + /// - body: The function to invoke. + /// + /// - Returns: The value returned by `body`, or `nil` if `body` wasn't called. + /// + /// - Complexity: O(1) when this instance has a unique reference to its + /// underlying storage; O(`count`) otherwise. (Not counting the call to + /// `body`.) + @inlinable + @inline(__always) + public mutating func withContiguousMutableStorageIfAvailable( + _ body: (inout UnsafeMutableBufferPointer) throws -> R + ) rethrows -> R? { + try _base._values.withUnsafeMutableBufferPointer(body) + } +} + +extension OrderedDictionary.Values: Equatable where Value: Equatable { + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + left.elementsEqual(right) + } +} + +extension OrderedDictionary.Values: Hashable where Value: Hashable { + @inlinable + public func hash(into hasher: inout Hasher) { + hasher.combine(count) // Discriminator + for item in self { + hasher.combine(item) + } + } +} diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift new file mode 100644 index 00000000..416f182c --- /dev/null +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift @@ -0,0 +1,1022 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// An ordered collection of key-value pairs. +/// +/// Like the standard `Dictionary`, ordered dictionaries use a hash table to +/// ensure that no two entries have the same keys, and to efficiently look up +/// values corresponding to specific keys. However, like an `Array` (and +/// unlike `Dictionary`), ordered dictionaries maintain their elements in a +/// particular user-specified order, and they support efficient random-access +/// traversal of their entries. +/// +/// `OrderedDictionary` is a useful alternative to `Dictionary` when the order +/// of elements is important, or when you need to be able to efficiently access +/// elements at various positions within the collection. +/// +/// You can create an ordered dictionary with any key type that conforms to the +/// `Hashable` protocol. +/// +/// let responses: OrderedDictionary = [ +/// 200: "OK", +/// 403: "Access forbidden", +/// 404: "File not found", +/// 500: "Internal server error", +/// ] +/// +/// ### Equality of Ordered Dictionaries +/// +/// Two ordered dictionaries are considered equal if they contain the same +/// elements, and *in the same order*. This matches the concept of equality of +/// an `Array`, and it is different from the unordered `Dictionary`. +/// +/// let a: OrderedDictionary = [1: "one", 2: "two"] +/// let b: OrderedDictionary = [2: "two", 1: "one"] +/// a == b // false +/// b.swapAt(0, 1) // `b` now has value [1: "one", 2: "two"] +/// a == b // true +/// +/// (`OrderedDictionary` only conforms to `Equatable` when its `Value` is +/// equatable.) +/// +/// ### Dictionary Operations +/// +/// `OrderedDictionary` provides many of the same operations as `Dictionary`. +/// +/// For example, you can look up and add/remove values using the familiar +/// key-based subscript, returning an optional value: +/// +/// var dictionary: OrderedDictionary = [:] +/// dictionary["one"] = 1 +/// dictionary["two"] = 2 +/// dictionary["three"] // nil +/// // dictionary is now ["one": 1, "two": 2] +/// +/// If a new entry is added using the subscript setter, it gets appended to the +/// end of the dictionary. (So that by default, the dictionary contains its +/// elements in the order they were originally inserted.) +/// +/// `OrderedDictionary` also implements the variant of this subscript that takes +/// a default value. Like with `Dictionary`, this is useful when you want to +/// perform in-place mutations on values: +/// +/// let text = "short string" +/// var counts: OrderedDictionary = [:] +/// for character in text { +/// counts[character, default: 0] += 1 +/// } +/// // counts is ["s": 2, "h": 1, "o": 1, +/// // "r": 2, "t": 2, " ": 1, +/// // "i": 1, "n": 1, "g": 1] +/// +/// If the `Value` type implements reference semantics, or when you need to +/// perform a series of individual mutations on the values, the closure-based +/// `modifyValue(forKey:default:_:)` method provides an easier-to-use +/// alternative to the defaulted key-based subscript. +/// +/// let text = "short string" +/// var counts: OrderedDictionary = [:] +/// for character in text { +/// counts.modifyValue(forKey: character, default: 0) { value in +/// value += 1 +/// } +/// } +/// // Same result as before +/// +/// (This isn't currently available on the regular `Dictionary`.) +/// +/// The `Dictionary` type's original `updateValue(_:forKey:)` method is also +/// available, and so is `index(forKey:)`, grouping/uniquing initializers +/// (`init(uniqueKeysWithValues:)`, `init(_:uniquingKeysWith:)`, +/// `init(grouping:by:)`), methods for merging one dictionary with another +/// (`merge`, `merging`), filtering dictionary entries (`filter(_:)`), +/// transforming values (`mapValues(_:)`), and a combination of these two +/// (`compactMapValues(_:)`). +/// +/// ### Sequence and Collection Operations +/// +/// Ordered dictionaries use integer indices representing offsets from the +/// beginning of the collection. However, to avoid ambiguity between key-based +/// and indexing subscripts, `OrderedDictionary` doesn't directly conform to +/// `Collection`. Instead, it only conforms to `Sequence`, and provides a +/// random-access collection view over its key-value pairs: +/// +/// responses[0] // `nil` (key-based subscript) +/// responses.elements[0] // `(200, "OK")` (index-based subscript) +/// +/// Because ordered dictionaries need to maintain unique keys, neither +/// `OrderedDictionary` nor its `elements` view can conform to the full +/// `MutableCollection` or `RangeReplaceableCollection` protocols. However, they +/// are able to partially implement requirements: they support mutations +/// that merely change the order of elements, or just remove a subset of +/// existing members: +/// +/// // Permutation operations from MutableCollection: +/// func swapAt(_ i: Index, _ j: Index) +/// func partition(by predicate: (Element) throws -> Bool) -> rethrows Index +/// func sort() where Element: Comparable +/// func sort(by predicate: (Element, Element) throws -> Bool) rethrows +/// func shuffle() +/// func shuffle(using generator: inout T) +/// +/// // Removal operations from RangeReplaceableCollection: +/// func removeAll(keepingCapacity: Bool = false) +/// func remove(at index: Index) -> Element +/// func removeSubrange(_ bounds: Range) +/// func removeLast() -> Element +/// func removeLast(_ n: Int) +/// func removeFirst() -> Element +/// func removeFirst(_ n: Int) +/// func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows +/// +/// `OrderedDictionary` also implements `reserveCapacity(_)` from +/// `RangeReplaceableCollection`, to allow for efficient insertion of a known +/// number of elements. (However, unlike `Array` and `Dictionary`, +/// `OrderedDictionary` does not provide a `capacity` property.) +/// +/// ### Keys and Values Views +/// +/// Like the standard `Dictionary`, `OrderedDictionary` provides `keys` and +/// `values` properties that provide lightweight views into the corresponding +/// parts of the dictionary. +/// +/// The `keys` collection is of type `OrderedSet`, containing all the keys +/// in the original dictionary. +/// +/// let d: OrderedDictionary = [2: "two", 1: "one", 0: "zero"] +/// d.keys // [2, 1, 0] as OrderedSet +/// +/// The `keys` property is read-only, so you cannot mutate the dictionary +/// through it. However, it returns an ordinary ordered set value, which can be +/// copied out and then mutated if desired. (Such mutations won't affect the +/// original dictionary value.) +/// +/// The `values` collection is a mutable random-access collection of the values +/// in the dictionary: +/// +/// d.values // "two", "one", "zero" +/// d.values[2] = "nada" +/// // `d` is now [2: "two", 1: "one", 0: "nada"] +/// d.values.sort() +/// // `d` is now [2: "nada", 1: "one", 0: "two"] +/// +/// Both views store their contents in regular `Array` values, accessible +/// through their `elements` property. +/// +/// ## Performance +/// +/// Like the standard `Dictionary` type, the performance of hashing operations +/// in `OrderedDictionary` is highly sensitive to the quality of hashing +/// implemented by the `Key` type. Failing to correctly implement hashing can +/// easily lead to unacceptable performance, with the severity of the effect +/// increasing with the size of the hash table. +/// +/// In particular, if a certain set of keys all produce the same hash value, +/// then hash table lookups regress to searching an element in an unsorted +/// array, i.e., a linear operation. To ensure hashed collection types exhibit +/// their target performance, it is important to ensure that such collisions +/// cannot be induced merely by adding a particular list of keys to the +/// dictionary. +/// +/// The easiest way to achieve this is to make sure `Key` implements hashing +/// following `Hashable`'s documented best practices. The conformance must +/// implement the `hash(into:)` requirement, and every bit of information that +/// is compared in `==` needs to be combined into the supplied `Hasher` value. +/// When used correctly, `Hasher` produces high-quality, randomly seeded hash +/// values that prevent repeatable hash collisions. +/// +/// When `Key` correctly conforms to `Hashable`, key-based lookups in an ordered +/// dictionary is expected to take O(1) equality checks on average. Hash +/// collisions can still occur organically, so the worst-case lookup performance +/// is technically still O(*n*) (where *n* is the size of the dictionary); +/// however, long lookup chains are unlikely to occur in practice. +/// +/// ## Implementation Details +/// +/// An ordered dictionary consists of an ordered set of keys, alongside a +/// regular `Array` value that contains their associated values. +@frozen +public struct OrderedDictionary { + @usableFromInline + internal var _keys: OrderedSet + + @usableFromInline + internal var _values: ContiguousArray + + @inlinable + @inline(__always) + internal init( + _uniqueKeys keys: OrderedSet, + values: ContiguousArray + ) { + self._keys = keys + self._values = values + } +} + +extension OrderedDictionary { + /// A read-only collection view for the keys contained in this dictionary, as + /// an `OrderedSet`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var keys: OrderedSet { _keys } + + /// A mutable collection view containing the values in this dictionary. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var values: Values { + get { Values(_base: self) } + _modify { + var values = Values(_base: self) + self = [:] + defer { self = values._base } + yield &values + } + } +} + +extension OrderedDictionary { + public typealias Index = Int + + /// A Boolean value indicating whether the dictionary is empty. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var isEmpty: Bool { _values.isEmpty } + + /// The number of elements in the dictionary. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var count: Int { _values.count } + + /// Returns the index for the given key. + /// + /// If the given key is found in the dictionary, this method returns an index + /// into the dictionary that corresponds with the key-value pair. + /// + /// let countryCodes: OrderedDictionary = ["BR": "Brazil", "GH": "Ghana", "JP": "Japan"] + /// let index = countryCodes.index(forKey: "JP") + /// + /// print("Country code for \(countryCodes[index!].value): '\(countryCodes[index!].key)'.") + /// // Prints "Country code for Japan: 'JP'." + /// + /// - Parameter key: The key to find in the dictionary. + /// + /// - Returns: The index for `key` and its associated value if `key` is in + /// the dictionary; otherwise, `nil`. + /// + /// - Complexity: Expected to be O(1) on average, if `Key` implements + /// high-quality hashing. + @inlinable + @inline(__always) + public func index(forKey key: Key) -> Index? { + _keys.firstIndex(of: key) + } + + /// Accesses the element at the specified index. This can be used to + /// perform in-place mutations on dictionary values. + /// + /// - Parameter offset: The offset of the element to access, measured from + /// the start of the collection. `offset` must be greater than or equal to + /// `0` and less than `count`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public subscript(offset offset: Index) -> Element { + (_keys[offset], _values[offset]) + } +} + +extension OrderedDictionary { + /// Accesses the value associated with the given key for reading and writing. + /// + /// This *key-based* subscript returns the value for the given key if the key + /// is found in the dictionary, or `nil` if the key is not found. + /// + /// The following example creates a new dictionary and prints the value of a + /// key found in the dictionary (`"Coral"`) and a key not found in the + /// dictionary (`"Cerise"`). + /// + /// var hues: OrderedDictionary = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156] + /// print(hues["Coral"]) + /// // Prints "Optional(16)" + /// print(hues["Cerise"]) + /// // Prints "nil" + /// + /// When you assign a value for a key and that key already exists, the + /// dictionary overwrites the existing value. If the dictionary doesn't + /// contain the key, the key and value are added as a new key-value pair. + /// + /// Here, the value for the key `"Coral"` is updated from `16` to `18` and a + /// new key-value pair is added for the key `"Cerise"`. + /// + /// hues["Coral"] = 18 + /// print(hues["Coral"]) + /// // Prints "Optional(18)" + /// + /// hues["Cerise"] = 330 + /// print(hues["Cerise"]) + /// // Prints "Optional(330)" + /// + /// If you assign `nil` as the value for the given key, the dictionary + /// removes that key and its associated value. + /// + /// In the following example, the key-value pair for the key `"Aquamarine"` + /// is removed from the dictionary by assigning `nil` to the key-based + /// subscript. + /// + /// hues["Aquamarine"] = nil + /// print(hues) + /// // Prints "["Coral": 18, "Heliotrope": 296, "Cerise": 330]" + /// + /// - Parameter key: The key to find in the dictionary. + /// + /// - Returns: The value associated with `key` if `key` is in the dictionary; + /// otherwise, `nil`. + /// + /// - Complexity: Looking up values in the dictionary through this subscript + /// has an expected complexity of O(1) hashing/comparison operations on + /// average, if `Key` implements high-quality hashing. Updating the + /// dictionary also has an amortized expected complexity of O(1) -- + /// although individual updates may need to copy or resize the dictionary's + /// underlying storage. + @inlinable + public subscript(key: Key) -> Value? { + get { + guard let index = _keys.firstIndex(of: key) else { return nil } + return _values[index] + } + set { + // We have a separate `set` in addition to `_modify` in hopes of getting + // rid of `_modify`'s swapAt dance in the usua case where the calle just + // wants to assign a new value. + let (index, bucket) = _keys._find(key) + switch (index, newValue) { + case let (index?, newValue?): // Assign + _values[index] = newValue + case let (index?, nil): // Remove + _keys._removeExistingMember(at: index, in: bucket) + _values.remove(at: index) + case let (nil, newValue?): // Insert + _keys._appendNew(key, in: bucket) + _values.append(newValue) + case (nil, nil): // Noop + break + } + } + _modify { + let (index, bucket) = _keys._find(key) + + // To support in-place mutations better, we swap the value to the end of + // the array, pop it off, then put things back in place when we're done. + var value: Value? = nil + if let index = index { + _values.swapAt(index, _values.count - 1) + value = _values.removeLast() + } + + defer { + switch (index, value) { + case let (index?, value?): // Assign + _values.append(value) + _values.swapAt(index, _values.count - 1) + case let (index?, nil): // Remove + if index < _values.count { + let standin = _values.remove(at: index) + _values.append(standin) + } + _keys._removeExistingMember(at: index, in: bucket) + case let (nil, value?): // Insert + _keys._appendNew(key, in: bucket) + _values.append(value) + case (nil, nil): // Noop + break + } + } + + yield &value + } + } + + /// Accesses the value with the given key. If the dictionary doesn't contain + /// the given key, accesses the provided default value as if the key and + /// default value existed in the dictionary. + /// + /// Use this subscript when you want either the value for a particular key + /// or, when that key is not present in the dictionary, a default value. This + /// example uses the subscript with a message to use in case an HTTP response + /// code isn't recognized: + /// + /// var responseMessages: OrderedDictionary = [ + /// 200: "OK", + /// 403: "Access forbidden", + /// 404: "File not found", + /// 500: "Internal server error"] + /// + /// let httpResponseCodes = [200, 403, 301] + /// for code in httpResponseCodes { + /// let message = responseMessages[code, default: "Unknown response"] + /// print("Response \(code): \(message)") + /// } + /// // Prints "Response 200: OK" + /// // Prints "Response 403: Access forbidden" + /// // Prints "Response 301: Unknown response" + /// + /// When a dictionary's `Value` type has value semantics, you can use this + /// subscript to perform in-place operations on values in the dictionary. + /// The following example uses this subscript while counting the occurrences + /// of each letter in a string: + /// + /// let message = "Hello, Elle!" + /// var letterCounts: [Character: Int] = [:] + /// for letter in message { + /// letterCounts[letter, default: 0] += 1 + /// } + /// // letterCounts == ["H": 1, "e": 2, "l": 4, "o": 1, ...] + /// + /// When `letterCounts[letter, defaultValue: 0] += 1` is executed with a + /// value of `letter` that isn't already a key in `letterCounts`, the + /// specified default value (`0`) is returned from the subscript, + /// incremented, and then added to the dictionary under that key. + /// + /// - Note: Do not use this subscript to modify dictionary values if the + /// dictionary's `Value` type is a class. In that case, the default value + /// and key are not written back to the dictionary after an operation. (For + /// a variant of this operation that supports this usecase, see + /// `updateValue(forKey:default:_:)`.) + /// + /// - Parameters: + /// - key: The key the look up in the dictionary. + /// - defaultValue: The default value to use if `key` doesn't exist in the + /// dictionary. + /// + /// - Returns: The value associated with `key` in the dictionary; otherwise, + /// `defaultValue`. + /// + /// - Complexity: Looking up values in the dictionary through this subscript + /// has an expected complexity of O(1) hashing/comparison operations on + /// average, if `Key` implements high-quality hashing. Updating the + /// dictionary also has an amortized expected complexity of O(1) -- + /// although individual updates may need to copy or resize the dictionary's + /// underlying storage. + @inlinable + public subscript( + key: Key, + default defaultValue: @autoclosure () -> Value + ) -> Value { + get { + guard let offset = _keys.firstIndex(of: key) else { return defaultValue() } + return _values[offset] + } + _modify { + let (inserted, index) = _keys.append(key) + if inserted { + assert(index == _values.count) + _values.append(defaultValue()) + } + var value: Value = _values.withUnsafeMutableBufferPointer { buffer in + assert(index < buffer.count) + return (buffer.baseAddress! + index).move() + } + defer { + _values.withUnsafeMutableBufferPointer { buffer in + assert(index < buffer.count) + (buffer.baseAddress! + index).initialize(to: value) + } + } + yield &value + } + } + +} + +extension OrderedDictionary { + /// Updates the value stored in the dictionary for the given key, or appends a + /// new key-value pair if the key does not exist. + /// + /// Use this method instead of key-based subscripting when you need to know + /// whether the new value supplants the value of an existing key. If the + /// value of an existing key is updated, `updateValue(_:forKey:)` returns + /// the original value. + /// + /// var hues: OrderedDictionary = [ + /// "Heliotrope": 296, + /// "Coral": 16, + /// "Aquamarine": 156] + /// + /// if let oldValue = hues.updateValue(18, forKey: "Coral") { + /// print("The old value of \(oldValue) was replaced with a new one.") + /// } + /// // Prints "The old value of 16 was replaced with a new one." + /// + /// If the given key is not present in the dictionary, this method appends the + /// key-value pair and returns `nil`. + /// + /// if let oldValue = hues.updateValue(330, forKey: "Cerise") { + /// print("The old value of \(oldValue) was replaced with a new one.") + /// } else { + /// print("No value was found in the dictionary for that key.") + /// } + /// // Prints "No value was found in the dictionary for that key." + /// + /// - Parameters: + /// - value: The new value to add to the dictionary. + /// - key: The key to associate with `value`. If `key` already exists in + /// the dictionary, `value` replaces the existing associated value. If + /// `key` isn't already a key of the dictionary, the `(key, value)` pair + /// is added. + /// + /// - Returns: The value that was replaced, or `nil` if a new key-value pair + /// was added. + /// + /// - Complexity: expected complexity is amortized O(1), if `Key` implements + /// high-quality hashing. + @inlinable + @discardableResult + public mutating func updateValue(_ value: Value, forKey key: Key) -> Value? { + let (index, bucket) = _keys._find(key) + if let index = index { + let old = _values[index] + _values[index] = value + return old + } + _keys._appendNew(key, in: bucket) + _values.append(value) + return nil + } + + /// Updates the value stored in the dictionary for the given key, or inserts a + /// new key-value pair at the specified index if the key does not exist. + /// + /// Use this method instead of key-based subscripting when you need to insert + /// new keys at a particular index. You can use the return value to + /// determine whether or not the new value supplanted the value of an existing + /// key. + /// + /// If the value of an existing key is updated, + /// `updateOrInsertValue(_:forKey:at:)` returns the original value and its + /// index. + /// + /// var hues: OrderedDictionary = [ + /// "Heliotrope": 296, + /// "Coral": 16, + /// "Aquamarine": 156] + /// let newIndex = hues.startIndex + /// let (old, index) = + /// hues.updateValue(18, forKey: "Coral", insertingAt: newIndex) + /// if let old = old { + /// print("The value '\(old)' at offset \(index.offset) was replaced.") + /// } + /// // Prints "The value '16' at offset 1 was replaced." + /// + /// If the given key is not present in the dictionary, this method inserts the + /// key-value pair at the specified index and returns `nil`. + /// + /// let (old, index) = + /// hues.updateValue(330, forKey: "Cerise", insertingAt: newIndex) + /// if let old = old { + /// print("The value '\(old)' at offset \(index.offset) was replaced.") + /// } else { + /// print("A new value was inserted at offset \(index.offset).") + /// } + /// // Prints "A new value was inserted at offset 0.") + /// + /// - Parameters: + /// - value: The new value to add to the dictionary. + /// - key: The key to associate with `value`. If `key` already exists in + /// the dictionary, `value` replaces the existing associated value. If + /// `key` isn't already a key of the dictionary, the `(key, value)` pair + /// is inserted. + /// - index: The index at which to insert the key, if it doesn't already + /// exist. + /// + /// - Returns: A pair `(old, index)`, where `old` is the value that was + /// replaced, or `nil` if a new key-value pair was added, and `index` + /// is the index corresponding to the updated (or inserted) value. + /// + /// - Complexity: O(`count`) + @inlinable + @discardableResult + public mutating func updateValue( + _ value: Value, + forKey key: Key, + insertingAt index: Index + ) -> (originalMember: Value?, index: Index) { + let (inserted, offset) = _keys.insert(key, at: index) + if inserted { + assert(offset == index) + _values.insert(value, at: offset) + return (nil, offset) + } + let old = _values[offset] + _values[offset] = value + return (old, offset) + } + + /// Ensures that the specified key exists in the dictionary (by appending one + /// with the supplied default value if necessary), then calls `body` to update + /// it in place. + /// + /// You can use this method to perform in-place operations on values in the + /// dictionary, whether or not `Value` has value semantics. The following + /// example uses this method while counting the occurrences of each letter + /// in a string: + /// + /// let message = "Hello, Elle!" + /// var letterCounts: [Character: Int] = [:] + /// for letter in message { + /// letterCounts.modifyValue(forKey: letter, default: 0) { count in + /// count += 1 + /// } + /// } + /// // letterCounts == ["H": 1, "e": 2, "l": 4, "o": 1, ...] + /// + /// - Parameters: + /// - key: The key to look up (or append). If `key` does not already exist + /// in the dictionary, it is appended with the supplied default value. + /// - defaultValue: The default value to append if `key` doesn't exist in + /// the dictionary. + /// - body: A function that performs an in-place mutation on the dictionary + /// value. + /// + /// - Returns: The return value of `body`. + /// + /// - Complexity: expected complexity is amortized O(1), if `Key` implements + /// high-quality hashing. (Ignoring the complexity of calling `body`.) + @inlinable + public mutating func modifyValue( + forKey key: Key, + default defaultValue: @autoclosure () -> Value, + _ body: (inout Value) throws -> R + ) rethrows -> R { + let (index, bucket) = _keys._find(key) + if let index = index { + return try body(&_values[index]) + } + _keys._appendNew(key, in: bucket) + _values.append(defaultValue()) + let i = _values.index(before: _values.endIndex) + return try body(&_values[i]) + } + + /// Ensures that the specified key exists in the dictionary (by inserting one + /// with the specified index and default value if necessary), then calls + /// `body` to update it in place. + /// + /// You can use this method to perform in-place operations on values in the + /// dictionary, whether or not `Value` has value semantics. The following + /// example uses this method while counting the occurrences of each letter + /// in a string: + /// + /// let message = "Hello, Elle!" + /// var letterCounts: [Character: Int] = [:] + /// for letter in message { + /// letterCounts.modifyValue(forKey: letter, default: 0) { count in + /// count += 1 + /// } + /// } + /// // letterCounts == ["H": 1, "e": 2, "l": 4, "o": 1, ...] + /// + /// - Parameters: + /// - key: The key to look up (or append). If `key` does not already exist + /// in the dictionary, it is appended with the supplied default value. + /// - defaultValue: The default value to append if `key` doesn't exist in + /// the dictionary. + /// - body: A function that performs an in-place mutation on the dictionary + /// value. + /// + /// - Returns: The return value of `body`. + /// + /// - Complexity: expected complexity is amortized O(1), if `Key` implements + /// high-quality hashing. (Ignoring the complexity of calling `body`.) + @inlinable + public mutating func modifyValue( + forKey key: Key, + insertingDefault defaultValue: @autoclosure () -> Value, + at index: Int, + _ body: (inout Value) throws -> R + ) rethrows -> R { + let (existingIndex, bucket) = _keys._find(key) + if let existingIndex = existingIndex { + return try body(&_values[existingIndex]) + } + _keys._insertNew(key, at: index, in: bucket) + _values.insert(defaultValue(), at: index) + return try body(&_values[index]) + } +} + +extension OrderedDictionary { + /// Removes the given key and its associated value from the dictionary. + /// + /// If the key is found in the dictionary, this method returns the key's + /// associated value. + /// + /// var hues: OrderedDictionary = [ + /// "Heliotrope": 296, + /// "Coral": 16, + /// "Aquamarine": 156] + /// if let value = hues.removeValue(forKey: "Coral") { + /// print("The value \(value) was removed.") + /// } + /// // Prints "The value 16 was removed." + /// + /// If the key isn't found in the dictionary, `removeValue(forKey:)` returns + /// `nil`. + /// + /// if let value = hues.removeValue(forKey: "Cerise") { + /// print("The value \(value) was removed.") + /// } else { + /// print("No value found for that key.") + /// } + /// // Prints "No value found for that key."" + /// + /// - Parameter key: The key to remove along with its associated value. + /// - Returns: The value that was removed, or `nil` if the key was not + /// present in the dictionary. + /// + /// - Complexity: O(`count`) + @inlinable + @discardableResult + public mutating func removeValue(forKey key: Key) -> Value? { + let (idx, bucket) = _keys._find(key) + guard let index = idx else { return nil } + _keys._removeExistingMember(at: index, in: bucket) + return _values.remove(at: index) + } +} + +extension OrderedDictionary { + /// Merges the key-value pairs in the given sequence into the dictionary, + /// using a combining closure to determine the value for any duplicate keys. + /// + /// Use the `combine` closure to select a value to use in the updated + /// dictionary, or to combine existing and new values. As the key-value + /// pairs are merged with the dictionary, the `combine` closure is called + /// with the current and new values for any duplicate keys that are + /// encountered. + /// + /// This example shows how to choose the current or new values for any + /// duplicate keys: + /// + /// var dictionary: OrderedDictionary = ["a": 1, "b": 2] + /// + /// // Keeping existing value for key "a": + /// dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current } + /// // ["b": 2, "a": 1, "c": 4] + /// + /// // Taking the new value for key "a": + /// dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new } + /// // ["b": 2, "a": 5, "c": 4, "d": 6] + /// + /// - Parameters: + /// - other: A sequence of key-value pairs. + /// - combine: A closure that takes the current and new values for any + /// duplicate keys. The closure returns the desired value for the final + /// dictionary. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the number of + /// elements in `keysAndValues`, if `Key` implements high-quality hashing. + @inlinable + public mutating func merge( + _ keysAndValues: __owned S, + uniquingKeysWith combine: (Value, Value) throws -> Value + ) rethrows where S.Element == (key: Key, value: Value) { + for (key, value) in keysAndValues { + let (index, bucket) = _keys._find(key) + if let index = index { + try { $0 = try combine($0, value) }(&_values[index]) + } else { + _keys._appendNew(key, in: bucket) + _values.append(value) + } + } + } + + /// Merges the key-value pairs in the given sequence into the dictionary, + /// using a combining closure to determine the value for any duplicate keys. + /// + /// Use the `combine` closure to select a value to use in the updated + /// dictionary, or to combine existing and new values. As the key-value + /// pairs are merged with the dictionary, the `combine` closure is called + /// with the current and new values for any duplicate keys that are + /// encountered. + /// + /// This example shows how to choose the current or new values for any + /// duplicate keys: + /// + /// var dictionary: OrderedDictionary = ["a": 1, "b": 2] + /// + /// // Keeping existing value for key "a": + /// dictionary.merge(zip(["a", "c"], [3, 4])) { (current, _) in current } + /// // ["b": 2, "a": 1, "c": 4] + /// + /// // Taking the new value for key "a": + /// dictionary.merge(zip(["a", "d"], [5, 6])) { (_, new) in new } + /// // ["b": 2, "a": 5, "c": 4, "d": 6] + /// + /// - Parameters: + /// - other: A sequence of key-value pairs. + /// - combine: A closure that takes the current and new values for any + /// duplicate keys. The closure returns the desired value for the final + /// dictionary. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the number of + /// elements in `keysAndValues`, if `Key` implements high-quality hashing. + @inlinable + public mutating func merge( + _ keysAndValues: __owned S, + uniquingKeysWith combine: (Value, Value) throws -> Value + ) rethrows where S.Element == (Key, Value) { + let mapped: LazyMapSequence = + keysAndValues.lazy.map { (key: $0.0, value: $0.1) } + try merge(mapped, uniquingKeysWith: combine) + } + + /// Creates a dictionary by merging key-value pairs in a sequence into this + /// dictionary, using a combining closure to determine the value for + /// duplicate keys. + /// + /// Use the `combine` closure to select a value to use in the returned + /// dictionary, or to combine existing and new values. As the key-value + /// pairs are merged with the dictionary, the `combine` closure is called + /// with the current and new values for any duplicate keys that are + /// encountered. + /// + /// This example shows how to choose the current or new values for any + /// duplicate keys: + /// + /// let dictionary: OrderedDictionary = ["a": 1, "b": 2] + /// let newKeyValues = zip(["a", "b"], [3, 4]) + /// + /// let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current } + /// // ["b": 2, "a": 1] + /// let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new } + /// // ["b": 4, "a": 3] + /// + /// - Parameters: + /// - other: A sequence of key-value pairs. + /// - combine: A closure that takes the current and new values for any + /// duplicate keys. The closure returns the desired value for the final + /// dictionary. + /// + /// - Returns: A new dictionary with the combined keys and values of this + /// dictionary and `other`. + /// + /// - Complexity: Expected to be O(`count` + *n*) on average, where *n* is the + /// number of elements in `keysAndValues`, if `Key` implements high-quality + /// hashing. + @inlinable + public __consuming func merging( + _ other: __owned S, + uniquingKeysWith combine: (Value, Value) throws -> Value + ) rethrows -> Self where S.Element == (key: Key, value: Value) { + var copy = self + try copy.merge(other, uniquingKeysWith: combine) + return copy + } + + /// Creates a dictionary by merging key-value pairs in a sequence into this + /// dictionary, using a combining closure to determine the value for + /// duplicate keys. + /// + /// Use the `combine` closure to select a value to use in the returned + /// dictionary, or to combine existing and new values. As the key-value + /// pairs are merged with the dictionary, the `combine` closure is called + /// with the current and new values for any duplicate keys that are + /// encountered. + /// + /// This example shows how to choose the current or new values for any + /// duplicate keys: + /// + /// let dictionary: OrderedDictionary = ["a": 1, "b": 2] + /// let newKeyValues = zip(["a", "b"], [3, 4]) + /// + /// let keepingCurrent = dictionary.merging(newKeyValues) { (current, _) in current } + /// // ["b": 2, "a": 1] + /// let replacingCurrent = dictionary.merging(newKeyValues) { (_, new) in new } + /// // ["b": 4, "a": 3] + /// + /// - Parameters: + /// - other: A sequence of key-value pairs. + /// - combine: A closure that takes the current and new values for any + /// duplicate keys. The closure returns the desired value for the final + /// dictionary. + /// + /// - Returns: A new dictionary with the combined keys and values of this + /// dictionary and `other`. + /// + /// - Complexity: Expected to be O(`count` + *n*) on average, where *n* is the + /// number of elements in `keysAndValues`, if `Key` implements high-quality + /// hashing. + @inlinable + public __consuming func merging( + _ other: __owned S, + uniquingKeysWith combine: (Value, Value) throws -> Value + ) rethrows -> Self where S.Element == (Key, Value) { + var copy = self + try copy.merge(other, uniquingKeysWith: combine) + return copy + } +} + +extension OrderedDictionary { + /// Returns a new dictionary containing the key-value pairs of the dictionary + /// that satisfy the given predicate. + /// + /// - Parameter isIncluded: A closure that takes a key-value pair as its + /// argument and returns a Boolean value indicating whether the pair + /// should be included in the returned dictionary. + /// + /// - Returns: A dictionary of the key-value pairs that `isIncluded` allows. + /// + /// - Complexity: O(`count`) + @inlinable + public func filter( + _ isIncluded: (Element) throws -> Bool + ) rethrows -> Self { + var result: OrderedDictionary = [:] + for element in self where try isIncluded(element) { + result._keys._appendNew(element.key) + result._values.append(element.value) + } + return result + } +} + +extension OrderedDictionary { + /// Returns a new dictionary containing the keys of this dictionary with the + /// values transformed by the given closure. + /// + /// - Parameter transform: A closure that transforms a value. `transform` + /// accepts each value of the dictionary as its parameter and returns a + /// transformed value of the same or of a different type. + /// - Returns: A dictionary containing the keys and transformed values of + /// this dictionary. + /// + /// - Complexity: O(`count`) + @inlinable + public func mapValues( + _ transform: (Value) throws -> T + ) rethrows -> OrderedDictionary { + OrderedDictionary( + _uniqueKeys: _keys, + values: ContiguousArray(try _values.map(transform))) + } + + /// Returns a new dictionary containing only the key-value pairs that have + /// non-`nil` values as the result of transformation by the given closure. + /// + /// Use this method to receive a dictionary with non-optional values when + /// your transformation produces optional values. + /// + /// In this example, note the difference in the result of using `mapValues` + /// and `compactMapValues` with a transformation that returns an optional + /// `Int` value. + /// + /// let data: OrderedDictionary = ["a": "1", "b": "three", "c": "///4///"] + /// + /// let m: [String: Int?] = data.mapValues { str in Int(str) } + /// // ["a": Optional(1), "b": nil, "c": nil] + /// + /// let c: [String: Int] = data.compactMapValues { str in Int(str) } + /// // ["a": 1] + /// + /// - Parameter transform: A closure that transforms a value. `transform` + /// accepts each value of the dictionary as its parameter and returns an + /// optional transformed value of the same or of a different type. + /// + /// - Returns: A dictionary containing the keys and non-`nil` transformed + /// values of this dictionary. + /// + /// - Complexity: O(`count`) + @inlinable + public func compactMapValues( + _ transform: (Value) throws -> T? + ) rethrows -> OrderedDictionary { + var result: OrderedDictionary = [:] + for (key, value) in self { + if let value = try transform(value) { + result._keys._appendNew(key) + result._values.append(value) + } + } + return result + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Codable.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Codable.swift new file mode 100644 index 00000000..365d225f --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Codable.swift @@ -0,0 +1,46 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: Encodable where Element: Encodable { + /// Encodes the elements of this ordered set into the given encoder. + /// + /// - Parameter encoder: The encoder to write data to. + @inlinable + public func encode(to encoder: Encoder) throws { + var container = encoder.singleValueContainer() + try container.encode(_elements) + } +} + +extension OrderedSet: Decodable where Element: Decodable { + /// Creates a new ordered set by decoding from the given decoder. + /// + /// This initializer throws an error if reading from the decoder fails, or + /// if the decoded contents contain duplicate values. + /// + /// - Parameter decoder: The decoder to read data from. + @inlinable + public init(from decoder: Decoder) throws { + let container = try decoder.singleValueContainer() + let elements = try container.decode(ContiguousArray.self) + + let (table, end) = _HashTable.create(untilFirstDuplicateIn: elements) + guard end == elements.endIndex else { + let context = DecodingError.Context( + codingPath: container.codingPath, + debugDescription: "Decoded elements aren't unique (first duplicate at offset \(end))") + throw DecodingError.dataCorrupted(context) + } + self.init( + _uniqueElements: elements, + elements.count > _HashTable.maximumUnhashedCount ? table : nil) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomDebugStringConvertible.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomDebugStringConvertible.swift new file mode 100644 index 00000000..effbe7d3 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomDebugStringConvertible.swift @@ -0,0 +1,36 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: CustomDebugStringConvertible { + /// A textual representation of this instance, suitable for debugging. + public var debugDescription: String { + _debugDescription(typeName: _debugTypeName()) + } + + internal func _debugTypeName() -> String { + "OrderedSet<\(Element.self)>" + } + + internal func _debugDescription(typeName: String) -> String { + var result = "\(typeName)([" + var first = true + for item in self { + if first { + first = false + } else { + result += ", " + } + debugPrint(item, terminator: "", to: &result) + } + result += "])" + return result + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomReflectable.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomReflectable.swift new file mode 100644 index 00000000..8b054628 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomReflectable.swift @@ -0,0 +1,17 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: CustomReflectable { + /// The custom mirror for this instance. + public var customMirror: Mirror { + Mirror(self, unlabeledChildren: _elements, displayStyle: .collection) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomStringConvertible.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomStringConvertible.swift new file mode 100644 index 00000000..2678ed60 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+CustomStringConvertible.swift @@ -0,0 +1,28 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: CustomStringConvertible { + /// A textual representation of this instance. + public var description: String { + var result = "[" + var first = true + for item in self { + if first { + first = false + } else { + result += ", " + } + print(item, terminator: "", to: &result) + } + result += "]" + return result + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Equatable.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Equatable.swift new file mode 100644 index 00000000..1190cd6e --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Equatable.swift @@ -0,0 +1,23 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: Equatable { + /// Returns a Boolean value indicating whether two values are equal. + /// + /// Two ordered sets are considered equal if they contain the same + /// elements in the same order. + /// + /// - Complexity: O(`min(left.count, right.count)`) + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + left.elementsEqual(right) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+ExpressibleByArrayLiteral.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+ExpressibleByArrayLiteral.swift new file mode 100644 index 00000000..1b92f341 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+ExpressibleByArrayLiteral.swift @@ -0,0 +1,32 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: ExpressibleByArrayLiteral { + /// Creates a new ordered set from the contents of an array literal. + /// + /// Duplicate elements in the literal are allowed, but the resulting + /// set will only contain the first occurrence of each. + /// + /// Do not call this initializer directly. It is used by the compiler when + /// you use an array literal. Instead, create a new set using an array + /// literal as its value by enclosing a comma-separated list of values in + /// square brackets. You can use an array literal anywhere a set is expected + /// by the type context. + /// + /// - Parameter elements: A variadic list of elements of the new set. + /// + /// - Complexity: O(`elements.count`) if `Element` implements + /// high-quality hashing. + @inlinable + public init(arrayLiteral elements: Element...) { + self.init(elements) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Hashable.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Hashable.swift new file mode 100644 index 00000000..3acba720 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Hashable.swift @@ -0,0 +1,24 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: Hashable { + /// Hashes the essential components of this value by feeding them into the + /// given hasher. + /// + /// Complexity: O(`count`) + @inlinable + public func hash(into hasher: inout Hasher) { + hasher.combine(count) // Discriminator + for item in _elements { + hasher.combine(item) + } + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Initializers.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Initializers.swift new file mode 100644 index 00000000..82a6a76b --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Initializers.swift @@ -0,0 +1,153 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet { + @inlinable + internal init(_uncheckedUniqueElements elements: ContiguousArray) { +#if DEBUG + self.init(_uniqueElements: elements) +#else + guard elements.count > _HashTable.maximumUnhashedCount else { + self.init(_uniqueElements: elements, nil) + return + } + let table = _HashTable.create(uncheckedUniqueElements: elements) + self.init(_uniqueElements: elements, table) +#endif + } + + /// Creates a set with the contents of the given sequence, which + /// must not include duplicate elements. + /// + /// In optimized builds, this initializer does not verify that the + /// elements are actually unique. This makes creating the set + /// somewhat faster if you know for sure that the elements are + /// unique (e.g., because they come from another collection with + /// guaranteed-unique members, such as a `Set`). However, if you + /// accidentally call this initializer with duplicate members, it + /// can return a corrupt set value that may be difficult to debug. + /// + /// - Parameter elements: A finite sequence of unique elements. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the + /// number of elements in the sequence, if `Element` implements + /// high-quality hashing. + @inlinable + @inline(__always) + public init(uncheckedUniqueElements elements: S) + where S.Element == Element { + self.init(_uncheckedUniqueElements: ContiguousArray(elements)) + } +} + +extension OrderedSet { + /// Creates a new set from a finite sequence of items. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform O(*n*) + /// comparisons on average (where *n* is the number of elements + /// in the sequence), provided that `Element` implements + /// high-quality hashing. + @inlinable + public init(_ elements: S) where S.Element == Element { + if S.self == Self.self { + self = elements as! Self + return + } + // Fast paths for when we know elements are all unique + if S.self == Set.self || S.self == SubSequence.self { + self.init(uncheckedUniqueElements: elements) + return + } + + self.init() + append(contentsOf: elements) + } + + // Specializations + + /// Creates a new set from a an existing set. This is functionally the same as + /// copying the value of `elements` into a new variable. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: O(1) + @inlinable + public init(_ elements: Self) { + self = elements + } + + /// Creates a new set from an existing slice of another set. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform + /// O(`elements.count`) operations on average, provided that + /// `Element` implements high-quality hashing. + @inlinable + public init(_ elements: SubSequence) { + self.init(uncheckedUniqueElements: elements._slice) + } + + /// Creates a new set from an existing `Set` value. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform + /// O(`elements.count`) operations on average, provided that + /// `Element` implements high-quality hashing. + @inlinable + public init(_ elements: Set) { + self.init(uncheckedUniqueElements: elements) + } + + /// Creates a new set from the keys view of a dictionary. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform + /// O(`elements.count`) operations on average, provided that + /// `Element` implements high-quality hashing. + @inlinable + public init(_ elements: Dictionary.Keys) { + self._elements = ContiguousArray(elements) + _regenerateHashTable() + _checkInvariants() + } + + /// Creates a new set from a collection of items. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform O(*n*) + /// comparisons on average (where *n* is the number of elements + /// in the sequence), provided that `Element` implements + /// high-quality hashing. + @inlinable + public init( + _ elements: C + ) where C.Element == Element { + // This code is careful not to copy storage if `C` is an Array + // or ContiguousArray and the elements are already unique. + let (table, firstDupe) = _HashTable.create( + untilFirstDuplicateIn: elements) + if firstDupe == elements.endIndex { + // Fast path: `elements` consists of unique values. + self.init(_uniqueElements: ContiguousArray(elements), table) + return + } + + // Otherwise keep the elements we've processed and add the rest one by one. + self.init(_uniqueElements: ContiguousArray(elements[.. (inserted: Bool, index: Int) { + let (index, bucket) = _find(item) + if let index = index { return (false, index) } + _appendNew(item, in: bucket) + return (true, _elements.index(before: _elements.endIndex)) + } + + /// Append a new member to the end of the set, if the set doesn't + /// already contain it. + /// + /// - Parameter item: The element to add to the set. + /// + /// - Returns: A pair `(inserted, index)`, where `inserted` is a Boolean value + /// indicating whether the operation added a new element, and `index` is + /// the index of `item` in the resulting set. + /// + /// - Complexity: The operation is expected to perform O(1) copy, hash, and + /// compare operations on the `Element` type, if it implements high-quality + /// hashing. + @inlinable + @inline(__always) + @discardableResult + public mutating func append(_ item: Element) -> (inserted: Bool, index: Int) { + let result = _append(item) + _checkInvariants() + return result + } + + /// Append the contents of a sequence to the end of the set, excluding + /// elements that are already members. + /// + /// This is functionally equivalent to `self.formUnion(elements)`, but it's + /// more explicit about how the new members are ordered in the new set. + /// + /// - Parameter elements: A finite sequence of elements to append. + /// + /// - Complexity: The operation is expected to perform amortized O(1) copy, + /// hash, and compare operations on the `Element` type, if it implements + /// high-quality hashing. + @inlinable + public mutating func append( + contentsOf elements: S + ) where S.Element == Element { + for item in elements { + _append(item) + } + _checkInvariants() + } +} + +extension OrderedSet { + @inlinable + internal mutating func _insertNew( + _ item: Element, + at index: Index, + in bucket: _Bucket + ) { + guard _elements.count < _capacity else { + _elements.insert(item, at: index) + _regenerateHashTable() + return + } + guard _table != nil else { + _elements.insert(item, at: index) + return + } + + _table!.update { hashTable in + assert(!hashTable.isOccupied(bucket)) + hashTable.adjustContents(preparingForInsertionOfElementAtOffset: index, in: _elements) + hashTable[bucket] = index + } + _elements.insert(item, at: index) + _checkInvariants() + } + + /// Insert a new member to this set at the specified index, if the set doesn't + /// already contain it. + /// + /// - Parameter item: The element to insert. + /// + /// - Returns: A pair `(inserted, index)`, where `inserted` is a Boolean value + /// indicating whether the operation added a new element, and `index` is + /// the index of `item` in the resulting set. If `inserted` is true, then + /// the returned `index` may be different from the index requested. + /// + /// - Complexity: The operation is expected to perform amortized + /// O(`self.count`) copy, hash, and compare operations on the `Element` + /// type, if it implements high-quality hashing. (Insertions need to make + /// room in the storage array to add the inserted element.) + @inlinable + public mutating func insert( + _ item: Element, + at index: Index + ) -> (inserted: Bool, index: Index) { + let (existing, bucket) = _find(item) + if let existing = existing { return (false, existing) } + _insertNew(item, at: index, in: bucket) + return (true, index) + } +} + +extension OrderedSet { + /// Replace the member at the given index with a new value that compares equal + /// to it. + /// + /// This is useful when equal elements can be distinguished by identity + /// comparison or some other means. + /// + /// - Parameter item: The new value that should replace the original element. + /// `item` must compare equal to the original value. + /// + /// - Parameter index: The index of the element to be replaced. + /// + /// - Returns: The original element that was replaced. + /// + /// - Complexity: Amortized O(1). + @inlinable + @discardableResult + public mutating func update(_ item: Element, at index: Index) -> Element { + let old = _elements[index] + precondition( + item == old, + "The replacement item must compare equal to the original") + _elements[index] = item + return old + } +} + +extension OrderedSet { + /// Adds the given element to the set unconditionally, either appending it to + /// the set, or replacing an existing value if it's already present. + /// + /// This is useful when equal elements can be distinguished by identity + /// comparison or some other means. + /// + /// - Parameter item: The value to append or replace. + /// + /// - Returns: The original element that was replaced by this operation, or + /// `nil` if the value was appended to the end of the collection. + /// + /// - Complexity: The operation is expected to perform amortized O(1) copy, + /// hash, and compare operations on the `Element` type, if it implements + /// high-quality hashing. + @inlinable + public mutating func updateOrAppend(_ item: Element) -> Element? { + let (inserted, index) = _append(item) + if inserted { return nil } + let old = _elements[index] + _elements[index] = item + _checkInvariants() + return old + } + + /// Adds the given element into the set unconditionally, either inserting it + /// at the specified index, or replacing an existing value if it's already + /// present. + /// + /// This is useful when equal elements can be distinguished by identity + /// comparison or some other means. + /// + /// - Parameter item: The value to append or replace. + /// + /// - Parameter index: The index at which to insert the new member if `item` + /// isn't already in the set. + /// + /// - Returns: The original element that was replaced by this operation, or + /// `nil` if the value was newly inserted into the collection. + /// + /// - Complexity: The operation is expected to perform amortized O(1) copy, + /// hash, and compare operations on the `Element` type, if it implements + /// high-quality hashing. + @inlinable + public mutating func updateOrInsert( + _ item: Element, + at index: Index + ) -> (originalMember: Element?, index: Index) { + let (existing, bucket) = _find(item) + if let existing = existing { + let old = _elements[existing] + _elements[existing] = item + return (old, existing) + } + _insertNew(item, at: index, in: bucket) + return (nil, index) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Invariants.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Invariants.swift new file mode 100644 index 00000000..588ecd88 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Invariants.swift @@ -0,0 +1,54 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet { + #if COLLECTIONS_INTERNAL_CHECKS + @inlinable + @inline(never) @_effects(releasenone) + internal func _checkInvariants() { + if _table == nil { + precondition(_elements.count <= _HashTable.maximumUnhashedCount, + "Oversized set without a hash table") + precondition(Set(_elements).count == _elements.count, + "Duplicate items in set") + return + } + // Check that each element in _elements can be found in the hash table. + for index in _elements.indices { + let item = _elements[index] + let i = _find(item).index + precondition(i != nil, + "Index \(index) not found in hash table (element: \(item))") + precondition( + i == index, + "Offset of element '\(item)' in hash table differs from its position") + } + // Check that the hash table has exactly as many entries as there are elements. + _table!.read { hashTable in + var it = hashTable.bucketIterator(startingAt: _Bucket(offset: 0)) + var c = 0 + repeat { + it.advance() + if it.isOccupied { c += 1 } + } while it.currentBucket.offset != 0 + precondition( + c == _elements.count, + """ + Number of entries in hash table (\(c)) differs + from number of elements (\(_elements.count)) + """) + } + } + #else + @inline(__always) @inlinable + public func _checkInvariants() {} + #endif // COLLECTIONS_INTERNAL_CHECKS +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial MutableCollection.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial MutableCollection.swift new file mode 100644 index 00000000..bb52bd3d --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial MutableCollection.swift @@ -0,0 +1,442 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// The parts of MutableCollection that OrderedSet is able to implement. + +extension OrderedSet { + /// Exchanges the values at the specified indices of the set. + /// + /// Both parameters must be valid indices below `endIndex`. Passing the same + /// index as both `i` and `j` has no effect. + /// + /// - Parameters: + /// - i: The index of the first value to swap. + /// - j: The index of the second value to swap. + /// + /// - Complexity: O(1) when the set's storage isn't shared with another + /// value; O(`count`) otherwise. + @inlinable + public mutating func swapAt(_ i: Index, _ j: Index) { + guard i != j else { return } + _elements.swapAt(i, j) + guard _table != nil else { return } + _ensureUnique() + _table!.update { hashTable in + hashTable.swapBucketValues(for: _elements[i], withCurrentValue: j, + and: _elements[j], withCurrentValue: i) + } + _checkInvariants() + } + + /// Reorders the elements of the set such that all the elements that match the + /// given predicate are after all the elements that don't match. + /// + /// After partitioning a collection, there is a pivot index `p` where + /// no element before `p` satisfies the `belongsInSecondPartition` + /// predicate and every element at or after `p` satisfies + /// `belongsInSecondPartition`. + /// + /// In the following example, an ordered set of numbers is partitioned by a + /// predicate that matches elements greater than 30. + /// + /// var numbers: OrderedSet = [30, 40, 20, 30, 30, 60, 10] + /// let p = numbers.partition(by: { $0 > 30 }) + /// // p == 5 + /// // numbers == [30, 10, 20, 30, 30, 60, 40] + /// + /// The `numbers` set is now arranged in two partitions. The first partition, + /// `numbers[.. Bool + ) rethrows -> Index { + try _partition(by: belongsInSecondPartition, callback: { a, b in }) + } +} + +extension OrderedSet { + @inlinable + public mutating func _partition( + by belongsInSecondPartition: (Element) throws -> Bool, + callback: (Int, Int) -> Void + ) rethrows -> Index { + guard _table != nil else { + return try _elements.partition(by: belongsInSecondPartition) + } + _ensureUnique() + let result: Index = try _table!.update { hashTable in + let maybeOffset: Int? = try _elements.withContiguousMutableStorageIfAvailable { buffer in + let pivot = try buffer._partition( + with: hashTable, + by: belongsInSecondPartition, + callback: callback) + return pivot - buffer.startIndex + } + if let offset = maybeOffset { + return _elements.index(startIndex, offsetBy: offset) + } + return try _elements._partition( + with: hashTable, + by: belongsInSecondPartition, + callback: callback) + } + _checkInvariants() + return result + } +} + +extension MutableCollection where Self: RandomAccessCollection, Element: Hashable { + @inlinable + internal mutating func _partition( + with hashTable: _UnsafeHashTable, + by belongsInSecondPartition: (Element) throws -> Bool, + callback: (Int, Int) -> Void + ) rethrows -> Index { + var low = startIndex + var high = endIndex + + while true { + // Invariants at this point: + // - low <= high + // - all elements in `startIndex ..< low` belong in the first partition + // - all elements in `high ..< endIndex` belong in the second partition + + // Find next element from `lo` that may not be in the right place. + while true { + if low == high { return low } + if try belongsInSecondPartition(self[low]) { break } + formIndex(after: &low) + } + + // Find next element down from `hi` that we can swap `lo` with. + while true { + formIndex(before: &high) + if low == high { return low } + if try !belongsInSecondPartition(self[high]) { break } + } + + // Swap the two elements as well as their associated hash table buckets. + swapAt(low, high) + let offsetLow = _offset(of: low) + let offsetHigh = _offset(of: high) + hashTable.swapBucketValues(for: self[low], withCurrentValue: offsetHigh, + and: self[high], withCurrentValue: offsetLow) + callback(offsetLow, offsetHigh) + + formIndex(after: &low) + } + } +} + +extension _UnsafeHashTable { + @inlinable + @inline(__always) + func swapBucketValues( + for left: Element, withCurrentValue leftValue: Int, + and right: Element, withCurrentValue rightValue: Int + ) { + let left = idealBucket(for: left) + let right = idealBucket(for: right) + swapBucketValues(for: left, withCurrentValue: leftValue, + and: right, withCurrentValue: rightValue) + } + + @usableFromInline + @_effects(releasenone) + func swapBucketValues( + for left: Bucket, withCurrentValue leftValue: Int, + and right: Bucket, withCurrentValue rightValue: Int + ) { + var it = bucketIterator(startingAt: left) + it.advance(until: leftValue) + assert(it.isOccupied) + it.currentValue = rightValue + + it = bucketIterator(startingAt: right) + it.advance(until: rightValue) + assert(it.isOccupied) + // Note: this second update may mistake the bucket for `right` with the + // bucket for `left` whose value we just updated. The second update will + // restore the original hash table contents in this case. This is okay! + // When this happens, the lookup chains for both elements include each + // other, so leaving the hash table unchanged still leaves us with a + // working hash table. + it.currentValue = leftValue + } +} + +extension OrderedSet { + /// Sorts the collection in place, using the given predicate as the + /// comparison between elements. + /// + /// When you want to sort a collection of elements that don't conform to + /// the `Comparable` protocol, pass a closure to this method that returns + /// `true` when the first element should be ordered before the second. + /// + /// Alternatively, use this method to sort a collection of elements that do + /// conform to `Comparable` when you want the sort to be descending instead + /// of ascending. Pass the greater-than operator (`>`) operator as the + /// predicate. + /// + /// `areInIncreasingOrder` must be a *strict weak ordering* over the + /// elements. That is, for any elements `a`, `b`, and `c`, the following + /// conditions must hold: + /// + /// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity) + /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are + /// both `true`, then `areInIncreasingOrder(a, c)` is also `true`. + /// (Transitive comparability) + /// - Two elements are *incomparable* if neither is ordered before the other + /// according to the predicate. If `a` and `b` are incomparable, and `b` + /// and `c` are incomparable, then `a` and `c` are also incomparable. + /// (Transitive incomparability) + /// + /// The sorting algorithm is not guaranteed to be stable. A stable sort + /// preserves the relative order of elements for which + /// `areInIncreasingOrder` does not establish an order. + /// + /// - Parameter areInIncreasingOrder: A predicate that returns `true` if its + /// first argument should be ordered before its second argument; + /// otherwise, `false`. If `areInIncreasingOrder` throws an error during + /// the sort, the elements may be in a different order, but none will be + /// lost. + /// + /// - Complexity: O(*n* log *n*), where *n* is the length of the collection. + @inlinable + public mutating func sort( + by areInIncreasingOrder: (Element, Element) throws -> Bool + ) rethrows { + defer { + // Note: This assumes that `sort(by:)` won't leave duplicate/missing + // elements in the table when the closure throws. This matches the + // stdlib's behavior in Swift 5.3, and it seems like a reasonable + // long-term assumption. + _regenerateExistingHashTable() + _checkInvariants() + } + try _elements.sort(by: areInIncreasingOrder) + } +} + +extension OrderedSet where Element: Comparable { + /// Sorts the set in place. + /// + /// You can sort an ordered set of elements that conform to the + /// `Comparable` protocol by calling this method. Elements are sorted in + /// ascending order. + /// + /// Here's an example of sorting a list of students' names. Strings in Swift + /// conform to the `Comparable` protocol, so the names are sorted in + /// ascending order according to the less-than operator (`<`). + /// + /// var students: OrderedSet = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"] + /// students.sort() + /// print(students) + /// // Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]" + /// + /// To sort the elements of your collection in descending order, pass the + /// greater-than operator (`>`) to the `sort(by:)` method. + /// + /// students.sort(by: >) + /// print(students) + /// // Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]" + /// + /// The sorting algorithm is not guaranteed to be stable. A stable sort + /// preserves the relative order of elements that compare equal. + /// + /// - Complexity: O(*n* log *n*), where *n* is the length of the collection. + @inlinable + public mutating func sort() { + defer { + // Note: This assumes that `sort(by:)` won't leave duplicate/missing + // elements in the table when the closure throws. This matches the + // stdlib's behavior in Swift 5.3, and it seems like a reasonable + // long-term assumption. + _regenerateExistingHashTable() + _checkInvariants() + } + _elements.sort() + } +} + +extension OrderedSet { + /// Shuffles the collection in place. + /// + /// Use the `shuffle()` method to randomly reorder the elements of an ordered + /// set. + /// + /// var names: OrderedSet + /// = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"] + /// names.shuffle() + /// // names == ["Luis", "Camila", "Luciana", "Sofía", "Alejandro", "Diego"] + /// + /// This method is equivalent to calling `shuffle(using:)`, passing in the + /// system's default random generator. + /// + /// - Complexity: O(*n*), where *n* is the length of the collection. + @inlinable + public mutating func shuffle() { + var generator = SystemRandomNumberGenerator() + shuffle(using: &generator) + } + + /// Shuffles the collection in place, using the given generator as a source + /// for randomness. + /// + /// You use this method to randomize the elements of a collection when you + /// are using a custom random number generator. For example, you can use the + /// `shuffle(using:)` method to randomly reorder the elements of an array. + /// + /// var names: OrderedSet + /// = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"] + /// names.shuffle(using: &myGenerator) + /// // names == ["Sofía", "Alejandro", "Camila", "Luis", "Diego", "Luciana"] + /// + /// - Parameter generator: The random number generator to use when shuffling + /// the collection. + /// + /// - Complexity: O(*n*), where *n* is the length of the collection. + /// + /// - Note: The algorithm used to shuffle a collection may change in a future + /// version of Swift. If you're passing a generator that results in the + /// same shuffled order each time you run your program, that sequence may + /// change when your program is compiled using a different version of + /// Swift. + @inlinable + public mutating func shuffle( + using generator: inout T + ) { + _elements.shuffle(using: &generator) + _regenerateExistingHashTable() + _checkInvariants() + } +} + +extension OrderedSet { + /// Reverses the elements of the ordered set in place. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func reverse() { + _elements.reverse() + // FIXME: Update hash table contents in place. + _regenerateHashTable() + _checkInvariants() + } +} + +extension OrderedSet { + + /// Moves all elements satisfying `belongsInSecondPartition` into a suffix + /// of the collection, returning the start position of the resulting suffix. + /// On return, the items before this pivot index remain in the order they + /// originally appeared in the collection. + /// + /// - Complexity: O(*n*) where n is the length of the collection. + @inlinable + internal mutating func _halfStablePartition( + values: UnsafeMutableBufferPointer, + by belongsInSecondPartition: ((key: Element, value: Value)) throws -> Bool + ) rethrows -> Int { + precondition(self.count == values.count) + var i = 0 + try _elements.withUnsafeMutableBufferPointer { keys in + while i < keys.count, try !belongsInSecondPartition((keys[i], values[i])) { + i += 1 + } + } + guard i < self.count else { return self.count } + + self._ensureUnique() + let table = _table + self._table = nil + defer { self._table = table } + + return try _elements.withUnsafeMutableBufferPointer { keys in + for j in i + 1 ..< keys.count { + guard try !belongsInSecondPartition((keys[j], values[j])) else { + continue + } + keys.swapAt(i, j) + values.swapAt(i, j) + table?.update { hashTable in + hashTable.swapBucketValues(for: keys[i], withCurrentValue: j, + and: keys[j], withCurrentValue: i) + } + i += 1 + } + return i + } + } + + @inlinable + internal mutating func _partition( + values: UnsafeMutableBufferPointer, + by belongsInSecondPartition: ((key: Element, value: Value)) throws -> Bool + ) rethrows -> Int { + self._ensureUnique() + let table = self._table + self._table = nil + defer { self._table = table } + return try _elements.withUnsafeMutableBufferPointer { keys in + assert(keys.count == values.count) + var low = keys.startIndex + var high = keys.endIndex + + while true { + // Invariants at this point: + // - low <= high + // - all elements in `startIndex ..< low` belong in the first partition + // - all elements in `high ..< endIndex` belong in the second partition + + // Find next element from `lo` that may not be in the right place. + while true { + if low == high { return low } + if try belongsInSecondPartition((keys[low], values[low])) { break } + low += 1 + } + + // Find next element down from `hi` that we can swap `lo` with. + while true { + high -= 1 + if low == high { return low } + if try !belongsInSecondPartition((keys[high], values[high])) { break } + } + + // Swap the two elements as well as their associated hash table buckets. + keys.swapAt(low, high) + values.swapAt(low, high) + table?.update { hashTable in + hashTable.swapBucketValues(for: keys[low], withCurrentValue: high, + and: keys[high], withCurrentValue: low) + } + low += 1 + } + } + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial RangeReplaceableCollection.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial RangeReplaceableCollection.swift new file mode 100644 index 00000000..87b851a4 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial RangeReplaceableCollection.swift @@ -0,0 +1,221 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// The parts of RangeReplaceableCollection that OrderedSet is able to implement. + +extension OrderedSet { + /// Removes all members from the set. + /// + /// - Parameter keepingCapacity: If `true`, the set's storage capacity is + /// preserved; if `false`, the underlying storage is released. The default + /// is `false`. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll(keepingCapacity keepCapacity: Bool = false) { + _elements.removeAll(keepingCapacity: keepCapacity) + guard keepCapacity else { + _table = nil + return + } + guard _table != nil else { return } + _ensureUnique() + _table!.update { hashTable in + hashTable.clear() + } + } + + /// Removes and returns the element at the specified position. + /// + /// All the elements following the specified position are moved to close the + /// resulting gap. + /// + /// - Parameter index: The position of the element to remove. `index` must be + /// a valid index of the collection that is not equal to the collection's + /// end index. + /// + /// - Returns: The removed element. + /// + /// - Complexity: O(`count`) + @inlinable + @discardableResult + public mutating func remove(at index: Index) -> Self.Element { + _elements._failEarlyRangeCheck(index, bounds: startIndex ..< endIndex) + let bucket = _bucket(for: index) + return _removeExistingMember(at: index, in: bucket) + } + + /// Removes the specified subrange of elements from the collection. + /// + /// All the elements following the specified subrange are moved to close the + /// resulting gap. + /// + /// - Parameter bounds: The subrange of the collection to remove. The bounds + /// of the range must be valid indices of the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeSubrange(_ bounds: Range) { + _elements._failEarlyRangeCheck( + bounds, + bounds: _elements.startIndex ..< _elements.endIndex) + guard _table != nil else { + _elements.removeSubrange(bounds) + _checkInvariants() + return + } + let c = bounds.count + guard c > 0 else { return } + let remainingCount = _elements.count - c + if remainingCount <= count / 2 || remainingCount < _minimumCapacity { + // Just generate a new table from scratch. + _elements.removeSubrange(bounds) + _regenerateHashTable() + _checkInvariants() + return + } + + _ensureUnique() + _table!.update { hashTable in + // Delete the hash table entries for all members we're removing. + for item in _elements[bounds] { + let (offset, bucket) = hashTable._find(item, in: _elements) + precondition(offset != nil, "Corrupt hash table") + hashTable.delete( + bucket: bucket, + hashValueGenerator: { offset, seed in + return _elements[offset]._rawHashValue(seed: seed) + }) + } + hashTable.adjustContents(preparingForRemovalOf: bounds, in: _elements) + } + _elements.removeSubrange(bounds) + _checkInvariants() + } + + /// Removes the specified subrange of elements from the collection. + /// + /// All the elements following the specified subrange are moved to close the + /// resulting gap. + /// + /// - Parameter bounds: The subrange of the collection to remove. The bounds + /// of the range must be valid indices of the collection. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeSubrange( + _ bounds: R + ) where R.Bound == Index { + removeSubrange(bounds.relative(to: self)) + } + + /// Removes the last element of a non-empty set. + /// + /// - Complexity: Expected to be O(`1`) on average, if `Element` implements + /// high-quality hashing. + @inlinable + @discardableResult + public mutating func removeLast() -> Element { + precondition(!isEmpty, "Cannot remove last element of an empty collection") + guard _table != nil else { + return _elements.removeLast() + } + guard _elements.count - 1 >= _minimumCapacity else { + let old = _elements.removeLast() + _regenerateHashTable() + return old + } + defer { _checkInvariants() } + let old = _elements.removeLast() + _ensureUnique() + _table!.update { hashTable in + var it = hashTable.bucketIterator(for: old) + it.advance(until: _elements.count) + // Delete the entry for the removed member. + hashTable.delete( + bucket: it.currentBucket, + hashValueGenerator: { offset, seed in + _elements[offset]._rawHashValue(seed: seed) + }) + } + return old + } + + /// Removes the last `n` element of the set. + /// + /// - Parameter n: The number of elements to remove from the collection. + /// `n` must be greater than or equal to zero and must not exceed the + /// number of elements in the collection. + /// + /// - Complexity: Expected to be O(`n`) on average, if `Element` implements + /// high-quality hashing. + @inlinable + public mutating func removeLast(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the collection") + removeSubrange(count - n ..< count) + } + + /// Removes the first element of a non-empty set. + /// + /// The members following the removed item need to be moved to close the + /// resulting gap in the storage array. + /// + /// - Complexity: O(`count`). + @inlinable + @discardableResult + public mutating func removeFirst() -> Element { + precondition(!isEmpty, "Cannot remove first element of an empty collection") + return remove(at: startIndex) + } + + /// Removes the first `n` elements of the set. + /// + /// The members following the removed items need to be moved to close the + /// resulting gap in the storage array. + /// + /// - Parameter n: The number of elements to remove from the collection. + /// `n` must be greater than or equal to zero and must not exceed the + /// number of elements in the set. + /// + /// - Complexity: O(`count`). + @inlinable + public mutating func removeFirst(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the collection") + removeSubrange(0 ..< n) + } + + /// Removes all the elements that satisfy the given predicate. + /// + /// Use this method to remove every element in a collection that meets + /// particular criteria. The order of the remaining elements is preserved. + /// + /// This example removes all the odd values from an + /// array of numbers: + /// + /// var numbers: OrderedSet = [5, 6, 7, 8, 9, 10, 11] + /// numbers.removeAll(where: { !$0.isMultiple(of: 2) }) + /// // numbers == [6, 8, 10] + /// + /// - Parameter shouldBeRemoved: A closure that takes an element of the + /// set as its argument and returns a Boolean value indicating + /// whether the element should be removed from the set. + /// + /// - Complexity: O(`count`) + @inlinable + public mutating func removeAll( + where shouldBeRemoved: (Element) throws -> Bool + ) rethrows { + defer { _regenerateHashTable() } + try _elements.removeAll(where: shouldBeRemoved) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Basics.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Basics.swift new file mode 100644 index 00000000..cd303b02 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Basics.swift @@ -0,0 +1,76 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// `OrderedSet` does not directly conform to `SetAlgebra` because its definition +// of equality conflicts with `SetAlgebra` requirements. However, it still +// implements most `SetAlgebra` requirements (except `insert`, which is replaced +// by `append`). +// +// `OrderedSet` also provides an `unordered` view that explicitly conforms to +// `SetAlgebra`. That view implements `Equatable` by ignoring element order, +// so it can satisfy `SetAlgebra` requirements. + +extension OrderedSet { + /// Creates an empty set. + /// + /// This initializer is equivalent to initializing with an empty array + /// literal. + /// + /// - Complexity: O(1) + @inlinable + public init() { + __storage = nil + _elements = [] + } +} + +extension OrderedSet { + /// Returns a Boolean value that indicates whether the given element exists + /// in the set. + /// + /// - Parameter element: An element to look for in the set. + /// + /// - Returns: `true` if `member` exists in the set; otherwise, `false`. + /// + /// - Complexity: This operation is expected to perform O(1) comparisons on + /// average, provided that `Element` implements high-quality hashing. + @inlinable + public func contains(_ element: Element) -> Bool { + _find_inlined(element).index != nil + } +} + +extension OrderedSet { + /// Removes the given element from the set. + /// + /// - Parameter member: The element of the set to remove. + /// + /// - Returns: The element equal to `member` if `member` is contained in the + /// set; otherwise, `nil`. In some cases, the returned element may be + /// distinguishable from `newMember` by identity comparison or some other + /// means. + /// + /// - Complexity: O(`count`). Removing an element from the middle of the + /// underlying ordered set needs to rearrange the remaining elements to + /// close the resulting gap. + /// + /// Removing the last element only takes (amortized) O(1) + /// hashing/comparisons operations, if `Element` implements high quality + /// hashing. + @inlinable + @discardableResult + public mutating func remove(_ member: Element) -> Element? { + let (idx, bucket) = _find(member) + guard let index = idx else { return nil } + return _removeExistingMember(at: index, in: bucket) + } +} + diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Operations.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Operations.swift new file mode 100644 index 00000000..9aac480d --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Operations.swift @@ -0,0 +1,582 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// `OrderedSet` does not directly conform to `SetAlgebra` because its definition +// of equality conflicts with `SetAlgebra` requirements. However, it still +// implements most `SetAlgebra` requirements (except `insert`, which is replaced +// by `append`). +// +// `OrderedSet` also provides an `unordered` view that explicitly conforms to +// `SetAlgebra`. That view implements `Equatable` by ignoring element order, +// so it can satisfy `SetAlgebra` requirements. + +extension OrderedSet { + /// Adds the elements of the given set to this set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the set, in the order they appear in `other`. + /// + /// var a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [0, 2, 4, 6] + /// a.formUnion(b) + /// // `a` is now `[1, 2, 3, 4, 0, 6]` + /// + /// - Parameter other: The set of elements to insert. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public mutating func formUnion(_ other: __owned Self) { + append(contentsOf: other) + } + + /// Returns a new set with the elements of both this and the given set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the result, in the order they appear in `other`. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [0, 2, 4, 6] + /// a.union(b) // [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: The set of elements to add. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + public __consuming func union(_ other: __owned Self) -> Self { + var result = self + result.formUnion(other) + return result + } + + // Generalizations + + /// Adds the elements of the given set to this set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the set, in the order they appear in `other`. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [0, 2, 4, 6] + /// a.formUnion(b.unordered) + /// // a is now [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: The set of elements to add. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public mutating func formUnion(_ other: __owned UnorderedView) { + formUnion(other._base) + } + + /// Returns a new set with the elements of both this and the given set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the result, in the order they appear in `other`. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [0, 2, 4, 6] + /// a.union(b.unordered) // [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: The set of elements to add. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public __consuming func union(_ other: __owned UnorderedView) -> Self { + union(other._base) + } + + /// Adds the elements of the given sequence to this set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the set, in the order they appear in `other`. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Array = [0, 2, 4, 6] + /// a.formUnion(b) + /// // a is now [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + public mutating func formUnion( + _ other: __owned S + ) where S.Element == Element { + append(contentsOf: other) + } + + /// Returns a new set with the elements of both this and the given set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the result, in the order they appear in `other`. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Array = [0, 2, 4, 6] + /// a.union(b) // [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + public __consuming func union( + _ other: __owned S + ) -> Self where S.Element == Element { + var result = self + result.formUnion(other) + return result + } +} + +extension OrderedSet { + /// Returns a new set with the elements that are common to both this set and + /// the provided other one, in the order they appear in `self`. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.intersection(other) // [2, 4] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public __consuming func intersection(_ other: Self) -> Self { + var result = Self() + for item in self { + if other.contains(item) { + result._appendNew(item) + } + } + return result + } + + /// Removes the elements of this set that aren't also in the given one. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.formIntersection(other) + /// // set is now [2, 4] + /// + /// - Parameter other: A set of elements. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public mutating func formIntersection(_ other: Self) { + self = self.intersection(other) + } + + // Generalizations + + /// Returns a new set with the elements that are common to both this set and + /// the provided other one, in the order they appear in `self`. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.intersection(other) // [2, 4] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + @inline(__always) + public __consuming func intersection(_ other: UnorderedView) -> Self { + intersection(other._base) + } + + /// Removes the elements of this set that aren't also in the given one. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.formIntersection(other) + /// // set is now [2, 4] + /// + /// - Parameter other: A set of elements. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + @inline(__always) + public mutating func formIntersection(_ other: UnorderedView) { + formIntersection(other._base) + } + + /// Returns a new set with the elements that are common to both this set and + /// the provided sequence, in the order they appear in `self`. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// set.intersection([6, 4, 2, 0] as Array) // [2, 4] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(*n*) on average where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public __consuming func intersection( + _ other: S + ) -> Self where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: self.count) { bitset in + for item in other { + if let index = self._find_inlined(item).index { + bitset.insert(index) + } + } + return self._extractSubset(using: bitset) + } + } + + /// Removes the elements of this set that aren't also in the given sequence. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// set.formIntersection([6, 4, 2, 0] as Array) + /// // set is now [2, 4] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(*n*) on average where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public mutating func formIntersection( + _ other: S + ) where S.Element == Element { + self = self.intersection(other) + } +} + +extension OrderedSet { + /// Returns a new set with the elements that are either in this set or in + /// `other`, but not in both. + /// + /// The result contains elements from `self` followed by elements in `other`, + /// in the same order they appeared in the original sets. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.symmetricDifference(other) // [1, 3, 6, 0] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public __consuming func symmetricDifference(_ other: __owned Self) -> Self { + _UnsafeBitset.withTemporaryBitset(capacity: self.count) { bitset1 in + _UnsafeBitset.withTemporaryBitset(capacity: other.count) { bitset2 in + bitset1.insertAll(upTo: self.count) + for item in other { + if let index = self._find(item).index { + bitset1.remove(index) + } + } + bitset2.insertAll(upTo: other.count) + for item in self { + if let index = other._find(item).index { + bitset2.remove(index) + } + } + var result = self._extractSubset(using: bitset1, + extraCapacity: bitset2.count) + for offset in bitset2 { + result._appendNew(other._elements[offset]) + } + return result + } + } + } + + /// Replace this set with the elements contained in this set or the given + /// set, but not both. + /// + /// On return, `self` contains elements originally from `self` followed by + /// elements in `other`, in the same order they appeared in the input values. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.formSymmetricDifference(other) + /// // set is now [1, 3, 6, 0] + /// + /// - Parameter other: Another set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public mutating func formSymmetricDifference(_ other: __owned Self) { + self = self.symmetricDifference(other) + } + + // Generalizations + + /// Returns a new set with the elements that are either in this set or in + /// `other`, but not in both. + /// + /// The result contains elements from `self` followed by elements in `other`, + /// in the same order they appeared in the original sets. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.symmetricDifference(other.unordered) // [1, 3, 6, 0] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public __consuming func symmetricDifference( + _ other: __owned UnorderedView + ) -> Self { + symmetricDifference(other._base) + } + + /// Replace this set with the elements contained in this set or the given + /// set, but not both. + /// + /// On return, `self` contains elements originally from `self` followed by + /// elements in `other`, in the same order they appeared in the input values. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.formSymmetricDifference(other.unordered) + /// // set is now [1, 3, 6, 0] + /// + /// - Parameter other: Another set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public mutating func formSymmetricDifference(_ other: __owned UnorderedView) { + formSymmetricDifference(other._base) + } + + /// Returns a new set with the elements that are either in this set or in + /// `other`, but not in both. + /// + /// The result contains elements from `self` followed by elements in `other`, + /// in the same order they appeared in the original input values. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: Array = [6, 4, 2, 0] + /// set.symmetricDifference(other) // [1, 3, 6, 0] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average where *n* is + /// the number of elements in `other`, if `Element` implements high-quality + /// hashing. + @inlinable + public __consuming func symmetricDifference( + _ other: __owned S + ) -> Self where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: self.count) { bitset in + var new = Self() + bitset.insertAll(upTo: self.count) + for item in other { + if let index = self._find(item).index { + bitset.remove(index) + } else { + new.append(item) + } + } + var result = _extractSubset(using: bitset, extraCapacity: new.count) + for item in new._elements { + result._appendNew(item) + } + return result + } + } + + /// Replace this set with the elements contained in this set or the given + /// sequence, but not both. + /// + /// On return, `self` contains elements originally from `self` followed by + /// elements in `other`, in the same order they first appeared in the input + /// values. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// set.formSymmetricDifference([6, 4, 2, 0] as Array) + /// // set is now [1, 3, 6, 0] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average where *n* is + /// the number of elements in `other`, if `Element` implements high-quality + /// hashing. + @inlinable + public mutating func formSymmetricDifference( + _ other: __owned S + ) where S.Element == Element { + self = self.symmetricDifference(other) + } +} + +extension OrderedSet { + /// Returns a new set containing the elements of this set that do not occur + /// in the given set. + /// + /// The result contains elements in the same order they appear in `self`. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.subtracting(other) // [1, 3] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public __consuming func subtracting(_ other: Self) -> Self { + _subtracting(other) + } + + /// Removes the elements of the given set from this set. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.subtract(other) + /// // set is now [1, 3] + /// + /// - Parameter other: Another set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public mutating func subtract(_ other: Self) { + self = subtracting(other) + } + + // Generalizations + + /// Returns a new set containing the elements of this set that do not occur + /// in the given set. + /// + /// The result contains elements in the same order they appear in `self`. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.subtracting(other.unordered) // [1, 3] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public __consuming func subtracting(_ other: UnorderedView) -> Self { + subtracting(other._base) + } + + /// Removes the elements of the given set from this set. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// let other: OrderedSet = [6, 4, 2, 0] + /// set.subtract(other.unordered) + /// // set is now [1, 3] + /// + /// - Parameter other: Another set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public mutating func subtract(_ other: UnorderedView) { + subtract(other._base) + } + + /// Returns a new set containing the elements of this set that do not occur + /// in the given sequence. + /// + /// The result contains elements in the same order they appear in `self`. + /// + /// let set: OrderedSet = [1, 2, 3, 4] + /// set.subtracting([6, 4, 2, 0] as Array) // [1, 3] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public __consuming func subtracting( + _ other: S + ) -> Self where S.Element == Element { + _subtracting(other) + } + + /// Removes the elements of the given sequence from this set. + /// + /// var set: OrderedSet = [1, 2, 3, 4] + /// set.subtract([6, 4, 2, 0] as Array) + /// // set is now [1, 3] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + @inline(__always) + public mutating func subtract( + _ other: S + ) where S.Element == Element { + self = _subtracting(other) + } + + @inlinable + __consuming func _subtracting( + _ other: S + ) -> Self where S.Element == Element { + guard count > 0 else { return Self() } + return _UnsafeBitset.withTemporaryBitset(capacity: count) { difference in + difference.insertAll(upTo: count) + for item in other { + if let index = self._find(item).index { + if difference.remove(index), difference.count == 0 { + return Self() + } + } + } + assert(difference.count > 0) + return _extractSubset(using: difference) + } + } +} + + diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Predicates.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Predicates.swift new file mode 100644 index 00000000..5aa94bb4 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Partial SetAlgebra+Predicates.swift @@ -0,0 +1,551 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// `OrderedSet` does not directly conform to `SetAlgebra` because its definition +// of equality conflicts with `SetAlgebra` requirements. However, it still +// implements most `SetAlgebra` requirements (except `insert`, which is replaced +// by `append`). +// +// `OrderedSet` also provides an `unordered` view that explicitly conforms to +// `SetAlgebra`. That view implements `Equatable` by ignoring element order, +// so it can satisfy `SetAlgebra` requirements. + +extension OrderedSet { + /// Returns a Boolean value that indicates whether this set is a subset of + /// the given set. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSubset(of other: Self) -> Bool { + guard other.count >= self.count else { return false } + for item in self { + guard other.contains(item) else { return false } + } + return true + } + + // Generalizations + + /// Returns a Boolean value that indicates whether this set is a subset of + /// the given set. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isSubset(of: a.unordered) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + @inline(__always) + public func isSubset(of other: UnorderedView) -> Bool { + isSubset(of: other._base) + } + + /// Returns a Boolean value that indicates whether this set is a subset of + /// the given set. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Set = [4, 2, 1] + /// b.isSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSubset(of other: Set) -> Bool { + guard other.count >= self.count else { return false } + for item in self { + guard other.contains(item) else { return false } + } + return true + } + + /// Returns a Boolean value that indicates whether this set is a subset of + /// the elements in the given sequence. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: Array = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isSubset(of: a) // true + /// + /// - Parameter other: A finite sequence. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public func isSubset( + of other: S + ) -> Bool where S.Element == Element { + guard !isEmpty else { return true } + return _UnsafeBitset.withTemporaryBitset(capacity: count) { seen in + // Mark elements in `self` that we've seen in `other`. + for item in other { + if let index = _find(item).index { + if seen.insert(index), seen.count == self.count { + // We've seen enough. + return true + } + } + } + return false + } + } +} + +extension OrderedSet { + /// Returns a Boolean value that indicates whether this set is a superset of + /// the given set. + /// + /// Set *A* is a superset of another set *B* if every member of *B* is also a + /// member of *A*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// a.isSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSuperset(of other: Self) -> Bool { + other.isSubset(of: self) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether this set is a superset of + /// the given set. + /// + /// Set *A* is a superset of another set *B* if every member of *B* is also a + /// member of *A*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Set = [4, 2, 1] + /// a.isSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSuperset(of other: UnorderedView) -> Bool { + isSuperset(of: other._base) + } + + @inlinable + public func isSuperset(of other: Set) -> Bool { + guard self.count >= other.count else { return false } + return _isSuperset(of: other) + } + + /// Returns a Boolean value that indicates whether this set is a superset of + /// the given sequence. + /// + /// Set *A* is a superset of another set *B* if every member of *B* is also a + /// member of *A*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Array = [4, 2, 1] + /// a.isSuperset(of: b) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public func isSuperset( + of other: S + ) -> Bool where S.Element == Element { + _isSuperset(of: other) + } + + @inlinable + internal func _isSuperset( + of other: S + ) -> Bool where S.Element == Element { + for item in other { + guard self.contains(item) else { return false } + } + return true + } +} + +extension OrderedSet { + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given set. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isStrictSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSubset(of other: Self) -> Bool { + self.count < other.count && self.isSubset(of: other) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given set. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isStrictSubset(of: a.unordered) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + @inline(__always) + public func isStrictSubset(of other: UnorderedView) -> Bool { + isStrictSubset(of: other._base) + } + + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given set. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: Set = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isStrictSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSubset(of other: Set) -> Bool { + self.count < other.count && self.isSubset(of: other) + } + + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given sequence. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: Array = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// b.isStrictSubset(of: a) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public func isStrictSubset( + of other: S + ) -> Bool where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: count) { seen in + // Mark elements in `self` that we've seen in `other`. + var isKnownStrict = false + for item in other { + if let index = _find(item).index { + if seen.insert(index), seen.count == self.count, isKnownStrict { + // We've seen enough. + return true + } + } else { + if !isKnownStrict, seen.count == self.count { return true } + isKnownStrict = true + } + } + return false + } + } +} + +extension OrderedSet { + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given set. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// a.isStrictSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSuperset(of other: Self) -> Bool { + self.count > other.count && other.isSubset(of: self) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given set. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [4, 2, 1] + /// a.isStrictSuperset(of: b.unordered) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + @inline(__always) + public func isStrictSuperset(of other: UnorderedView) -> Bool { + isStrictSuperset(of: other._base) + } + + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given set. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Set = [4, 2, 1] + /// a.isStrictSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSuperset(of other: Set) -> Bool { + self.count > other.count && other.isSubset(of: self) + } + + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given sequence. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Array = [4, 2, 1] + /// a.isStrictSuperset(of: b) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public func isStrictSuperset( + of other: S + ) -> Bool where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: count) { seen in + // Mark elements in `self` that we've seen in `other`. + for item in other { + guard let index = _find(item).index else { + return false + } + if seen.insert(index), seen.count == self.count { + // We've seen enough. + return false + } + } + return seen.count < self.count + } + } +} + +extension OrderedSet { + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given set. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [5, 6] + /// a.isDisjoint(with: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(min(`self.count`, `other.count`)) on + /// average, if `Element` implements high-quality hashing. + @inlinable + public func isDisjoint(with other: Self) -> Bool { + guard !self.isEmpty && !other.isEmpty else { return true } + if self.count <= other.count { + for item in self { + if other.contains(item) { return false } + } + } else { + for item in other { + if self.contains(item) { return false } + } + } + return true + } + + // Generalizations + + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given set. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: OrderedSet = [5, 6] + /// a.isDisjoint(with: b.unordered) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(min(`self.count`, `other.count`)) on + /// average, if `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public func isDisjoint(with other: UnorderedView) -> Bool { + isDisjoint(with: other._base) + } + + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given set. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Set = [5, 6] + /// a.isDisjoint(with: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(min(`self.count`, `other.count`)) on + /// average, if `Element` implements high-quality hashing. + @inlinable + public func isDisjoint(with other: Set) -> Bool { + guard !self.isEmpty && !other.isEmpty else { return true } + if self.count <= other.count { + for item in self { + if other.contains(item) { return false } + } + } else { + for item in other { + if self.contains(item) { return false } + } + } + return true + } + + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given sequence. + /// + /// let a: OrderedSet = [1, 2, 3, 4] + /// let b: Array = [5, 6] + /// a.isDisjoint(with: b) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public func isDisjoint( + with other: S + ) -> Bool where S.Element == Element { + guard !self.isEmpty else { return true } + for item in other { + if self.contains(item) { return false } + } + return true + } +} + diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+RandomAccessCollection.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+RandomAccessCollection.swift new file mode 100644 index 00000000..ac7e1e65 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+RandomAccessCollection.swift @@ -0,0 +1,253 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: RandomAccessCollection { + /// The index type for ordered sets, `Int`. + /// + /// `OrderedSet` indices are integer offsets from the start of the collection, + /// starting at zero for the first element (if exists). + public typealias Index = Int + + /// The type that represents the indices that are valid for subscripting an + /// ordered set, in ascending order. + public typealias Indices = Range + + // For SubSequence, see OrderedSet+SubSequence.swift. + + /// The position of the first element in a nonempty ordered set. + /// + /// For an instance of `OrderedSet`, `startIndex` is always zero. If the set + /// is empty, `startIndex` is equal to `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var startIndex: Index { _elements.startIndex } + + /// The set's "past the end" position---that is, the position one greater + /// than the last valid subscript argument. + /// + /// In an `OrderedSet`, `endIndex` always equals the count of elements. + /// If the set is empty, `endIndex` is equal to `startIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var endIndex: Index { _elements.endIndex } + + /// The indices that are valid for subscripting the collection, in ascending + /// order. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var indices: Indices { _elements.indices } + + /// Returns the position immediately after the given index. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately after `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(after i: Index) -> Index { i + 1 } + + /// Returns the position immediately before the given index. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately before `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(before i: Index) -> Index { i - 1 } + + /// Replaces the given index with its successor. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(after i: inout Index) { i += 1 } + + /// Replaces the given index with its predecessor. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(before i: inout Index) { i -= 1 } + + /// Returns an index that is the specified distance from the given index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, or the returned value will not be a valid index. + /// + /// - Parameters: + /// - i: A valid index of the set. + /// - distance: The distance to offset `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`. If `distance` + /// is positive, this is the same value as the result of `distance` calls to + /// `index(after:)`. If `distance` is negative, this is the same value as + /// the result of `abs(distance)` calls to `index(before:)`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(_ i: Index, offsetBy distance: Int) -> Index { + i + distance + } + + /// Returns an index that is the specified distance from the given index, + /// unless that distance is beyond a given limiting index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, unless the index passed as `limit` prevents offsetting + /// beyond those bounds. (Otherwise the returned value won't be a valid index + /// in the set.) + /// + /// - Parameters: + /// - i: A valid index of the set. + /// - distance: The distance to offset `i`. + /// - limit: A valid index of the collection to use as a limit. If + /// `distance > 0`, `limit` has no effect if it is less than `i`. + /// Likewise, if `distance < 0`, `limit` has no effect if it is greater + /// than `i`. + /// - Returns: An index offset by `distance` from the index `i`, unless that + /// index would be beyond `limit` in the direction of movement. In that + /// case, the method returns `nil`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index( + _ i: Index, + offsetBy distance: Int, + limitedBy limit: Index + ) -> Index? { + _elements.index(i, offsetBy: distance, limitedBy: limit) + } + + /// Returns the distance between two indices. + /// + /// - Parameters: + /// - start: A valid index of the collection. + /// - end: Another valid index of the collection. If `end` is equal to + /// `start`, the result is zero. + /// + /// - Returns: The distance between `start` and `end`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func distance(from start: Index, to end: Index) -> Int { + end - start + } + + /// Accesses the element at the specified position. + /// + /// - Parameter index: The position of the element to access. `index` must be + /// greater than or equal to `startIndex` and less than `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public subscript(position: Index) -> Element { + _elements[position] + } + + /// Accesses a contiguous subrange of the set's elements. + /// + /// The returned `Subsequence` instance uses the same indices for the same + /// elements as the original set. In particular, that slice, unlike an + /// `OrderedSet`, may have a nonzero `startIndex` and an `endIndex` that is + /// not equal to `count`. Always use the slice's `startIndex` and `endIndex` + /// properties instead of assuming that its indices start or end at a + /// particular value. + /// + /// - Parameter bounds: A range of valid indices in the set. + /// + /// - Complexity: O(1) + @inlinable + public subscript(bounds: Range) -> SubSequence { + _failEarlyRangeCheck(bounds, bounds: startIndex ..< endIndex) + return SubSequence(base: self, bounds: bounds) + } + + /// A Boolean value indicating whether the collection is empty. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var isEmpty: Bool { _elements.isEmpty } + + /// The number of elements in the set. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var count: Int { _elements.count } + + @inlinable + public func _customIndexOfEquatableElement(_ element: Element) -> Index?? { + guard let table = _table else { + return _elements._customIndexOfEquatableElement(element) + } + return table.read { hashTable in + let (o, _) = hashTable._find(element, in: _elements) + guard let offset = o else { return .some(nil) } + return offset + } + } + + @inlinable + @inline(__always) + public func _customLastIndexOfEquatableElement(_ element: Element) -> Index?? { + // OrderedSet holds unique elements. + _customIndexOfEquatableElement(element) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ index: Index, bounds: Range) { + _elements._failEarlyRangeCheck(index, bounds: bounds) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ index: Index, bounds: ClosedRange) { + _elements._failEarlyRangeCheck(index, bounds: bounds) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ range: Range, bounds: Range) { + _elements._failEarlyRangeCheck(range, bounds: bounds) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+ReserveCapacity.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+ReserveCapacity.swift new file mode 100644 index 00000000..908a1a80 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+ReserveCapacity.swift @@ -0,0 +1,132 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet { + /// Creates an empty set with preallocated space for at least the + /// specified number of elements. + /// + /// Use this initializer to avoid intermediate reallocations of a + /// set's storage buffer when you know in advance how many elements + /// you'll insert into the set after creation. + /// + /// If you have a good idea of the expected working size of the set, calling + /// this initializer with `persistent` set to true can sometimes improve + /// performance by eliminating churn due to repeated rehashings when the set + /// temporarily shrinks below its regular size. You can cancel any capacity + /// you've previously reserved by persistently reserving a capacity of zero. + /// (This also shrinks the hash table to the ideal size for its current number + /// elements.) + /// + /// - Parameter minimumCapacity: The minimum number of elements that the newly + /// created set should be able to store without reallocating its storage. + /// + /// - Parameter persistent: If set to true, prevent removals from shrinking + /// storage below the specified capacity. By default, removals are allowed + /// to shrink storage below any previously reserved capacity. + /// + /// - Complexity: O(`minimumCapacity`) + @inlinable + public init(minimumCapacity: Int, persistent: Bool = false) { + self.init() + self._reserveCapacity(minimumCapacity, persistent: persistent) + } +} + +extension OrderedSet { + /// Reserves enough space to store the specified number of elements. + /// + /// This method ensures that the set has unique mutable storage, with space + /// allocated for at least the requested number of elements. + /// + /// If you are adding a known number of elements to a set, call this method + /// once before the first insertion to avoid multiple reallocations. + /// + /// Do not call this method in a loop -- it does not use an exponential + /// allocation strategy, so doing that can result in quadratic instead of + /// linear performance. + /// + /// - Parameter minimumCapacity: The minimum number of elements that the set + /// should be able to store without reallocating its storage. + /// + /// - Complexity: O(`max(count, minimumCapacity)`) + @inlinable + public mutating func reserveCapacity(_ minimumCapacity: Int) { + self._reserveCapacity(minimumCapacity, persistent: false) + } +} + +extension OrderedSet { + /// Reserves enough space to store the specified number of elements. + /// + /// This method ensures that the set has unique mutable storage, with space + /// allocated for at least the requested number of elements. + /// + /// If you are adding a known number of elements to a set, call this method + /// once before the first insertion to avoid multiple reallocations. + /// + /// Do not call this method in a loop -- it does not use an exponential + /// allocation strategy, so doing that can result in quadratic instead of + /// linear performance. + /// + /// If you have a good idea of the expected working size of the set, calling + /// this method with `persistent` set to true can sometimes improve + /// performance by eliminating churn due to repeated rehashings when the set + /// temporarily shrinks below its regular size. You can cancel any capacity + /// you've previously reserved by persistently reserving a capacity of zero. + /// (This also shrinks the hash table to the ideal size for its current number + /// elements.) + /// + /// - Parameter minimumCapacity: The minimum number of elements that the set + /// should be able to store without reallocating its storage. + /// + /// - Parameter persistent: If set to true, prevent removals from shrinking + /// storage below the specified capacity. By default, removals are allowed + /// to shrink storage below any previously reserved capacity. + /// + /// - Complexity: O(`max(count, minimumCapacity)`) + @inlinable + internal mutating func _reserveCapacity( + _ minimumCapacity: Int, + persistent: Bool + ) { + precondition(minimumCapacity >= 0, "Minimum capacity cannot be negative") + defer { _checkInvariants() } + + _elements.reserveCapacity(minimumCapacity) + + let currentScale = _scale + let newScale = _HashTable.scale(forCapacity: minimumCapacity) + + let reservedScale = persistent ? newScale : _reservedScale + + if currentScale < newScale { + // Grow the table. + _regenerateHashTable(scale: newScale, reservedScale: reservedScale) + return + } + + let requiredScale = _HashTable.scale(forCapacity: self.count) + let minScale = Swift.max(Swift.max(newScale, reservedScale), requiredScale) + if minScale < currentScale { + // Shrink the table. + _regenerateHashTable(scale: minScale, reservedScale: reservedScale) + return + } + + // When we have the right size table, ensure it's unique and it has the + // right persisted reservation. + _ensureUnique() + if _reservedScale != reservedScale { + // Remember reserved scale. + __storage!.header.reservedScale = reservedScale + } + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Sequence.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Sequence.swift new file mode 100644 index 00000000..663c6706 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Sequence.swift @@ -0,0 +1,57 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet: Sequence { + /// The type that allows iteration over an ordered set's elements. + public typealias Iterator = IndexingIterator + + @inlinable + public func _customContainsEquatableElement(_ element: Element) -> Bool? { + _find(element).index != nil + } + + @inlinable + public __consuming func _copyToContiguousArray() -> ContiguousArray { + _elements._copyToContiguousArray() + } + + @inlinable + public __consuming func _copyContents( + initializing ptr: UnsafeMutableBufferPointer + ) -> (Iterator, UnsafeMutableBufferPointer.Index) { + guard !isEmpty else { return (makeIterator(), 0) } + let copied: Int = _elements.withUnsafeBufferPointer { buffer in + guard let p = ptr.baseAddress else { + preconditionFailure("Attempt to copy contents into nil buffer pointer") + } + let c = Swift.min(buffer.count, ptr.count) + p.initialize(from: buffer.baseAddress!, count: c) + return c + } + return (Iterator(_elements: self, _position: copied), copied) + } + + /// Call `body(p)`, where `p` is a buffer pointer to the collection’s + /// contiguous storage. Ordered sets always have contiguous storage. + /// + /// - Parameter body: A function to call. The function must not escape its + /// unsafe buffer pointer argument. + /// + /// - Returns: The value returned by `body`. + /// + /// - Complexity: O(1) (ignoring time spent in `body`) + @inlinable + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + try _elements.withContiguousStorageIfAvailable(body) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+SubSequence.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+SubSequence.swift new file mode 100644 index 00000000..14d6ab03 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+SubSequence.swift @@ -0,0 +1,355 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet { + /// A collection that represents a contiguous slice of an ordered set. + /// + /// Ordered set slices are random access collections that support efficient + /// membership testing. `contains(_:)` and `firstIndex(of:)`/`lastIndex(of:)` + /// are expected to have a complexity of O(1), as long as `Element` has + /// high-quality hashing. + @frozen + public struct SubSequence { + @usableFromInline + internal var _base: OrderedSet + + @usableFromInline + internal var _bounds: Range + + @inlinable + @inline(__always) + internal init(base: OrderedSet, bounds: Range) { + self._base = base + self._bounds = bounds + } + } +} + +extension OrderedSet.SubSequence { + @inlinable + internal var _slice: Array.SubSequence { + _base._elements[_bounds] + } + + @inlinable + internal func _index(of element: Element) -> Index? { + guard let index = _base._find(element).index else { return nil } + guard _bounds.contains(index) else { return nil } + return index + } +} + +extension OrderedSet.SubSequence: Sequence { + // A type representing the collection’s elements. + public typealias Element = OrderedSet.Element + /// The type that allows iteration over the collection's elements. + public typealias Iterator = IndexingIterator + + @inlinable + public func _customContainsEquatableElement(_ element: Element) -> Bool? { + _index(of: element) != nil + } + + @inlinable + public __consuming func _copyToContiguousArray() -> ContiguousArray { + _slice._copyToContiguousArray() + } + + @inlinable + public __consuming func _copyContents( + initializing ptr: UnsafeMutableBufferPointer + ) -> (Iterator, UnsafeMutableBufferPointer.Index) { + guard !isEmpty else { return (makeIterator(), 0) } + let copied: Int = _slice.withUnsafeBufferPointer { buffer in + guard let p = ptr.baseAddress else { + preconditionFailure("Attempt to copy contents into nil buffer pointer") + } + let c = Swift.min(buffer.count, ptr.count) + if c > 0 { + p.initialize(from: buffer.baseAddress!, count: c) + } + return c + } + return (Iterator(_elements: self, _position: _bounds.lowerBound + copied), + copied) + } + + /// Call `body(p)`, where `p` is a buffer pointer to the collection’s + /// contiguous storage. Ordered sets always have contiguous storage. + /// + /// - Parameter body: A function to call. The function must not escape its + /// unsafe buffer pointer argument. + /// + /// - Returns: The value returned by `body`. + /// + /// - Complexity: O(1) (ignoring time spent in `body`) + @inlinable + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + try _slice.withContiguousStorageIfAvailable(body) + } +} + +extension OrderedSet.SubSequence: RandomAccessCollection { + /// The index type for ordered sets, `Int`. + /// + /// Indices in the order set are integer offsets from the start of the + /// collection, starting at zero for the first element (if exists). + public typealias Index = Int + + /// The type that represents the indices that are valid for subscripting an + /// ordered set, in ascending order. + public typealias Indices = Array.SubSequence.Indices + + /// Ordered set subsequences are self-slicing. + public typealias SubSequence = Self + + /// The position of the first element in a nonempty ordered set slice. + /// + /// Note that instances of `OrderedSet.SubSequence` generally aren't indexed + /// from zero. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var startIndex: Index { _bounds.lowerBound } + + /// The "past the end" position---that is, the position one greater + /// than the last valid subscript argument. + /// + /// Note that instances of `OrderedSet.SubSequence` generally aren't indexed + /// from zero, so `endIndex` may differ from the `count`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var endIndex: Index { _bounds.upperBound } + + /// The indices that are valid for subscripting the collection, in ascending + /// order. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var indices: Indices { _slice.indices } + + /// Returns the position immediately after the given index. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately after `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(after i: Index) -> Index { i + 1 } + + /// Returns the position immediately before the given index. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Returns: The index immediately before `i`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(before i: Index) -> Index { i - 1 } + + /// Replaces the given index with its successor. + /// + /// The specified index must be a valid index less than `endIndex`, or the + /// returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(after i: inout Index) { i += 1 } + + /// Replaces the given index with its predecessor. + /// + /// The specified index must be a valid index greater than `startIndex`, or + /// the returned value won't be a valid index in the set. + /// + /// - Parameter i: A valid index of the collection. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func formIndex(before i: inout Index) { i -= 1 } + + /// Returns an index that is the specified distance from the given index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, or the returned value will not be a valid index. + /// + /// - Parameters: + /// - i: A valid index of the set. + /// - distance: The distance to offset `i`. + /// + /// - Returns: An index offset by `distance` from the index `i`. If `distance` + /// is positive, this is the same value as the result of `distance` calls to + /// `index(after:)`. If `distance` is negative, this is the same value as + /// the result of `abs(distance)` calls to `index(before:)`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index(_ i: Index, offsetBy distance: Int) -> Index { + i + distance + } + + /// Returns an index that is the specified distance from the given index, + /// unless that distance is beyond a given limiting index. + /// + /// The value passed as `distance` must not offset `i` beyond the bounds of + /// the collection, unless the index passed as `limit` prevents offsetting + /// beyond those bounds. (Otherwise the returned value won't be a valid index + /// in the set.) + /// + /// - Parameters: + /// - i: A valid index of the set. + /// - distance: The distance to offset `i`. + /// - limit: A valid index of the collection to use as a limit. If + /// `distance > 0`, `limit` has no effect if it is less than `i`. + /// Likewise, if `distance < 0`, `limit` has no effect if it is greater + /// than `i`. + /// - Returns: An index offset by `distance` from the index `i`, unless that + /// index would be beyond `limit` in the direction of movement. In that + /// case, the method returns `nil`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func index( + _ i: Index, + offsetBy distance: Int, + limitedBy limit: Index + ) -> Index? { + _slice.index(i, offsetBy: distance, limitedBy: limit) + } + + /// Returns the distance between two indices. + /// + /// - Parameters: + /// - start: A valid index of the collection. + /// - end: Another valid index of the collection. If `end` is equal to + /// `start`, the result is zero. + /// + /// - Returns: The distance between `start` and `end`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public func distance(from start: Index, to end: Index) -> Int { + end - start + } + + /// Accesses the element at the specified position. + /// + /// - Parameter index: The position of the element to access. `index` must be + /// greater than or equal to `startIndex` and less than `endIndex`. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public subscript(position: Index) -> Element { + _slice[position] + } + + /// Accesses a contiguous subrange of the set's elements. + /// + /// The returned `Subsequence` instance uses the same indices for the same + /// elements as the original set. In particular, that slice, unlike an + /// `OrderedSet`, may have a nonzero `startIndex` and an `endIndex` that is + /// not equal to `count`. Always use the slice's `startIndex` and `endIndex` + /// properties instead of assuming that its indices start or end at a + /// particular value. + /// + /// - Parameter bounds: A range of valid indices in the set. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public subscript(bounds: Range) -> SubSequence { + _failEarlyRangeCheck(bounds, bounds: startIndex ..< endIndex) + return SubSequence(base: _base, bounds: bounds) + } + + /// A Boolean value indicating whether the collection is empty. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var isEmpty: Bool { _bounds.isEmpty } + + /// The number of elements in the set. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public var count: Int { _bounds.count } + + @inlinable + @inline(__always) + public func _customIndexOfEquatableElement(_ element: Element) -> Index?? { + .some(_index(of: element)) + } + + @inlinable + @inline(__always) + public func _customLastIndexOfEquatableElement(_ element: Element) -> Index?? { + .some(_index(of: element)) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ index: Index, bounds: Range) { + _slice._failEarlyRangeCheck(index, bounds: bounds) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ index: Index, bounds: ClosedRange) { + _slice._failEarlyRangeCheck(index, bounds: bounds) + } + + @inlinable + @inline(__always) + public func _failEarlyRangeCheck(_ range: Range, bounds: Range) { + _slice._failEarlyRangeCheck(range, bounds: bounds) + } +} + +extension OrderedSet.SubSequence: Equatable { + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + left.elementsEqual(right) + } +} + +extension OrderedSet.SubSequence: Hashable { + @inlinable + public func hash(into hasher: inout Hasher) { + hasher.combine(count) + for item in self { + hasher.combine(item) + } + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+Testing.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+Testing.swift new file mode 100644 index 00000000..2b87dfad --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+Testing.swift @@ -0,0 +1,125 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet._UnstableInternals { + @_spi(Testing) public var capacity: Int { base._capacity } + @_spi(Testing) public var minimumCapacity: Int { base._minimumCapacity } + @_spi(Testing) public var scale: Int { base._scale } + @_spi(Testing) public var reservedScale: Int { base._reservedScale } + @_spi(Testing) public var bias: Int { base._bias } +} + +extension OrderedSet { + @_spi(Testing) + @_alwaysEmitIntoClient + public static var _minimumScale: Int { + _HashTable.minimumScale + } + + @_spi(Testing) + @_alwaysEmitIntoClient + public static func _minimumCapacity(forScale scale: Int) -> Int { + _HashTable.minimumCapacity(forScale: scale) + } + + @_spi(Testing) + @_alwaysEmitIntoClient + public static func _maximumCapacity(forScale scale: Int) -> Int { + _HashTable.maximumCapacity(forScale: scale) + } + + @_spi(Testing) + @_alwaysEmitIntoClient + public static func _scale(forCapacity capacity: Int) -> Int { + _HashTable.scale(forCapacity: capacity) + } + + @_spi(Testing) + @_alwaysEmitIntoClient + public static func _biasRange(scale: Int) -> Range { + guard scale != 0 else { return Range(uncheckedBounds: (0, 1)) } + return Range(uncheckedBounds: (0, (1 &<< scale) - 1)) + } +} + +extension OrderedSet._UnstableInternals { + @_spi(Testing) + @_alwaysEmitIntoClient + public var hasHashTable: Bool { base._table != nil } + + @_spi(Testing) + @_alwaysEmitIntoClient + public var hashTableIdentity: ObjectIdentifier? { + guard let storage = base.__storage else { return nil } + return ObjectIdentifier(storage) + } + + @_spi(Testing) + public var hashTableContents: [Int?] { + guard let table = base._table else { return [] } + return table.read { hashTable in + hashTable.debugContents() + } + } + + @_spi(Testing) + @_alwaysEmitIntoClient + mutating public func _regenerateHashTable(bias: Int) { + base._ensureUnique() + let new = base._table!.copy() + base._table!.read { source in + new.update { target in + target.bias = bias + var it = source.bucketIterator(startingAt: _Bucket(offset: 0)) + repeat { + target[it.currentBucket] = it.currentValue + it.advance() + } while it.currentBucket.offset != 0 + } + } + base._table = new + } + + @_spi(Testing) + @_alwaysEmitIntoClient + public mutating func reserveCapacity( + _ minimumCapacity: Int, + persistent: Bool + ) { + base._reserveCapacity(minimumCapacity, persistent: persistent) + } +} + +extension OrderedSet { + @_spi(Testing) + public init( + _scale scale: Int, + bias: Int, + contents: S + ) where S.Element == Element { + let contents = ContiguousArray(contents) + precondition(scale >= _HashTable.scale(forCapacity: contents.count)) + precondition(scale <= _HashTable.maximumScale) + precondition(bias >= 0 && Self._biasRange(scale: scale).contains(bias)) + precondition(scale >= _HashTable.minimumScale || bias == 0) + let table = _HashTable(scale: Swift.max(scale, _HashTable.minimumScale)) + table.header.bias = bias + let (success, index) = table.update { hashTable in + hashTable.fill(untilFirstDuplicateIn: contents) + } + precondition(success, "Duplicate element at index \(index)") + self.init( + _uniqueElements: contents, + scale < _HashTable.minimumScale ? nil : table) + precondition(self._scale == scale) + precondition(self._bias == bias) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+UnorderedView.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+UnorderedView.swift new file mode 100644 index 00000000..cc679d43 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+UnorderedView.swift @@ -0,0 +1,986 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet { + /// An unordered view into an ordered set, providing `SetAlgebra` + /// conformance. + public struct UnorderedView { + public typealias Element = OrderedSet.Element + + @usableFromInline + internal var _base: OrderedSet + + @inlinable + @inline(__always) + internal init(_base: OrderedSet) { + self._base = _base + } + } + + /// Create a new ordered set with the same members as the supplied + /// unordered view. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public init(_ view: UnorderedView) { + self = view._base + } + + /// Access a view of the members of this set as an unordered + /// `SetAlgebra` value. + /// + /// This is useful when you need to pass an ordered set to a + /// function that is generic over `SetAlgebra`. + /// + /// The unordered view has a definition of equality that ignores the + /// order of members, so that it can satisfy `SetAlgebra` + /// requirements. New elements inserted to the unordered view get + /// appended to the end of the set. + /// + /// - Complexity: O(1) for both the getter and the setter. + @inlinable + public var unordered: UnorderedView { + @inline(__always) + get { + UnorderedView(_base: self) + } + @inline(__always) + _modify { + var view = UnorderedView(_base: self) + self = OrderedSet() + defer { self = view._base } + yield &view + } + } +} + +extension OrderedSet.UnorderedView: CustomStringConvertible { + /// A textual representation of this instance. + public var description: String { + _base.description + } +} + +extension OrderedSet.UnorderedView: CustomDebugStringConvertible { + /// A textual representation of this instance, suitable for debugging. + public var debugDescription: String { + _base._debugDescription(typeName: "\(_base._debugTypeName()).UnorderedView") + } +} + +extension OrderedSet.UnorderedView: CustomReflectable { + /// The custom mirror for this instance. + public var customMirror: Mirror { + Mirror(self, unlabeledChildren: _base._elements, displayStyle: .collection) + } +} + +extension OrderedSet.UnorderedView: Equatable { + /// Returns a Boolean value indicating whether two values are equal. + /// Two unordered sets are considered equal if they contain the same + /// elements, but not necessarily in the same order. + /// + /// - Complexity: O(`min(left.count, right.count)`) + @inlinable + public static func ==(left: Self, right: Self) -> Bool { + if left._base.__storage != nil, + left._base.__storage === right._base.__storage + { + return true + } + guard left._base.count == right._base.count else { return false } + + for item in left._base { + if !right._base.contains(item) { return false } + } + return true + } +} + +extension OrderedSet.UnorderedView: Hashable { + /// Hashes the essential components of this value by feeding them into the + /// given hasher. + /// + /// Complexity: O(`count`) + @inlinable + public func hash(into hasher: inout Hasher) { + // Generate a seed from a snapshot of the hasher. This makes members' hash + // values depend on the state of the hasher, which improves hashing + // quality. (E.g., it makes it possible to resolve collisions by passing in + // a different hasher.) + let copy = hasher + let seed = copy.finalize() + + var hash = 0 + for member in _base { + hash ^= member._rawHashValue(seed: seed) + } + hasher.combine(hash) + } +} + +extension OrderedSet.UnorderedView: ExpressibleByArrayLiteral { + /// Creates a new unordered set from the contents of an array literal. + @inlinable + @inline(__always) + public init(arrayLiteral elements: Element...) { + _base = OrderedSet(elements) + } +} + +extension OrderedSet.UnorderedView: SetAlgebra {} + +extension OrderedSet.UnorderedView { + /// Creates an empty set. + /// + /// This initializer is equivalent to initializing with an empty array + /// literal. + @inlinable + @inline(__always) + public init() { + _base = OrderedSet() + } + + /// Creates a new set from a finite sequence of items. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform O(*n*) + /// comparisons on average (where *n* is the number of elements + /// in the sequence), provided that `Element` implements + /// high-quality hashing. + @inlinable + @inline(__always) + public init(_ elements: S) where S.Element == Element { + _base = OrderedSet(elements) + } + + // Specializations + + /// Creates a new set from a an existing set. This is functionally the same as + /// copying the value of `elements` into a new variable. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: O(1) + @inlinable + @inline(__always) + public init(_ elements: Self) { + self = elements + } + + /// Creates a new set from an existing `Set` value. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform O(*n*) + /// comparisons on average (where *n* is the number of elements + /// in the set), provided that `Element` implements high-quality + /// hashing. + @inlinable + @inline(__always) + public init(_ elements: Set) { + self._base = OrderedSet(elements) + } + + /// Creates a new set from the keys of a dictionary value. + /// + /// - Parameter elements: The elements to use as members of the new set. + /// + /// - Complexity: This operation is expected to perform O(*n*) + /// comparisons on average (where *n* is the number of elements + /// in the set), provided that `Element` implements high-quality + /// hashing. + @inlinable + @inline(__always) + public init(_ elements: Dictionary.Keys) { + self._base = OrderedSet(elements) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a Boolean value that indicates whether the given element exists + /// in the set. + /// + /// - Parameter element: An element to look for in the set. + /// + /// - Returns: `true` if `member` exists in the set; otherwise, `false`. + /// + /// - Complexity: This operation is expected to perform O(1) comparisons on + /// average, provided that `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public func contains(_ element: Element) -> Bool { + _base.contains(element) + } +} + +extension OrderedSet.UnorderedView { + /// Inserts the given element in the set if it is not already present. + /// + /// If an element equal to `newMember` is already contained in the set, this + /// method has no effect. + /// + /// If `newMember` was not already a member, it gets appended to the end of + /// the underlying ordered set value. + /// + /// - Parameter newMember: An element to insert into the set. + /// + /// - Returns: `(true, newMember)` if `newMember` was not contained in the + /// set. If an element equal to `newMember` was already contained in the + /// set, the method returns `(false, oldMember)`, where `oldMember` is the + /// element that was equal to `newMember`. In some cases, `oldMember` may + /// be distinguishable from `newMember` by identity comparison or some + /// other means. + /// + /// - Complexity: This operation is expected to perform O(1) + /// hashing/comparison operations on average (over many insertions to the + /// same set), provided that `Element` implements high-quality hashing. + @inlinable + public mutating func insert( + _ newMember: __owned Element + ) -> (inserted: Bool, memberAfterInsert: Element) { + let (inserted, index) = _base.append(newMember) + return (inserted, _base[index]) + } + + /// Inserts the given element into the set unconditionally. + /// + /// If an element equal to `newMember` is already contained in the set, + /// `newMember` replaces the existing element. + /// + /// If `newMember` was not already a member, it gets appended to the end of + /// the underlying ordered set value. + /// + /// - Parameter newMember: An element to insert into the set. + /// + /// - Returns: The original member equal to `newMember` if the set already + /// contained such a member; otherwise, `nil`. In some cases, the returned + /// element may be distinguishable from `newMember` by identity comparison + /// or some other means. + /// + /// - Complexity: This operation is expected to perform O(1) + /// hashing/comparison operations on average (over many insertions to the + /// same set), provided that `Element` implements high-quality hashing. + @inlinable + public mutating func update(with newMember: __owned Element) -> Element? { + let (inserted, index) = _base.append(newMember) + if inserted { return nil } + let old = _base._elements[index] + _base._elements[index] = newMember + return old + } +} + +extension OrderedSet.UnorderedView { + /// Removes the given element from the set. + /// + /// - Parameter member: The element of the set to remove. + /// + /// - Returns: The element equal to `member` if `member` is contained in the + /// set; otherwise, `nil`. In some cases, the returned element may be + /// distinguishable from `newMember` by identity comparison or some other + /// means. + /// + /// - Complexity: O(`count`). Removing an element from the middle of the + /// underlying ordered set needs to rearrange the remaining elements to + /// close the resulting gap. + /// + /// Removing the last element only takes (amortized) O(1) + /// hashing/comparisons operations, if `Element` implements high quality + /// hashing. + @inlinable + @inline(__always) + @discardableResult + public mutating func remove(_ member: Self.Element) -> Self.Element? { + _base.remove(member) + } +} + +extension OrderedSet.UnorderedView { + /// Adds the elements of the given set to this set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the set, in the order they appear in `other`. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [0, 2, 4, 6] + /// set.formUnion(other) + /// // `set` is now `[1, 2, 3, 4, 0, 6]` + /// + /// - Parameter other: The set of elements to insert. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + @inline(__always) + public mutating func formUnion(_ other: __owned Self) { + _base.formUnion(other._base) + } + + /// Returns a new set with the elements of both this and the given set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the result, in the order they appear in `other`. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [0, 2, 4, 6] + /// a.union(b) // [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: The set of elements to add. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + public __consuming func union(_ other: __owned Self) -> Self { + _base.union(other._base).unordered + } + + // Generalizations + + /// Adds the elements of the given sequence to this set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the set, in the order they appear in `other`. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.formUnion([0, 2, 4, 6]) + /// // `set` is now `[1, 2, 3, 4, 0, 6]` + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public mutating func formUnion( + _ other: __owned S + ) where S.Element == Element { + _base.formUnion(other) + } + + /// Returns a new set with the elements of both this and the given set. + /// + /// Members of `other` that aren't already in `self` get appended to the end + /// of the result, in the order they appear in `other`. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// a.union([0, 2, 4, 6]) // [1, 2, 3, 4, 0, 6] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + `other.count`) on average, + /// if `Element` implements high-quality hashing. + @inlinable + public __consuming func union( + _ other: __owned S + ) -> Self where S.Element == Element { + _base.union(other).unordered + } +} + +extension OrderedSet.UnorderedView { + /// Returns a new set with the elements that are common to both this set and + /// the provided other one, in the order they appear in `self`. + /// + /// let set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [6, 4, 2, 0] + /// set.intersection(other) // [2, 4] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public __consuming func intersection(_ other: Self) -> Self { + _base.intersection(other._base).unordered + } + + /// Removes the elements of this set that aren't also in the given one. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [6, 4, 2, 0] + /// set.formIntersection(other) + /// // set is now [2, 4] + /// + /// - Parameter other: A set of elements. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public mutating func formIntersection(_ other: Self) { + _base.formIntersection(other._base) + } + + // Generalizations + + /// Returns a new set with the elements that are common to both this set and + /// the provided sequence, in the order they appear in `self`. + /// + /// let set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.intersection([6, 4, 2, 0] as Array) // [2, 4] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(*n*) on average where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public __consuming func intersection( + _ other: S + ) -> Self where S.Element == Element { + _base.intersection(other).unordered + } + + /// Removes the elements of this set that aren't also in the given sequence. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.formIntersection([6, 4, 2, 0] as Array) + /// // set is now [2, 4] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(*n*) on average where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public mutating func formIntersection( + _ other: S + ) where S.Element == Element { + _base.formIntersection(other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a new set with the elements that are either in this set or in + /// `other`, but not in both. + /// + /// The result contains elements from `self` followed by elements in `other`, + /// in the same order they appeared in the original sets. + /// + /// let set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [6, 4, 2, 0] + /// set.symmetricDifference(other) // [1, 3, 6, 0] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public __consuming func symmetricDifference(_ other: __owned Self) -> Self { + _base.symmetricDifference(other._base).unordered + } + + /// Replace this set with the elements contained in this set or the given + /// set, but not both. + /// + /// On return, `self` contains elements originally from `self` followed by + /// elements in `other`, in the same order they appeared in the input values. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [6, 4, 2, 0] + /// set.formSymmetricDifference(other) + /// // set is now [1, 3, 6, 0] + /// + /// - Parameter other: Another set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public mutating func formSymmetricDifference(_ other: __owned Self) { + _base.formSymmetricDifference(other._base) + } + + // Generalizations + + /// Returns a new set with the elements that are either in this set or in the + /// given sequence, but not in both. + /// + /// The result contains elements from `self` followed by elements in `other`, + /// in the same order they first appeared in the input values. + /// + /// let set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.symmetricDifference([6, 4, 2, 0] as Array) // [1, 3, 6, 0] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average where *n* is + /// the number of elements in `other`, if `Element` implements high-quality + /// hashing. + @inlinable + public __consuming func symmetricDifference( + _ other: __owned S + ) -> Self where S.Element == Element { + _base.symmetricDifference(other).unordered + } + + /// Replace this set with the elements contained in this set or the given + /// sequence, but not both. + /// + /// On return, `self` contains elements originally from `self` followed by + /// elements in `other`, in the same order they first appeared in the input + /// values. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.formSymmetricDifference([6, 4, 2, 0] as Array) + /// // set is now [1, 3, 6, 0] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average where *n* is + /// the number of elements in `other`, if `Element` implements high-quality + /// hashing. + @inlinable + public mutating func formSymmetricDifference( + _ other: __owned S + ) where S.Element == Element { + _base.formSymmetricDifference(other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a new set containing the elements of this set that do not occur + /// in the given set. + /// + /// The result contains elements in the same order they appear in `self`. + /// + /// let set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [6, 4, 2, 0] + /// set.subtracting(other) // [1, 3] + /// + /// - Parameter other: Another set. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public __consuming func subtracting(_ other: Self) -> Self { + _base.subtracting(other._base).unordered + } + + /// Removes the elements of the given set from this set. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let other: OrderedSet.UnorderedView = [6, 4, 2, 0] + /// set.subtract(other) + /// // set is now [1, 3] + /// + /// - Parameter other: Another set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public mutating func subtract(_ other: Self) { + _base.subtract(other._base) + } + + // Generalizations + + /// Returns a new set containing the elements of this set that do not occur + /// in the given sequence. + /// + /// The result contains elements in the same order they appear in `self`. + /// + /// let set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.subtracting([6, 4, 2, 0] as Array) // [1, 3] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: A new set. + /// + /// - Complexity: Expected to be O(`self.count + other.count`) on average, if + /// `Element` implements high-quality hashing. + @inlinable + public __consuming func subtracting( + _ other: S + ) -> Self where S.Element == Element { + _base.subtracting(other).unordered + } + + /// Removes the elements of the given sequence from this set. + /// + /// var set: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// set.subtract([6, 4, 2, 0] as Array) + /// // set is now [1, 3] + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public mutating func subtract( + _ other: S + ) where S.Element == Element { + _base.subtract(other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a Boolean value that indicates whether this set is a subset of + /// the given set. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// b.isSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSubset(of other: Self) -> Bool { + _base.isSubset(of: other._base) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether this set is a subset of + /// the given set. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: Set = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// b.isSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSubset(of other: Set) -> Bool { + _base.isSubset(of: other) + } + + /// Returns a Boolean value that indicates whether this set is a subset of + /// the elements in the given sequence. + /// + /// Set *A* is a subset of another set *B* if every member of *A* is also a + /// member of *B*, ignoring the order they appear in the two sets. + /// + /// let a: Array = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// b.isSubset(of: a) // true + /// + /// - Parameter other: A finite sequence. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public func isSubset( + of other: S + ) -> Bool where S.Element == Element { + _base.isSubset(of: other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a Boolean value that indicates whether this set is a superset of + /// the given set. + /// + /// Set *A* is a superset of another set *B* if every member of *B* is also a + /// member of *A*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// a.isSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSuperset(of other: Self) -> Bool { + _base.isSuperset(of: other._base) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether this set is a superset of + /// the given set. + /// + /// Set *A* is a superset of another set *B* if every member of *B* is also a + /// member of *A*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: Set = [4, 2, 1] + /// a.isSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isSuperset(of other: Set) -> Bool { + _base.isSuperset(of: other) + } + + /// Returns a Boolean value that indicates whether this set is a superset of + /// the given sequence. + /// + /// Set *A* is a superset of another set *B* if every member of *B* is also a + /// member of *A*, ignoring the order they appear in the two sets. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: Array = [4, 2, 1] + /// a.isSuperset(of: b) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if the set is a subset of `other`; otherwise, `false`. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public func isSuperset( + of other: S + ) -> Bool where S.Element == Element { + _base.isSuperset(of: other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given set. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// b.isStrictSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSubset(of other: Self) -> Bool { + _base.isStrictSubset(of: other._base) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given set. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: Set = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// b.isStrictSubset(of: a) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSubset(of other: Set) -> Bool { + _base.isStrictSubset(of: other) + } + + /// Returns a Boolean value that indicates whether the set is a strict subset + /// of the given sequence. + /// + /// Set *A* is a strict subset of another set *B* if every member of *A* is + /// also a member of *B* and *B* contains at least one element that is not a + /// member of *A*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: Array = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// b.isStrictSubset(of: a) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if `self` is a strict subset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public func isStrictSubset( + of other: S + ) -> Bool where S.Element == Element { + _base.isStrictSubset(of: other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given set. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [4, 2, 1] + /// a.isStrictSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSuperset(of other: Self) -> Bool { + _base.isStrictSuperset(of: other._base) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given set. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: Set = [4, 2, 1] + /// a.isStrictSuperset(of: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`other.count`) on average, if `Element` + /// implements high-quality hashing. + @inlinable + public func isStrictSuperset(of other: Set) -> Bool { + _base.isStrictSuperset(of: other) + } + + /// Returns a Boolean value that indicates whether the set is a strict + /// superset of the given sequence. + /// + /// Set *A* is a strict superset of another set *B* if every member of *B* is + /// also a member of *A* and *A* contains at least one element that is *not* + /// a member of *B*. (Ignoring the order the elements appear in the sets.) + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: Array = [4, 2, 1] + /// a.isStrictSuperset(of: b) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if `self` is a strict superset of `other`; otherwise, + /// `false`. + /// + /// - Complexity: Expected to be O(`self.count` + *n*) on average, where *n* + /// is the number of elements in `other`, if `Element` implements + /// high-quality hashing. + @inlinable + public func isStrictSuperset( + of other: S + ) -> Bool where S.Element == Element { + _base.isStrictSuperset(of: other) + } +} + +extension OrderedSet.UnorderedView { + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given set. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: OrderedSet.UnorderedView = [5, 6] + /// a.isDisjoint(with: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(min(`self.count`, `other.count`)) on + /// average, if `Element` implements high-quality hashing. + @inlinable + public func isDisjoint(with other: Self) -> Bool { + _base.isDisjoint(with: other._base) + } + + // Generalizations + + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given set. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: Set = [5, 6] + /// a.isDisjoint(with: b) // true + /// + /// - Parameter other: Another set. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(min(`self.count`, `other.count`)) on + /// average, if `Element` implements high-quality hashing. + @inlinable + public func isDisjoint(with other: Set) -> Bool { + _base.isDisjoint(with: other) + } + + /// Returns a Boolean value that indicates whether the set has no members in + /// common with the given sequence. + /// + /// let a: OrderedSet.UnorderedView = [1, 2, 3, 4] + /// let b: Array = [5, 6] + /// a.isDisjoint(with: b) // true + /// + /// - Parameter other: A finite sequence of elements. + /// + /// - Returns: `true` if `self` has no elements in common with `other`; + /// otherwise, `false`. + /// + /// - Complexity: Expected to be O(*n*) on average, where *n* is the number of + /// elements in `other`, if `Element` implements high-quality hashing. + @inlinable + public func isDisjoint( + with other: S + ) -> Bool where S.Element == Element { + _base.isDisjoint(with: other) + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet+UnstableInternals.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet+UnstableInternals.swift new file mode 100644 index 00000000..0243b3c1 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet+UnstableInternals.swift @@ -0,0 +1,48 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension OrderedSet { + /// Exposes some private implementation details and low-level unsafe + /// operations, primarily to allow clear box testing. + /// + /// This struct is a private implementation detail, therefore it and its + /// members are not covered by any source compatibility promises -- they + /// may disappear in any new release. + @frozen + public struct _UnstableInternals { + @usableFromInline + internal typealias _Bucket = _HashTable.Bucket + + @usableFromInline + internal var base: OrderedSet + + @inlinable + init(_ base: OrderedSet) { + self.base = base + } + } + + @inlinable + public var __unstable: _UnstableInternals { + @inline(__always) + get { + _UnstableInternals(self) + } + + @inline(__always) + _modify { + var view = _UnstableInternals(self) + self = OrderedSet() + defer { self = view.base } + yield &view + } + } +} diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet.swift new file mode 100644 index 00000000..09752760 --- /dev/null +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet.swift @@ -0,0 +1,496 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// An ordered collection of unique elements. +/// +/// Similar to the standard `Set`, ordered sets ensure that each element appears +/// only once in the collection, and they provide efficient tests for +/// membership. However, like `Array` (and unlike `Set`), ordered sets maintain +/// their elements in a particular user-specified order, and they support +/// efficient random-access traversal of their members. +/// +/// `OrderedSet` is a useful alternative to `Set` when the order of elements is +/// important, or when you need to be able to efficiently access elements at +/// various positions within the collection. It can also be used instead of an +/// `Array` when each element needs to be unique, or when you need to be able to +/// quickly determine if a value is a member of the collection. +/// +/// You can create an ordered set with any element type that conforms to the +/// `Hashable` protocol. +/// +/// let buildingMaterials: OrderedSet = ["straw", "sticks", "bricks"] +/// +/// +/// # Equality of Ordered Sets +/// +/// Two ordered sets are considered equal if they contain the same elements, and +/// *in the same order*. This matches the concept of equality of an `Array`, and +/// it is different from the unordered `Set`. +/// +/// let a: OrderedSet = [1, 2, 3, 4] +/// let b: OrderedSet = [4, 3, 2, 1] +/// a == b // false +/// b.sort() // `b` now has value [1, 2, 3, 4] +/// a == b // true +/// +/// # Set Operations +/// +/// `OrderedSet` implements most, but not all, `SetAlgebra` requirements. In +/// particular, it supports the membership test `contains(_:)` as well as all +/// high-level set operations such as `union(_:)`, `intersection(_:)` or +/// `isSubset(of:)`. +/// +/// buildingMaterials.contains("glass") // false +/// buildingMaterials.intersection(["brick", "straw"]) // ["straw", "brick"] +/// +/// Operations that return an ordered set usually preserve the ordering of +/// elements in their input. For example, in the case of the `intersection` call +/// above, the ordering of elements in the result is guaranteed to match their +/// order in the first input set, `buildingMaterials`. +/// +/// On the other hand, predicates such as `isSubset(of:)` tend to ignore element +/// ordering: +/// +/// let moreMaterials: OrderedSet = ["bricks", "glass", "sticks", "straw"] +/// buildingMaterials.isSubset(of: moreMaterials) // true +/// +/// However, `OrderedSet` does not implement `insert(_:)` nor `update(with:)` -- +/// it provides its own variants for insertion that are more explicit about +/// where in the collection new elements gets inserted: +/// +/// func insert(_ item: Element, at index: Index) -> (inserted: Bool, index: Int) +/// func append(_ item: Element) -> (inserted: Bool, index: Int) +/// func update(at index: Int, with item: Element) -> Element +/// func updateOrAppend(_ item: Element) -> Element? +/// +/// Additionally,`OrderedSet` has an order-sensitive definition of equality (see +/// above) that is incompatible with `SetAlgebra`'s documented semantic +/// requirements. Accordingly, `OrderedSet` does not (cannot) itself conform to +/// `SetAlgebra`. +/// +/// # Unordered Set View +/// +/// For cases where `SetAlgebra` conformance is desired (such as when passing an +/// ordered set to a function that is generic over that protocol), `OrderedSet` +/// provides an efficient *unordered view* of its elements that conforms to +/// `SetAlgebra`. The unordered view implements the same concept of equality as +/// the standard `Set`, ignoring element ordering. +/// +/// var a: OrderedSet = [0, 1, 2, 3] +/// let b: OrderedSet = [3, 2, 1, 0] +/// a == b // false +/// a.unordered == b.unordered // true +/// +/// func frobnicate(_ set: S) { ... } +/// frobnicate(a) // error: `OrderedSet` does not conform to `SetAlgebra` +/// frobnicate(a.unordered) // OK +/// +/// The unordered view is mutable. Insertions into it implicitly append new +/// elements to the end of the collection. +/// +/// buildingMaterials.unordered.insert("glass") // => inserted: true +/// // buildingMaterials is now ["straw", "sticks", "brick", "glass"] +/// +/// Accessing the unordered view is an efficient operation, with constant +/// (minimal) overhead. Direct mutations of the unordered view (such as the +/// insertion above) are executed in place when possible. However, as usual with +/// copy-on-write collections, if you make a copy of the view (such as by +/// extracting its value into a named variable), the resulting values will share +/// the same underlying storage, so mutations of either will incur a copy of the +/// whole set. +/// +/// # Sequence and Collection Operations +/// +/// Ordered sets are random-access collections. Members are assigned integer +/// indices, with the first element always being at index `0`: +/// +/// let buildingMaterials: OrderedSet = ["straw", "sticks", "bricks"] +/// buildingMaterials[1] // "sticks" +/// buildingMaterials.firstIndex(of: "bricks") // 2 +/// +/// for i in 0 ..< buildingMaterials.count { +/// print("Little piggie #\(i) built a house of \(buildingMaterials[i])") +/// } +/// // Little piggie #0 built a house of straw +/// // Little piggie #1 built a house of sticks +/// // Little piggie #2 built a house of bricks +/// +/// Because `OrderedSet` needs to keep its members unique, it cannot conform to +/// the full `MutableCollection` or `RangeReplaceableCollection` protocols. +/// Operations such as `MutableCollection`'s subscript setter or +/// `RangeReplaceableCollection`'s `replaceSubrange` assume the ability to +/// insert/replace arbitrary elements in the collection, but allowing that could +/// lead to duplicate values. +/// +/// However, `OrderedSet` is able to partially implement these two protocols; +/// namely, there is no issue with mutation operations that merely change the +/// order of elements, or just remove some subset of existing members: +/// +/// // Permutation operations from MutableCollection: +/// func swapAt(_ i: Int, _ j: Int) +/// func partition(by predicate: (Element) throws -> Bool) -> rethrows Int +/// func sort() where Element: Comparable +/// func sort(by predicate: (Element, Element) throws -> Bool) rethrows +/// func shuffle() +/// func shuffle(using generator: inout T) +/// func reverse() +/// +/// // Removal operations from RangeReplaceableCollection: +/// func removeAll(keepingCapacity: Bool = false) +/// func remove(at index: Int) -> Element +/// func removeSubrange(_ bounds: Range) +/// func removeLast() -> Element +/// func removeLast(_ n: Int) +/// func removeFirst() -> Element +/// func removeFirst(_ n: Int) +/// func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows +/// +/// `OrderedSet` also implements `reserveCapacity(_)` from +/// `RangeReplaceableCollection`, to allow for efficient insertion of a known +/// number of elements. (However, unlike `Array` and `Set`, `OrderedSet` does +/// not provide a `capacity` property.) +/// +/// # Accessing The Contents of an Ordered Set as an Array +/// +/// In cases where you need to pass the contents of an ordered set to a function +/// that only takes an array value or (or something that's generic over +/// `RangeReplaceableCollection` or `MutableCollection`), then the best option +/// is usually to directly extract the members of the `OrderedSet` as an `Array` +/// value using its `elements` property. `OrderedSet` uses a standard array +/// value for element storage, so extracting the array value has minimal +/// overhead. +/// +/// func pickyFunction(_ items: Array) +/// +/// var set: OrderedSet = [0, 1, 2, 3] +/// pickyFunction(set) // error +/// pickyFunction(set.elements) // OK +/// +/// It is also possible to mutate the set by updating the value of the +/// `elements` property. This guarantees that direct mutations happen in place +/// when possible (i.e., without spurious copy-on-write copies). +/// +/// However, the set needs to ensure the uniqueness of its members, so every +/// update to `elements` includes a postprocessing step to detect and remove +/// duplicates over the entire array. This can be slower than doing the +/// equivalent updates with direct `OrderedSet` operations, so updating +/// `elements` is best used in cases where direct implementations aren't +/// available -- for example, when you need to call a `MutableCollection` +/// algorithm that isn't directly implemented by `OrderedSet` itself. +/// +/// # Performance +/// +/// Like the standard `Set` type, the performance of hashing operations in +/// `OrderedSet` is highly sensitive to the quality of hashing implemented by +/// the `Element` type. Failing to correctly implement hashing can easily lead +/// to unacceptable performance, with the severity of the effect increasing with +/// the size of the hash table. +/// +/// In particular, if a certain set of elements all produce the same hash value, +/// then hash table lookups regress to searching an element in an unsorted +/// array, i.e., a linear operation. To ensure hashed collection types exhibit +/// their target performance, it is important to ensure that such collisions +/// cannot be induced merely by adding a particular list of members to the set. +/// +/// The easiest way to achieve this is to make sure `Element` implements hashing +/// following `Hashable`'s documented best practices. The conformance must +/// implement the `hash(into:)` requirement, and every bit of information that +/// is compared in `==` needs to be combined into the supplied `Hasher` value. +/// When used correctly, `Hasher` produces high-quality, randomly seeded hash +/// values that prevent repeatable hash collisions. +/// +/// When `Element` implements `Hashable` correctly, testing for membership in an +/// ordered set is expected to take O(1) equality checks on average. Hash +/// collisions can still occur organically, so the worst-case lookup performance +/// is technically still O(*n*) (where *n* is the size of the set); however, +/// long lookup chains are unlikely to occur in practice. +/// +/// # Implementation Details +/// +/// An `OrderedSet` stores its members in a regular `Array` value (exposed by +/// the `elements` property). It also maintains a standalone hash table +/// containing array indices alongside the array; this is used to implement fast +/// membership tests. The size of the array is limited by the capacity of the +/// corresponding hash table, so indices stored inside the hash table can be +/// encoded into fewer bits than a standard `Int` value, leading to a storage +/// representation that can often be more compact than that of `Set` itself. +/// +/// Inserting or removing a single member (or a range of members) needs to +/// perform the corresponding operation in the storage array, in addition to +/// renumbering any subsequent members in the hash table. Therefore, these +/// operations are expected to have performance characteristics similar to an +/// `Array`: inserting or removing an element to the end of an ordered set is +/// expected to execute in O(1) operations, while they are expected to take +/// linear time at the front (or in the middle) of the set. (Note that this is +/// different to the standard `Set`, where insertions and removals are expected +/// to take amortized O(1) time.) +@frozen +public struct OrderedSet where Element: Hashable +{ + @usableFromInline + internal typealias _Bucket = _HashTable.Bucket + + @usableFromInline + internal var __storage: _HashTable.Storage? + + @usableFromInline + internal var _elements: ContiguousArray + + @inlinable + internal init( + _uniqueElements: ContiguousArray, + _ table: _HashTable? = nil + ) { + self.__storage = table?._storage + self._elements = ContiguousArray(_uniqueElements) + } + + @inlinable + @inline(__always) + internal var _table: _HashTable? { + get { __storage.map { _HashTable($0) } } + set { __storage = newValue?._storage } + } +} + +extension OrderedSet { + /// A view of the members of this set, as a regular array value. + /// + /// It is possible to mutate the set by updating the value of this property. + /// This guarantees that direct mutations happen in place when possible (i.e., + /// without spurious copy-on-write copies). + /// + /// However, the set needs to ensure the uniqueness of its members, so every + /// update to `elements` includes a postprocessing step to detect and remove + /// duplicates over the entire array. This can be slower than doing the + /// equivalent updates with direct `OrderedSet` operations, so updating + /// `elements` is best used in cases where direct implementations aren't + /// available -- for example, when you need to call a `MutableCollection` + /// algorithm that isn't directly implemented by `OrderedSet` itself. + /// + /// - Complexity: O(1) for the getter. Mutating this property has an expected + /// complexity of O(`count`), if `Element` implements high-quality hashing. + @inlinable + public var elements: [Element] { + get { + Array(_elements) + } + set { + self = .init(newValue) + } + _modify { + var members = Array(_elements) + _elements = [] + defer { self = .init(members) } + yield &members + } + } +} + +extension OrderedSet { + /// The maximum number of elements this instance can store before it needs + /// to resize its hash table. + @inlinable + internal var _capacity: Int { + _table?.capacity ?? _HashTable.maximumUnhashedCount + } + + @inlinable + internal var _minimumCapacity: Int { + if _scale == _reservedScale { return 0 } + return _HashTable.minimumCapacity(forScale: _scale) + } + + @inlinable + internal var _scale: Int { + _table?.scale ?? 0 + } + + @inlinable + internal var _reservedScale: Int { + _table?.reservedScale ?? 0 + } + + @inlinable + internal var _bias: Int { + _table?.bias ?? 0 + } +} + +extension OrderedSet { + @inlinable + internal mutating func _regenerateHashTable(scale: Int, reservedScale: Int) { + assert(_HashTable.maximumCapacity(forScale: scale) >= _elements.count) + assert(reservedScale == 0 || reservedScale >= _HashTable.minimumScale) + _table = _HashTable.create( + uncheckedUniqueElements: _elements, + scale: Swift.max(scale, reservedScale), + reservedScale: reservedScale) + } + + @inlinable + internal mutating func _regenerateHashTable() { + let reservedScale = _reservedScale + guard + _elements.count > _HashTable.maximumUnhashedCount || reservedScale != 0 + else { + // We have too few elements; disable hashing. + _table = nil + return + } + let scale = _HashTable.scale(forCapacity: _elements.count) + _regenerateHashTable(scale: scale, reservedScale: reservedScale) + } + + @inlinable + internal mutating func _regenerateExistingHashTable() { + assert(_capacity >= _elements.count) + guard _table != nil else { + return + } + _ensureUnique() + _table!.update { hashTable in + hashTable.clear() + hashTable.fill(uncheckedUniqueElements: _elements) + } + } +} + +extension OrderedSet { + @inlinable + @inline(__always) + internal mutating func _isUnique() -> Bool { + isKnownUniquelyReferenced(&__storage) + } + + @inlinable + internal mutating func _ensureUnique() { + if __storage == nil { return } + if isKnownUniquelyReferenced(&__storage) { return } + _table = _table!.copy() + } +} + +extension OrderedSet { + @inlinable + internal func _find(_ item: Element) -> (index: Index?, bucket: _Bucket) { + _find_inlined(item) + } + + @inlinable + @inline(__always) + internal func _find_inlined(_ item: Element) -> (index: Index?, bucket: _Bucket) { + _elements.withUnsafeBufferPointer { elements in + guard let table = _table else { + return (elements.firstIndex(of: item), _Bucket(offset: 0)) + } + return table.read { hashTable in + hashTable._find(item, in: elements) + } + } + } + + @inlinable + internal func _bucket(for index: Index) -> _Bucket { + guard let table = _table else { return _Bucket(offset: 0) } + return table.read { hashTable in + var it = hashTable.bucketIterator(for: _elements[index]) + it.advance(until: index) + precondition(it.isOccupied, "Corrupt hash table") + return it.currentBucket + } + } + + /// Returns the index of the given element in the set, or `nil` if the element + /// is not a member of the set. + /// + /// `OrderedSet` members are always unique, so the first index of an element + /// is always the same as its last index. + /// + /// - Complexity: This operation is expected to perform O(1) comparisons on + /// average, provided that `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public func firstIndex(of element: Element) -> Index? { + _find(element).index + } + + /// Returns the index of the given element in the set, or `nil` if the element + /// is not a member of the set. + /// + /// `OrderedSet` members are always unique, so the first index of an element + /// is always the same as its last index. + /// + /// - Complexity: This operation is expected to perform O(1) comparisons on + /// average, provided that `Element` implements high-quality hashing. + @inlinable + @inline(__always) + public func lastIndex(of element: Element) -> Index? { + _find(element).index + } +} + +extension OrderedSet { + @inlinable + @inline(never) + internal __consuming func _extractSubset( + using bitset: _UnsafeBitset, + extraCapacity: Int = 0 + ) -> Self { + assert(bitset.count == 0 || bitset.max()! <= count) + if bitset.count == 0 { return Self(minimumCapacity: extraCapacity) } + if bitset.count == self.count { + if extraCapacity <= self._capacity - self.count { + return self + } + var copy = self + copy.reserveCapacity(count + extraCapacity) + return copy + } + var result = Self(minimumCapacity: bitset.count + extraCapacity) + for offset in bitset { + result._appendNew(_elements[offset]) + } + assert(result.count == bitset.count) + return result + } +} + +extension OrderedSet { + @inlinable + @discardableResult + internal mutating func _removeExistingMember( + at index: Index, + in bucket: _Bucket + ) -> Element { + guard _elements.count - 1 >= _minimumCapacity else { + let old = _elements.remove(at: index) + _regenerateHashTable() + return old + } + guard _table != nil else { + return _elements.remove(at: index) + } + + defer { _checkInvariants() } + _ensureUnique() + _table!.update { hashTable in + // Delete the entry for the removed member. + hashTable.delete( + bucket: bucket, + hashValueGenerator: { offset, seed in + _elements[offset]._rawHashValue(seed: seed) + }) + hashTable.adjustContents(preparingForRemovalOf: index, in: _elements) + } + return _elements.remove(at: index) + } +} diff --git a/Sources/OrderedCollections/Utilities/RandomAccessCollection+Offsets.swift b/Sources/OrderedCollections/Utilities/RandomAccessCollection+Offsets.swift new file mode 100644 index 00000000..54a56fa8 --- /dev/null +++ b/Sources/OrderedCollections/Utilities/RandomAccessCollection+Offsets.swift @@ -0,0 +1,30 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension RandomAccessCollection { + @inlinable + @inline(__always) + internal func _index(at offset: Int) -> Index { + index(startIndex, offsetBy: offset) + } + + @inlinable + @inline(__always) + internal func _offset(of index: Index) -> Int { + distance(from: startIndex, to: index) + } + + @inlinable + @inline(__always) + internal subscript(_offset offset: Int) -> Element { + self[_index(at: offset)] + } +} diff --git a/Sources/OrderedCollections/Utilities/_UnsafeBitset.swift b/Sources/OrderedCollections/Utilities/_UnsafeBitset.swift new file mode 100644 index 00000000..9470c610 --- /dev/null +++ b/Sources/OrderedCollections/Utilities/_UnsafeBitset.swift @@ -0,0 +1,385 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// A simple bitmap of a fixed number of bits, implementing a sorted set of +/// small nonnegative `Int` values. +/// +/// Because `_UnsafeBitset` implements a flat bit vector, it isn't suitable for +/// holding arbitrarily large integers. The maximal element a bitset can store +/// is fixed at its initialization. +@usableFromInline +@frozen +internal struct _UnsafeBitset { + @usableFromInline + internal let _words: UnsafeMutableBufferPointer + + @usableFromInline + internal var _count: Int + + @inlinable + @inline(__always) + internal init(words: UnsafeMutableBufferPointer, count: Int) { + self._words = words + self._count = count + } + + @inlinable + @inline(__always) + internal init(words: UnsafeMutablePointer, wordCount: Int, count: Int) { + self._words = UnsafeMutableBufferPointer(start: words, count: wordCount) + self._count = count + } + + @inlinable + @inline(__always) + internal var count: Int { + _count + } +} + +extension _UnsafeBitset { + @usableFromInline + internal var _actualCount: Int { + return _words.reduce(0) { $0 + $1.count } + } +} + +extension _UnsafeBitset { + @inlinable + @inline(__always) + static func withTemporaryBitset( + capacity: Int, + run body: (inout _UnsafeBitset) throws -> R + ) rethrows -> R { + var result: R? + try _withTemporaryBitset(capacity: capacity) { bitset in + result = try body(&bitset) + } + return result! + } + + @usableFromInline + @inline(never) + static func _withTemporaryBitset( + capacity: Int, + run body: (inout _UnsafeBitset) throws -> Void + ) rethrows { + let wordCount = _UnsafeBitset.wordCount(forCapacity: capacity) + if wordCount <= 2 { + var buffer: (Word, Word) = (.empty, .empty) + return try withUnsafeMutablePointer(to: &buffer) { p in + // Homogeneous tuples are layout-compatible with their component type. + let words = UnsafeMutableRawPointer(p).assumingMemoryBound(to: Word.self) + var bitset = _UnsafeBitset(words: words, wordCount: wordCount, count: 0) + return try body(&bitset) + } + } + let words = UnsafeMutableBufferPointer.allocate(capacity: wordCount) + words.initialize(repeating: .empty) + defer { words.deallocate() } + var bitset = _UnsafeBitset(words: words, count: 0) + return try body(&bitset) + } +} + +extension _UnsafeBitset { + @inline(__always) + internal static func word(for element: Int) -> Int { + assert(element >= 0) + // Note: We perform on UInts to get faster unsigned math (shifts). + let element = UInt(bitPattern: element) + let capacity = UInt(bitPattern: Word.capacity) + return Int(bitPattern: element / capacity) + } + + @inline(__always) + internal static func bit(for element: Int) -> Int { + assert(element >= 0) + // Note: We perform on UInts to get faster unsigned math (masking). + let element = UInt(bitPattern: element) + let capacity = UInt(bitPattern: Word.capacity) + return Int(bitPattern: element % capacity) + } + + @inline(__always) + internal static func split(_ element: Int) -> (word: Int, bit: Int) { + return (word(for: element), bit(for: element)) + } + + @inline(__always) + internal static func join(word: Int, bit: Int) -> Int { + assert(bit >= 0 && bit < Word.capacity) + return word &* Word.capacity &+ bit + } +} + +extension _UnsafeBitset { + @usableFromInline + @_effects(readnone) + @inline(__always) + internal static func wordCount(forCapacity capacity: Int) -> Int { + return word(for: capacity &+ Word.capacity &- 1) + } + + internal var capacity: Int { + @inline(__always) + get { + return _words.count &* Word.capacity + } + } + + @inline(__always) + internal func isValid(_ element: Int) -> Bool { + return element >= 0 && element < capacity + } + + @inline(__always) + internal func contains(_ element: Int) -> Bool { + assert(isValid(element)) + let (word, bit) = _UnsafeBitset.split(element) + return _words[word].contains(bit) + } + + @usableFromInline + @_effects(releasenone) + @discardableResult + internal mutating func insert(_ element: Int) -> Bool { + assert(isValid(element)) + let (word, bit) = _UnsafeBitset.split(element) + let inserted = _words[word].insert(bit) + if inserted { _count += 1 } + return inserted + } + + @usableFromInline + @_effects(releasenone) + @discardableResult + internal mutating func remove(_ element: Int) -> Bool { + assert(isValid(element)) + let (word, bit) = _UnsafeBitset.split(element) + let removed = _words[word].remove(bit) + if removed { _count -= 1 } + return removed + } + + @usableFromInline + @_effects(releasenone) + internal mutating func clear() { + guard _words.count > 0 else { return } + _words.baseAddress!.assign(repeating: .empty, count: _words.count) + _count = 0 + } + + @usableFromInline + @_effects(releasenone) + internal mutating func insertAll(upTo max: Int) { + assert(max <= capacity) + guard max > 0 else { return } + let (w, b) = _UnsafeBitset.split(max) + for i in 0 ..< w { + _count += Word.capacity - _words[i].count + _words[i] = .allBits + } + if b > 0 { + _count += _words[w].insert(bitsBelow: b) + } + } + + @usableFromInline + @_effects(releasenone) + internal mutating func removeAll(upTo max: Int) { + assert(max <= capacity) + guard max > 0 else { return } + let (w, b) = _UnsafeBitset.split(max) + for i in 0 ..< w { + _count -= _words[i].count + _words[i] = .empty + } + if b > 0 { + _count -= _words[w].remove(bitsBelow: b) + } + } +} + +extension _UnsafeBitset: Sequence { + @usableFromInline + internal typealias Element = Int + + @inlinable + @inline(__always) + internal var underestimatedCount: Int { + return count + } + + @inlinable + @inline(__always) + func makeIterator() -> Iterator { + return Iterator(self) + } + + @usableFromInline + @frozen + internal struct Iterator: IteratorProtocol { + @usableFromInline + internal let bitset: _UnsafeBitset + + @usableFromInline + internal var index: Int + + @usableFromInline + internal var word: Word + + @inlinable + internal init(_ bitset: _UnsafeBitset) { + self.bitset = bitset + self.index = 0 + self.word = bitset._words.count > 0 ? bitset._words[0] : .empty + } + + @usableFromInline + @_effects(releasenone) + internal mutating func next() -> Int? { + if let bit = word.next() { + return _UnsafeBitset.join(word: index, bit: bit) + } + while (index + 1) < bitset._words.count { + index += 1 + word = bitset._words[index] + if let bit = word.next() { + return _UnsafeBitset.join(word: index, bit: bit) + } + } + return nil + } + } +} + +//////////////////////////////////////////////////////////////////////////////// +extension _UnsafeBitset { + @usableFromInline + @frozen + internal struct Word { + @usableFromInline + internal var value: UInt + + @inlinable + @inline(__always) + internal init(_ value: UInt) { + self.value = value + } + } +} + +extension _UnsafeBitset.Word { + @inlinable + @inline(__always) + internal static var capacity: Int { + return UInt.bitWidth + } + + @inlinable + @inline(__always) + internal var count: Int { + value.nonzeroBitCount + } + + @inlinable + @inline(__always) + internal var isEmpty: Bool { + value == 0 + } + + @inlinable + @inline(__always) + internal func contains(_ bit: Int) -> Bool { + assert(bit >= 0 && bit < UInt.bitWidth) + return value & (1 &<< bit) != 0 + } + + @inlinable + @inline(__always) + @discardableResult + internal mutating func insert(_ bit: Int) -> Bool { + assert(bit >= 0 && bit < UInt.bitWidth) + let mask: UInt = 1 &<< bit + let inserted = value & mask == 0 + value |= mask + return inserted + } + + @inlinable + @inline(__always) + @discardableResult + internal mutating func remove(_ bit: Int) -> Bool { + assert(bit >= 0 && bit < UInt.bitWidth) + let mask: UInt = 1 &<< bit + let removed = value & mask != 0 + value &= ~mask + return removed + } +} + +extension _UnsafeBitset.Word { + @inlinable + @inline(__always) + internal mutating func insert(bitsBelow bit: Int) -> Int { + assert(bit >= 0 && bit < Self.capacity) + let mask: UInt = (1 as UInt &<< bit) &- 1 + let inserted = bit - (value & mask).nonzeroBitCount + value |= mask + return inserted + } + + @inlinable + @inline(__always) + internal mutating func remove(bitsBelow bit: Int) -> Int { + assert(bit >= 0 && bit < Self.capacity) + let mask = UInt.max &<< bit + let removed = (value & ~mask).nonzeroBitCount + value &= mask + return removed + } +} + +extension _UnsafeBitset.Word { + @inlinable + @inline(__always) + internal static var empty: Self { + Self(0) + } + + @inlinable + @inline(__always) + internal static var allBits: Self { + Self(UInt.max) + } +} + +// Word implements Sequence by using a copy of itself as its Iterator. +// Iteration with `next()` destroys the word's value; however, this won't cause +// problems in normal use, because `next()` is usually called on a separate +// iterator, not the original word. +extension _UnsafeBitset.Word: Sequence, IteratorProtocol { + @inlinable + internal var underestimatedCount: Int { + count + } + + /// Return the index of the lowest set bit in this word, + /// and also destructively clear it. + @inlinable + internal mutating func next() -> Int? { + guard value != 0 else { return nil } + let bit = value.trailingZeroBitCount + value &= value &- 1 // Clear lowest nonzero bit. + return bit + } +} diff --git a/Sources/UniquedModule/RandomAccessCollection+Offsets.swift b/Sources/UniquedModule/RandomAccessCollection+Offsets.swift new file mode 100644 index 00000000..2b14f016 --- /dev/null +++ b/Sources/UniquedModule/RandomAccessCollection+Offsets.swift @@ -0,0 +1,27 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension RandomAccessCollection { + @inline(__always) + internal func _index(at offset: Int) -> Index { + index(startIndex, offsetBy: offset) + } + + @inline(__always) + internal func _offset(of index: Index) -> Int { + distance(from: startIndex, to: index) + } + + @inline(__always) + internal subscript(_offset offset: Int) -> Element { + self[_index(at: offset)] + } +} diff --git a/Sources/UniquedModule/Uniqued+Codable.swift b/Sources/UniquedModule/Uniqued+Codable.swift new file mode 100644 index 00000000..56b04540 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Codable.swift @@ -0,0 +1,51 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: Encodable where Base: Encodable { + /// Encodes the elements of this deque into the given encoder in an unkeyed + /// container. + /// + /// This function throws an error if any values are invalid for the given + /// encoder's format. + /// + /// - Parameter encoder: The encoder to write data to. + public func encode(to encoder: Encoder) throws { + var container = encoder.singleValueContainer() + try container.encode(_elements) + } +} + +extension Uniqued: Decodable where Base: Decodable { + /// Creates a new uniqued collection by decoding from the given decoder. + /// + /// This initializer throws an error if reading from the decoder fails, or + /// if the decoded contents contain duplicate values. + /// + /// - Parameter decoder: The decoder to read data from. + public init(from decoder: Decoder) throws { + let container = try decoder.singleValueContainer() + let elements = try container.decode(Base.self) + + let (storage, end) = _HashTableStorage.create( + from: elements, + stoppingOnFirstDuplicateValue: true) + guard end == elements.endIndex else { + let offset = elements._offset(of: end) + let context = DecodingError.Context( + codingPath: container.codingPath, + debugDescription: "Decoded elements aren't unique (first duplicate at offset \(offset))") + throw DecodingError.dataCorrupted(context) + } + self.init( + _uniqueElements: elements, + storage: elements.count > _UnsafeHashTable.maximumUnhashedCount ? storage : nil) + } +} diff --git a/Sources/UniquedModule/Uniqued+CustomDebugStringConvertible.swift b/Sources/UniquedModule/Uniqued+CustomDebugStringConvertible.swift new file mode 100644 index 00000000..e36a2cd4 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+CustomDebugStringConvertible.swift @@ -0,0 +1,38 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: CustomDebugStringConvertible { + public var debugDescription: String { + _debugDescription(typeName: _debugTypeName()) + } + + internal func _debugTypeName() -> String { + // Prefer the name "OrderedSet" when Base is a regular array. + Base.self == [Element].self + ? "OrderedSet<\(Element.self)>" + : "Uniqued<\(Base.self)>" + } + + internal func _debugDescription(typeName: String) -> String { + var result = "\(typeName)([" + var first = true + for item in self { + if first { + first = false + } else { + result += ", " + } + debugPrint(item, terminator: "", to: &result) + } + result += "])" + return result + } +} diff --git a/Sources/UniquedModule/Uniqued+CustomReflectable.swift b/Sources/UniquedModule/Uniqued+CustomReflectable.swift new file mode 100644 index 00000000..c3614594 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+CustomReflectable.swift @@ -0,0 +1,16 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: CustomReflectable { + public var customMirror: Mirror { + Mirror(self, unlabeledChildren: _elements, displayStyle: .collection) + } +} diff --git a/Sources/UniquedModule/Uniqued+CustomStringConvertible.swift b/Sources/UniquedModule/Uniqued+CustomStringConvertible.swift new file mode 100644 index 00000000..53b4d265 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+CustomStringConvertible.swift @@ -0,0 +1,27 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: CustomStringConvertible { + public var description: String { + var result = "[" + var first = true + for item in self { + if first { + first = false + } else { + result += ", " + } + print(item, terminator: "", to: &result) + } + result += "]" + return result + } +} diff --git a/Sources/UniquedModule/Uniqued+Equatable.swift b/Sources/UniquedModule/Uniqued+Equatable.swift new file mode 100644 index 00000000..885c5580 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Equatable.swift @@ -0,0 +1,16 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: Equatable where Element: Equatable { + public static func ==(left: Self, right: Self) -> Bool { + left.elementsEqual(right) + } +} diff --git a/Sources/UniquedModule/Uniqued+ExpressibleByArrayLiteral.swift b/Sources/UniquedModule/Uniqued+ExpressibleByArrayLiteral.swift new file mode 100644 index 00000000..acdbef17 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+ExpressibleByArrayLiteral.swift @@ -0,0 +1,20 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: ExpressibleByArrayLiteral where Base: RangeReplaceableCollection +{ + // Note: we need the `RangeReplaceableCollection` conformance to be able to + // de-dupe contents & convert the input array into `Base`. + + public init(arrayLiteral elements: Element...) { + self.init(elements) + } +} diff --git a/Sources/UniquedModule/Uniqued+Hashable.swift b/Sources/UniquedModule/Uniqued+Hashable.swift new file mode 100644 index 00000000..1b44b9f4 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Hashable.swift @@ -0,0 +1,19 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: Hashable where Element: Hashable { + public func hash(into hasher: inout Hasher) { + hasher.combine(count) // Discriminator + for item in _elements { + hasher.combine(item) + } + } +} diff --git a/Sources/UniquedModule/Uniqued+Initializers.swift b/Sources/UniquedModule/Uniqued+Initializers.swift new file mode 100644 index 00000000..3e64bf23 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Initializers.swift @@ -0,0 +1,53 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued { + public init(uncheckedUniqueElements elements: Base) { + guard elements.count > _UnsafeHashTable.maximumUnhashedCount else { + self.init(_uniqueElements: elements, storage: nil) + return + } + let storage = _HashTableStorage.create( + from: elements, + stoppingOnFirstDuplicateValue: false).storage + self.init(_uniqueElements: elements, storage: storage) + } + + public init(uniqueElements elements: Base) { + let (storage, index) = _HashTableStorage.create( + from: elements, + stoppingOnFirstDuplicateValue: true) + guard index == elements.endIndex else { + let offset = elements._offset(of: index) + preconditionFailure("Duplicate element at offset \(offset)") + } + self.init( + _uniqueElements: elements, + storage: elements.count > _UnsafeHashTable.maximumUnhashedCount ? storage : nil) + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + public init(minimumCapacity: Int) { + self.init() + self.reserveCapacity(minimumCapacity) + } + + public init(uncheckedUniqueElements elements: S) + where S.Element == Element { + self.init(uncheckedUniqueElements: Base(elements)) + } + + public init(uniqueElements elements: S) + where S.Element == Element { + self.init(uniqueElements: Base(elements)) + } +} diff --git a/Sources/UniquedModule/Uniqued+Insertions.swift b/Sources/UniquedModule/Uniqued+Insertions.swift new file mode 100644 index 00000000..943ea944 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Insertions.swift @@ -0,0 +1,214 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued where Base: RangeReplaceableCollection { + @_spi(UnsafeInternals) + public mutating func _appendNew(_ item: Element) { + assert(!contains(item)) + _elements.append(item) + guard _elements.count <= _capacity else { + _regenerateHashTable() + return + } + guard _storage != nil else { return } + _ensureUnique() + _storage!.update { hashTable in + var it = hashTable.bucketIterator(for: item) + it.advanceToNextUnoccupiedBucket() + it.currentValue = _elements.count - 1 + } + } + + @_spi(UnsafeInternals) + public mutating func _appendNew(_ item: Element, in bucket: _Bucket) { + _elements.append(item) + + guard _elements.count < _capacity else { + _regenerateHashTable() + return + } + guard _storage != nil else { return } + _ensureUnique() + _storage!.update { hashTable in + hashTable[bucket] = _elements.count - 1 + } + } + + @_spi(UnsafeInternals) + @discardableResult + public mutating func _append(_ item: Element) -> (inserted: Bool, index: Base.Index) { + let (index, bucket) = _find(item) + if let index = index { return (false, index) } + _appendNew(item, in: bucket) + return (true, _elements.index(before: _elements.endIndex)) + } + + @discardableResult + public mutating func append(_ item: Element) -> (inserted: Bool, index: Base.Index) { + let result = _append(item) + _checkInvariants() + return result + } + + public mutating func append( + contentsOf elements: S + ) where S.Element == Element { + for item in elements { + _append(item) + } + _checkInvariants() + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + internal mutating func _prependNew(_ item: Element, in bucket: _Bucket) { + _elements.insert(item, at: _elements.startIndex) + + guard _elements.count < _capacity else { + _regenerateHashTable() + return + } + guard _storage != nil else { return } + _ensureUnique() + _storage!.update { hashTable in + hashTable.bias &+= 1 + hashTable[bucket] = 0 + } + } + + @discardableResult + public mutating func prepend(_ item: Element) -> (inserted: Bool, index: Base.Index) { + let (index, bucket) = _find(item) + if let index = index { return (false, index) } + + _prependNew(item, in: bucket) + return (true, _elements.startIndex) + } + + public mutating func prepend( + contentsOf elements: S + ) where S.Element == Element { + var new = Self() + for item in elements { + guard !self.contains(item) else { continue } + new._append(item) + } + let inserted = new._elements.count + guard inserted > 0 else { return } + _elements.insert(contentsOf: new._elements, at: _elements.startIndex) + defer { _checkInvariants() } + if _elements.count > _capacity { + _regenerateHashTable() + return + } + if _storage == nil { + return + } + _ensureUnique() + _storage!.update { hashTable in + hashTable.bias += inserted + var i = 0 + while i != inserted { + var it = hashTable.bucketIterator(for: _elements[_elements._index(at: i)]) + it.advanceToNextUnoccupiedBucket() + it.currentValue = i + i += 1 + } + } + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + internal mutating func _insertNew( + _ item: Element, + at index: Index, + bucket: _Bucket + ) -> Int { + let offset = _elements._offset(of: index) + guard _elements.count < _capacity else { + _elements.insert(item, at: index) + _regenerateHashTable() + return offset + } + guard _storage != nil else { + _elements.insert(item, at: index) + return offset + } + + _storage!.update { hashTable in + hashTable.adjustContents(preparingForInsertionOfElementAtOffset: offset, in: _elements) + hashTable[bucket] = offset + } + _elements.insert(item, at: index) + _checkInvariants() + return offset + } + + public mutating func insert( + _ item: Element, at index: Index + ) -> (inserted: Bool, index: Index) { + let (existing, bucket) = _find(item) + if let existing = existing { return (false, existing) } + + let offset = _insertNew(item, at: index, bucket: bucket) + return (true, _elements._index(at: offset)) + } +} + +extension Uniqued where Base: MutableCollection { + /// Replace the member at the given index with a new value that compares equal + /// to it. + /// + /// This is useful when equal elements can be distinguished by identity + /// comparison or some other means. + /// + /// This method does not invalidate any indices in `self`. + /// + /// - Complexity: O(1) if the collection instance has no outstanding copies. + /// Otherwise O(n) where _n_ is `self.count`. + /// + /// - Parameter index: The index of the element to be replaced. + /// - Parameter item: The new value that should replace the original element. + /// `item` must compare equal to the original value. + /// - Returns: The original element that was replaced. + @discardableResult + public mutating func update(at index: Index, with item: Element) -> Element { + let old = _elements[index] + precondition(item == old, "The replacement item must compare equal to the original") + _elements[index] = item + return old + } +} + +extension Uniqued where Base: RangeReplaceableCollection & MutableCollection { + /// Inserts the given element into the set unconditionally, either appending + /// it to the set, or replacing an existing value if it's already present. + /// + /// This is useful when equal elements can be distinguished by identity + /// comparison or some other means. + /// + /// This method does not invalidate indices when the return value is non-`nil`. + /// Otherwise indices in `self` may get invalidated, depending on the + /// behavior of the `append` method of the underlying `Base` collection. + /// + /// - Complexity: O(1) on average, amortized over many calls on the same collection. + /// + /// - Parameter item: The value to append or replace. + /// - Returns: The original element that was replaced by this operation, or `nil` if the value was appended to the end of the collection. + public mutating func updateOrAppend(_ item: Element) -> Element? { + let (inserted, index) = _append(item) + if inserted { return nil } + let old = _elements[index] + _elements[index] = item + _checkInvariants() + return old + } +} diff --git a/Sources/UniquedModule/Uniqued+Invariants.swift b/Sources/UniquedModule/Uniqued+Invariants.swift new file mode 100644 index 00000000..5eb0888b --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Invariants.swift @@ -0,0 +1,54 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued { + #if COLLECTIONS_INTERNAL_CHECKS + @_spi(Testing) + @inline(never) @_effects(releasenone) + public func _checkInvariants() { + if _storage == nil { + precondition(_elements.count <= _UnsafeHashTable.maximumUnhashedCount, + "Oversized set without a hash table") + precondition(Set(_elements).count == _elements.count, + "Duplicate items in set") + return + } + // Check that each element in _elements can be found in the hash table. + for index in _elements.indices { + let item = _elements[index] + let (found, _, offset) = _find(item) + precondition(found, "Element '\(item)' not found in hash table") + precondition( + _index(at: offset) == index, + "Offset of element '\(item)' in hash table differs from its position") + } + // Check that the hash table has exactly as many entries as there are elements. + _storage!.read { hashTable in + var it = hashTable.bucketIterator(startingAt: _Bucket(offset: 0)) + var c = 0 + repeat { + it.advance() + if it.isOccupied { c += 1 } + } while it.currentBucket.offset != 0 + precondition( + c == _elements.count, + """ + Number of entries in hash table (\(c)) differs + from number of elements (\(_elements.count)) + """) + } + } + #else + @_spi(Testing) + @inline(__always) @inlinable + public func _checkInvariants() {} + #endif // COLLECTIONS_INTERNAL_CHECKS +} diff --git a/Sources/UniquedModule/Uniqued+Partial MutableCollection.swift b/Sources/UniquedModule/Uniqued+Partial MutableCollection.swift new file mode 100644 index 00000000..47a13f6e --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Partial MutableCollection.swift @@ -0,0 +1,210 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// The parts of MutableCollection that Uniqued is able to implement. + +extension Uniqued where Base: MutableCollection { + public mutating func swapAt(_ i: Index, _ j: Index) { + guard i != j else { return } + _elements.swapAt(i, j) + guard _storage != nil else { return } + _ensureUnique() + _storage!.update { hashTable in + let iOffset = _elements._offset(of: i) + let jOffset = _elements._offset(of: j) + hashTable.swapBucketValues(for: _elements[i], withCurrentValue: jOffset, + and: _elements[j], withCurrentValue: iOffset) + } + _checkInvariants() + } + + public mutating func partition( + by belongsInSecondPartition: (Element) throws -> Bool + ) rethrows -> Index { + try _partition(by: belongsInSecondPartition, callback: { a, b in }) + } +} + +extension Uniqued where Base: MutableCollection { + public mutating func _partition( + by belongsInSecondPartition: (Element) throws -> Bool, + callback: (Int, Int) -> Void + ) rethrows -> Index { + guard _storage != nil else { + return try _elements.partition(by: belongsInSecondPartition) + } + _ensureUnique() + let result: Index = try _storage!.update { hashTable in + let maybeOffset: Int? = try _elements.withContiguousMutableStorageIfAvailable { buffer in + let pivot = try buffer._partition( + with: hashTable, + by: belongsInSecondPartition, + callback: callback) + return pivot - buffer.startIndex + } + if let offset = maybeOffset { + return _elements.index(startIndex, offsetBy: offset) + } + return try _elements._partition( + with: hashTable, + by: belongsInSecondPartition, + callback: callback) + } + _checkInvariants() + return result + } +} + +extension MutableCollection where Self: RandomAccessCollection, Element: Hashable { + internal mutating func _partition( + with hashTable: _UnsafeHashTable, + by belongsInSecondPartition: (Element) throws -> Bool, + callback: (Int, Int) -> Void + ) rethrows -> Index { + var low = startIndex + var high = endIndex + + while true { + // Invariants at this point: + // - low <= high + // - all elements in `startIndex ..< low` belong in the first partition + // - all elements in `high ..< endIndex` belong in the second partition + + // Find next element from `lo` that may not be in the right place. + while true { + if low == high { return low } + if try belongsInSecondPartition(self[low]) { break } + formIndex(after: &low) + } + + // Find next element down from `hi` that we can swap `lo` with. + while true { + formIndex(before: &high) + if low == high { return low } + if try !belongsInSecondPartition(self[high]) { break } + } + + // Swap the two elements as well as their associated hash table buckets. + swapAt(low, high) + hashTable.swapBucketValues(for: self[low], withCurrentValue: _offset(of: high), + and: self[high], withCurrentValue: _offset(of: low)) + callback(_offset(of: low), _offset(of: high)) + + formIndex(after: &low) + } + } +} + +extension _UnsafeHashTable { + func swapBucketValues( + for left: Element, withCurrentValue leftValue: Int, + and right: Element, withCurrentValue rightValue: Int + ) { + var it = bucketIterator(for: left) + it.advance(until: leftValue) + assert(it.isOccupied) + it.currentValue = rightValue + + it = bucketIterator(for: right) + it.advance(until: rightValue) + assert(it.isOccupied) + // Note: this second update may mistake the bucket for `right` with the + // bucket for `left` whose value we just updated. The second update will + // restore the original hash table contents in this case. This is okay! + // When this happens, the lookup chains for both elements include each + // other, so leaving the hash table unchanged still leaves us with a + // working hash table. + it.currentValue = leftValue + } +} + +extension Uniqued where Base: MutableCollection { + public mutating func sort( + by areInIncreasingOrder: (Element, Element) throws -> Bool + ) rethrows { + defer { + // Note: This assumes that `sort(by:)` won't leave duplicate/missing + // elements in the table when the closure throws. This matches the + // stdlib's behavior in Swift 5.3, and it seems like a reasonable + // long-term assumption. + _regenerateExistingHashTable() + _checkInvariants() + } + try _elements.sort(by: areInIncreasingOrder) + } +} + +extension Uniqued where Base: MutableCollection, Element: Comparable { + public mutating func sort() { + sort(by: <) + } +} + +extension Uniqued where Base: MutableCollection { + public mutating func shuffle() { + var generator = SystemRandomNumberGenerator() + shuffle(using: &generator) + } + + public mutating func shuffle( + using generator: inout T + ) { + _elements.shuffle(using: &generator) + _regenerateHashTable() + _checkInvariants() + } +} + +extension Uniqued { + @_spi(UnsafeInternals) + public mutating func _partition( + values: UnsafeMutableBufferPointer, + by belongsInSecondPartition: ((key: Key, value: Value)) throws -> Bool + ) rethrows -> Int + where Base == ContiguousArray { + let storage = _uniqueStorage() + return try _elements.withUnsafeMutableBufferPointer { keys in + assert(keys.count == values.count) + var low = keys.startIndex + var high = keys.endIndex + + while true { + // Invariants at this point: + // - low <= high + // - all elements in `startIndex ..< low` belong in the first partition + // - all elements in `high ..< endIndex` belong in the second partition + + // Find next element from `lo` that may not be in the right place. + while true { + if low == high { return low } + if try belongsInSecondPartition((keys[low], values[low])) { break } + low += 1 + } + + // Find next element down from `hi` that we can swap `lo` with. + while true { + high -= 1 + if low == high { return low } + if try !belongsInSecondPartition((keys[high], values[high])) { break } + } + + // Swap the two elements as well as their associated hash table buckets. + keys.swapAt(low, high) + values.swapAt(low, high) + storage?.update { hashTable in + hashTable.swapBucketValues(for: keys[low], withCurrentValue: high, + and: keys[high], withCurrentValue: low) + } + low += 1 + } + } + } +} diff --git a/Sources/UniquedModule/Uniqued+Partial RangeReplaceableCollection.swift b/Sources/UniquedModule/Uniqued+Partial RangeReplaceableCollection.swift new file mode 100644 index 00000000..171d1600 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Partial RangeReplaceableCollection.swift @@ -0,0 +1,115 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// The parts of RangeReplaceableCollection that Uniqued is able to implement. + +extension Uniqued where Base: RangeReplaceableCollection { + public mutating func reserveCapacity(_ minimumCapacity: Int) { + precondition(minimumCapacity >= 0, "Minimum capacity cannot be negative") + _elements.reserveCapacity(minimumCapacity) + let currentScale = _scale + let newScale = _UnsafeHashTable.scale(forCapacity: minimumCapacity) + let minScale = _UnsafeHashTable.scale(forCapacity: self.count) + if currentScale < newScale { + // Grow the table. + _regenerateHashTable(scale: newScale, reservedScale: newScale) + } else if newScale < currentScale, minScale < currentScale { + // Shrink the table. + _regenerateHashTable(scale: minScale, reservedScale: newScale) + } + if _reservedScale != newScale { + // Remember reserved scale. + _ensureUnique() + _storage!.header.reservedScale = newScale + } + _checkInvariants() + } + + public mutating func removeAll(keepingCapacity keepCapacity: Bool = false) { + _elements.removeAll(keepingCapacity: keepCapacity) + guard keepCapacity else { + _storage = nil + return + } + _ensureUnique() + _storage!.update { hashTable in + hashTable.clear() + } + } + + public mutating func remove(at index: Index) -> Self.Element { + _elements._failEarlyRangeCheck(index, bounds: startIndex ..< endIndex) + let bucket = _bucket(for: index) + return _removeExistingMember(at: index, bucket: bucket) + } + + public mutating func removeSubrange(_ bounds: Range) { + _elements._failEarlyRangeCheck(bounds, bounds: _elements.startIndex ..< _elements.endIndex) + guard _storage != nil else { + _elements.removeSubrange(bounds) + _checkInvariants() + return + } + let startOffset = _elements._offset(of: bounds.lowerBound) + let endOffset = _elements._offset(of: bounds.upperBound) + let c = endOffset - startOffset + guard c > 0 else { return } + let remainingCount = _elements.count - c + if remainingCount <= count / 2 || remainingCount < _minimumCapacity { + // Just generate a new table from scratch. + _elements.removeSubrange(bounds) + _regenerateHashTable() + _checkInvariants() + return + } + + _ensureUnique() + _storage!.update { hashTable in + // Delete the hash table entries for all members we're removing. + for item in _elements[bounds] { + let (offset, bucket) = hashTable._find(item, in: _elements) + precondition(offset != nil, "Corrupt hash table") + hashTable.delete( + bucket: bucket, + hashValueGenerator: { offset, seed in + let index = _elements._index(at: offset) + return _elements[index]._rawHashValue(seed: seed) + }) + } + hashTable.adjustContents(preparingForRemovalOf: bounds, in: _elements) + } + _elements.removeSubrange(bounds) + _checkInvariants() + } + + public mutating func removeLast() -> Element { + precondition(!isEmpty, "Cannot remove last element of an empty collection") + return remove(at: self._index(at: count - 1)) + } + + public mutating func removeLast(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the collection") + removeSubrange(self._index(at: count - n) ..< self._index(at: count)) + } + + @discardableResult + public mutating func removeFirst() -> Element { + precondition(!isEmpty, "Cannot remove first element of an empty collection") + return remove(at: startIndex) + } + + public mutating func removeFirst(_ n: Int) { + precondition(n >= 0, "Can't remove a negative number of elements") + precondition(n <= count, "Can't remove more elements than there are in the collection") + removeSubrange(self._index(at: 0) ..< self._index(at: n)) + } +} diff --git a/Sources/UniquedModule/Uniqued+Partial SetAlgebra.swift b/Sources/UniquedModule/Uniqued+Partial SetAlgebra.swift new file mode 100644 index 00000000..6510a282 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Partial SetAlgebra.swift @@ -0,0 +1,514 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// `Uniqued` does not directly conform to `SetAlgebra` because its definition +// of equality conflicts with `SetAlgebra` requirements. However, it still +// implements most `SetAlgebra` requirements (except `insert`, which is replaced +// by `append`). +// +// `Uniqued` also provides an `unordered` view that explicitly conforms to +// `SetAlgebra`. That view implements `Equatable` by ignoring element order, +// so it can satisfy `SetAlgebra` requirements. + +extension Uniqued where Base: RangeReplaceableCollection { + public init() { + _storage = nil + _elements = Base() + } + + public init(_ elements: S) where S.Element == Element { + if S.self == Self.self { + self = elements as! Self + return + } + if S.self == Set.self { + // Fast path for when we know elements are all unique + self.init(uncheckedUniqueElements: Base(elements)) + return + } + + self.init() + append(contentsOf: elements) + } + + // Specializations + + public init(_ elements: Self) { + self = elements + } + + public init(_ elements: SubSequence) { + self.init(uncheckedUniqueElements: Base(elements._slice)) + } + + public init(_ elements: Set) { + self.init(uncheckedUniqueElements: Base(elements)) + } + + public init(_ elements: Base) { + let (storage, firstDupe) = _HashTableStorage.create( + from: elements, + stoppingOnFirstDuplicateValue: true) + if firstDupe == elements.endIndex { + // Fast path: `elements` consists of unique values. + self.init(_uniqueElements: elements, storage: storage) + return + } + + // Otherwise keep the elements we've processed and add the rest one by one. + var contents = elements + contents.removeLast(elements.count - elements._offset(of: firstDupe)) + self.init(_uniqueElements: contents, storage: storage) + self.append(contentsOf: elements[firstDupe...]) + } + + public init(_ elements: Dictionary.Keys) { + self._elements = Base(elements) + _regenerateHashTable() + _checkInvariants() + } +} + +extension Uniqued { + public func contains(_ element: Element) -> Bool { + guard let storage = _storage else { + return _elements.contains(element) + } + return storage.read { hashTable in + hashTable._find(element, in: _elements).offset != nil + } + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + @discardableResult + public mutating func remove(_ member: Element) -> Element? { + let (idx, bucket) = _find(member) + guard let index = idx else { return nil } + return _removeExistingMember(at: index, bucket: bucket) + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + public mutating func formUnion(_ other: __owned Self) { + for item in other { + append(item) + } + } + + public __consuming func union(_ other: __owned Self) -> Self { + var result = self + result.formUnion(other) + return result + } + + // Generalizations + + @inline(__always) + public mutating func formUnion(_ other: __owned UnorderedView) { + formUnion(other._base) + } + + @inline(__always) + public __consuming func union(_ other: __owned UnorderedView) -> Self { + union(other._base) + } + + public mutating func formUnion( + _ other: __owned S + ) where S.Element == Element { + for item in other { + append(item) + } + } + + public __consuming func union( + _ other: __owned S + ) -> Self where S.Element == Element { + var result = self + result.formUnion(other) + return result + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + public __consuming func intersection(_ other: Self) -> Self { + var result = Self() + for item in self { + if other.contains(item) { + result._appendNew(item) + } + } + return result + } + + public mutating func formIntersection(_ other: Self) { + self = self.intersection(other) + } + + // Generalizations + + @inline(__always) + public __consuming func intersection(_ other: UnorderedView) -> Self { + intersection(other._base) + } + + @inline(__always) + public mutating func formIntersection(_ other: UnorderedView) { + formIntersection(other._base) + } + + public __consuming func intersection( + _ other: S + ) -> Self where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: self.count) { bitset in + for item in other { + if let index = self.firstIndex(of: item) { + bitset.insert(_elements._offset(of: index)) + } + } + return self._extractSubset(using: bitset) + } + } + + public mutating func formIntersection( + _ other: S + ) where S.Element == Element { + self = self.intersection(other) + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + public __consuming func symmetricDifference(_ other: __owned Self) -> Self { + _UnsafeBitset.withTemporaryBitset(capacity: self.count) { bitset1 in + _UnsafeBitset.withTemporaryBitset(capacity: other.count) { bitset2 in + bitset1.insertAll(upTo: self.count) + for item in other { + if let offset = self._offset(of: item) { + bitset1.remove(offset) + } + } + bitset2.insertAll(upTo: other.count) + for item in self { + if let offset = other._offset(of: item) { + bitset2.remove(offset) + } + } + var result = self._extractSubset(using: bitset1, + extraCapacity: bitset2.count) + for offset in bitset2 { + let index = other._elements._index(at: offset) + result._appendNew(other._elements[index]) + } + return result + } + } + } + + public mutating func formSymmetricDifference(_ other: __owned Self) { + self = self.symmetricDifference(other) + } + + // Generalizations + + @inline(__always) + public __consuming func symmetricDifference(_ other: __owned UnorderedView) -> Self { + symmetricDifference(other._base) + } + + @inline(__always) + public mutating func formSymmetricDifference(_ other: __owned UnorderedView) { + formSymmetricDifference(other._base) + } + + public __consuming func symmetricDifference( + _ other: __owned S + ) -> Self where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: self.count) { bitset in + var new = Self() + bitset.insertAll(upTo: self.count) + for item in other { + if let offset = self._offset(of: item) { + bitset.remove(offset) + } else { + new.append(item) + } + } + var result = Self(minimumCapacity: bitset.count + new.count) + for offset in bitset { + let index = self._elements._index(at: offset) + result._appendNew(self._elements[index]) + } + for item in new._elements { + result._appendNew(item) + } + return result + } + } + + public mutating func formSymmetricDifference( + _ other: __owned S + ) where S.Element == Element { + self = self.symmetricDifference(other) + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + @inline(__always) + public __consuming func subtracting(_ other: Self) -> Self { + _subtracting(other) + } + + @inline(__always) + public mutating func subtract(_ other: Self) { + self = subtracting(other) + } + + // Generalizations + + @inline(__always) + public __consuming func subtracting(_ other: UnorderedView) -> Self { + subtracting(other._base) + } + + @inline(__always) + public mutating func subtract(_ other: UnorderedView) { + subtract(other._base) + } + + @inline(__always) + public __consuming func subtracting( + _ other: S + ) -> Self where S.Element == Element { + _subtracting(other) + } + + @inline(__always) + public mutating func subtract( + _ other: S + ) where S.Element == Element { + self = _subtracting(other) + } + + __consuming func _subtracting( + _ other: S + ) -> Self where S.Element == Element { + guard count > 0 else { return Self() } + return _UnsafeBitset.withTemporaryBitset(capacity: count) { difference in + difference.insertAll(upTo: count) + for item in other { + if let offset = self._offset(of: item) { + if difference.remove(offset), difference.count == 0 { + return Self() + } + } + } + assert(difference.count > 0) + return _extractSubset(using: difference) + } + } +} + +extension Uniqued { + public func isSubset(of other: Self) -> Bool { + guard other.count >= self.count else { return false } + for item in self { + guard other.contains(item) else { return false } + } + return true + } + + // Generalizations + + @inline(__always) + public func isSubset(of other: UnorderedView) -> Bool { + isSubset(of: other._base) + } + + public func isSubset(of other: Set) -> Bool { + guard other.count >= self.count else { return false } + for item in self { + guard other.contains(item) else { return false } + } + return true + } + + public func isSubset( + of other: S + ) -> Bool where S.Element == Element { + guard !isEmpty else { return true } + return _UnsafeBitset.withTemporaryBitset(capacity: count) { seen in + // Mark elements in `self` that we've seen in `other`. + for item in other { + if let offset = _offset(of: item) { + if seen.insert(offset), seen.count == self.count { + // We've seen enough. + return true + } + } + } + return false + } + } +} + +extension Uniqued { + public func isSuperset(of other: Self) -> Bool { + other.isSubset(of: self) + } + + // Generalizations + + public func isSuperset(of other: UnorderedView) -> Bool { + isSuperset(of: other._base) + } + + public func isSuperset(of other: Set) -> Bool { + guard self.count >= other.count else { return false } + return _isSuperset(of: other) + } + + public func isSuperset( + of other: S + ) -> Bool where S.Element == Element { + _isSuperset(of: other) + } + + internal func _isSuperset( + of other: S + ) -> Bool where S.Element == Element { + for item in other { + guard self.contains(item) else { return false } + } + return true + } +} + +extension Uniqued { + public func isStrictSubset(of other: Self) -> Bool { + self.count < other.count && self.isSubset(of: other) + } + + // Generalizations + + @inline(__always) + public func isStrictSubset(of other: UnorderedView) -> Bool { + isStrictSubset(of: other._base) + } + + public func isStrictSubset(of other: Set) -> Bool { + self.count < other.count && self.isSubset(of: other) + } + + public func isStrictSubset( + of other: S + ) -> Bool where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: count) { seen in + // Mark elements in `self` that we've seen in `other`. + var isKnownStrict = false + for item in other { + if let offset = _offset(of: item) { + if seen.insert(offset), seen.count == self.count, isKnownStrict { + // We've seen enough. + return true + } + } else { + if !isKnownStrict, seen.count == self.count { return true } + isKnownStrict = true + } + } + return false + } + } +} + +extension Uniqued { + public func isStrictSuperset(of other: Self) -> Bool { + self.count > other.count && other.isSubset(of: self) + } + + // Generalizations + + @inline(__always) + public func isStrictSuperset(of other: UnorderedView) -> Bool { + isStrictSuperset(of: other._base) + } + + public func isStrictSuperset(of other: Set) -> Bool { + self.count > other.count && other.isSubset(of: self) + } + + public func isStrictSuperset( + of other: S + ) -> Bool where S.Element == Element { + _UnsafeBitset.withTemporaryBitset(capacity: count) { seen in + // Mark elements in `self` that we've seen in `other`. + for item in other { + guard let offset = _offset(of: item) else { + return false + } + if seen.insert(offset), seen.count == self.count { + // We've seen enough. + return false + } + } + return seen.count < self.count + } + } +} + +extension Uniqued { + public func isDisjoint(with other: Self) -> Bool { + guard !self.isEmpty && !other.isEmpty else { return true } + if self.count <= other.count { + for item in self { + if other.contains(item) { return false } + } + } else { + for item in other { + if self.contains(item) { return false } + } + } + return true + } + + // Generalizations + + @inline(__always) + public func isDisjoint(with other: UnorderedView) -> Bool { + isDisjoint(with: other._base) + } + + public func isDisjoint(with other: Set) -> Bool { + guard !self.isEmpty && !other.isEmpty else { return true } + if self.count <= other.count { + for item in self { + if other.contains(item) { return false } + } + } else { + for item in other { + if self.contains(item) { return false } + } + } + return true + } + + public func isDisjoint( + with other: S + ) -> Bool where S.Element == Element { + guard !self.isEmpty else { return true } + for item in other { + if self.contains(item) { return false } + } + return true + } +} + diff --git a/Sources/UniquedModule/Uniqued+RandomAccessCollection.swift b/Sources/UniquedModule/Uniqued+RandomAccessCollection.swift new file mode 100644 index 00000000..21069700 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+RandomAccessCollection.swift @@ -0,0 +1,77 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: RandomAccessCollection { + public typealias Index = Base.Index + public typealias Indices = Base.Indices + // For SubSequence, see Uniqued+SubSequence.swift. + + public var startIndex: Index { _elements.startIndex } + public var endIndex: Index { _elements.endIndex } + public var indices: Indices { _elements.indices } + + public func index(after i: Index) -> Index { _elements.index(after: i) } + public func index(before i: Index) -> Index { _elements.index(before: i) } + public func formIndex(after i: inout Index) { _elements.formIndex(after: &i) } + public func formIndex(before i: inout Index) { _elements.formIndex(before: &i) } + + public func index(_ i: Index, offsetBy distance: Int) -> Index { + _elements.index(i, offsetBy: distance) + } + + public func index(_ i: Index, offsetBy distance: Int, limitedBy limit: Index) -> Index? { + _elements.index(i, offsetBy: distance, limitedBy: limit) + } + + public func distance(from start: Index, to end: Index) -> Int { + _elements.distance(from: start, to: end) + } + + public subscript(position: Index) -> Element { + _elements[position] + } + + public subscript(bounds: Range) -> SubSequence { + _failEarlyRangeCheck(bounds, bounds: startIndex ..< endIndex) + return SubSequence(base: self, bounds: bounds) + } + + public var isEmpty: Bool { _elements.isEmpty } + public var count: Int { _elements.count } + + public func _customIndexOfEquatableElement(_ element: Element) -> Index?? { + guard let storage = _storage else { + return _elements._customIndexOfEquatableElement(element) + } + return storage.read { hashTable in + let (o, _) = hashTable._find(element, in: _elements) + guard let offset = o else { return .some(nil) } + return _elements._index(at: offset) + } + } + + public func _customLastIndexOfEquatableElement(_ element: Element) -> Index?? { + // Uniqued holds unique elements. + _customIndexOfEquatableElement(element) + } + + public func _failEarlyRangeCheck(_ index: Index, bounds: Range) { + _elements._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck(_ index: Index, bounds: ClosedRange) { + _elements._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck(_ range: Range, bounds: Range) { + _elements._failEarlyRangeCheck(range, bounds: bounds) + } +} diff --git a/Sources/UniquedModule/Uniqued+Sequence.swift b/Sources/UniquedModule/Uniqued+Sequence.swift new file mode 100644 index 00000000..4df06bcf --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Sequence.swift @@ -0,0 +1,39 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued: Sequence { + public typealias Element = Base.Element + public typealias Iterator = Base.Iterator + + public func makeIterator() -> Iterator { + _elements.makeIterator() + } + + public func _customContainsEquatableElement(_ element: Element) -> Bool? { + _find(element).index != nil + } + + public __consuming func _copyToContiguousArray() -> ContiguousArray { + _elements._copyToContiguousArray() + } + + public __consuming func _copyContents( + initializing ptr: UnsafeMutableBufferPointer + ) -> (Iterator, UnsafeMutableBufferPointer.Index) { + _elements._copyContents(initializing: ptr) + } + + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + try _elements.withContiguousStorageIfAvailable(body) + } +} diff --git a/Sources/UniquedModule/Uniqued+SubSequence.swift b/Sources/UniquedModule/Uniqued+SubSequence.swift new file mode 100644 index 00000000..61a20471 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+SubSequence.swift @@ -0,0 +1,124 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued { + public struct SubSequence { + internal var _startIndex: Base.Index + internal var _endIndex: Base.Index + internal var _base: Uniqued + + public init(base: Uniqued, bounds: Range) { + self._base = base + self._startIndex = bounds.lowerBound + self._endIndex = bounds.upperBound + } + } +} + +extension Uniqued.SubSequence { + internal var _slice: Base.SubSequence { + _base._elements[_startIndex ..< _endIndex] + } + + internal func _index(of element: Element) -> Index? { + guard let index = _base._find(element).index else { return nil } + guard _startIndex <= index && index < _endIndex else { return nil } + return index + } +} + +extension Uniqued.SubSequence: Sequence { + public typealias Element = Base.Element + public typealias Iterator = Base.SubSequence.Iterator + + public func makeIterator() -> Iterator { + _slice.makeIterator() + } + + public func _customContainsEquatableElement(_ element: Element) -> Bool? { + _index(of: element) != nil + } + + public __consuming func _copyToContiguousArray() -> ContiguousArray { + _slice._copyToContiguousArray() + } + + public __consuming func _copyContents( + initializing ptr: UnsafeMutableBufferPointer + ) -> (Iterator, UnsafeMutableBufferPointer.Index) { + _slice._copyContents(initializing: ptr) + } + + public func withContiguousStorageIfAvailable( + _ body: (UnsafeBufferPointer) throws -> R + ) rethrows -> R? { + try _slice.withContiguousStorageIfAvailable(body) + } +} + +extension Uniqued.SubSequence: RandomAccessCollection { + public typealias Index = Base.Index + public typealias Indices = Base.SubSequence.Indices + public typealias SubSequence = Self + + public var startIndex: Index { _startIndex } + public var endIndex: Index { _endIndex } + public var indices: Indices { _slice.indices } + + public func index(after i: Index) -> Index { _slice.index(after: i) } + public func index(before i: Index) -> Index { _slice.index(before: i) } + public func formIndex(after i: inout Index) { _slice.formIndex(after: &i) } + public func formIndex(before i: inout Index) { _slice.formIndex(before: &i) } + + public func index(_ i: Index, offsetBy distance: Int) -> Index { + _slice.index(i, offsetBy: distance) + } + + public func index(_ i: Index, offsetBy distance: Int, limitedBy limit: Index) -> Index? { + _slice.index(i, offsetBy: distance, limitedBy: limit) + } + + public func distance(from start: Index, to end: Index) -> Int { + _slice.distance(from: start, to: end) + } + + public subscript(position: Index) -> Element { + _slice[position] + } + + public subscript(bounds: Range) -> SubSequence { + _failEarlyRangeCheck(bounds, bounds: startIndex ..< endIndex) + return SubSequence(base: _base, bounds: bounds) + } + + public var isEmpty: Bool { _startIndex == _endIndex } + public var count: Int { distance(from: _startIndex, to: _endIndex) } + + public func _customIndexOfEquatableElement(_ element: Element) -> Index?? { + .some(_index(of: element)) + } + + public func _customLastIndexOfEquatableElement(_ element: Element) -> Index?? { + .some(_index(of: element)) + } + + public func _failEarlyRangeCheck(_ index: Index, bounds: Range) { + _slice._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck(_ index: Index, bounds: ClosedRange) { + _slice._failEarlyRangeCheck(index, bounds: bounds) + } + + public func _failEarlyRangeCheck(_ range: Range, bounds: Range) { + _slice._failEarlyRangeCheck(range, bounds: bounds) + } +} diff --git a/Sources/UniquedModule/Uniqued+Testing.swift b/Sources/UniquedModule/Uniqued+Testing.swift new file mode 100644 index 00000000..6094a0a9 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+Testing.swift @@ -0,0 +1,141 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension _Bucket: CustomStringConvertible { + public var description: String { "Bucket(@\(offset))"} +} + +extension _UnsafeHashTable: CustomStringConvertible { + public var description: String { + var d = """ + _UnsafeHashTable\(_header.pointee._description) + load factor: \(debugLoadFactor()) + """ + if bucketCount < 128 { + d += "\n " + d += debugContents() + .lazy + .map { $0 == nil ? "_" : "\($0!)" } + .joined(separator: " ") + } + return d + } + + internal func debugOccupiedCount() -> Int { + var count = 0 + var it = bucketIterator(startingAt: _Bucket(offset: 0)) + repeat { + if it.isOccupied { + count += 1 + } + it.advance() + } while it.currentBucket.offset != 0 + return count + } + + internal func debugLoadFactor() -> Double { + return Double(debugOccupiedCount()) / Double(bucketCount) + } + + internal func debugContents() -> [Int?] { + var result: [Int?] = [] + result.reserveCapacity(bucketCount) + var it = bucketIterator(startingAt: _Bucket(offset: 0)) + repeat { + result.append(it.currentValue) + it.advance() + } while it.currentBucket.offset != 0 + return result + } +} + +extension _UnsafeHashTable.BucketIterator: CustomStringConvertible { + var description: String { + func pad(_ s: String, to length: Int, by padding: Character = " ") -> String { + let c = s.count + guard c < length else { return s } + return String(repeating: padding, count: length - c) + s + } + let offset = pad(String(_currentBucket.offset), to: 4) + let value: String + if let v = currentValue { + value = pad(String(v), to: 4) + } else { + value = " nil" + } + let remainingBits = pad(String(_nextBits, radix: 2), to: _remainingBitCount, by: "0") + return "BucketIterator(scale: \(_scale), bucket: \(offset), value: \(value), bits: \(remainingBits) (\(_remainingBitCount) bits))" + } +} + +extension Uniqued { + @_spi(Testing) public var _hasHashTable: Bool { _storage != nil } + + @_spi(Testing) public var _hashTableIdentity: ObjectIdentifier? { + guard let storage = _storage else { return nil } + return ObjectIdentifier(storage) + } + + @_spi(Testing) public var _hashTableContents: [Int?] { + _storage!.read { hashTable in + hashTable.debugContents() + } + } + + @_spi(Testing) mutating public func _regenerateHashTable(bias: Int) { + _ensureUnique() + let new = _storage!.copy() + _storage!.read { source in + new.update { target in + target.bias = bias + var it = source.bucketIterator(startingAt: _Bucket(offset: 0)) + repeat { + target[it.currentBucket] = it.currentValue + it.advance() + } while it.currentBucket.offset != 0 + } + } + _storage = new + } +} + +extension Uniqued { + @_spi(Testing) public init( + _scale scale: Int, + bias: Int, + contents: Base + ) { + precondition(scale >= _UnsafeHashTable.scale(forCapacity: contents.count)) + precondition(scale <= _UnsafeHashTable.maximumScale) + precondition(bias >= 0 && _UnsafeHashTable.biasRange(scale: scale).contains(bias)) + precondition(scale >= _UnsafeHashTable.minimumScale || bias == 0) + let storage = _HashTableStorage.create(scale: Swift.max(scale, _UnsafeHashTable.minimumScale)) + storage.header.bias = bias + let (success, index) = storage.update { hashTable in + hashTable.fill(from: contents, stoppingOnFirstDuplicateValue: true) + } + precondition(success, "Duplicate element at index \(index)") + _storage = scale < _UnsafeHashTable.minimumScale ? nil : storage + _elements = contents + precondition(self._scale == scale) + precondition(self._bias == bias) + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + @_spi(Testing) public init( + _scale scale: Int, + bias: Int, + contents: C + ) where C.Element == Element { + self.init(_scale: scale, bias: bias, contents: Base(contents)) + } +} diff --git a/Sources/UniquedModule/Uniqued+UnorderedView.swift b/Sources/UniquedModule/Uniqued+UnorderedView.swift new file mode 100644 index 00000000..1fd498d6 --- /dev/null +++ b/Sources/UniquedModule/Uniqued+UnorderedView.swift @@ -0,0 +1,368 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension Uniqued { + public struct UnorderedView { + public typealias Element = Base.Element + + internal var _base: Uniqued + + internal init(_base: Uniqued) { + self._base = _base + } + } + + @inline(__always) + public init(_ view: UnorderedView) { + self = view._base + } + + public var unordered: UnorderedView { + _read { + yield UnorderedView(_base: self) + } + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + public var unordered: UnorderedView { + get { + UnorderedView(_base: self) + } + _modify { + var view = UnorderedView(_base: self) + self = Uniqued() + defer { self = view._base } + yield &view + } + } +} + +extension Uniqued.UnorderedView: CustomStringConvertible { + public var description: String { + _base.description + } +} + +extension Uniqued.UnorderedView: CustomDebugStringConvertible { + public var debugDescription: String { + _base._debugDescription(typeName: "\(_base._debugTypeName()).UnorderedView") + } +} + +extension Uniqued.UnorderedView: Equatable { + public static func ==(left: Self, right: Self) -> Bool { + if left._base._hasHashTable && left._base._storage === right._base._storage { + return true + } + guard left._base.count == right._base.count else { return false } + + for item in left._base { + if !right._base.contains(item) { return false } + } + return true + } +} + +extension Uniqued.UnorderedView: Hashable { + public func hash(into hasher: inout Hasher) { + // Generate a seed from a snapshot of the hasher. This makes members' hash + // values depend on the state of the hasher, which improves hashing + // quality. (E.g., it makes it possible to resolve collisions by passing in + // a different hasher.) + let copy = hasher + let seed = copy.finalize() + + var hash = 0 + for member in _base { + hash ^= member._rawHashValue(seed: seed) + } + hasher.combine(hash) + } +} + +extension Uniqued.UnorderedView: ExpressibleByArrayLiteral where Base: RangeReplaceableCollection { + @inline(__always) + public init(arrayLiteral elements: Element...) { + _base = Uniqued(elements) + } +} + +extension Uniqued.UnorderedView: SetAlgebra +where Base: RangeReplaceableCollection & MutableCollection { +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + public init() { + _base = Uniqued() + } + + public init(_ elements: S) where S.Element == Element { + _base = Uniqued(elements) + } + + // Specializations + + public init(_ elements: Self) { + self = elements + } + + public init(_ elements: Set) { + self._base = Uniqued(elements) + } + + public init(_ elements: Dictionary.Keys) { + self._base = Uniqued(elements) + } +} + +extension Uniqued.UnorderedView { + public func contains(_ element: Element) -> Bool { + _base.contains(element) + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + public mutating func insert( + _ newMember: __owned Element + ) -> (inserted: Bool, memberAfterInsert: Element) { + let (inserted, index) = _base.append(newMember) + return (inserted, _base[index]) + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection & MutableCollection { + public mutating func update(with newMember: __owned Element) -> Element? { + let (inserted, index) = _base.append(newMember) + if inserted { return nil } + let old = _base._elements[index] + _base._elements[index] = newMember + return old + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + @inline(__always) + @discardableResult + public mutating func remove(_ member: Self.Element) -> Self.Element? { + _base.remove(member) + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + @inline(__always) + public mutating func formUnion(_ other: __owned Self) { + _base.formUnion(other._base) + } + + @inline(__always) + public __consuming func union(_ other: __owned Self) -> Self { + _base.union(other._base).unordered + } + + // Generalizations + + @inline(__always) + public mutating func formUnion( + _ other: __owned S + ) where S.Element == Element { + _base.formUnion(other) + } + + @inline(__always) + public __consuming func union( + _ other: __owned S + ) -> Self where S.Element == Element { + _base.union(other).unordered + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + @inline(__always) + public __consuming func intersection(_ other: Self) -> Self { + _base.intersection(other._base).unordered + } + + @inline(__always) + public mutating func formIntersection(_ other: Self) { + _base.formIntersection(other._base) + } + + // Generalizations + + @inline(__always) + public __consuming func intersection( + _ other: S + ) -> Self where S.Element == Element { + _base.intersection(other).unordered + } + + @inline(__always) + public mutating func formIntersection( + _ other: S + ) where S.Element == Element { + _base.formIntersection(other) + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + @inline(__always) + public __consuming func symmetricDifference(_ other: __owned Self) -> Self { + _base.symmetricDifference(other._base).unordered + } + + @inline(__always) + public mutating func formSymmetricDifference(_ other: __owned Self) { + _base.formSymmetricDifference(other._base) + } + + // Generalizations + + @inline(__always) + public __consuming func symmetricDifference( + _ other: __owned S + ) -> Self where S.Element == Element { + _base.symmetricDifference(other).unordered + } + + @inline(__always) + public mutating func formSymmetricDifference( + _ other: __owned S + ) where S.Element == Element { + _base.formSymmetricDifference(other) + } +} + +extension Uniqued.UnorderedView where Base: RangeReplaceableCollection { + @inline(__always) + public __consuming func subtracting(_ other: Self) -> Self { + _base.subtracting(other._base).unordered + } + + @inline(__always) + public mutating func subtract(_ other: Self) { + _base.subtract(other._base) + } + + // Generalizations + @inline(__always) + public __consuming func subtracting( + _ other: S + ) -> Self where S.Element == Element { + _base.subtracting(other).unordered + } + + @inline(__always) + public mutating func subtract( + _ other: S + ) where S.Element == Element { + _base.subtract(other) + } +} + +extension Uniqued.UnorderedView { + @inline(__always) + public func isSubset(of other: Self) -> Bool { + _base.isSubset(of: other._base) + } + + // Generalizations + + @inline(__always) + public func isSubset(of other: Set) -> Bool { + _base.isSubset(of: other) + } + + @inline(__always) + public func isSubset( + of other: S + ) -> Bool where S.Element == Element { + _base.isSubset(of: other) + } +} + +extension Uniqued.UnorderedView { + @inline(__always) + public func isSuperset(of other: Self) -> Bool { + _base.isSuperset(of: other._base) + } + + // Generalizations + + @inline(__always) + public func isSuperset(of other: Set) -> Bool { + _base.isSuperset(of: other) + } + + @inline(__always) + public func isSuperset( + of other: S + ) -> Bool where S.Element == Element { + _base.isSuperset(of: other) + } +} + +extension Uniqued.UnorderedView { + @inline(__always) + public func isStrictSubset(of other: Self) -> Bool { + _base.isStrictSubset(of: other._base) + } + + // Generalizations + + @inline(__always) + public func isStrictSubset(of other: Set) -> Bool { + _base.isStrictSubset(of: other) + } + + @inline(__always) + public func isStrictSubset( + of other: S + ) -> Bool where S.Element == Element { + _base.isStrictSubset(of: other) + } +} + +extension Uniqued.UnorderedView { + public func isStrictSuperset(of other: Self) -> Bool { + _base.isStrictSuperset(of: other._base) + } + + // Generalizations + + public func isStrictSuperset(of other: Set) -> Bool { + _base.isStrictSuperset(of: other) + } + + public func isStrictSuperset( + of other: S + ) -> Bool where S.Element == Element { + _base.isStrictSuperset(of: other) + } +} + +extension Uniqued.UnorderedView { + public func isDisjoint(with other: Self) -> Bool { + _base.isDisjoint(with: other._base) + } + + // Generalizations + + public func isDisjoint(with other: Set) -> Bool { + _base.isDisjoint(with: other) + } + + public func isDisjoint( + with other: S + ) -> Bool where S.Element == Element { + _base.isDisjoint(with: other) + } +} diff --git a/Sources/UniquedModule/Uniqued.swift b/Sources/UniquedModule/Uniqued.swift new file mode 100644 index 00000000..b4247670 --- /dev/null +++ b/Sources/UniquedModule/Uniqued.swift @@ -0,0 +1,203 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// An ordered collection of unique elements. +public struct Uniqued +where Base: RandomAccessCollection, Base.Element: Hashable +{ + internal var _storage: _HashTableStorage? + internal var _elements: Base + + internal init(_uniqueElements: Base, storage: _HashTableStorage? = nil) { + self._storage = storage + self._elements = _uniqueElements + } +} + +extension Uniqued { + public var contents: Base { + _elements + } +} + +extension Uniqued { + /// The maximum number of elements this instance can store before it needs + /// to resize its hash table. + @_spi(Testing) public var _capacity: Int { + _storage?.header.capacity ?? _UnsafeHashTable.maximumUnhashedCount + } + + @_spi(Testing) public var _minimumCapacity: Int { + if _scale == _reservedScale { return 0 } + return _UnsafeHashTable.minimumCapacity(forScale: _scale) + } + + @_spi(Testing) public var _scale: Int { + _storage?.header.scale ?? 0 + } + + @_spi(Testing) public var _reservedScale: Int { + _storage?.header.reservedScale ?? 0 + } + + @_spi(Testing) public var _bias: Int { + _storage?.header.bias ?? 0 + } +} + +extension Uniqued { + internal mutating func _regenerateHashTable(scale: Int, reservedScale: Int) { + assert(_UnsafeHashTable.maximumCapacity(forScale: scale) >= _elements.count) + assert(reservedScale == 0 || reservedScale >= _UnsafeHashTable.minimumScale) + if scale < _UnsafeHashTable.minimumScale && reservedScale == 0 { + _storage = nil + return + } + _storage = _HashTableStorage.create( + from: _elements, + scale: Swift.max(scale, reservedScale), + reservedScale: reservedScale, + stoppingOnFirstDuplicateValue: false).storage + } + + internal mutating func _regenerateHashTable() { + let reservedScale = _reservedScale + guard + _elements.count > _UnsafeHashTable.maximumUnhashedCount || reservedScale != 0 + else { + // We have too few elements; disable hashing. + _storage = nil + return + } + let scale = _UnsafeHashTable.scale(forCapacity: _elements.count) + _regenerateHashTable(scale: scale, reservedScale: reservedScale) + } + + internal mutating func _regenerateExistingHashTable() { + assert(_capacity >= _elements.count) + guard _storage != nil else { + return + } + _ensureUnique() + _storage!.update { hashTable in + hashTable.clear() + hashTable.fill(from: _elements, stoppingOnFirstDuplicateValue: false) + } + } + + internal mutating func _isUnique() -> Bool { + isKnownUniquelyReferenced(&_storage) + } + + internal mutating func _ensureUnique() { + if isKnownUniquelyReferenced(&_storage) { return } + _storage = _storage!.copy() + } + + internal mutating func _uniqueStorage() -> _HashTableStorage? { + if _storage == nil { return nil } + _ensureUnique() + return _storage + } +} + +extension Uniqued { + @_spi(UnsafeInternals) + public func _find(_ item: Element) -> (index: Index?, bucket: _Bucket) { + guard let storage = _storage else { + return (_elements.firstIndex(of: item), _Bucket(offset: 0)) + } + return storage.read { hashTable in + let (offset, bucket) = hashTable._find(item, in: _elements) + return (offset.map { _elements._index(at: $0) }, bucket) + } + } + + internal func _offset(of element: Element) -> Int? { + guard let storage = _storage else { + return _elements.firstIndex(of: element).map { _elements._offset(of: $0) } + } + return storage.read { hashTable in + hashTable._find(element, in: _elements).offset + } + } + + internal func _bucket(for index: Index) -> _Bucket { + guard let storage = _storage else { return _Bucket(offset: 0) } + return storage.read { hashTable in + var it = hashTable.bucketIterator(for: _elements[index]) + let offset = _elements._offset(of: index) + it.advance(until: offset) + precondition(it.isOccupied, "Corrupt hash table") + return it.currentBucket + } + } + + public func firstIndex(of element: Element) -> Index? { + _find(element).index + } + + public func lastIndex(of element: Element) -> Index? { + _find(element).index + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + internal __consuming func _extractSubset( + using bitset: _UnsafeBitset, + extraCapacity: Int = 0 + ) -> Self { + assert(bitset.count == 0 || bitset.max()! <= count) + if bitset.count == 0 { return Self() } + if bitset.count == self.count { return self } + var result = Self() + result.reserveCapacity(bitset.count + extraCapacity) + result._storage?.header.reservedScale = 0 + for offset in bitset { + let index = _elements._index(at: offset) + result._appendNew(_elements[index]) + } + assert(result.count == bitset.count) + return result + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + @_spi(UnsafeInternals) + @discardableResult + public mutating func _removeExistingMember( + at index: Index, + bucket: _Bucket + ) -> Element { + guard _elements.count - 1 >= _minimumCapacity else { + let old = _elements.remove(at: index) + _regenerateHashTable() + return old + } + guard _storage != nil else { + return _elements.remove(at: index) + } + + defer { _checkInvariants() } + _ensureUnique() + _storage!.update { hashTable in + // Delete the entry for the removed member. + hashTable.delete( + bucket: bucket, + hashValueGenerator: { offset, seed in + let index = _elements._index(at: offset) + return _elements[index]._rawHashValue(seed: seed) + }) + hashTable.adjustContents(preparingForRemovalOf: index, in: _elements) + } + return _elements.remove(at: index) + } +} diff --git a/Sources/UniquedModule/_Bucket.swift b/Sources/UniquedModule/_Bucket.swift new file mode 100644 index 00000000..128e7ea8 --- /dev/null +++ b/Sources/UniquedModule/_Bucket.swift @@ -0,0 +1,32 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// Identifies a particular bucket within a hash table by its offset. +/// Having a dedicated wrapper type for this prevents passing a bucket number +/// to a function that expects a word index, or vice versa. +@_spi(UnsafeInternals) @_spi(Testing) +public struct _Bucket { + /// The distance of this bucket from the first bucket in the hash table. + internal var offset: Int + + @inline(__always) + internal init(offset: Int) { + assert(offset >= 0) + self.offset = offset + } +} + +extension _Bucket: Equatable { + @inline(__always) + public static func == (left: Self, right: Self) -> Bool { + left.offset == right.offset + } +} diff --git a/Sources/UniquedModule/_HashTableStorage.swift b/Sources/UniquedModule/_HashTableStorage.swift new file mode 100644 index 00000000..dee26a99 --- /dev/null +++ b/Sources/UniquedModule/_HashTableStorage.swift @@ -0,0 +1,108 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// A class holding hash table storage for a `Uniqued` collection. +/// Values in the hash table are offsets into separate element storage, so +/// this class doesn't need to be generic over `Uniqued`'s `Element` type. +internal final class _HashTableStorage: ManagedBuffer<_HashTableHeader, UInt64> { + /// Allocate a new empty hash table buffer of the specified scale. + static func create(scale: Int, reservedScale: Int = 0) -> _HashTableStorage { + assert(scale >= _UnsafeHashTable.minimumScale && scale <= _UnsafeHashTable.maximumScale) + let wordCount = _UnsafeHashTable.wordCount(forScale: scale) + let storage = self.create( + minimumCapacity: wordCount, + makingHeaderWith: { object in + #if COLLECTIONS_DETERMINISTIC_HASHING + let seed = scale << 6 + #else + let seed = Int(bitPattern: Unmanaged.passUnretained(object).toOpaque()) + #endif + return _HashTableHeader(scale: scale, reservedScale: reservedScale, seed: seed) + }) + storage.withUnsafeMutablePointerToElements { elements in + elements.initialize(repeating: 0, count: wordCount) + } + return unsafeDowncast(storage, to: _HashTableStorage.self) + } + + /// Populate a new hash table with data from `self`. + /// + /// - Parameter scale: The desired hash table scale or nil to use the minimum scale that satisfies invariants. + /// - Parameter reservedScale: The reserved scale to remember in the returned storage. + /// - Parameter duplicates: The strategy to use to handle duplicate items. + /// - Returns: `(storage, index)` where `storage` is a storage instance. The contents of `storage` reflects all elements in `contents[contents.startIndex ..< index]`. `index` is usually `contents.endIndex`, except when the function was asked to reject duplicates, in which case `index` addresses the first duplicate element in `contents` (if any). + static func create( + from contents: C, + scale: Int? = nil, + reservedScale: Int = 0, + stoppingOnFirstDuplicateValue: Bool = true + ) -> (storage: _HashTableStorage, end: C.Index) + where C.Element: Hashable { + let minScale = _UnsafeHashTable.scale(forCapacity: contents.count) + let scale = scale ?? Swift.max(Swift.max(minScale, reservedScale), + _UnsafeHashTable.minimumScale) + assert(scale >= minScale && scale >= reservedScale) + let storage = _HashTableStorage.create(scale: scale, reservedScale: reservedScale) + let (_, index) = storage.update { hashTable in + hashTable.fill( + from: contents, + stoppingOnFirstDuplicateValue: stoppingOnFirstDuplicateValue) + } + return (storage, index) + } + + /// Create and return a new copy of this instance. The result has the same + /// scale and seed, and contains the exact same bucket data as the original instance. + internal func copy() -> _HashTableStorage { + self.read { hashTable in + let wordCount = hashTable.wordCount + let new = Self.create( + minimumCapacity: wordCount, + makingHeaderWith: { _ in hashTable._header.pointee }) + new.withUnsafeMutablePointerToElements { elements in + elements.initialize(from: hashTable._buckets, count: wordCount) + } + return unsafeDowncast(new, to: _HashTableStorage.self) + } + } + + /// Call `body` with a hash table handle suitable for read-only use. + /// + /// - Warning: The handle supplied to `body` is only valid for the duration of + /// the closure call. The closure must not escape it outside the call. + @inline(__always) + internal func read(_ body: (_UnsafeHashTable) throws -> R) rethrows -> R { + return try self.withUnsafeMutablePointers { header, elements in + let hashTable = _UnsafeHashTable(header: header, buckets: elements, readonly: true) + defer { withExtendedLifetime(self) {} } + return try body(hashTable) + } + } + + /// Call `body` with a hash table handle suitable for mutating use. + /// + /// - Warning: The handle supplied to `body` is only valid for the duration of + /// the closure call. The closure must not escape it outside the call. + @inline(__always) + internal func update(_ body: (_UnsafeHashTable) throws -> R) rethrows -> R { + return try self.withUnsafeMutablePointers { header, elements in + let hashTable = _UnsafeHashTable(header: header, buckets: elements, readonly: false) + defer { withExtendedLifetime(self) {} } + return try body(hashTable) + } + } +} + +extension _HashTableStorage: CustomStringConvertible { + internal var description: String { + "_HashTableStorage\(header._description)" + } +} diff --git a/Sources/UniquedModule/_HashtableHeader.swift b/Sources/UniquedModule/_HashtableHeader.swift new file mode 100644 index 00000000..ef1af955 --- /dev/null +++ b/Sources/UniquedModule/_HashtableHeader.swift @@ -0,0 +1,98 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// The storage header for hash table buffers. +/// +/// Note that we don't store the number of items currently in the table; +/// that information can be easily retrieved from the element storage. +internal struct _HashTableHeader { + /// We are packing the scale data into the lower bits of the seed & bias + /// to saves a bit of space that would be otherwise taken up by padding. + /// + /// Layout: + /// + /// 63 6 5 0 + /// ├──────────────────────────────────────────────┼────────┤ + /// │ seed │ scale │ + /// └──────────────────────────────────────────────┴────────┘ + /// 63 6 5 0 + /// ├──────────────────────────────────────────────┼────────┤ + /// │ bias │ rsvd │ + /// └──────────────────────────────────────────────┴────────┘ + var _scaleAndSeed: UInt64 + var _reservedScaleAndBias: UInt64 + + init(scale: Int, reservedScale: Int, seed: Int) { + assert(scale >= _UnsafeHashTable.minimumScale && scale <= _UnsafeHashTable.maximumScale) + assert(reservedScale >= 0 && reservedScale <= _UnsafeHashTable.maximumScale) + _scaleAndSeed = UInt64(truncatingIfNeeded: seed) << (Swift.max(UInt64.bitWidth - Int.bitWidth, 6)) + _scaleAndSeed &= ~0x3F + _scaleAndSeed |= UInt64(truncatingIfNeeded: scale) + _reservedScaleAndBias = UInt64(truncatingIfNeeded: reservedScale) + assert(self.scale == scale) + assert(self.reservedScale == reservedScale) + assert(self.bias == 0) + } + + /// The scale of the hash table. A table of scale *n* holds 2^*n* buckets, + /// each of which contain an *n*-bit value. + @inline(__always) + var scale: Int { Int(_scaleAndSeed & 0x3F) } + + /// The scale corresponding to the last call to `reserveCapacity`. + /// We remember this here to make sure we don't shrink the table below its reserved size. + var reservedScale: Int { + @inline(__always) + get { Int(_reservedScaleAndBias & 0x3F) } + set { + assert(newValue >= 0 && newValue < 64) + _reservedScaleAndBias &= ~0x3F + _reservedScaleAndBias |= UInt64(truncatingIfNeeded: newValue) & 0x3F + } + } + + /// The hasher seed to use within this hash table. + @inline(__always) + var seed: Int { + Int(truncatingIfNeeded: _scaleAndSeed) + } + + /// A bias value that needs to be added to buckets to convert them into offsets + /// into element storage. (This allows O(1) insertions at the front when the + /// underlying storage supports it.) + var bias: Int { + @inline(__always) + get { Int(truncatingIfNeeded: _reservedScaleAndBias) &>> 6 } + set { + let limit = (1 &<< scale) - 1 + var bias = newValue + if bias < 0 { bias += limit } + if bias >= limit { bias -= limit } + assert(bias >= 0 && bias < limit) + _reservedScaleAndBias &= 0x3F + _reservedScaleAndBias |= UInt64(truncatingIfNeeded: bias) &<< 6 + assert(self.bias >= 0 && self.bias < limit) + } + } + + /// The maximum number of items that can fit into this table. + var capacity: Int { _UnsafeHashTable.maximumCapacity(forScale: scale) } +} + +extension _HashTableHeader: CustomStringConvertible { + internal var _description: String { + "(scale: \(scale), reservedScale: \(reservedScale), bias: \(bias), seed: \(String(seed, radix: 16)))" + } + + internal var description: String { + "_HashTableHeader\(_description)" + } +} diff --git a/Sources/UniquedModule/_UnsafeBitset.swift b/Sources/UniquedModule/_UnsafeBitset.swift new file mode 100644 index 00000000..079a2b90 --- /dev/null +++ b/Sources/UniquedModule/_UnsafeBitset.swift @@ -0,0 +1,321 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// A simple bitmap of a fixed number of bits, implementing a sorted set of +/// small nonnegative `Int` values. +/// +/// Because `_UnsafeBitset` implements a flat bit vector, it isn't suitable for +/// holding arbitrarily large integers. The maximal element a bitset can store +/// is fixed at its initialization. +internal struct _UnsafeBitset { + internal let _words: UnsafeMutableBufferPointer + internal var _count: Int + + @inline(__always) + internal init(words: UnsafeMutableBufferPointer, count: Int) { + self._words = words + self._count = count + } + + @inline(__always) + internal init(words: UnsafeMutablePointer, wordCount: Int, count: Int) { + self._words = UnsafeMutableBufferPointer(start: words, count: wordCount) + self._count = count + } + + @inline(__always) + internal var count: Int { + _count + } +} + +extension _UnsafeBitset { + internal var _actualCount: Int { + return _words.reduce(0) { $0 + $1.count } + } +} + +extension _UnsafeBitset { + static func withTemporaryBitset( + capacity: Int, + run body: (inout _UnsafeBitset) throws -> R + ) rethrows -> R { + let wordCount = _UnsafeBitset.wordCount(forCapacity: capacity) + if wordCount <= 2 { + var buffer: (Word, Word) = (.empty, .empty) + return try withUnsafeMutablePointer(to: &buffer) { p in + // Homogeneous tuples are layout-compatible with their component type. + let words = UnsafeMutableRawPointer(p).assumingMemoryBound(to: Word.self) + var bitset = _UnsafeBitset(words: words, wordCount: wordCount, count: 0) + return try body(&bitset) + } + } + let words = UnsafeMutableBufferPointer.allocate(capacity: wordCount) + words.initialize(repeating: .empty) + defer { words.deallocate() } + var bitset = _UnsafeBitset(words: words, count: 0) + return try body(&bitset) + } +} + +extension _UnsafeBitset { + @inline(__always) + internal static func word(for element: Int) -> Int { + assert(element >= 0) + // Note: We perform on UInts to get faster unsigned math (shifts). + let element = UInt(bitPattern: element) + let capacity = UInt(bitPattern: Word.capacity) + return Int(bitPattern: element / capacity) + } + + @inline(__always) + internal static func bit(for element: Int) -> Int { + assert(element >= 0) + // Note: We perform on UInts to get faster unsigned math (masking). + let element = UInt(bitPattern: element) + let capacity = UInt(bitPattern: Word.capacity) + return Int(bitPattern: element % capacity) + } + + @inline(__always) + internal static func split(_ element: Int) -> (word: Int, bit: Int) { + return (word(for: element), bit(for: element)) + } + + @inline(__always) + internal static func join(word: Int, bit: Int) -> Int { + assert(bit >= 0 && bit < Word.capacity) + return word &* Word.capacity &+ bit + } +} + +extension _UnsafeBitset { + @inline(__always) + internal static func wordCount(forCapacity capacity: Int) -> Int { + return word(for: capacity &+ Word.capacity &- 1) + } + + internal var capacity: Int { + @inline(__always) + get { + return _words.count &* Word.capacity + } + } + + @inline(__always) + internal func isValid(_ element: Int) -> Bool { + return element >= 0 && element < capacity + } + + @inline(__always) + internal func contains(_ element: Int) -> Bool { + assert(isValid(element)) + let (word, bit) = _UnsafeBitset.split(element) + return _words[word].contains(bit) + } + + @discardableResult + internal mutating func insert(_ element: Int) -> Bool { + assert(isValid(element)) + let (word, bit) = _UnsafeBitset.split(element) + let inserted = _words[word].insert(bit) + if inserted { _count += 1 } + return inserted + } + + @discardableResult + internal mutating func remove(_ element: Int) -> Bool { + assert(isValid(element)) + let (word, bit) = _UnsafeBitset.split(element) + let removed = _words[word].remove(bit) + if removed { _count -= 1 } + return removed + } + + internal mutating func clear() { + guard _words.count > 0 else { return } + _words.baseAddress!.assign(repeating: .empty, count: _words.count) + _count = 0 + } + + internal mutating func insertAll(upTo max: Int) { + assert(max <= capacity) + guard max > 0 else { return } + let (w, b) = _UnsafeBitset.split(max) + for i in 0 ..< w { + _count += Word.capacity - _words[i].count + _words[i] = .allBits + } + if b > 0 { + _count += _words[w].insert(bitsBelow: b) + } + } + + internal mutating func removeAll(upTo max: Int) { + assert(max <= capacity) + guard max > 0 else { return } + let (w, b) = _UnsafeBitset.split(max) + for i in 0 ..< w { + _count -= _words[i].count + _words[i] = .empty + } + if b > 0 { + _count -= _words[w].remove(bitsBelow: b) + } + } +} + +extension _UnsafeBitset: Sequence { + internal typealias Element = Int + + internal var underestimatedCount: Int { + return count + } + + func makeIterator() -> Iterator { + return Iterator(self) + } + + internal struct Iterator: IteratorProtocol { + @usableFromInline + internal let bitset: _UnsafeBitset + @usableFromInline + internal var index: Int + @usableFromInline + internal var word: Word + + @inlinable + internal init(_ bitset: _UnsafeBitset) { + self.bitset = bitset + self.index = 0 + self.word = bitset._words.count > 0 ? bitset._words[0] : .empty + } + + internal mutating func next() -> Int? { + if let bit = word.next() { + return _UnsafeBitset.join(word: index, bit: bit) + } + while (index + 1) < bitset._words.count { + index += 1 + word = bitset._words[index] + if let bit = word.next() { + return _UnsafeBitset.join(word: index, bit: bit) + } + } + return nil + } + } +} + +//////////////////////////////////////////////////////////////////////////////// +extension _UnsafeBitset { + internal struct Word { + internal var value: UInt + + internal init(_ value: UInt) { + self.value = value + } + } +} + +extension _UnsafeBitset.Word { + @inline(__always) + internal static var capacity: Int { + return UInt.bitWidth + } + + @inline(__always) + internal var count: Int { + value.nonzeroBitCount + } + + @inline(__always) + internal var isEmpty: Bool { + value == 0 + } + + @inline(__always) + internal func contains(_ bit: Int) -> Bool { + assert(bit >= 0 && bit < UInt.bitWidth) + return value & (1 &<< bit) != 0 + } + + @inline(__always) + @discardableResult + internal mutating func insert(_ bit: Int) -> Bool { + assert(bit >= 0 && bit < UInt.bitWidth) + let mask: UInt = 1 &<< bit + let inserted = value & mask == 0 + value |= mask + return inserted + } + + @inline(__always) + @discardableResult + internal mutating func remove(_ bit: Int) -> Bool { + assert(bit >= 0 && bit < UInt.bitWidth) + let mask: UInt = 1 &<< bit + let removed = value & mask != 0 + value &= ~mask + return removed + } +} + +extension _UnsafeBitset.Word { + @inline(__always) + internal mutating func insert(bitsBelow bit: Int) -> Int { + assert(bit >= 0 && bit < Self.capacity) + let mask: UInt = (1 as UInt &<< bit) &- 1 + let inserted = bit - (value & mask).nonzeroBitCount + value |= mask + return inserted + } + + @inline(__always) + internal mutating func remove(bitsBelow bit: Int) -> Int { + assert(bit >= 0 && bit < Self.capacity) + let mask = UInt.max &<< bit + let removed = (value & ~mask).nonzeroBitCount + value &= mask + return removed + } +} + +extension _UnsafeBitset.Word { + @inline(__always) + internal static var empty: Self { + Self(0) + } + + @inline(__always) + internal static var allBits: Self { + Self(UInt.max) + } +} + +// Word implements Sequence by using a copy of itself as its Iterator. +// Iteration with `next()` destroys the word's value; however, this won't cause +// problems in normal use, because `next()` is usually called on a separate +// iterator, not the original word. +extension _UnsafeBitset.Word: Sequence, IteratorProtocol { + internal var underestimatedCount: Int { + count + } + + /// Return the index of the lowest set bit in this word, + /// and also destructively clear it. + internal mutating func next() -> Int? { + guard value != 0 else { return nil } + let bit = value.trailingZeroBitCount + value &= value &- 1 // Clear lowest nonzero bit. + return bit + } +} diff --git a/Sources/UniquedModule/_UnsafeHashTable.swift b/Sources/UniquedModule/_UnsafeHashTable.swift new file mode 100644 index 00000000..e465ed41 --- /dev/null +++ b/Sources/UniquedModule/_UnsafeHashTable.swift @@ -0,0 +1,707 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +/// A non-owning handle to hash table storage, implementing higher-level table operations. +/// +/// - Warning: `_UnsafeHashTable` values do not have ownership of their underlying storage buffer. +/// You must not escape these handles outside the closure call that produced them. +@_spi(Testing) public struct _UnsafeHashTable { + /// A pointer to the table header. + internal var _header: UnsafeMutablePointer<_HashTableHeader> + + /// A pointer to bucket storage. + internal var _buckets: UnsafeMutablePointer + + #if DEBUG + /// True when this handle does not support table mutations. + /// (This is only checked in debug builds.) + internal let _readonly: Bool + #endif + + /// Initialize a new hash table handle for storage at the supplied locations. + @inline(__always) + internal init( + header: UnsafeMutablePointer<_HashTableHeader>, + buckets: UnsafeMutablePointer, + readonly: Bool + ) { + self._header = header + self._buckets = buckets + #if DEBUG + self._readonly = readonly + #endif + } + + /// Check that this handle supports mutating operations. + /// Every member that mutates table data must start by calling this function. + /// This helps preventing COW violations. + /// + /// Note that this is a noop in release builds. + @inline(__always) + func assertMutable() { + #if DEBUG + assert(!_readonly, "Attempt to mutate a hash table through a read-only handle") + #endif + } +} + +extension _UnsafeHashTable { + /// The minimum hash table scale. + @inline(__always) + @_spi(Testing) + public static var minimumScale: Int { 5 } + + /// The maximum hash table scale. + @inline(__always) + @_spi(Testing) + public static var maximumScale: Int { + Swift.min(Int.bitWidth, 56) + } + + /// The maximum number of items for which we do not create a hash table. + @inline(__always) + @_spi(Testing) + public static var maximumUnhashedCount: Int { + (1 &<< (minimumScale - 1)) - 1 + } + + /// The maximum hash table load factor. + @inline(__always) + static var maximumLoadFactor: Double { 3 / 4 } + + /// The minimum hash table load factor. + @inline(__always) + static var minimumLoadFactor: Double { 1 / 4 } + + /// The maximum number of items that can be held in a hash table of the given scale. + @_spi(Testing) + public static func maximumCapacity(forScale scale: Int) -> Int { + guard scale >= minimumScale else { return maximumUnhashedCount } + let bucketCount = 1 &<< scale + return Int(Double(bucketCount) * maximumLoadFactor) + } + + /// The maximum number of items that can be held in a hash table of the given scale. + @_spi(Testing) + public static func minimumCapacity(forScale scale: Int) -> Int { + guard scale >= minimumScale else { return 0 } + let bucketCount = 1 &<< scale + return Int(Double(bucketCount) * minimumLoadFactor) + } + + /// The minimum hash table scale that can hold the specified number of elements. + @_spi(Testing) + public static func scale(forCapacity capacity: Int) -> Int { + guard capacity > maximumUnhashedCount else { return 0 } + let capacity = Swift.max(capacity, 1) + // Calculate the minimum number of entries we need to allocate to satisfy + // the maximum load factor. `capacity + 1` below ensures that we always + // leave at least one hole. + let minimumEntries = Swift.max( + Int((Double(capacity) / maximumLoadFactor).rounded(.up)), + capacity + 1) + // The actual number of entries we need to allocate is the lowest power of + // two greater than or equal to the minimum entry count. Calculate its + // exponent. + let scale = (Swift.max(minimumEntries, 2) - 1)._binaryLogarithm() + 1 + assert(scale >= minimumScale && scale < Int.bitWidth) + // The scale is the exponent corresponding to the bucket count. + assert(self.maximumCapacity(forScale: scale) >= capacity) + return scale + } + + @_spi(Testing) + public static func biasRange(scale: Int) -> Range { + guard scale != 0 else { return 0 ..< 1 } + return 0 ..< (1 &<< scale) - 1 + } + + /// The count of 64-bit words that a hash table of the specified scale + /// will need to have in its storage. + internal static func wordCount(forScale scale: Int) -> Int { + ((scale &<< scale) + UInt64.bitWidth - 1) / UInt64.bitWidth + } +} + +extension _UnsafeHashTable { + /// The scale of the hash table. A table of scale *n* holds 2^*n* buckets, + /// each of which contain an *n*-bit value. + @inline(__always) + internal var scale: Int { _header.pointee.scale } + + /// The scale corresponding to the last call to `reserveCapacity`. + /// We store this to make sure we don't shrink the table below its reserved size. + @inline(__always) + internal var reservedScale: Int { + get { _header.pointee.reservedScale } + nonmutating set { _header.pointee.reservedScale = newValue } + } + + /// The hasher seed to use within this hash table. + @inline(__always) + internal var seed: Int { _header.pointee.seed } + + /// A bias value that needs to be added to buckets to convert them into offsets + /// into element storage. (This allows O(1) insertions at the front when the + /// underlying storage supports it.) + @inline(__always) + internal var bias: Int { + get { _header.pointee.bias } + nonmutating set { _header.pointee.bias = newValue } + } + + /// The number of buckets within this hash table. This is always a power of two. + @inline(__always) + internal var bucketCount: Int { 1 &<< scale } + + @inline(__always) + internal var bucketMask: UInt64 { UInt64(truncatingIfNeeded: bucketCount) - 1 } + + /// The number of bits used to store all the buckets in this hash table. + /// Each bucket holds a value that is `scale` bits wide. + @inline(__always) + internal var bitCount: Int { scale &<< scale } + + /// The number of 64-bit words that are available in the storage buffer, + /// rounded up to the nearest whole number if necessary. + @inline(__always) + internal var wordCount: Int { (bitCount + UInt64.bitWidth - 1) / UInt64.bitWidth } + + /// The maximum number of items that can fit into this table. + @inline(__always) + internal var capacity: Int { _UnsafeHashTable.maximumCapacity(forScale: scale) } + + /// Return the bucket logically following `bucket` in this hash table. + /// The buckets form a cycle, so the last bucket is logically followed by the first. + @inline(__always) + func bucket(after bucket: _Bucket) -> _Bucket { + var offset = bucket.offset + 1 + if offset == bucketCount { + offset = 0 + } + return _Bucket(offset: offset) + } + + /// Return the bucket logically preceding `bucket` in this hash table. + /// The buckets form a cycle, so the first bucket is logically preceded by the last. + @inline(__always) + func bucket(before bucket: _Bucket) -> _Bucket { + let offset = (bucket.offset == 0 ? bucketCount : bucket.offset) - 1 + return _Bucket(offset: offset) + } + + /// Return the index of the word logically following `word` in this hash table. + /// The buckets form a cycle, so the last word is logically followed by the first. + /// + /// Note that the last word may be only partially filled if `scale` is less than 6. + @inline(__always) + func word(after word: Int) -> Int { + var result = word + 1 + if result == wordCount { + result = 0 + } + return result + } + + /// Return the index of the word logically preceding `word` in this hash table. + /// The buckets form a cycle, so the first word is logically preceded by the first. + /// + /// Note that the last word may be only partially filled if `scale` is less than 6. + @inline(__always) + func word(before word: Int) -> Int { + if word == 0 { + return wordCount - 1 + } + return word - 1 + } + + /// Return the index of the 64-bit storage word that holds the first bit + /// corresponding to `bucket`, along with its bit position within the word. + internal func position(of bucket: _Bucket) -> (word: Int, bit: Int) { + let start = bucket.offset &* scale + return (start &>> 6, start & 0x3F) + } +} + +extension _UnsafeHashTable { + /// Decode and return the logical value corresponding to the specified bucket value. + /// + /// The nil value is represented by an all-zero bit pattern. + /// Other values are stored as the complement of the lowest `scale` bits + /// after taking `bias` into account. + /// The range of representable values is `0 ..< bucketCount - 1`. + /// (Note that the value `bucketCount - 1` is missing from this range, as its + /// encoding is used for `nil`. This isn't an issue, because the maximum load + /// factor guarantees that the hash table will never be completely full.) + func _value(forBucketContents bucketContents: UInt64) -> Int? { + let mask = bucketMask + assert(bucketContents <= mask) + guard bucketContents != 0 else { return nil } + let v = (bucketContents ^ mask) &+ UInt64(truncatingIfNeeded: bias) + return Int(truncatingIfNeeded: v >= mask ? v - mask : v) + } + + /// Encodes the specified logical value into a `scale`-bit bit pattern suitable + /// for storing into a bucket. + /// + /// The nil value is represented by an all-zero bit pattern. + /// Other values are stored as the complement of their lowest `scale` bits. + /// The range of representable values is `0 ..< bucketCount - 1`. + /// (Note that the value `bucketCount - 1` is missing from this range, as it + /// its encoding is used for `nil`. This isn't an issue, because the maximum + /// load factor guarantees that the hash table will never be completely full.) + func _bucketContents(for value: Int?) -> UInt64 { + guard var value = value else { return 0 } + let mask = Int(truncatingIfNeeded: bucketMask) + assert(value >= 0 && value < mask) + value &-= bias + if value < 0 { value += mask } + assert(value >= 0 && value < mask) + return UInt64(truncatingIfNeeded: value ^ mask) + } + + subscript(word word: Int) -> UInt64 { + @inline(__always) get { + assert(word >= 0 && word < bucketCount) + return _buckets[word] + } + @inline(__always) nonmutating set { + assert(word >= 0 && word < bucketCount) + assertMutable() + _buckets[word] = newValue + } + } + + subscript(raw bucket: _Bucket) -> UInt64 { + get { + assert(bucket.offset < bucketCount) + let (word, bit) = position(of: bucket) + var value = self[word: word] &>> bit + let extractedBits = 64 - bit + if extractedBits < scale { + let word2 = self.word(after: word) + value &= (1 &<< extractedBits) - 1 + value |= self[word: word2] &<< extractedBits + } + return value & bucketMask + } + nonmutating set { + assertMutable() + assert(bucket.offset < bucketCount) + let mask = bucketMask + assert(newValue <= mask) + let (word, bit) = position(of: bucket) + self[word: word] &= ~(mask &<< bit) + self[word: word] |= newValue &<< bit + let extractedBits = 64 - bit + if extractedBits < scale { + let word2 = self.word(after: word) + self[word: word2] &= ~((1 &<< (scale - extractedBits)) - 1) + self[word: word2] |= newValue &>> extractedBits + } + } + } + + func isOccupied(_ bucket: _Bucket) -> Bool { + self[raw: bucket] != 0 + } + + /// Return or update the current value stored in the specified bucket. + /// A nil value indicates that the bucket is empty. + subscript(bucket: _Bucket) -> Int? { + get { + let contents = self[raw: bucket] + return _value(forBucketContents: contents) + } + nonmutating set { + assertMutable() + let v = _bucketContents(for: newValue) + self[raw: bucket] = v + } + } +} + +extension _UnsafeHashTable { + /// An infinite iterator construct for visiting a chain of buckets within the hash table. + /// This is a convenient tool for linear probing. + /// + /// Beyond merely providing bucket values, bucket iterators can also tell + /// you their current oposition within the hash table, and (for mutable hash tables) + /// they allow you update the value of the currently visited bucket. + /// (This is useful when implementing simple insertions, for example.) + /// + /// The bucket iterator caches some bucket contents, so if you are looping over an iterator + /// you must be careful to only modify hash table contents through the iterator itself. + /// + /// - Warning: Like `_UnsafeHashTable` itself, `BucketIterator` does not have + /// ownership of its underlying storage buffer. You must not escape iterator + /// values outside the closure call that produced the original hash table. + struct BucketIterator { + /// The hash table we are iterating over. + let _hashTable: _UnsafeHashTable + + /// The current position within the hash table. + var _currentBucket: _Bucket + + /// The raw bucket value corresponding to `_currentBucket`. + var _currentRawValue: UInt64 + + /// Remaining bits not yet processed from the last word read. + var _nextBits: UInt64 + + /// Count of usable bits in `_nextBits`. (They start at bit 0.) + var _remainingBitCount: Int + + /// Create a new iterator starting at the specified bucket. + init(hashTable: _UnsafeHashTable, startingAt bucket: _Bucket) { + assert(hashTable.scale >= _UnsafeHashTable.minimumScale) + assert(bucket.offset >= 0 && bucket.offset < hashTable.bucketCount) + self._hashTable = hashTable + self._currentBucket = bucket + var (word, bit) = hashTable.position(of: bucket) + + // The `scale == 5` case is special because the last word is only half filled there, + // which is why the code below needs to special case it. + // (For all scales > 5, the last bucket ends exactly on a word boundary.) + + if bit + hashTable.scale <= 64 { + // We're in luck, the current bucket is stored entirely within one word. + let w = _hashTable[word: word] + _currentRawValue = (w &>> bit) & _hashTable.bucketMask + let c = (hashTable.scale == 5 && word == hashTable.wordCount - 1 ? 32 : 64) + self._remainingBitCount = c - (bit + hashTable.scale) + self._nextBits = (_remainingBitCount == 0 ? 0 : w &>> (bit + hashTable.scale)) + assert(_remainingBitCount >= 0) + assert(bit < c) + } else { + // We need to read two words. + assert(hashTable.scale != 5 || word < hashTable.wordCount - 1) + assert(bit > 0) + let w1 = _hashTable[word: word] + word = hashTable.word(after: word) + let w2 = _hashTable[word: word] + self._currentRawValue = ((w1 &>> bit) | (w2 &<< (64 - bit))) & _hashTable.bucketMask + let overhang = hashTable.scale - (64 - bit) + self._nextBits = w2 &>> overhang + let c = (hashTable.scale == 5 && word == hashTable.wordCount - 1 ? 32 : 64) + self._remainingBitCount = c - overhang + } + assert(_currentRawValue <= _hashTable.bucketMask) + } + + /// The scale of the hash table. A table of scale *n* holds 2^*n* buckets, + /// each of which contain an *n*-bit value. + @inline(__always) + var _scale: Int { _hashTable.scale } + + /// The current position within the hash table. + @inline(__always) + var currentBucket: _Bucket { _currentBucket } + + var isOccupied: Bool { + _currentRawValue != 0 + } + + /// The value of the bucket at the current position in the hash table. + /// Setting this property overwrites the bucket value. + /// + /// A nil value indicates an empty bucket. + var currentValue: Int? { + @inline(__always) + get { _hashTable._value(forBucketContents: _currentRawValue) } + set { + _hashTable.assertMutable() + let v = _hashTable._bucketContents(for: newValue) + let pattern = v ^ _currentRawValue + + assert(_currentBucket.offset < _hashTable.bucketCount) + let (word, bit) = _hashTable.position(of: _currentBucket) + _hashTable[word: word] ^= pattern &<< bit + let extractedBits = 64 - bit + if extractedBits < _scale { + let word2 = _hashTable.word(after: word) + _hashTable[word: word2] ^= pattern &>> extractedBits + } + _currentRawValue = v + } + } + + /// Advance this iterator to the next bucket within the hash table. + /// The buckets form a cycle, so the last bucket is logically followed + /// by the first. Therefore, the iterator never runs out of buckets -- + /// you must devise some way to guarantee to stop iterating. + /// + /// In the typical case, you stop iterating buckets when you find the + /// element you're looking for, or when you run across an empty bucket + /// (terminating the chain with a negative lookup result). + mutating func advance() { + _currentBucket = _hashTable.bucket(after: _currentBucket) + if _remainingBitCount >= _scale { + _currentRawValue = _nextBits & _hashTable.bucketMask + _nextBits &>>= _scale + _remainingBitCount -= _scale + return + } + var word = _hashTable.position(of: _currentBucket).word + if _remainingBitCount != 0 { + word = _hashTable.word(after: word) + } + let c = (_hashTable.scale == 5 && word == _hashTable.wordCount - 1 ? 32 : 64) + let w = _hashTable[word: word] + _currentRawValue = (_nextBits | (w &<< _remainingBitCount)) & _hashTable.bucketMask + _nextBits = w &>> (_scale - _remainingBitCount) + _remainingBitCount = c - (_scale - _remainingBitCount) + } + + /// Advance this iterator until it points to an occupied bucket with the + /// specified value, or an unoccupied bucket -- whichever comes first. + mutating func advance(until expected: Int) { + while isOccupied && currentValue != expected { + advance() + } + } + + /// Advance this iterator until it points to an unoccupied bucket. + /// Useful when inserting an element that we know isn't already in the table. + mutating func advanceToNextUnoccupiedBucket() { + while isOccupied { + advance() + } + } + } + + @inline(__always) + func idealBucket(forHashValue hashValue: Int) -> _Bucket { + return _Bucket(offset: hashValue & (bucketCount - 1)) + } + + @inline(__always) + func idealBucket(for element: Element) -> _Bucket { + let hashValue = element._rawHashValue(seed: seed) + return idealBucket(forHashValue: hashValue) + } + + /// Return a bucket iterator for the chain starting at the bucket corresponding + /// to the specified value. + @inline(__always) + func bucketIterator(for element: Element) -> BucketIterator { + let bucket = idealBucket(for: element) + return bucketIterator(startingAt: bucket) + } + + /// Return a bucket iterator for the chain starting at the specified bucket. + @inline(__always) + func bucketIterator(startingAt bucket: _Bucket) -> BucketIterator { + BucketIterator(hashTable: self, startingAt: bucket) + } +} + +extension _UnsafeHashTable { + internal func _find( + _ item: Base.Element, + in elements: Base + ) -> (offset: Int?, bucket: _Bucket) + where Base.Element: Hashable { + var iterator = self.bucketIterator(for: item) + let start = iterator.currentBucket + repeat { + guard let offset = iterator.currentValue else { + return (nil, iterator.currentBucket) + } + if elements[_offset: offset] == item { + return (offset, iterator.currentBucket) + } + iterator.advance() + } while iterator.currentBucket.offset != start.offset + fatalError("Hash table has no unoccupied buckets") + } +} + +extension _UnsafeHashTable { + internal func firstUnoccupiedBucket(before bucket: _Bucket) -> _Bucket { + var bucket = bucket + repeat { + bucket = self.bucket(before: bucket) + } while isOccupied(bucket) + return bucket + } + + internal func delete( + bucket: _Bucket, + hashValueGenerator: (Int, Int) -> Int // (offset, seed) -> hashValue + ) { + assertMutable() + var it = bucketIterator(startingAt: bucket) + assert(it.isOccupied) + it.advance() + guard it.isOccupied else { + // Fast path: Don't get the start bucket when there's nothing to do. + self[bucket] = nil + return + } + // If we've put a hole in the middle of a collision chain, some element after + // the hole may belong where the new hole is. + + // Find the first bucket in the collision chain that contains the entry we've just deleted. + let start = self.bucket(after: firstUnoccupiedBucket(before: bucket)) + var hole = bucket + + while it.isOccupied { + let hash = hashValueGenerator(it.currentValue!, seed) + let candidate = idealBucket(forHashValue: hash) + + // Does this element belong between start and hole? We need two + // separate tests depending on whether [start, hole] wraps around the + // end of the storage. + let c0 = candidate.offset >= start.offset + let c1 = candidate.offset <= hole.offset + if start.offset <= hole.offset ? (c0 && c1) : (c0 || c1) { + // Fill the hole. Here we are mutating table contents behind the back of + // the iterator; this is okay since we know we are never going to revisit + // `hole` with it. + self[hole] = it.currentValue + hole = it.currentBucket + } + it.advance() + } + self[hole] = nil + } +} + +extension _UnsafeHashTable { + internal func adjustContents( + preparingForInsertionOfElementAtOffset offset: Int, + in elements: Base + ) where Base.Element: Hashable { + assertMutable() + let index = elements._index(at: offset) + if offset < elements.count / 2 { + self.bias += 1 + if offset <= capacity / 8 { + var i = 1 + for item in elements[..= offset else { continue } + it.currentValue = value + 1 + } while it.currentBucket.offset != 0 + } + } + } +} + +extension _UnsafeHashTable { + @inline(__always) + internal func adjustContents( + preparingForRemovalOf index: Base.Index, + in elements: Base + ) where Base.Element: Hashable { + let next = elements.index(after: index) + adjustContents(preparingForRemovalOf: index ..< next, in: elements) + } + + internal func adjustContents( + preparingForRemovalOf bounds: Range, + in elements: Base + ) where Base.Element: Hashable { + assertMutable() + let startOffset = elements._offset(of: bounds.lowerBound) + let endOffset = elements._offset(of: bounds.upperBound) + let c = endOffset - startOffset + guard c > 0 else { return } + let remainingCount = elements.count - c + + if startOffset >= remainingCount / 2 { + var i = endOffset + for item in elements[bounds.upperBound...] { + var it = self.bucketIterator(for: item) + it.advance(until: i) + it.currentValue = i - c + i += 1 + } + } else { + var i = 0 + for item in elements[..( + from elements: C, + stoppingOnFirstDuplicateValue: Bool = true + ) -> (success: Bool, end: C.Index) + where C.Element: Hashable { + assertMutable() + assert(elements.count <= capacity) + // Iterate over elements and insert their offset into the hash table. + var offset = 0 + loop: for index in elements.indices { + // Find the insertion position. We know that we're inserting a new item, + // so there is no need to compare it with any of the existing ones. + var it = bucketIterator(for: elements[index]) + if stoppingOnFirstDuplicateValue { + while let offset = it.currentValue { + guard elements[_offset: offset] != elements[index] else { + return (false, index) + } + it.advance() + } + } else { + it.advanceToNextUnoccupiedBucket() + } + it.currentValue = offset + offset += 1 + } + return (true, elements.endIndex) + } +} diff --git a/Tests/DequeTests/DequeInternals.swift b/Tests/DequeTests/DequeInternals.swift new file mode 100644 index 00000000..67ab3c8d --- /dev/null +++ b/Tests/DequeTests/DequeInternals.swift @@ -0,0 +1,83 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsTestSupport +@_spi(Testing) import DequeModule + +internal struct DequeLayout: CustomStringConvertible { + let capacity: Int + let startSlot: Int + let count: Int + let startValue: Int + + init(capacity: Int, startSlot: Int, count: Int, startValue: Int = 0) { + self.capacity = capacity + self.startSlot = startSlot + self.count = count + self.startValue = startValue + } + + var valueRange: Range { startValue ..< startValue + count } + + var description: String { + var result = "DequeLayout(capacity: \(capacity), startSlot: \(startSlot), count: \(count)" + if count > 0 { + result += ", startValue: \(startValue)" + } + result += ")" + return result + } + + var isWrapped: Bool { + startSlot + count > capacity + } +} + +extension Deque { + init(layout: DequeLayout, contents: C) where C.Element == Element { + precondition(contents.count == layout.count) + self.init(_capacity: layout.capacity, startSlot: layout.startSlot, contents: Array(contents)) + } +} + +extension LifetimeTracker { + func deque( + with layout: DequeLayout + ) -> (deque: Deque>, contents: [LifetimeTracked]) { + let contents = self.instances(for: layout.valueRange) + let deque = Deque(layout: layout, contents: contents) + return (deque, contents) + } +} + +func withEveryDeque( + _ label: String, + ofCapacities capacities: C, + startValue: Int = 0, + file: StaticString = #file, line: UInt = #line, + _ body: (DequeLayout) throws -> Void +) rethrows -> Void where C.Element == Int { + // Exhaustive tests for all deque layouts of various capacities + for capacity in capacities { + for startSlot in 0 ..< capacity { + for count in 0 ... capacity { + let layout = DequeLayout( + capacity: capacity, + startSlot: startSlot, + count: count, + startValue: startValue) + let entry = TestContext.current.push("\(label): \(layout)", file: file, line: line) + defer { TestContext.current.pop(entry) } + try body(layout) + } + } + } +} diff --git a/Tests/DequeTests/DequeTests.swift b/Tests/DequeTests/DequeTests.swift new file mode 100644 index 00000000..48ad4a5f --- /dev/null +++ b/Tests/DequeTests/DequeTests.swift @@ -0,0 +1,323 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +import CollectionsTestSupport +@_spi(Testing) import DequeModule + +final class DequeTests: CollectionTestCase { + func test_testingSPIs() { + let deque = Deque(_capacity: 5, startSlot: 2, contents: [10, 20, 30, 40]) + expectEqual(deque.count, 4) + expectEqual(deque._capacity, 5) + expectEqual(deque._startSlot, 2) + expectEqualElements(deque, [10, 20, 30, 40]) + } + + func test_CollectionConformance() { + checkBidirectionalCollection(Deque(), expectedContents: []) + checkBidirectionalCollection(Deque([1]), expectedContents: [1]) + checkBidirectionalCollection(Deque([1, 2, 3]), expectedContents: [1, 2, 3]) + checkBidirectionalCollection(Deque(0 ..< 10), expectedContents: 0 ..< 10) + + // Exhaustive tests for all deque layouts of various capacities + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withLifetimeTracking { tracker in + let (deque, contents) = tracker.deque(with: layout) + checkBidirectionalCollection(deque, expectedContents: contents) + } + } + } + + func test_ExpressibleByArrayLiteral() { + let deque: Deque = [1, 2, 3, 4] + expectEqual(Array(deque), [1, 2, 3, 4]) + } + + func test_description() { + expectEqual("\([] as Deque)", "[]") + expectEqual("\([1, 2, 3] as Deque)", "[1, 2, 3]") + expectEqual("\([1, 2, nil, 3] as Deque)", "[Optional(1), Optional(2), nil, Optional(3)]") + + let deque: Deque = [1, 2, 3] + expectEqual("\(deque)", "[description(1), description(2), description(3)]") + } + + func test_debugDescription() { + expectEqual(String(reflecting: [] as Deque), + "Deque([])") + expectEqual(String(reflecting: [1, 2, 3] as Deque), + "Deque([1, 2, 3])") + expectEqual(String(reflecting: [1, 2, nil, 3] as Deque), + "Deque>([Optional(1), Optional(2), nil, Optional(3)])") + + let deque: Deque = [1, 2, 3] + expectEqual(String(reflecting: deque), "Deque([debugDescription(1), debugDescription(2), debugDescription(3)])") + } + + func test_customMirror() { + let deque: Deque = [1, 2, 3] + let mirror = Mirror(reflecting: deque) + expectEqual(mirror.displayStyle, .collection) + expectNil(mirror.superclassMirror) + expectTrue(mirror.children.compactMap { $0.label }.isEmpty) // No label + expectEqualElements(mirror.children.map { $0.value as? Int }, deque.map { $0 }) + } + + func test_Equatable_Hashable() { + let c1 = [1, 2, 3, 4] + let c2 = [1, 2] + let equivalenceClasses: [[Deque]] = [ + [ + Deque(_capacity: 4, startSlot: 0, contents: c1), + Deque(_capacity: 6, startSlot: 0, contents: c1), + Deque(_capacity: 4, startSlot: 2, contents: c1), + ], + [ + Deque(_capacity: 2, startSlot: 0, contents: c2), + Deque(_capacity: 6, startSlot: 0, contents: c2), + Deque(_capacity: 2, startSlot: 1, contents: c2), + ], + [ + Deque(), + Deque(_capacity: 0, startSlot: 0, contents: []), + Deque(_capacity: 6, startSlot: 0, contents: []), + Deque(_capacity: 2, startSlot: 1, contents: []), + ], + ] + checkHashable(equivalenceClasses: equivalenceClasses) + } + + func test_Encodable() throws { + let d1: Deque = [] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalEncoder.encode(d1), v1) + + let d2: Deque = [0, 1, 2, 3] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalEncoder.encode(d2), v2) + + try withEveryDeque("deque", ofCapacities: [0, 1, 3]) { layout in + try withLifetimeTracking { tracker in + let (deque, contents) = tracker.deque(with: layout) + let encoded = try MinimalEncoder.encode(deque) + expectEqual(encoded, .array(contents.map { .int($0.payload) })) + } + } + } + + func test_Decodable() throws { + let d1: Deque = [] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalDecoder.decode(v1, as: Deque.self), d1) + + let d2: Deque = [0, 1, 2, 3] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalDecoder.decode(v2, as: Deque.self), d2) + + try withEveryDeque("deque", ofCapacities: [0, 1, 3]) { layout in + let contents = Array(0 ..< layout.count) + let deque = Deque(layout: layout, contents: contents) + let input: MinimalDecoder.Value = .array(contents.map { .int($0) }) + let decoded = try MinimalDecoder.decode(input, as: Deque.self) + expectEqual(decoded, deque) + } + } + + func test_copyToContiguousArray() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withLifetimeTracking { tracker in + let (deque, contents) = tracker.deque(with: layout) + let actual = deque._copyToContiguousArray() + expectEqualElements(actual, contents) + } + } + } + + func test_partial_copyContents() { + // `Deque` supports `_copyContents` invocations with buffer sizes below + // `underestimatedCount`. This isn't a requirement, so the `Collection` + // checker doesn't cover this case. + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("prefix", in: 0 ... layout.count) { prefix in + withLifetimeTracking { tracker in + let (deque, contents) = tracker.deque(with: layout) + + var it: Deque>.Iterator? + let head = Array>( + unsafeUninitializedCapacity: prefix + ) { buffer, count in + (it, count) = deque._copyContents(initializing: buffer) + } + let tail = Array(IteratorSequence(it!)) + expectEqualElements(head, contents.prefix(upTo: prefix)) + expectEqualElements(tail, contents.suffix(from: prefix)) + } + } + } + } + + func test_unsafeUninitializedInitializer_nothrow() { + withEvery("capacity", in: 0 ..< 100) { cap in + withEvery("count", in: [0, cap / 3, cap / 2, 2 * cap / 3, cap] as Set) { count in + withLifetimeTracking { tracker in + let contents = tracker.instances(for: 0 ..< count) + let d1 = Deque>( + unsafeUninitializedCapacity: cap, + initializingWith: { target, c in + expectNotNil(target.baseAddress) + expectEqual(target.count, cap) + expectEqual(c, 0) + contents.withUnsafeBufferPointer { source in + precondition(source.count <= target.count) + target.baseAddress!.initialize( + from: source.baseAddress!, + count: source.count) + } + c = count + }) + expectEqualElements(d1, contents) + } + } + } + } + + struct TestError: Error, Equatable { + let value: Int + init(_ value: Int) { self.value = value } + } + + func test_unsafeUninitializedInitializer_throw() { + func workaroundSR14134(cap: Int, count: Int, tracker: LifetimeTracker) { + // This function works around https://bugs.swift.org/browse/SR-14134 + let contents = tracker.instances(for: 0 ..< count) + expectThrows( + try Deque>( + unsafeUninitializedCapacity: cap, + initializingWith: { target, c in + expectNotNil(target.baseAddress) + expectEqual(target.count, cap) + expectEqual(c, 0) + contents.withUnsafeBufferPointer { source in + precondition(source.count <= target.count) + target.baseAddress!.initialize( + from: source.baseAddress!, + count: source.count) + } + c = count + throw TestError(count) + }) + ) { error in + expectEqual(error as? TestError, TestError(count)) + } + } + + withEvery("capacity", in: 0 ..< 100) { cap in + withEvery("count", in: [0, cap / 3, cap / 2, 2 * cap / 3, cap] as Set) { count in + withLifetimeTracking { tracker in + workaroundSR14134(cap: cap, count: count, tracker: tracker) + } + } + } + } + + func test_popFirst() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents[...].popFirst() + let actual = deque.popFirst() + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_prependOne() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instance(for: layout.count) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(extra, at: 0) + deque.prepend(extra) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_prependManyFromMinimalSequence() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("prependCount", in: 0 ..< 10) { prependCount in + withEvery("underestimatedCount", in: [UnderestimatedCountBehavior.precise, .half, .value(min(1, prependCount))]) { underestimatedCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extras = tracker.instances(for: layout.count ..< layout.count + prependCount) + let sequence = MinimalSequence(elements: extras, underestimatedCount: underestimatedCount) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(contentsOf: extras, at: 0) + deque.prepend(contentsOf: sequence) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_prependManyFromMinimalCollection() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("prependCount", in: 0 ..< 10) { prependCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instances(for: layout.count ..< layout.count + prependCount) + let minimal = MinimalCollection(extra) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(contentsOf: extra, at: 0) + deque.prepend(contentsOf: minimal) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_prependManyFromArray() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("prependCount", in: 0 ..< 10) { prependCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instances(for: layout.count ..< layout.count + prependCount) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(contentsOf: extra, at: 0) + deque.prepend(contentsOf: extra) + expectEqualElements(deque, contents) + } + } + } + } + } + } + +} + diff --git a/Tests/DequeTests/MutableCollectionTests.swift b/Tests/DequeTests/MutableCollectionTests.swift new file mode 100644 index 00000000..992bda15 --- /dev/null +++ b/Tests/DequeTests/MutableCollectionTests.swift @@ -0,0 +1,163 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +import CollectionsTestSupport +@_spi(Testing) import DequeModule + +final class MutableCollectiontests: CollectionTestCase { + // Note: Most of the test below are exhaustively testing the behavior + // of a particular mutation or query on every possible deque layout + // of a small set of capacities. This helps catching issues that may only + // occur within rare constellations of deque state -- such as when the range + // of occupied slots is wrapped at a particular point. + + func test_subscript_assignment() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("offset", in: 0 ..< layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let replacement = tracker.instance(for: layout.count) + contents[offset] = replacement + withHiddenCopies(if: isShared, of: &deque) { deque in + deque[offset] = replacement + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_subscript_inPlaceMutation() { + func checkMutation( + _ item: inout LifetimeTracked, + tracker: LifetimeTracker, + delta: Int, + file: StaticString = #file, + line: UInt = #line + ) { + expectTrue(isKnownUniquelyReferenced(&item)) + item = tracker.instance(for: item.payload + delta) + } + + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("offset", in: 0 ..< layout.count) { offset in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + // Discard `contents` and recreate it from scratch to make sure its + // elements are uniquely referenced. + contents = tracker.instances(for: 0 ..< layout.count) + + checkMutation(&contents[offset], tracker: tracker, delta: 100) + checkMutation(&deque[offset], tracker: tracker, delta: 100) + + expectEqualElements(deque, contents) + } + } + } + } + + func test_subscript_rangeAssignmentAcrossInstances() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 6]) { layout in + withEveryRange("targetRange", in: 0 ..< layout.count) { targetRange in + let replacementCount = 4 + withEvery("replacementStartSlot", in: 0 ..< replacementCount) { replacementStartSlot in + withEveryRange("sourceRange", in: 0 ..< replacementCount) { sourceRange in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let replacementLayout = DequeLayout( + capacity: replacementCount, + startSlot: replacementStartSlot, + count: replacementCount, + startValue: layout.count) + let (replacementDeque, replacementArray) = tracker.deque(with: replacementLayout) + contents[targetRange] = replacementArray[sourceRange] + withHiddenCopies(if: isShared, of: &deque) { deque in + deque[targetRange] = replacementDeque[sourceRange] + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + } + + func test_subscript_rangeAssignmentWithinTheSameInstance() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEveryRange("targetRange", in: 0 ..< layout.count) { targetRange in + withEveryRange("sourceRange", in: 0 ..< layout.count) { sourceRange in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + contents[targetRange] = contents[sourceRange] + withHiddenCopies(if: isShared, of: &deque) { deque in + deque[targetRange] = deque[sourceRange] + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_swapAt() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("i", in: 0 ..< layout.count) { i in + withEvery("j", in: 0 ..< layout.count) { j in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + contents.swapAt(i, j) + withHiddenCopies(if: isShared, of: &deque) { deque in + deque.swapAt(i, j) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_withContiguousMutableStorageIfAvailable() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, expected) = tracker.deque(with: layout) + let replacement = tracker.instances(for: 100 ..< 100 + layout.count) + let actual: [LifetimeTracked]? = withHiddenCopies(if: isShared, of: &deque) { deque in + deque.withContiguousMutableStorageIfAvailable { buffer in + let result = Array(buffer) + expectEqual(buffer.count, replacement.count, trapping: true) + for i in 0 ..< replacement.count { + buffer[i] = replacement[i] + } + return result + } + } + if let actual = actual { + expectFalse(layout.isWrapped) + expectEqualElements(actual, expected) + expectEqualElements(deque, replacement) + } else { + expectTrue(layout.isWrapped) + } + } + } + } + } +} diff --git a/Tests/DequeTests/RangeReplaceableCollectionTests.swift b/Tests/DequeTests/RangeReplaceableCollectionTests.swift new file mode 100644 index 00000000..0af5c110 --- /dev/null +++ b/Tests/DequeTests/RangeReplaceableCollectionTests.swift @@ -0,0 +1,451 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +import CollectionsTestSupport +@_spi(Testing) import DequeModule + +/// Exhaustive tests for `Deque`'s implementations for `RangeReplaceableCollection` +/// requirements. +final class RangeReplaceableCollectionTests: CollectionTestCase { + // Note: Most of the test below are exhaustively testing the behavior + // of a particular mutation or query on every possible deque layout + // of a small set of capacities. This helps catching issues that may only + // occur within rare constellations of deque state -- such as when the range + // of occupied slots is wrapped at a particular point. + + func test_emptyInitializer() { + let deque = Deque() + expectTrue(deque.isEmpty) + expectEqual(deque.count, 0) + expectEqual(deque.startIndex, deque.endIndex) + expectEqual(deque.distance(from: deque.startIndex, to: deque.endIndex), 0) + expectEqual(Array(deque), []) + } + + func test_singleElement() { + let deque = Deque([42]) + expectFalse(deque.isEmpty) + expectEqual(deque.count, 1) + expectLessThan(deque.startIndex, deque.endIndex) + expectEqual(deque.index(after: deque.startIndex), deque.endIndex) + expectEqual(deque.distance(from: deque.startIndex, to: deque.endIndex), 1) + expectEqual(deque[0], 42) + expectEqual(Array(deque), [42]) + } + + func test_sequenceInitializer() { + withEvery("count", in: [0, 1, 2, 10, 100]) { count in + let ucVariants: [UnderestimatedCountBehavior] = [.precise, .half, .value(min(1, count))] + withEvery("underestimatedCount", in: ucVariants) { underestimatedCount in + withLifetimeTracking { tracker in + let contents = tracker.instances(for: 0 ..< count) + let d1 = Deque(MinimalSequence(elements: contents, underestimatedCount: underestimatedCount)) + expectEqualElements(d1, contents) + } + } + } + } + + func test_replaceSubrange_withMinimalCollection() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEveryRange("range", in: 0 ..< layout.count) { range in + withEvery("replacementCount", in: [0, 1, 2, 3, 5, 10]) { replacementCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extras = tracker.instances(for: layout.count ..< layout.count + replacementCount) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.replaceSubrange(range, with: extras) + let minimal = MinimalCollection(extras) + deque.replaceSubrange(range, with: minimal) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_replaceSubrange_withArray() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEveryRange("range", in: 0 ..< layout.count) { range in + withEvery("replacementCount", in: [0, 1, 2, 3, 5, 10]) { replacementCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extras = tracker.instances(for: layout.count ..< layout.count + replacementCount) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.replaceSubrange(range, with: extras) + deque.replaceSubrange(range, with: extras) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_reserveCapacity() { + // FIXME: Implement + } + + func test_repeatingInitializer() { + withEvery("count", in: 0 ..< 10) { count in + withLifetimeTracking { tracker in + let item = tracker.instance(for: 0) + let deque = Deque(repeating: item, count: count) + expectEqual(Array(deque), Array(repeating: item, count: count)) + } + } + } + + func test_appendOne() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instance(for: layout.count) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.append(extra) + deque.append(extra) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_appendManyFromMinimalSequence() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("appendCount", in: 0 ..< 10) { appendCount in + withEvery("underestimatedCount", in: [UnderestimatedCountBehavior.precise, .half, .value(min(1, appendCount))]) { underestimatedCount in + withEvery("isContiguous", in: [false, true]) { isContiguous in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extras = tracker.instances(for: layout.count ..< layout.count + appendCount) + let sequence = MinimalSequence( + elements: extras, + underestimatedCount: underestimatedCount, + isContiguous: isContiguous) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.append(contentsOf: extras) + deque.append(contentsOf: sequence) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + } + + + func test_appendManyFromMinimalCollection() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("appendCount", in: 0 ..< 10) { appendCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instances(for: layout.count ..< layout.count + appendCount) + let minimal = MinimalCollection(extra) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.append(contentsOf: extra) + deque.append(contentsOf: minimal) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_appendManyFromArray() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("appendCount", in: 0 ..< 10) { appendCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instances(for: layout.count ..< layout.count + appendCount) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.append(contentsOf: extra) + deque.append(contentsOf: extra) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_insertOneElement() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("offset", in: 0 ... layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extra = tracker.instance(for: layout.count) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(extra, at: offset) + deque.insert(extra, at: offset) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_insertFromMinimalCollection() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("offset", in: 0 ... layout.count) { offset in + withEvery("insertCount", in: 0 ..< 10) { insertCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extras = tracker.instances(for: layout.count ..< layout.count + insertCount) + let minimal = MinimalCollection(extras) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(contentsOf: extras, at: offset) + deque.insert(contentsOf: minimal, at: offset) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_insertFromArray() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("offset", in: 0 ... layout.count) { offset in + withEvery("insertCount", in: 0 ..< 10) { insertCount in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + let extras = tracker.instances(for: layout.count ..< layout.count + insertCount) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.insert(contentsOf: extras, at: offset) + deque.insert(contentsOf: extras, at: offset) + expectEqualElements(deque, contents) + } + } + } + } + } + } + } + + func test_removeOne() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("offset", in: 0 ..< layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents.remove(at: offset) + let actual = deque.remove(at: offset) + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_removeSubrange() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEveryRange("range", in: 0 ..< layout.count) { range in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.removeSubrange(range) + deque.removeSubrange(range) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_customRemoveLast_one() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + guard layout.count > 0 else { return } + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents._customRemoveLast() + let actual = deque._customRemoveLast() + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_removeLast() { + // `removeLast`'s implementation in the stdlib is derived from `_customRemoveLast`. + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + guard layout.count > 0 else { return } + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents.removeLast() + let actual = deque.removeLast() + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_popLast() { + // `popLast`'s implementation in the stdlib is derived from `_customRemoveLast`. + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents.popLast() + let actual = deque.popLast() + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_customRemoveLast_many() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + guard layout.count > 0 else { return } + withEvery("n", in: 0 ... layout.count) { n in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.removeLast(n) + expectTrue(deque._customRemoveLast(n)) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_removeLast_many() { + // `removeLast`'s implementation in the stdlib is derived from `_customRemoveLast`. + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + guard layout.count > 0 else { return } + withEvery("n", in: 0 ... layout.count) { n in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.removeLast(n) + deque.removeLast(n) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_removeFirst_one() { + // `removeLast`'s implementation in the stdlib is derived from `_customRemoveLast`. + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + guard layout.count > 0 else { return } + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + let expected = contents.removeFirst() + let actual = deque.removeFirst() + expectEqual(actual, expected) + expectEqualElements(deque, contents) + } + } + } + } + } + + func test_removeFirst_many() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + guard layout.count > 0 else { return } + withEvery("n", in: 0 ... layout.count) { n in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.removeFirst(n) + deque.removeFirst(n) + expectEqualElements(deque, contents) + } + } + } + } + } + } + + func test_removeAll_discardingCapacity() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + guard layout.count > 0 else { return } + var deque: Deque> = [] + withLifetimeTracking { tracker in + var contents: [LifetimeTracked] = [] + (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.removeAll() + deque.removeAll() + expectEqual(deque.count, 0) + expectEqual(deque._capacity, 0) // This assumes the empty singleton has zero capacity. + } + } // All elements must be deinitialized at this point. + withExtendedLifetime(deque) {} + } + } + } + + func test_removeAll_keepingCapacity() { + withEveryDeque("deque", ofCapacities: [0, 1, 2, 3, 5, 10]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + guard layout.count > 0 else { return } + var deque: Deque> = [] + withLifetimeTracking { tracker in + var contents: [LifetimeTracked] = [] + (deque, contents) = tracker.deque(with: layout) + withHiddenCopies(if: isShared, of: &deque) { deque in + contents.removeAll(keepingCapacity: true) + deque.removeAll(keepingCapacity: true) + expectEqual(deque.count, 0) + expectEqual(deque._capacity, layout.capacity) + } + } // All elements must be deinitialized at this point. + withExtendedLifetime(deque) {} + } + } + } +} diff --git a/Tests/OrderedCollectionsTests/HashTable/BItsetTests.swift b/Tests/OrderedCollectionsTests/HashTable/BItsetTests.swift new file mode 100644 index 00000000..20a48fbd --- /dev/null +++ b/Tests/OrderedCollectionsTests/HashTable/BItsetTests.swift @@ -0,0 +1,187 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#if DEBUG // These unit tests need access to OrderedSet internals +import XCTest +import CollectionsTestSupport +@_spi(Testing) @testable import OrderedCollections + +class BitsetTests: CollectionTestCase { + typealias Word = _UnsafeBitset.Word + + func test_empty() { + withEvery("capacity", in: 0 ..< 500) { capacity in + _UnsafeBitset.withTemporaryBitset(capacity: capacity) { bitset in + expectGreaterThanOrEqual(bitset.capacity, capacity) + expectEqual(bitset.count, 0) + expectEqual(bitset._actualCount, 0) + withEvery("i", in: 0 ..< capacity) { i in + expectFalse(bitset.contains(i)) + } + } + } + } + + func test_insert() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withEvery("seed", in: 0 ..< 3) { seed in + var rng = RepeatableRandomNumberGenerator(seed: seed) + let items = (0 ..< capacity).shuffled(using: &rng) + _UnsafeBitset.withTemporaryBitset(capacity: capacity) { bitset in + var c = 0 + withEvery("item", in: items) { item in + expectFalse(bitset.contains(item)) + expectTrue(bitset.insert(item)) + + expectTrue(bitset.contains(item)) + expectFalse(bitset.insert(item)) + + c += 1 + expectEqual(bitset.count, c) + } + } + } + } + } + + func withRandomBitsets( + capacity: Int, + loadFactor: Double, + body: (inout _UnsafeBitset, inout Set) throws -> Void + ) rethrows { + precondition(loadFactor >= 0 && loadFactor <= 1) + try withEvery("seed", in: 0 ..< 10) { seed in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var items = (0 ..< capacity).shuffled(using: &rng) + items.removeLast(Int((1 - loadFactor) * Double(capacity))) + try _UnsafeBitset.withTemporaryBitset(capacity: capacity) { bitset in + for item in items { + bitset.insert(item) + } + var set = Set(items) + try body(&bitset, &set) + } + } + } + + func test_remove() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + var c = contents.count + withEvery("item", in: 0 ..< capacity) { item in + if contents.contains(item) { + expectTrue(bitset.remove(item)) + expectFalse(bitset.contains(item)) + c -= 1 + expectEqual(bitset.count, c) + } else { + expectFalse(bitset.remove(item)) + expectEqual(bitset.count, c) + } + } + expectEqual(bitset.count, 0) + withEvery("item", in: 0 ..< capacity) { item in + expectFalse(bitset.contains(item)) + } + } + } + } + + func test_clear() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + bitset.clear() + expectEqual(bitset.count, 0) + withEvery("item", in: 0 ..< capacity) { item in + expectFalse(bitset.contains(item)) + } + } + } + } + + func test_insertAll_upTo() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + + let cutoff = capacity / 2 + bitset.insertAll(upTo: cutoff) + expectEqual( + bitset.count, + capacity / 2 + contents.lazy.filter { $0 >= cutoff }.count) + withEvery("item", in: 0 ..< capacity) { item in + if item < cutoff { + expectTrue(bitset.contains(item)) + } else { + expectEqual(bitset.contains(item), contents.contains(item)) + } + } + + bitset.insertAll(upTo: capacity) + expectEqual(bitset.count, capacity) + withEvery("item", in: 0 ..< capacity) { item in + expectTrue(bitset.contains(item)) + } + } + } + } + + func test_removeAll_upTo() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + + let cutoff = capacity / 2 + bitset.removeAll(upTo: cutoff) + expectEqual( + bitset.count, + contents.lazy.filter { $0 >= cutoff }.count) + withEvery("item", in: 0 ..< capacity) { item in + if item < cutoff { + expectFalse(bitset.contains(item)) + } else { + expectEqual(bitset.contains(item), contents.contains(item)) + } + } + + bitset.removeAll(upTo: capacity) + expectEqual(bitset.count, 0) + withEvery("item", in: 0 ..< capacity) { item in + expectFalse(bitset.contains(item)) + } + } + } + } + + func test_Sequence() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + expectEqual(bitset.underestimatedCount, contents.count) + let expected = contents.sorted() + var actual: [Int] = [] + actual.reserveCapacity(bitset.count) + for item in bitset { + actual.append(item) + } + expectEqual(actual, expected) + } + } + } + + func test_max() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + let max = bitset.max() + expectEqual(max, contents.max()) + } + } + } + +} +#endif // DEBUG diff --git a/Tests/OrderedCollectionsTests/HashTable/HashTableTests.swift b/Tests/OrderedCollectionsTests/HashTable/HashTableTests.swift new file mode 100644 index 00000000..213d9bd0 --- /dev/null +++ b/Tests/OrderedCollectionsTests/HashTable/HashTableTests.swift @@ -0,0 +1,618 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#if DEBUG // These unit tests need access to OrderedSet internals +import XCTest +import CollectionsTestSupport +@_spi(Testing) @testable import OrderedCollections + +class HashTableTests: CollectionTestCase { + typealias Bucket = _HashTable.Bucket + + func test_capacity() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let scale = _HashTable.scale(forCapacity: capacity) + let maximumCapacity = _HashTable.maximumCapacity(forScale: scale) + let minimumCapacity = _HashTable.minimumCapacity(forScale: scale) + + if scale == 0 { + expectEqual(minimumCapacity, 0) + expectEqual(maximumCapacity, _HashTable.maximumUnhashedCount) + expectGreaterThanOrEqual(maximumCapacity, capacity) + } else { + let bucketCount = 1 &<< scale + expectGreaterThanOrEqual(scale, _HashTable.minimumScale) + expectLessThan(scale, _HashTable.maximumScale) + expectGreaterThanOrEqual(maximumCapacity, capacity) + expectGreaterThan(bucketCount, maximumCapacity) + expectLessThan(minimumCapacity, maximumCapacity) + expectLessThanOrEqual(minimumCapacity, capacity) + expectGreaterThan(minimumCapacity, 0) + } + } + } + + func test_Storage_create() { + let s5 = _HashTable(scale: 5) + expectEqual(s5.header.scale, 5) + expectEqual(s5.header.reservedScale, 0) + expectTrue(s5.description.starts(with: "_HashTable(scale: 5, reservedScale: 0, bias: 0, seed: ")) + expectTrue(s5.header.description.starts(with: "_HashTable.Header(scale: 5, reservedScale: 0, bias: 0, seed: ")) + s5.read { hashTable in + for i in 0 ..< 32 { + let bucket = Bucket(offset: i) + expectNil(hashTable[bucket], "\(bucket.offset)") + } + } + + let s6 = _HashTable(scale: 6) + expectEqual(s6.header.scale, 6) + expectEqual(s6.header.reservedScale, 0) + expectTrue(s6.description.starts(with: "_HashTable(scale: 6, reservedScale: 0, bias: 0, seed: ")) + expectTrue(s6.header.description.starts(with: "_HashTable.Header(scale: 6, reservedScale: 0, bias: 0, seed: ")) + s6.read { hashTable in + for i in 0 ..< 64 { + let bucket = Bucket(offset: i) + expectNil(hashTable[bucket], "\(bucket.offset)") + } + } + + expectNotEqual(s6.header.seed, s5.header.seed) // This is somewhat shaky b/c we're losing address bits + + expectEqual(s5.header.capacity, 24) // 0.75 * 2^5 + expectEqual(s6.header.capacity, 48) // 0.75 * 2^6 + } + + func test_Storage_read() { + let s5 = _HashTable(scale: 5) + s5.read { hashTable in + expectEqual(hashTable.scale, 5) + expectEqual(hashTable.reservedScale, 0) + expectEqual(hashTable.seed, s5.header.seed) + expectTrue(hashTable.description.starts(with: "_HashTable.UnsafeHandle(scale: 5, reservedScale: 0, bias: 0, seed: ")) + } + let s6 = _HashTable(scale: 6) + s6.read { hashTable in + expectEqual(hashTable.scale, 6) + expectEqual(hashTable.reservedScale, 0) + expectEqual(hashTable.seed, s6.header.seed) + expectTrue(hashTable.description.starts(with: "_HashTable.UnsafeHandle(scale: 6, reservedScale: 0, bias: 0, seed: ")) + } + } + + func test_counts() { + let s5 = _HashTable(scale: 5) + s5.read { hashTable in + expectEqual(hashTable.bucketCount, 32) + expectEqual(hashTable.bitCount, 5 * 32) + expectEqual(hashTable.wordCount, 3) // 2.5 rounded up + expectEqual(hashTable.capacity, 24) // 0.75 * 32 + } + let s6 = _HashTable(scale: 6) + s6.read { hashTable in + expectEqual(hashTable.bucketCount, 64) + expectEqual(hashTable.bitCount, 6 * 64) + expectEqual(hashTable.wordCount, 6) + expectEqual(hashTable.capacity, 48) // 0.75 * 64 + } + let s12 = _HashTable(scale: 12) + s12.read { hashTable in + expectEqual(hashTable.bucketCount, 4096) + expectEqual(hashTable.bitCount, 12 * 4096) + expectEqual(hashTable.wordCount, 768) + expectEqual(hashTable.capacity, 3072) // 0.75 * 4096 + } + } + + func test_bucket_after() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + storage.read { hashTable in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let input = Bucket(offset: offset) + let expected = Bucket(offset: offset == hashTable.bucketCount - 1 ? 0 : offset + 1) + let actual = hashTable.bucket(after: input) + expectEqual(actual, expected) + } + } + } + } + func test_bucket_before() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + storage.read { hashTable in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let input = Bucket(offset: offset) + let expected = Bucket(offset: offset == 0 ? hashTable.bucketCount - 1 : offset - 1) + let actual = hashTable.bucket(before: input) + expectEqual(actual, expected) + } + } + } + } + func test_word_after() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + storage.read { hashTable in + withEvery("input", in: 0 ..< hashTable.wordCount) { input in + let expected = (input == hashTable.wordCount - 1 ? 0 : input + 1) + let actual = hashTable.word(after: input) + expectEqual(actual, expected) + } + } + } + } + func test_word_before() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + storage.read { hashTable in + withEvery("input", in: 0 ..< hashTable.wordCount) { input in + let expected = (input == 0 ? hashTable.wordCount - 1 : input - 1) + let actual = hashTable.word(before: input) + expectEqual(actual, expected) + } + } + } + } + func test_coordinates_for_bucket() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + storage.read { hashTable in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let (word, bit) = hashTable.position(of: Bucket(offset: offset)) + expectGreaterThanOrEqual(bit, 0) + expectGreaterThanOrEqual(word, 0) + expectLessThan(bit, 64) + expectLessThan(word, hashTable.wordCount) + let pos = 64 * word + bit + expectEqual(pos % scale, 0) + expectEqual(pos / scale, offset) + } + } + } + } + + func test_bucketContents_forValue() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + storage.read { hashTable in + expectEqual(hashTable._bucketContents(for: nil), 0) + expectEqual(hashTable._value(forBucketContents: 0), nil) + withEvery("value", in: 0 ..< hashTable.bucketCount - 1) { value in + let contents = hashTable._bucketContents(for: value) + expectEqual(hashTable._value(forBucketContents: contents), value) + } + } + } + } + + func test_subscript_by_bucket() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTable(scale: scale) + let bucketCount = 1 << scale + let contents: [Int?] = Array(0 ..< bucketCount - 1) + [nil] + storage.update { hashTable in + for offset in 0 ..< bucketCount { + let bucket = Bucket(offset: offset) + hashTable[bucket] = contents[offset] + } + } + storage.read { hashTable in + withEvery("offset", in: 0 ..< bucketCount) { offset in + let bucket = Bucket(offset: offset) + expectEqual(hashTable[bucket], contents[offset]) + } + } + } + } + + /// Create hash table storage of scale `scale`, filled with equal-sized lookup chains + /// of length `chainLength`, separated by holes of length `holeLength`, with the + /// first chain starting at `startOffset`. The chains contain bucket values that + /// sequentially count up from 0. + func sampleTable( + scale: Int, + chainLength: Int, + holeLength: Int, + startingAt startOffset: Int + ) -> (table: _HashTable, contents: [Int?]) { + let bucketCount = 1 << scale + + var contents: [Int?] = [] + contents.reserveCapacity(bucketCount + chainLength + holeLength) + contents.append(contentsOf: repeatElement(nil, count: startOffset)) + var i = 0 + while contents.count < bucketCount { + contents.append(contentsOf: (i ..< i + chainLength).map { $0 }) + i += chainLength + contents.append(contentsOf: repeatElement(nil, count: holeLength)) + } + contents.removeLast(contents.count - bucketCount) + + let storage = _HashTable(scale: scale) + storage.update { hashTable in + for offset in 0 ..< bucketCount { + let bucket = Bucket(offset: offset) + hashTable[bucket] = contents[offset] + } + } + return (storage, contents) + } + + /// Call `body` with a hash table of scale `scale`, filled with equal-sized lookup chains + /// of length `chainLength`, separated by holes of length `holeLength`, with the + /// first chain starting at `startOffset`. The chains contain bucket values that + /// sequentially count up from 0. + func withSampleHashTable( + scale: Int, + chainLength: Int, + holeLength: Int, + startingAt startOffset: Int, + body: (_UnsafeHashTable, [Int?]) throws -> R + ) rethrows -> R { + let (storage, contents) = sampleTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset) + return try storage.update { hashTable in + try body(hashTable, contents) + } + } + + /// Create hash table storage of scale `scale`, filled with a single huge lookup chain + /// of buckets counting sequentially up starting at 0, terminating with the penultimate + /// bucket. The last bucket remains unoccupied. + /// + /// This is useful for testing all possible bucket values. + func sampleTable(scale: Int) -> (table: _HashTable, contents: [Int?]) { + sampleTable(scale: scale, chainLength: (1 << scale) - 1, holeLength: 1, startingAt: 0) + } + + /// Call `body` with a hash table of scale `scale`, filled with a single huge lookup chain + /// of buckets counting sequentially up starting at 0, terminating with the penultimate + /// bucket. The last bucket remains unoccupied. + /// + /// This is useful for testing all possible bucket values. + func withSampleHashTable( + scale: Int, + body: (_UnsafeHashTable, [Int?]) throws -> R + ) rethrows -> R { + let (table, contents) = sampleTable(scale: scale) + return try table.update { hashTable in + try body(hashTable, contents) + } + } + + func test_bucketIterator_read() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withSampleHashTable(scale: scale) { hashTable, contents in + // Start an iterator at the first bucket and cycle through + // all buckets twice, checking the values we see at every step. + let bucket = Bucket(offset: 0) + var it = hashTable.bucketIterator(startingAt: bucket) + expectEqual(it.currentBucket, bucket) + expectEqual(it.isOccupied, contents[bucket.offset] != nil) + expectEqual(it.currentValue, contents[bucket.offset]) + withEvery("iteration", in: 0 ..< 2) { iteration in + var c = hashTable.bucketCount + if iteration == 1 { c /= 2 } // Don't let advance() trap + withEvery("offset", in: 0 ..< c) { offset in + let expected = contents[offset] + expectEqual(it.currentBucket, Bucket(offset: offset)) + expectEqual(it.isOccupied, expected != nil) + expectEqual(it.currentValue, expected) + it.advance() + } + } + } + } + } + + func test_bucketIterator_read_with_holes() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + // Start an iterator at the first bucket and cycle through + // all buckets twice, checking the values we see at every step. + let bucket = Bucket(offset: 0) + var it = hashTable.bucketIterator(startingAt: bucket) + expectEqual(it.currentBucket, bucket) + expectEqual(it.isOccupied, contents[bucket.offset] != nil) + expectEqual(it.currentValue, contents[bucket.offset]) + withEvery("iteration", in: 0 ..< 2) { iteration in + var c = hashTable.bucketCount + if iteration == 1 { c /= 2 } // Don't let advance() trap + withEvery("offset", in: 0 ..< c) { offset in + let expected = contents[offset] + expectEqual(it.currentBucket, Bucket(offset: offset)) + expectEqual(it.isOccupied, expected != nil) + expectEqual(it.currentValue, expected) + it.advance() + } + } + } + } + } + } + } + } + + func test_bucketIterator_start_in_middle() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withSampleHashTable(scale: scale) { hashTable, contents in + var expected = hashTable.bucketIterator(startingAt: Bucket(offset: 0)) + // Start a new iterator at every bucket and check that its initial + // state is match exactly what we'd get by starting at the first + // bucket and advancing step by step to the same position. + withEvery("start", in: 0 ..< hashTable.bucketCount) { start in + let bucket = Bucket(offset: start) + let actual = hashTable.bucketIterator(startingAt: bucket) + + expectEqual(expected.currentBucket, bucket) + expectEqual(expected.currentValue, contents[start]) + + expectEqual(actual.currentBucket, bucket) + expectEqual(actual.currentValue, contents[start]) + + expectEqual(actual._currentBucket, expected._currentBucket) + expectEqual(actual._currentRawValue, expected._currentRawValue) + expectEqual(actual._nextBits, expected._nextBits) + expectEqual(actual._remainingBitCount, expected._remainingBitCount) + + expected.advance() + } + } + } + } + + func test_bucketIterator_start_in_middle_with_holes() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + var expected = hashTable.bucketIterator(startingAt: Bucket(offset: 0)) + // Start a new iterator at every bucket and check that its initial + // state is match exactly what we'd get by starting at the first + // bucket and advancing step by step to the same position. + withEvery("start", in: 0 ..< hashTable.bucketCount) { start in + let bucket = Bucket(offset: start) + let actual = hashTable.bucketIterator(startingAt: bucket) + + expectEqual(expected.currentBucket, bucket) + expectEqual(expected.currentValue, contents[start]) + + expectEqual(actual.currentBucket, bucket) + expectEqual(actual.currentValue, contents[start]) + + expectEqual(actual._currentBucket, expected._currentBucket) + expectEqual(actual._currentRawValue, expected._currentRawValue) + expectEqual(actual._nextBits, expected._nextBits) + expectEqual(actual._remainingBitCount, expected._remainingBitCount) + + expected.advance() + } + } + } + } + } + } + } + + func test_bucketIterator_advance_until() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + var offset = 0 + var it = hashTable.bucketIterator(startingAt: Bucket(offset: offset)) + let step = 2 + + for _ in 0 ..< hashTable.bucketCount { + if let value = contents[offset] { + // `advance(until:)` should not move if we're already on the right value. + it.advance(until: value) + expectEqual(it.currentBucket.offset, offset) + + // `advance(until:)` should stop when it find the value we're looking for, + // or at the next hole, whichever comes first. + it.advance(until: value + step) + expectTrue(it.currentValue == nil || it.currentValue == value + step) + var o = offset + while true { + o += 1 + if o == contents.count { o = 0 } + if o == it.currentBucket.offset { break } + expectNotNil(contents[o]) + } + offset = o + } else { + // `advance(until:)` should not move if we're on a hole. + it.advance(until: 0) + expectEqual(it.currentBucket.offset, offset) + + // Move to the next bucket. + offset += 1 + if offset == contents.count { offset = 0 } + it.advance() + } + } + } + } + } + } + } + } + + func test_bucketIterator_advance_toNextUnoccupiedBucket() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + var offset = 0 + var it = hashTable.bucketIterator(startingAt: Bucket(offset: offset)) + + let holeCount = contents.reduce(into: 0) { count, item in + if item == nil { count += 1 } + } + + for _ in 0 ..< holeCount * 3 / 2 { + if contents[offset] != nil { + it.advanceToNextUnoccupiedBucket() + + expectNil(it.currentValue) + + while contents[offset] != nil { + offset += 1 + if offset == contents.count { offset = 0 } + } + expectEqual(it.currentBucket.offset, offset) + } else { + // `advanceToNextUnoccupiedBucket()` should not move if we're already on a hole. + it.advanceToNextUnoccupiedBucket() + expectEqual(it.currentBucket.offset, offset) + + // Move to the next bucket. + offset += 1 + if offset == contents.count { offset = 0 } + it.advance() + } + } + } + } + } + } + } + } + + func test_bucketIterator_write() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withSampleHashTable(scale: scale) { hashTable, contents in + let storage = _HashTable(scale: scale) + let bucketCount = 1 << scale + let contents: [Int?] = Array(0 ..< bucketCount - 1) + [nil] + storage.update { hashTable in + // Start an iterator at the first bucket and cycle through + // all buckets, updating values at every step. + let bucket = Bucket(offset: 0) + var it = hashTable.bucketIterator(startingAt: bucket) + withEvery("writeOffset", in: 0 ..< contents.count) { writeOffset in + it.currentValue = contents[writeOffset] + it.advance() + } + // Cycle through one more time, verifying that contents match. + it = hashTable.bucketIterator(startingAt: bucket) + withEvery("readOffset", in: 0 ..< contents.count) { readOffset in + expectEqual(it.currentValue, contents[readOffset]) + it.advance() + } + } + } + } + } + + func test_Storage_copy() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (s1, contents) = sampleTable(scale: scale) + let s2 = s1.copy() + s1.read { original in + s2.read { copy in + expectEqual(copy.scale, original.scale) + expectEqual(copy.reservedScale, original.reservedScale) + expectEqual(copy.seed, original.seed) + var it = copy.bucketIterator(startingAt: Bucket(offset: 0)) + withEvery("offset", in: 0 ..< contents.count) { offset in + expectEqual(it.currentValue, contents[offset]) + it.advance() + } + } + } + } + } + + func test_bias() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (storage, contents) = sampleTable(scale: scale) + withEvery("bias", in: [0, 1, -1, 2, -2, 30, -30]) { bias in + storage.update { hashTable in hashTable.bias = bias } + storage.read { hashTable in + var it = hashTable.bucketIterator(startingAt: Bucket(offset: 0)) + repeat { + if let v = contents[it.currentBucket.offset] { + let m = hashTable.bucketCount - 1 + var expected = (v + bias) % m + if expected < 0 { expected += m } + expectEqual(it.currentValue, expected) + } else { + expectNil(it.currentValue) + } + it.advance() + } while it.currentBucket.offset != 0 + } + } + } + } + + func test_rawSubscript() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (storage, contents) = sampleTable(scale: scale) + storage.read { hashTable in + var bucket = Bucket(offset: 0) + repeat { + let expected = hashTable._bucketContents(for: contents[bucket.offset]) + expectEqual(hashTable[raw: bucket], expected) + bucket = hashTable.bucket(after: bucket) + } while bucket.offset != 0 + } + } + } + + func test_isOccupied() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (storage, contents) = sampleTable(scale: scale) + storage.read { hashTable in + var bucket = Bucket(offset: 0) + repeat { + expectEqual(hashTable.isOccupied(bucket), contents[bucket.offset] != nil) + bucket = hashTable.bucket(after: bucket) + } while bucket.offset != 0 + } + } + } + +} + +#endif diff --git a/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Tests.swift b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Tests.swift new file mode 100644 index 00000000..c940cdd6 --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Tests.swift @@ -0,0 +1,1382 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import OrderedCollections + +import CollectionsTestSupport + +class OrderedDictionaryTests: CollectionTestCase { + func test_empty() { + let d = OrderedDictionary() + expectEqualElements(d, []) + expectEqual(d.count, 0) + } + + func test_init_minimumCapacity() { + let d = OrderedDictionary(minimumCapacity: 1000) + expectGreaterThanOrEqual(d.keys.__unstable.capacity, 1000) + expectGreaterThanOrEqual(d.values.elements.capacity, 1000) + expectEqual(d.keys.__unstable.reservedScale, 0) + } + + func test_init_minimumCapacity_persistent() { + let d = OrderedDictionary(minimumCapacity: 1000, persistent: true) + expectGreaterThanOrEqual(d.keys.__unstable.capacity, 1000) + expectGreaterThanOrEqual(d.values.elements.capacity, 1000) + expectNotEqual(d.keys.__unstable.reservedScale, 0) + } + + func test_uniqueKeysWithValues_Dictionary() { + let items: Dictionary = [ + "zero": 0, + "one": 1, + "two": 2, + "three": 3, + ] + let d = OrderedDictionary(uncheckedUniqueKeysWithValues: items) + expectEqualElements(d, items) + } + + func test_uniqueKeysWithValues_labeled_tuples() { + let items: KeyValuePairs = [ + "zero": 0, + "one": 1, + "two": 2, + "three": 3, + ] + let d = OrderedDictionary(uncheckedUniqueKeysWithValues: items) + expectEqualElements(d, items) + } + + func test_uniqueKeysWithValues_unlabeled_tuples() { + let items: [(String, Int)] = [ + ("zero", 0), + ("one", 1), + ("two", 2), + ("three", 3), + ] + let d = OrderedDictionary(uncheckedUniqueKeysWithValues: items) + expectEqualElements(d, items) + } + + func test_uniqueKeys_values() { + let d = OrderedDictionary( + uncheckedUniqueKeys: ["zero", "one", "two", "three"], + values: [0, 1, 2, 3]) + expectEqualElements(d, [ + (key: "zero", value: 0), + (key: "one", value: 1), + (key: "two", value: 2), + (key: "three", value: 3), + ]) + } + + func test_uniquing_initializer_labeled_tuples() { + let items: KeyValuePairs = [ + "a": 1, + "b": 1, + "c": 1, + "a": 2, + "a": 2, + "b": 1, + "d": 3, + ] + let d = OrderedDictionary(items, uniquingKeysWith: +) + expectEqualElements(d, [ + (key: "a", value: 5), + (key: "b", value: 2), + (key: "c", value: 1), + (key: "d", value: 3) + ]) + } + + func test_uniquing_initializer_unlabeled_tuples() { + let items: [(String, Int)] = [ + ("a", 1), + ("b", 1), + ("c", 1), + ("a", 2), + ("a", 2), + ("b", 1), + ("d", 3), + ] + let d = OrderedDictionary(items, uniquingKeysWith: +) + expectEqualElements(d, [ + (key: "a", value: 5), + (key: "b", value: 2), + (key: "c", value: 1), + (key: "d", value: 3) + ]) + } + + func test_grouping_initializer() { + let items: [String] = [ + "one", "two", "three", "four", "five", + "six", "seven", "eight", "nine", "ten" + ] + let d = OrderedDictionary(grouping: items, by: { $0.count }) + expectEqualElements(d, [ + (key: 3, value: ["one", "two", "six", "ten"]), + (key: 5, value: ["three", "seven", "eight"]), + (key: 4, value: ["four", "five", "nine"]), + ]) + } + + func test_uncheckedUniqueKeysWithValues_labeled_tuples() { + let items: KeyValuePairs = [ + "zero": 0, + "one": 1, + "two": 2, + "three": 3, + ] + let d = OrderedDictionary(uncheckedUniqueKeysWithValues: items) + expectEqualElements(d, items) + } + + func test_uncheckedUniqueKeysWithValues_unlabeled_tuples() { + let items: [(String, Int)] = [ + ("zero", 0), + ("one", 1), + ("two", 2), + ("three", 3), + ] + let d = OrderedDictionary(uncheckedUniqueKeysWithValues: items) + expectEqualElements(d, items) + } + + func test_uncheckedUniqueKeys_values() { + let d = OrderedDictionary( + uncheckedUniqueKeys: ["zero", "one", "two", "three"], + values: [0, 1, 2, 3]) + expectEqualElements(d, [ + (key: "zero", value: 0), + (key: "one", value: 1), + (key: "two", value: 2), + (key: "three", value: 3), + ]) + } + + func test_ExpressibleByDictionaryLiteral() { + let d0: OrderedDictionary = [:] + expectTrue(d0.isEmpty) + + let d1: OrderedDictionary = [ + "one": 1, + "two": 2, + "three": 3, + "four": 4, + ] + expectEqualElements(d1.map { $0.key }, ["one", "two", "three", "four"]) + expectEqualElements(d1.map { $0.value }, [1, 2, 3, 4]) + } + + func test_keys() { + let d: OrderedDictionary = [ + "one": 1, + "two": 2, + "three": 3, + "four": 4, + ] + expectEqual(d.keys, ["one", "two", "three", "four"] as OrderedSet) + } + + func test_counts() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, _, _) = tracker.orderedDictionary(keys: 0 ..< count) + expectEqual(d.isEmpty, count == 0) + expectEqual(d.count, count) + expectEqual(d.underestimatedCount, count) + } + } + } + + func test_index_forKey() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, _) = tracker.orderedDictionary(keys: 0 ..< count) + withEvery("offset", in: 0 ..< count) { offset in + expectEqual(d.index(forKey: keys[offset]), offset) + } + expectNil(d.index(forKey: tracker.instance(for: -1))) + expectNil(d.index(forKey: tracker.instance(for: count))) + } + } + } + + func test_subscript_offset() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withEvery("offset", in: 0 ..< count) { offset in + let item = d[offset: offset] + expectEqual(item.key, keys[offset]) + expectEqual(item.value, values[offset]) + } + } + } + } + + func test_subscript_getter() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withEvery("offset", in: 0 ..< count) { offset in + expectEqual(d[keys[offset]], values[offset]) + } + expectNil(d[tracker.instance(for: -1)]) + expectNil(d[tracker.instance(for: count)]) + } + } + } + + func test_subscript_setter_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + d[keys[offset]] = replacement + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_subscript_setter_remove() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d[keys[offset]] = nil + keys.remove(at: offset) + values.remove(at: offset) + withEvery("i", in: 0 ..< count - 1) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_subscript_setter_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + d[keys[offset]] = values[offset] + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_subscript_setter_noop() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let key = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + d[key] = nil + } + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + + func mutate( + _ value: inout T, + _ body: (inout T) throws -> R + ) rethrows -> R { + try body(&value) + } + + func test_subscript_modify_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + mutate(&d[keys[offset]]) { $0 = replacement } + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_subscript_modify_remove() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + mutate(&d[key]) { v in + expectEqual(v, values[offset]) + v = nil + } + keys.remove(at: offset) + values.remove(at: offset) + withEvery("i", in: 0 ..< count - 1) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_subscript_modify_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + mutate(&d[keys[offset]]) { v in + expectNil(v) + v = values[offset] + } + expectEqual(d.count, offset + 1) + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_subscript_modify_noop() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let key = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + mutate(&d[key]) { v in + expectNil(v) + v = nil + } + } + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + + func test_defaulted_subscript_getter() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let fallback = tracker.instance(for: -1) + withEvery("offset", in: 0 ..< count) { offset in + let key = keys[offset] + expectEqual(d[key, default: fallback], values[offset]) + } + expectEqual( + d[tracker.instance(for: -1), default: fallback], + fallback) + expectEqual( + d[tracker.instance(for: count), default: fallback], + fallback) + } + } + } + } + + func test_defaulted_subscript_modify_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + let fallback = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + mutate(&d[key, default: fallback]) { v in + expectEqual(v, values[offset]) + v = replacement + } + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_defaulted_subscript_modify_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + let fallback = tracker.instance(for: -1) + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + mutate(&d[key, default: fallback]) { v in + expectEqual(v, fallback) + v = values[offset] + } + expectEqual(d.count, offset + 1) + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_updateValue_forKey_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + let old = d.updateValue(replacement, forKey: key) + expectEqual(old, values[offset]) + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_updateValue_forKey_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + let old = d.updateValue(values[offset], forKey: key) + expectNil(old) + expectEqual(d.count, offset + 1) + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_updateValue_forKey_insertingAt_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + let (old, index) = + d.updateValue(replacement, forKey: key, insertingAt: 0) + expectEqual(old, values[offset]) + expectEqual(index, offset) + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_updateValue_forKey_insertingAt_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[count - 1 - offset] + let value = values[count - 1 - offset] + let (old, index) = + d.updateValue(value, forKey: key, insertingAt: 0) + expectNil(old) + expectEqual(index, 0) + expectEqual(d.count, offset + 1) + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[count - 1 - offset + i]) + expectEqual(v, values[count - 1 - offset + i]) + } + } + } + } + } + } + } + + func test_modifyValue_forKey_default_closure_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + let fallback = tracker.instance(for: -2) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + d.modifyValue(forKey: key, default: fallback) { value in + expectEqual(value, values[offset]) + value = replacement + } + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_modifyValue_forKey_default_closure_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + let fallback = tracker.instance(for: -2) + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + d.modifyValue(forKey: key, default: fallback) { value in + expectEqual(value, fallback) + value = values[offset] + } + expectEqual(d.count, offset + 1) + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_modifyValue_forKey_insertingDefault_at_closure_update() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + let fallback = tracker.instance(for: -2) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[offset] + let value = values[offset] + d.modifyValue(forKey: key, insertingDefault: fallback, at: 0) { v in + expectEqual(v, value) + v = replacement + } + values[offset] = replacement + withEvery("i", in: 0 ..< count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + } + } + } + } + } + } + + func test_modifyValue_forKey_insertingDefault_at_closure_insert() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + let keys = tracker.instances(for: 0 ..< count) + let values = tracker.instances(for: (0 ..< count).map { 100 + $0 }) + var d: OrderedDictionary, LifetimeTracked> = [:] + let fallback = tracker.instance(for: -2) + withEvery("offset", in: 0 ..< count) { offset in + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys[count - 1 - offset] + let value = values[count - 1 - offset] + d.modifyValue(forKey: key, insertingDefault: fallback, at: 0) { v in + expectEqual(v, fallback) + v = value + } + expectEqual(d.count, offset + 1) + withEvery("i", in: 0 ... offset) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[count - 1 - offset + i]) + expectEqual(v, values[count - 1 - offset + i]) + } + } + } + } + } + } + } + + func test_removeValue_forKey() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + let key = keys.remove(at: offset) + let expected = values.remove(at: offset) + let actual = d.removeValue(forKey: key) + expectEqual(actual, expected) + + expectEqual(d.count, values.count) + withEvery("i", in: 0 ..< values.count) { i in + let (k, v) = d[offset: i] + expectEqual(k, keys[i]) + expectEqual(v, values[i]) + } + expectNil(d.removeValue(forKey: key)) + } + } + } + } + } + } + + func test_merge_labeled_tuple() { + var d: OrderedDictionary = [ + "one": 1, + "two": 1, + "three": 1, + ] + + let items: KeyValuePairs = [ + "one": 1, + "one": 1, + "three": 1, + "four": 1, + "one": 1, + ] + + d.merge(items, uniquingKeysWith: +) + + expectEqualElements(d, [ + "one": 4, + "two": 1, + "three": 2, + "four": 1, + ] as KeyValuePairs) + } + + func test_merge_unlabeled_tuple() { + var d: OrderedDictionary = [ + "one": 1, + "two": 1, + "three": 1, + ] + + let items: [(String, Int)] = [ + ("one", 1), + ("one", 1), + ("three", 1), + ("four", 1), + ("one", 1), + ] + + d.merge(items, uniquingKeysWith: +) + + expectEqualElements(d, [ + "one": 4, + "two": 1, + "three": 2, + "four": 1, + ] as KeyValuePairs) + } + + func test_merging_labeled_tuple() { + let d: OrderedDictionary = [ + "one": 1, + "two": 1, + "three": 1, + ] + + let items: KeyValuePairs = [ + "one": 1, + "one": 1, + "three": 1, + "four": 1, + "one": 1, + ] + + let d2 = d.merging(items, uniquingKeysWith: +) + + expectEqualElements(d, [ + "one": 1, + "two": 1, + "three": 1, + ] as KeyValuePairs) + + expectEqualElements(d2, [ + "one": 4, + "two": 1, + "three": 2, + "four": 1, + ] as KeyValuePairs) + } + + func test_merging_unlabeled_tuple() { + let d: OrderedDictionary = [ + "one": 1, + "two": 1, + "three": 1, + ] + + let items: [(String, Int)] = [ + ("one", 1), + ("one", 1), + ("three", 1), + ("four", 1), + ("one", 1), + ] + + let d2 = d.merging(items, uniquingKeysWith: +) + + expectEqualElements(d, [ + "one": 1, + "two": 1, + "three": 1, + ] as KeyValuePairs) + + expectEqualElements(d2, [ + "one": 4, + "two": 1, + "three": 2, + "four": 1, + ] as KeyValuePairs) + } + + func test_filter() { + let items = (0 ..< 100).map { ($0, 100 * $0) } + let d = OrderedDictionary(uniqueKeysWithValues: items) + + var c = 0 + let d2 = d.filter { item in + c += 1 + expectEqual(item.value, 100 * item.key) + return item.key.isMultiple(of: 2) + } + expectEqual(c, 100) + expectEqualElements(d, items) + + expectEqualElements(d2, (0 ..< 50).compactMap { key in + return (key: 2 * key, value: 200 * key) + }) + } + + func test_mapValues() { + let items = (0 ..< 100).map { ($0, 100 * $0) } + let d = OrderedDictionary(uniqueKeysWithValues: items) + + var c = 0 + let d2 = d.mapValues { value -> String in + c += 1 + expectTrue(value.isMultiple(of: 100)) + return "\(value)" + } + expectEqual(c, 100) + expectEqualElements(d, items) + + expectEqualElements(d2, (0 ..< 100).compactMap { key in + (key: key, value: "\(100 * key)") + }) + } + + func test_compactMapValue() { + let items = (0 ..< 100).map { ($0, 100 * $0) } + let d = OrderedDictionary(uniqueKeysWithValues: items) + + var c = 0 + let d2 = d.compactMapValues { value -> String? in + c += 1 + guard value.isMultiple(of: 200) else { return nil } + expectTrue(value.isMultiple(of: 100)) + return "\(value)" + } + expectEqual(c, 100) + expectEqualElements(d, items) + + expectEqualElements(d2, (0 ..< 50).map { key in + (key: 2 * key, value: "\(200 * key)") + }) + } + + func test_CustomStringConvertible() { + let a: OrderedDictionary = [:] + expectEqual(a.description, "[:]") + + let b: OrderedDictionary = [0: 1] + expectEqual(b.description, "[0: 1]") + + let c: OrderedDictionary = [0: 1, 2: 3, 4: 5] + expectEqual(c.description, "[0: 1, 2: 3, 4: 5]") + } + + func test_CustomDebugStringConvertible() { + let a: OrderedDictionary = [:] + expectEqual(a.debugDescription, + "OrderedDictionary([:])") + + let b: OrderedDictionary = [0: 1] + expectEqual(b.debugDescription, + "OrderedDictionary([0: 1])") + + let c: OrderedDictionary = [0: 1, 2: 3, 4: 5] + expectEqual(c.debugDescription, + "OrderedDictionary([0: 1, 2: 3, 4: 5])") + } + + func test_customReflectable() { + do { + let d: OrderedDictionary = [1: 2, 3: 4, 5: 6] + let mirror = Mirror(reflecting: d) + expectEqual(mirror.displayStyle, .dictionary) + expectNil(mirror.superclassMirror) + expectTrue(mirror.children.compactMap { $0.label }.isEmpty) // No label + expectEqualElements( + mirror.children.compactMap { $0.value as? (key: Int, value: Int) }, + d.map { $0 }) + } + } + + func test_Equatable_Hashable() { + let samples: [[OrderedDictionary]] = [ + [[:], [:]], + [[1: 100], [1: 100]], + [[2: 200], [2: 200]], + [[3: 300], [3: 300]], + [[100: 1], [100: 1]], + [[1: 1], [1: 1]], + [[100: 100], [100: 100]], + [[1: 100, 2: 200], [1: 100, 2: 200]], + [[2: 200, 1: 100], [2: 200, 1: 100]], + [[1: 100, 2: 200, 3: 300], [1: 100, 2: 200, 3: 300]], + [[2: 200, 1: 100, 3: 300], [2: 200, 1: 100, 3: 300]], + [[3: 300, 2: 200, 1: 100], [3: 300, 2: 200, 1: 100]], + [[3: 300, 1: 100, 2: 200], [3: 300, 1: 100, 2: 200]] + ] + checkHashable(equivalenceClasses: samples) + } + + func test_Encodable() throws { + let d1: OrderedDictionary = [:] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalEncoder.encode(d1), v1) + + let d2: OrderedDictionary = [0: 1] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1)]) + expectEqual(try MinimalEncoder.encode(d2), v2) + + let d3: OrderedDictionary = [0: 1, 2: 3] + let v3: MinimalEncoder.Value = + .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalEncoder.encode(d3), v3) + + let d4 = OrderedDictionary( + uniqueKeys: 0 ..< 100, + values: (0 ..< 100).map { 100 * $0 }) + let v4: MinimalEncoder.Value = + .array((0 ..< 100).flatMap { [.int($0), .int(100 * $0)] }) + expectEqual(try MinimalEncoder.encode(d4), v4) + } + + func test_Decodable() throws { + typealias OD = OrderedDictionary + let d1: OD = [:] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalDecoder.decode(v1, as: OD.self), d1) + + let d2: OD = [0: 1] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1)]) + expectEqual(try MinimalDecoder.decode(v2, as: OD.self), d2) + + let d3: OD = [0: 1, 2: 3] + let v3: MinimalEncoder.Value = + .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalDecoder.decode(v3, as: OD.self), d3) + + let d4 = OrderedDictionary( + uniqueKeys: 0 ..< 100, + values: (0 ..< 100).map { 100 * $0 }) + let v4: MinimalEncoder.Value = + .array((0 ..< 100).flatMap { [.int($0), .int(100 * $0)] }) + expectEqual(try MinimalDecoder.decode(v4, as: OD.self), d4) + + let v5: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2)]) + expectThrows(try MinimalDecoder.decode(v5, as: OD.self)) { error in + guard case DecodingError.dataCorrupted(let context) = error else { + expectFailure("Unexpected error \(error)") + return + } + expectEqual(context.debugDescription, + "Unkeyed container reached end before value in key-value pair") + + } + + let v6: MinimalEncoder.Value = .array([.int(0), .int(1), .int(0), .int(2)]) + expectThrows(try MinimalDecoder.decode(v6, as: OD.self)) { error in + guard case DecodingError.dataCorrupted(let context) = error else { + expectFailure("Unexpected error \(error)") + return + } + expectEqual(context.debugDescription, "Duplicate key at offset 2") + } + } + + func test_swapAt() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("i", in: 0 ..< count) { i in + withEvery("j", in: 0 ..< count) { j in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + keys.swapAt(i, j) + values.swapAt(i, j) + withHiddenCopies(if: isShared, of: &d) { d in + d.swapAt(i, j) + expectEqualElements(d.values, values) + expectEqual(d[keys[i]], values[i]) + expectEqual(d[keys[j]], values[j]) + } + } + } + } + } + } + } + + func test_partition() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + var items = Array(zip(keys, values)) + let expectedPivot = items.partition { $0.0.payload < count / 2 } + withHiddenCopies(if: isShared, of: &d) { d in + let actualPivot = d.partition { $0.key.payload < count / 2 } + expectEqual(actualPivot, expectedPivot) + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_sort() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + var items = Array(zip(keys, values)) + items.sort(by: { $0.0 < $1.0 }) + withHiddenCopies(if: isShared, of: &d) { d in + d.sort() + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_sort_by() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + var items = Array(zip(keys, values)) + items.sort(by: { $0.0 > $1.0 }) + withHiddenCopies(if: isShared, of: &d) { d in + d.sort(by: { $0.key > $1.key }) + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_shuffle() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withEvery("seed", in: 0 ..< 10) { seed in + var d = OrderedDictionary( + uniqueKeys: 0 ..< count, + values: 100 ..< 100 + count) + var items = (0 ..< count).map { (key: $0, value: 100 + $0) } + withHiddenCopies(if: isShared, of: &d) { d in + expectEqualElements(d, items) + + var rng1 = RepeatableRandomNumberGenerator(seed: seed) + items.shuffle(using: &rng1) + + var rng2 = RepeatableRandomNumberGenerator(seed: seed) + d.shuffle(using: &rng2) + + items.sort(by: { $0.key < $1.key }) + d.sort() + expectEqualElements(d, items) + } + } + } + if count >= 2 { + // Check that shuffling with the system RNG does permute the elements. + var d = OrderedDictionary( + uniqueKeys: 0 ..< count, + values: 100 ..< 100 + count) + let original = d + var success = false + for _ in 0 ..< 1000 { + d.shuffle() + if !d.elementsEqual( + original, + by: { $0.key == $1.key && $0.value == $1.value} + ) { + success = true + break + } + } + expectTrue(success) + } + } + } + + func test_reverse() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + var items = Array(zip(keys, values)) + withHiddenCopies(if: isShared, of: &d) { d in + items.reverse() + d.reverse() + expectEqualElements(d, items) + } + } + } + } + } + + func test_removeAll() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, _, _) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.removeAll() + expectEqual(d.keys.__unstable.scale, 0) + expectEqualElements(d, []) + } + } + } + } + } + + func test_removeAll_keepCapacity() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, _, _) = tracker.orderedDictionary(keys: 0 ..< count) + let origScale = d.keys.__unstable.scale + withHiddenCopies(if: isShared, of: &d) { d in + d.removeAll(keepingCapacity: true) + expectEqual(d.keys.__unstable.scale, origScale) + expectEqualElements(d, []) + } + } + } + } + } + + func test_remove_at() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + let actual = d.remove(at: offset) + let expectedKey = keys.remove(at: offset) + let expectedValue = values.remove(at: offset) + expectEqual(actual.key, expectedKey) + expectEqual(actual.value, expectedValue) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeSubrange() { + withEvery("count", in: 0 ..< 30) { count in + withEveryRange("range", in: 0 ..< count) { range in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.removeSubrange(range) + keys.removeSubrange(range) + values.removeSubrange(range) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeSubrange_rangeExpression() { + let d = OrderedDictionary(uniqueKeys: 0 ..< 30, values: 100 ..< 130) + let item = (0 ..< 30).map { (key: $0, value: 100 + $0) } + + var d1 = d + d1.removeSubrange(...10) + expectEqualElements(d1, item[11...]) + + var d2 = d + d2.removeSubrange(..<10) + expectEqualElements(d2, item[10...]) + + var d3 = d + d3.removeSubrange(10...) + expectEqualElements(d3, item[0 ..< 10]) + } + + func test_removeLast() { + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< 30) + withEvery("i", in: 0 ..< d.count) { i in + withHiddenCopies(if: isShared, of: &d) { d in + let actual = d.removeLast() + let expectedKey = keys.removeLast() + let expectedValue = values.removeLast() + expectEqual(actual.key, expectedKey) + expectEqual(actual.value, expectedValue) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + + func test_removeFirst() { + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< 30) + withEvery("i", in: 0 ..< d.count) { i in + withHiddenCopies(if: isShared, of: &d) { d in + let actual = d.removeFirst() + let expectedKey = keys.removeFirst() + let expectedValue = values.removeFirst() + expectEqual(actual.key, expectedKey) + expectEqual(actual.value, expectedValue) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + + func test_removeLast_n() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("suffix", in: 0 ..< count) { suffix in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.removeLast(suffix) + keys.removeLast(suffix) + values.removeLast(suffix) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeFirst_n() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("prefix", in: 0 ..< count) { prefix in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.removeFirst(prefix) + keys.removeFirst(prefix) + values.removeFirst(prefix) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeAll_where() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("n", in: [2, 3, 4]) { n in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + var items = zip(keys, values).map { (key: $0.0, value: $0.1) } + withHiddenCopies(if: isShared, of: &d) { d in + d.removeAll(where: { !$0.key.payload.isMultiple(of: n) }) + items.removeAll(where: { !$0.key.payload.isMultiple(of: n) }) + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_Sequence() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let items = zip(keys, values).map { (key: $0.0, value: $0.1) } + checkSequence( + { d }, + expectedContents: items, + by: { $0.key == $1.0 && $0.value == $1.1 }) + } + } + } + +} + diff --git a/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Utils.swift b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Utils.swift new file mode 100644 index 00000000..37db3faa --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary Utils.swift @@ -0,0 +1,31 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsTestSupport +import OrderedCollections + +extension LifetimeTracker { + func orderedDictionary( + keys: Keys + ) -> ( + dictionary: OrderedDictionary, LifetimeTracked>, + keys: [LifetimeTracked], + values: [LifetimeTracked] + ) + where Keys.Element == Int + { + let k = Array(keys) + let keys = self.instances(for: k) + let values = self.instances(for: k.map { $0 + 100 }) + let dictionary = OrderedDictionary(uniqueKeys: keys, values: values) + return (dictionary, keys, values) + } +} diff --git a/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary+Elements Tests.swift b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary+Elements Tests.swift new file mode 100644 index 00000000..1bfc2410 --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary+Elements Tests.swift @@ -0,0 +1,515 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import OrderedCollections + +import CollectionsTestSupport + +class OrderedDictionaryElementsTests: CollectionTestCase { + func test_elements_getter() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let items = zip(keys, values).map { (key: $0.0, value: $0.1) } + expectEqualElements(d.elements, items) + } + } + } + + func test_elements_modify() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let items = zip(keys, values).map { (key: $0.0, value: $0.1) } + + var d2 = OrderedDictionary, LifetimeTracked>() + + swap(&d.elements, &d2.elements) + + expectEqualElements(d, []) + expectEqualElements(d2, items) + } + } + } + + func test_keys_values() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + + expectEqualElements(d.elements.keys, keys) + expectEqualElements(d.elements.values, values) + + values.reverse() + d.elements.values.reverse() + expectEqualElements(d.elements.values, values) + } + } + } + + func test_index_forKey() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, _) = tracker.orderedDictionary(keys: 0 ..< count) + withEvery("offset", in: 0 ..< count) { offset in + expectEqual(d.elements.index(forKey: keys[offset]), offset) + } + expectNil(d.elements.index(forKey: tracker.instance(for: -1))) + expectNil(d.elements.index(forKey: tracker.instance(for: count))) + } + } + } + + func test_RandomAccessCollection() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let items = zip(keys, values).map { (key: $0.0, value: $0.1) } + checkBidirectionalCollection( + d.elements, expectedContents: items, + by: { $0 == $1 }) + } + } + } + + func test_CustomStringConvertible() { + let a: OrderedDictionary = [:] + expectEqual(a.elements.description, "[:]") + + let b: OrderedDictionary = [0: 1] + expectEqual(b.elements.description, "[0: 1]") + + let c: OrderedDictionary = [0: 1, 2: 3, 4: 5] + expectEqual(c.elements.description, "[0: 1, 2: 3, 4: 5]") + } + + func test_CustomDebugStringConvertible() { + let a: OrderedDictionary = [:] + expectEqual(a.elements.debugDescription, + "OrderedDictionary.Elements([:])") + + let b: OrderedDictionary = [0: 1] + expectEqual(b.elements.debugDescription, + "OrderedDictionary.Elements([0: 1])") + + let c: OrderedDictionary = [0: 1, 2: 3, 4: 5] + expectEqual(c.elements.debugDescription, + "OrderedDictionary.Elements([0: 1, 2: 3, 4: 5])") + } + + func test_customReflectable() { + do { + let d: OrderedDictionary = [1: 2, 3: 4, 5: 6] + let mirror = Mirror(reflecting: d.elements) + expectEqual(mirror.displayStyle, .collection) + expectNil(mirror.superclassMirror) + expectTrue(mirror.children.compactMap { $0.label }.isEmpty) // No label + expectEqualElements( + mirror.children.compactMap { $0.value as? (key: Int, value: Int) }, + d.map { $0 }) + } + } + + func test_Equatable_Hashable() { + let samples: [[OrderedDictionary]] = [ + [[:], [:]], + [[1: 100], [1: 100]], + [[2: 200], [2: 200]], + [[3: 300], [3: 300]], + [[100: 1], [100: 1]], + [[1: 1], [1: 1]], + [[100: 100], [100: 100]], + [[1: 100, 2: 200], [1: 100, 2: 200]], + [[2: 200, 1: 100], [2: 200, 1: 100]], + [[1: 100, 2: 200, 3: 300], [1: 100, 2: 200, 3: 300]], + [[2: 200, 1: 100, 3: 300], [2: 200, 1: 100, 3: 300]], + [[3: 300, 2: 200, 1: 100], [3: 300, 2: 200, 1: 100]], + [[3: 300, 1: 100, 2: 200], [3: 300, 1: 100, 2: 200]] + ] + checkHashable(equivalenceClasses: samples.map { $0.map { $0.elements }}) + } + + func test_swapAt() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("i", in: 0 ..< count) { i in + withEvery("j", in: 0 ..< count) { j in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + keys.swapAt(i, j) + values.swapAt(i, j) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.swapAt(i, j) + expectEquivalentElements( + d, zip(keys, values), + by: { $0.key == $1.0 && $0.value == $1.1 }) + expectEqual(d[keys[i]], values[i]) + expectEqual(d[keys[j]], values[j]) + } + } + } + } + } + } + } + + func test_partition() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + var items = Array(zip(keys, values)) + let expectedPivot = items.partition { $0.0.payload < count / 2 } + withHiddenCopies(if: isShared, of: &d) { d in + let actualPivot = d.elements.partition { $0.key.payload < count / 2 } + expectEqual(actualPivot, expectedPivot) + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_sort() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + var items = Array(zip(keys, values)) + items.sort(by: { $0.0 < $1.0 }) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.sort() + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_sort_by() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + var items = Array(zip(keys, values)) + items.sort(by: { $0.0 > $1.0 }) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.sort(by: { $0.key > $1.key }) + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_shuffle() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withEvery("seed", in: 0 ..< 10) { seed in + var d = OrderedDictionary( + uniqueKeys: 0 ..< count, + values: 100 ..< 100 + count) + var items = (0 ..< count).map { (key: $0, value: 100 + $0) } + withHiddenCopies(if: isShared, of: &d) { d in + expectEqualElements(d.elements, items) + + var rng1 = RepeatableRandomNumberGenerator(seed: seed) + items.shuffle(using: &rng1) + + var rng2 = RepeatableRandomNumberGenerator(seed: seed) + d.elements.shuffle(using: &rng2) + + items.sort(by: { $0.key < $1.key }) + d.elements.sort() + expectEqualElements(d, items) + } + } + } + if count >= 2 { + // Check that shuffling with the system RNG does permute the elements. + var d = OrderedDictionary( + uniqueKeys: 0 ..< count, + values: 100 ..< 100 + count) + let original = d + var success = false + for _ in 0 ..< 1000 { + d.elements.shuffle() + if !d.elementsEqual( + original, + by: { $0.key == $1.key && $0.value == $1.value} + ) { + success = true + break + } + } + expectTrue(success) + } + } + } + + func test_reverse() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + var items = Array(zip(keys, values)) + withHiddenCopies(if: isShared, of: &d) { d in + items.reverse() + d.elements.reverse() + expectEqualElements(d, items) + } + } + } + } + } + + func test_removeAll() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, _, _) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.removeAll() + expectEqual(d.keys.__unstable.scale, 0) + expectEqualElements(d, []) + } + } + } + } + } + + func test_removeAll_keepCapacity() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, _, _) = tracker.orderedDictionary(keys: 0 ..< count) + let origScale = d.keys.__unstable.scale + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.removeAll(keepingCapacity: true) + expectEqual(d.keys.__unstable.scale, origScale) + expectEqualElements(d, []) + } + } + } + } + } + + func test_remove_at() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + let actual = d.elements.remove(at: offset) + let expectedKey = keys.remove(at: offset) + let expectedValue = values.remove(at: offset) + expectEqual(actual.key, expectedKey) + expectEqual(actual.value, expectedValue) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeSubrange() { + withEvery("count", in: 0 ..< 30) { count in + withEveryRange("range", in: 0 ..< count) { range in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.removeSubrange(range) + keys.removeSubrange(range) + values.removeSubrange(range) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeSubrange_rangeExpression() { + let d = OrderedDictionary(uniqueKeys: 0 ..< 30, values: 100 ..< 130) + let item = (0 ..< 30).map { (key: $0, value: 100 + $0) } + + var d1 = d + d1.elements.removeSubrange(...10) + expectEqualElements(d1, item[11...]) + + var d2 = d + d2.elements.removeSubrange(..<10) + expectEqualElements(d2, item[10...]) + + var d3 = d + d3.elements.removeSubrange(10...) + expectEqualElements(d3, item[0 ..< 10]) + } + + func test_removeLast() { + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< 30) + withEvery("i", in: 0 ..< d.count) { i in + withHiddenCopies(if: isShared, of: &d) { d in + let actual = d.elements.removeLast() + let expectedKey = keys.removeLast() + let expectedValue = values.removeLast() + expectEqual(actual.key, expectedKey) + expectEqual(actual.value, expectedValue) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + + func test_removeFirst() { + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< 30) + withEvery("i", in: 0 ..< d.count) { i in + withHiddenCopies(if: isShared, of: &d) { d in + let actual = d.elements.removeFirst() + let expectedKey = keys.removeFirst() + let expectedValue = values.removeFirst() + expectEqual(actual.key, expectedKey) + expectEqual(actual.value, expectedValue) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + + func test_removeLast_n() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("suffix", in: 0 ..< count) { suffix in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.removeLast(suffix) + keys.removeLast(suffix) + values.removeLast(suffix) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeFirst_n() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("prefix", in: 0 ..< count) { prefix in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.removeFirst(prefix) + keys.removeFirst(prefix) + values.removeFirst(prefix) + expectEqualElements( + d, + zip(keys, values).map { (key: $0.0, value: $0.1) }) + } + } + } + } + } + } + + func test_removeAll_where() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("n", in: [2, 3, 4]) { n in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + var items = zip(keys, values).map { (key: $0.0, value: $0.1) } + withHiddenCopies(if: isShared, of: &d) { d in + d.elements.removeAll(where: { !$0.key.payload.isMultiple(of: n) }) + items.removeAll(where: { !$0.key.payload.isMultiple(of: n) }) + expectEqualElements(d, items) + } + } + } + } + } + } + + func test_slice_keys() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, keys, _) = tracker.orderedDictionary(keys: 0 ..< count) + withEveryRange("range", in: 0 ..< count) { range in + expectEqual(d.elements[range].keys, d.keys[range]) + expectEqualElements(d.elements[range].keys, keys[range]) + } + } + } + } + + func test_slice_values() { + withEvery("count", in: 0 ..< 30) { count in + withLifetimeTracking { tracker in + let (d, _, values) = tracker.orderedDictionary(keys: 0 ..< count) + withEveryRange("range", in: 0 ..< count) { range in + expectEqualElements(d.elements[range].values, d.values[range]) + expectEqualElements(d.elements[range].values, values[range]) + } + } + } + } + + func test_slice_index_forKey() { + withEvery("count", in: 0 ..< 30) { count in + withEveryRange("range", in: 0 ..< count) { range in + withLifetimeTracking { tracker in + let (d, keys, _) = tracker.orderedDictionary(keys: 0 ..< count) + withEvery("offset", in: 0 ..< count) { offset in + let actual = d.elements[range].index(forKey: keys[offset]) + let expected = range.contains(offset) ? offset : nil + expectEqual(actual, expected) + } + expectNil(d.elements[range].index(forKey: tracker.instance(for: -1))) + expectNil(d.elements[range].index(forKey: tracker.instance(for: count))) + } + } + } + } +} diff --git a/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary+Values Tests.swift b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary+Values Tests.swift new file mode 100644 index 00000000..c80a5fb4 --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedDictionary/OrderedDictionary+Values Tests.swift @@ -0,0 +1,209 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import OrderedCollections + +import CollectionsTestSupport + +class OrderedDictionaryValueTests: CollectionTestCase { + func test_values_getter() { + let d: OrderedDictionary = [ + "one": 1, + "two": 2, + "three": 3, + "four": 4, + ] + expectEqualElements(d.values, [1, 2, 3, 4]) + } + + func test_values_RandomAccessCollection() { + withEvery("count", in: 0 ..< 30) { count in + let keys = 0 ..< count + let values = keys.map { $0 + 100 } + let d = OrderedDictionary(uniqueKeys: keys, values: values) + checkBidirectionalCollection(d.values, expectedContents: values) + } + } + + func test_values_subscript_assignment() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instance(for: -1) + withHiddenCopies(if: isShared, of: &d) { d in + d.values[offset] = replacement + values[offset] = replacement + expectEqualElements(d.values, values) + expectEqual(d[keys[offset]], values[offset]) + } + } + } + } + } + } + + func test_values_subscript_inPlaceMutation() { + func checkMutation( + _ item: inout LifetimeTracked, + tracker: LifetimeTracker, + delta: Int, + file: StaticString = #file, + line: UInt = #line + ) { + expectTrue(isKnownUniquelyReferenced(&item)) + item = tracker.instance(for: item.payload + delta) + } + + withEvery("count", in: 0 ..< 30) { count in + withEvery("offset", in: 0 ..< count) { offset in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + // Discard `values` and recreate it from scratch to make sure its + // elements are uniquely referenced. + values = tracker.instances(for: values.lazy.map { $0.payload }) + + checkMutation(&values[offset], tracker: tracker, delta: 10) + checkMutation(&d.values[offset], tracker: tracker, delta: 10) + + expectEqualElements(d.values, values) + expectEqual(d[keys[offset]], values[offset]) + } + } + } + } + + func test_swapAt() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("i", in: 0 ..< count) { i in + withEvery("j", in: 0 ..< count) { j in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + values.swapAt(i, j) + withHiddenCopies(if: isShared, of: &d) { d in + d.values.swapAt(i, j) + expectEqualElements(d.values, values) + expectEqual(d[keys[i]], values[i]) + expectEqual(d[keys[j]], values[j]) + } + } + } + } + } + } + } + + func test_partition() { + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var (d, keys, values) = tracker.orderedDictionary( + keys: (0 ..< count).shuffled(using: &rng)) + let expectedPivot = values.partition { $0.payload < 100 + count / 2 } + withHiddenCopies(if: isShared, of: &d) { d in + let actualPivot = d.values.partition { $0.payload < 100 + count / 2 } + expectEqual(actualPivot, expectedPivot) + expectEqualElements(d.values, values) + withEvery("i", in: 0 ..< count) { i in + expectEqual(d[keys[i]], values[i]) + } + } + } + } + } + } + } + + func test_withUnsafeBufferPointer() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, _, values) = tracker.orderedDictionary(keys: 0 ..< count) + typealias R = [LifetimeTracked] + let actual = + withHiddenCopies(if: isShared, of: &d) { d -> R in + d.values.withUnsafeBufferPointer { buffer -> R in + Array(buffer) + } + } + expectEqualElements(actual, values) + } + } + } + } + + func test_withUnsafeMutableBufferPointer() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instances(for: (0 ..< count).map { -$0 }) + typealias R = [LifetimeTracked] + let actual = + withHiddenCopies(if: isShared, of: &d) { d -> R in + d.values.withUnsafeMutableBufferPointer { buffer -> R in + let result = Array(buffer) + expectEqual(buffer.count, replacement.count, trapping: true) + for i in 0 ..< replacement.count { + buffer[i] = replacement[i] + } + return result + } + } + expectEqualElements(actual, values) + expectEqualElements(d.values, replacement) + withEvery("i", in: 0 ..< count) { i in + expectEqual(d[keys[i]], replacement[i]) + } + } + } + } + } + + func test_withContiguousMutableStorageIfAvailable() { + withEvery("count", in: 0 ..< 30) { count in + withEvery("isShared", in: [false, true]) { isShared in + withLifetimeTracking { tracker in + var (d, keys, values) = tracker.orderedDictionary(keys: 0 ..< count) + let replacement = tracker.instances(for: (0 ..< count).map { -$0 }) + typealias R = [LifetimeTracked] + let actual = + withHiddenCopies(if: isShared, of: &d) { d -> R? in + d.values.withContiguousMutableStorageIfAvailable { buffer -> R in + let result = Array(buffer) + expectEqual(buffer.count, replacement.count, trapping: true) + for i in 0 ..< replacement.count { + buffer[i] = replacement[i] + } + return result + } + } + if let actual = actual { + expectEqualElements(actual, values) + expectEqualElements(d.values, replacement) + withEvery("i", in: 0 ..< count) { i in + expectEqual(d[keys[i]], replacement[i]) + } + } else { + expectFailure("OrderedDictionary.Value isn't contiguous?") + } + } + } + } + } + + +} diff --git a/Tests/OrderedCollectionsTests/OrderedSet/OrderedSet.UnorderedView Tests.swift b/Tests/OrderedCollectionsTests/OrderedSet/OrderedSet.UnorderedView Tests.swift new file mode 100644 index 00000000..63fe2e45 --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedSet/OrderedSet.UnorderedView Tests.swift @@ -0,0 +1,78 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import OrderedCollections +import CollectionsTestSupport + +class OrderedSetUnorderedViewTests: CollectionTestCase { + func test_unordered_insert() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + withLifetimeTracking { tracker in + let input = (0 ..< dupes * count) + .map { tracker.instance(for: $0 / dupes) } + .shuffled() + let reference: [Int: LifetimeTracked] = + .init(input.lazy.map { ($0.payload, $0) }, + uniquingKeysWith: { a, b in a }) + var set = OrderedSet>() + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let ref = reference[item.payload] + let (inserted, member) = set.unordered.insert(item) + expectEqual(inserted, ref === item) + expectEqual(member, item) + expectIdentical(member, ref) + expectTrue(set.contains(item)) + } + } + } + } + // Check CoW copying behavior + do { + var set = OrderedSet(0 ..< 30) + let copy = set + expectTrue(set.unordered.insert(30).inserted) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } + + func test_unordered_update() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + withLifetimeTracking { tracker in + let input = (0 ..< dupes * count) + .map { tracker.instance(for: $0 / dupes) } + .shuffled() + var reference: [Int: LifetimeTracked] = [:] + var set = OrderedSet>() + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let old = set.unordered.update(with: item) + expectIdentical(old, reference[item.payload]) + reference[item.payload] = item + expectTrue(set.contains(item)) + } + } + } + } + // Check CoW copying behavior + do { + var set = OrderedSet(0 ..< 30) + let copy = set + expectNil(set.unordered.update(with: 30)) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } +} diff --git a/Tests/OrderedCollectionsTests/OrderedSet/OrderedSetInternals.swift b/Tests/OrderedCollectionsTests/OrderedSet/OrderedSetInternals.swift new file mode 100644 index 00000000..0215248a --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedSet/OrderedSetInternals.swift @@ -0,0 +1,81 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsTestSupport +@_spi(Testing) import OrderedCollections + +struct OrderedSetLayout: Hashable, CustomStringConvertible { + let scale: Int + let bias: Int + let count: Int + + var description: String { + "OrderedSetLayout(scale: \(scale), bias: \(bias), count: \(count))" + } +} + +func withOrderedSetLayouts( + scales: [Int], + file: StaticString = #file, + line: UInt = #line, + run body: (OrderedSetLayout) throws -> Void +) rethrows { + for scale in scales { + for count in _interestingCounts(forScale: scale) { + for bias in _interestingBiases(forScale: scale) { + let layout = OrderedSetLayout(scale: scale, bias: bias, count: count) + let entry = TestContext.current.push("layout: \(layout)") + defer { TestContext.current.pop(entry) } + try body(layout) + } + } + } +} + +func _interestingCounts(forScale scale: Int) -> [Int] { + precondition(scale == 0 || scale >= OrderedSet._minimumScale) + let min = OrderedSet._minimumCapacity(forScale: scale) + let max = OrderedSet._maximumCapacity(forScale: scale) + return [min, min + (max - min) / 2, max] +} + +func _interestingBiases(forScale scale: Int) -> [Int] { + // If we have no hash table, we can only use a bias of 0. + if scale < OrderedSet._minimumScale { return [0] } + let range = OrderedSet._biasRange(scale: scale) + // For the minimum scale, try all biases. + if scale == OrderedSet._minimumScale { return Array(range) } + // Otherwise try 3 biases each from the start, middle, and end of range. + var result: [Int] = [] + result += range.prefix(3) + result += range.prefix(range.count / 2 + 1).suffix(3) + result += range.suffix(3) + return result +} + +extension OrderedSet { + init(layout: OrderedSetLayout, contents: [Element]) { + self.init(_scale: layout.scale, bias: layout.bias, contents: contents) + } +} + +extension OrderedSet { + init(layout: OrderedSetLayout, contents: C) + where C.Element == Element { + self.init(_scale: layout.scale, bias: layout.bias, contents: contents) + } +} + +extension OrderedSet where Element == Int { + init(layout: OrderedSetLayout) { + self.init(layout: layout, contents: 0 ..< layout.count) + } +} diff --git a/Tests/OrderedCollectionsTests/OrderedSet/OrderedSetTests.swift b/Tests/OrderedCollectionsTests/OrderedSet/OrderedSetTests.swift new file mode 100644 index 00000000..b0f7e7f3 --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedSet/OrderedSetTests.swift @@ -0,0 +1,1363 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import OrderedCollections +import CollectionsTestSupport + +class OrderedSetTests: CollectionTestCase { + func test_init_uncheckedUniqueElements_concrete() { + withEvery("count", in: 0 ..< 20) { count in + let contents = Array(0 ..< count) + let set = OrderedSet(uncheckedUniqueElements: contents) + expectEqual(set.count, count) + expectEqual(set.isEmpty, count == 0) + expectEqualElements(set, 0 ..< count) + for i in 0 ..< count { + expectTrue(set.contains(i)) + } + } + } + + func test_init_empty() { + let set = OrderedSet() + expectEqual(set.count, 0) + expectTrue(set.isEmpty) + expectEqualElements(set, []) + } + + func test_init_self() { + withEvery("count", in: 0 ..< 20) { count in + let set = OrderedSet(0 ..< count) + let copy = OrderedSet(set) + expectEqualElements(copy, set) + expectEqual(set.__unstable.hashTableIdentity, copy.__unstable.hashTableIdentity) + } + } + + func test_init_set() { + withEvery("count", in: 0 ..< 20) { count in + let set = Set(0 ..< count) + let ordered = OrderedSet(set) + expectEqual(ordered.count, count) + expectEqualElements(ordered, set) + } + } + + func test_init_dictionary_keys() { + withEvery("count", in: 0 ..< 20) { count in + let dict: [Int: Int] + = .init(uniqueKeysWithValues: (0 ..< count).lazy.map { (key: $0, value: 2 * $0) }) + let ordered = OrderedSet(dict.keys) + expectEqual(ordered.count, count) + expectEqualElements(ordered, dict.keys) + } + } + + /// Create a new `OrderedSet` instance using the generic initializer. + static func _genericInitializer( + from elements: S + ) -> OrderedSet { + return OrderedSet(elements) + } + + + func test_generic_init_self() { + withEvery("count", in: 0 ..< 20) { count in + let set = OrderedSet(0 ..< count) + let copy: OrderedSet = Self._genericInitializer(from: set) + expectEqualElements(copy, set) + expectEqual(set.__unstable.hashTableIdentity, copy.__unstable.hashTableIdentity) + } + } + + func test_generic_init_set() { + withEvery("count", in: 0 ..< 20) { count in + let expected = Set(0 ..< count) + let actual = Self._genericInitializer(from: expected) + expectEqualElements(actual, expected) + } + } + + func test_generic_init_array() { + withEvery("count", in: 0 ..< 20) { count in + let expected = Array(0 ..< count) + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) } + let actual = Self._genericInitializer(from: input) + expectEqualElements(actual, expected) + } + } + } + + func test_firstIndexOf_lastIndexOf() { + withEvery("count", in: 0 ..< 20) { count in + let contents = Array(0 ..< count) + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) } + let set = OrderedSet(input) + withEvery("item", in: contents) { item in + expectNotNil(set.firstIndex(of: item)) { index in + expectEqual(set[index], item) + expectEqual(contents[index], item) + expectEqual(set.lastIndex(of: item), index) + } + } + expectNil(set.firstIndex(of: count)) + expectNil(set.lastIndex(of: count)) + } + } + } + + func test_Collection() { + withEvery("count", in: [0, 1, 15, 16, 20]) { count in + let scale = OrderedSet._scale(forCapacity: count) + withEvery("bias", in: OrderedSet._biasRange(scale: scale)) { bias in + let contents = Array(0 ..< count) + let set = OrderedSet(_scale: scale, bias: bias, contents: contents) + checkBidirectionalCollection(set, expectedContents: contents) + } + } + } + + func test_CustomStringConvertible() { + let a: OrderedSet = [] + expectEqual(a.description, "[]") + + let b: OrderedSet = [0] + expectEqual(b.description, "[0]") + + let c: OrderedSet = [0, 1, 2, 3, 4] + expectEqual(c.description, "[0, 1, 2, 3, 4]") + } + + func test_CustomDebugStringConvertible() { + let a: OrderedSet = [] + expectEqual(a.debugDescription, "OrderedSet([])") + + let b: OrderedSet = [0] + expectEqual(b.debugDescription, "OrderedSet([0])") + + let c: OrderedSet = [0, 1, 2, 3, 4] + expectEqual(c.debugDescription, "OrderedSet([0, 1, 2, 3, 4])") + } + + func test_customReflectable() { + do { + let set: OrderedSet = [1, 2, 3] + let mirror = Mirror(reflecting: set) + expectEqual(mirror.displayStyle, .collection) + expectNil(mirror.superclassMirror) + expectTrue(mirror.children.compactMap { $0.label }.isEmpty) // No label + expectEqualElements(mirror.children.map { $0.value as? Int }, set.map { $0 }) + } + } + + func test_Equatable_Hashable() { + let samples: [[OrderedSet]] = [ + [[1, 2, 3], + [1, 2, 3]], + [[3, 2, 1], + [3, 2, 1]], + [[1, 1, 1], + [1, 1, 1], + [1, 1], + [1]], + [[1, 2], + [1, 2, 2], + [1, 1, 2], + [1, 1, 2, 2]], + ] + checkHashable(equivalenceClasses: samples) + + // Check that hash encoding matches that of the underlying arrays. + for equivalenceClass in samples { + for item in equivalenceClass { + expectEqual(item.hashValue, item.elements.hashValue) + } + } + } + + func test_ExpressibleByArrayLiteral() { + do { + let set: OrderedSet = [] + expectEqualElements(set, [] as [Int]) + } + + do { + let set: OrderedSet = [1, 2, 3] + expectEqualElements(set, 1 ... 3) + } + + do { + let set: OrderedSet = [ + 1, 2, 3, 4, 5, 6, 7, 8, + 1, 2, 3, 4, 5, 6, 7, 8, + 1, 2, 3, 4, 5, 6, 7, 8, + 1, 2, 3, 4, 5, 6, 7, 8, + ] + expectEqualElements(set, 1 ... 8) + } + + do { + let set: OrderedSet = [ + 1, 1, 1, 1, + 2, 2, 2, 2, + 3, 3, 3, 3, + 4, 4, 4, 4, + 5, 5, 5, 5, + 6, 6, 6, 6, + 7, 7, 7, 7, + 8, 8, 8, 8, + ] + expectEqualElements(set, 1 ... 8) + } + + do { + let set: OrderedSet = [ + 1, 2, 3, 4, 5, 6, 7, 8, + 9, 10, 11, 12, 13, 14, 15, 16, + 17, 18, 19, 20, 21, 22, 23, 24, + 25, 26, 27, 28, 29, 30, 31, 32] + expectEqualElements(set, 1 ... 32) + } + } + + func test_Encodable() throws { + let s1: OrderedSet = [] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalEncoder.encode(s1), v1) + + let s2: OrderedSet = [0, 1, 2, 3] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalEncoder.encode(s2), v2) + + let s3: OrderedSet = [3, 2, 1, 0] + let v3: MinimalEncoder.Value = .array([.int(3), .int(2), .int(1), .int(0)]) + expectEqual(try MinimalEncoder.encode(s3), v3) + + let s4 = OrderedSet(0 ..< 100) + let v4: MinimalEncoder.Value = .array((0 ..< 100).map { .int($0) }) + expectEqual(try MinimalEncoder.encode(s4), v4) + } + + func test_Decodable() throws { + let s1: OrderedSet = [] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalDecoder.decode(v1, as: OrderedSet.self), s1) + + let s2: OrderedSet = [0, 1, 2, 3] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalDecoder.decode(v2, as: OrderedSet.self), s2) + + let s3 = OrderedSet(0 ..< 100) + let v3: MinimalEncoder.Value = .array((0 ..< 100).map { .int($0) }) + expectEqual(try MinimalDecoder.decode(v3, as: OrderedSet.self), s3) + + expectThrows(try MinimalDecoder.decode(.int(0), as: OrderedSet.self)) + + let v4: MinimalEncoder.Value = .array([.int(0), .int(1), .int(0)]) + expectThrows(try MinimalDecoder.decode(v4, as: OrderedSet.self)) { error in + expectNotNil(error as? DecodingError) { error in + guard case .dataCorrupted(let context) = error else { + expectFailure("Unexpected error \(error)") + return + } + expectEqual(context.debugDescription, + "Decoded elements aren't unique (first duplicate at offset 2)") + } + } + } + + func test_append_many() { + #if COLLECTIONS_INTERNAL_CHECKS + // This test just takes too long with O(n) appends. + let count = 1_000 + #else + let count = 10_000 + #endif + + var set: OrderedSet = [] + withEvery("item", in: 0 ..< count) { item in + let res1 = set.append(item) + expectTrue(res1.inserted) + expectEqual(set[res1.index], item) + + let res2 = set.append(item) + expectFalse(res2.inserted) + expectEqual(res2.index, res1.index) + + expectEqual(set[res1.index], item) // Original index must remain valid. + expectEqual(set[res2.index], item) + } + } + + func test_append() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) }.shuffled() + var reference: [Int: Int] = [:] // Value to expected offset + var actual: OrderedSet = [] + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let (inserted, index) = actual.append(item) + expectEqual(actual[index], item) + if let expectedOffset = reference[item] { + // Existing item + expectFalse(inserted) + expectEqual(index, expectedOffset) + } else { + expectTrue(inserted) + expectEqual(index, reference.count) + reference[item] = reference.count + } + } + } + } + // Check CoW copying behavior + do { + var set = OrderedSet(0 ..< 30) + let copy = set + expectTrue(set.append(30).inserted) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } + + func test_append_contentsOf() { + withEvery("chunkLength", in: 1 ..< 10) { chunkLength in + withEvery("chunkOverlap", in: 0 ... chunkLength) { chunkOverlap in + var actual: OrderedSet = [] + var chunkStart = 0 + var expectedCount = 0 + withEvery("iteration", in: 0 ..< 100) { _ in + let chunk = chunkStart ..< chunkStart + chunkLength + actual.append(contentsOf: chunk) + expectedCount = chunk.upperBound + expectEqual(actual.count, expectedCount) + chunkStart += chunkLength - chunkOverlap + } + expectEqualElements(actual, 0 ..< expectedCount) + } + } + } + + func test_insert_at() { + withOrderedSetLayouts(scales: [0, 5, 6]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + withEvery("offset", in: 0 ... count) { offset in + var set = OrderedSet(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let i = set.index(set.startIndex, offsetBy: offset) + let (inserted, index) = set.insert(count, at: i) + expectTrue(inserted) + expectEqual(set.count, count + 1) + expectEqual(set[index], count) + expectEqualElements(set[..) + expectEqualElements(set, (0 ..< count).reversed()) + } + } + } + } + } + + func test_shuffle() { + withOrderedSetLayouts(scales: [0, 5, 6]) { layout in + guard layout.count > 1 else { return } + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + var contents = Array(0 ..< count) + var set = OrderedSet(layout: layout, contents: 0 ..< count) + withHiddenCopies(if: isShared, of: &set) { set in + var rng1 = RepeatableRandomNumberGenerator(seed: seed) + contents.shuffle(using: &rng1) + + var rng2 = RepeatableRandomNumberGenerator(seed: seed) + set.shuffle(using: &rng2) + + expectEqualElements(set, contents) + + // Check that shuffling with system RNG does permute the elements. + var success = false + for _ in 0 ..< 1000 { + set.shuffle() + if !set.elementsEqual(contents) { + success = true + break + } + } + expectTrue(success) + } + } + } + } + } + + func test_reverse() { + withOrderedSetLayouts(scales: [0, 5, 6]) { layout in + guard layout.count > 1 else { return } + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + var contents = Array(0 ..< count) + var set = OrderedSet(layout: layout, contents: 0 ..< count) + withHiddenCopies(if: isShared, of: &set) { set in + contents.reverse() + set.reverse() + expectEqualElements(set, contents) + } + } + } + } + + func test_remove_at() { + withOrderedSetLayouts(scales: [0, 5, 6]) { layout in + withEvery("offset", in: 0 ..< layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + var set = OrderedSet(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let count = layout.count + let index = set._index(at: offset) + let old = set.remove(at: index) + expectEqual(old, offset) + expectEqualElements(set[..._minimumCapacity(forScale: scale) { + expectLessThan(set.__unstable.scale, scale) + } else { + expectEqual(set.__unstable.scale, scale) + } + } + } + } + + + + func test_remove_existing_element() { + withOrderedSetLayouts(scales: [0, 5, 6]) { layout in + withEvery("item", in: 0 ..< layout.count) { item in + withEvery("isShared", in: [false, true]) { isShared in + var set = OrderedSet(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let count = layout.count + let old = set.remove(item) + expectEqual(old, item) + expectEqualElements(set[..._minimumCapacity(forScale: layout.scale) { + expectLessThan(set.__unstable.scale, layout.scale) + } + + expectEqualElements(set[_offsets: ..= offsetRange.upperBound { + expectEqual(set.firstIndex(of: i), + set._index(at: i - offsetRange.count)) + } else { + expectNil(set.firstIndex(of: i)) + } + } + } + } + } + } + } + + func test_init_minimumCapacity() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let expectedScale = OrderedSet._scale(forCapacity: capacity) + let set = OrderedSet(minimumCapacity: capacity) + expectEqual(set.__unstable.scale, expectedScale) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, + OrderedSet._minimumCapacity(forScale: expectedScale)) + } + } + + func test_init_minimumCapacity_persistent() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let expectedScale = OrderedSet._scale(forCapacity: capacity) + let set = OrderedSet(minimumCapacity: capacity, persistent: true) + expectEqual(set.__unstable.scale, expectedScale) + expectEqual(set.__unstable.reservedScale, expectedScale) + expectEqual(set.__unstable.minimumCapacity, 0) + } + } + + func test_reserveCapacity_empty() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let expectedScale = OrderedSet._scale(forCapacity: capacity) + var set = OrderedSet() + expectEqual(set.__unstable.scale, 0) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, 0) + + set.reserveCapacity(capacity) + expectEqual(set.__unstable.scale, expectedScale) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, + OrderedSet._minimumCapacity(forScale: expectedScale)) + + set.reserveCapacity(0) + expectEqual(set.__unstable.scale, 0) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, 0) + } + } + + func test_reserveCapacity_empty_persistent() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let scale = OrderedSet._scale(forCapacity: capacity) + var set = OrderedSet(minimumCapacity: capacity, persistent: true) + expectEqual(set.__unstable.scale, scale) + expectEqual(set.__unstable.reservedScale, scale) + expectEqual(set.__unstable.minimumCapacity, 0) + + set.reserveCapacity(capacity) + expectEqual(set.__unstable.scale, scale) + expectEqual(set.__unstable.reservedScale, scale) + expectEqual(set.__unstable.minimumCapacity, 0) + + let scale2 = OrderedSet._scale(forCapacity: 2 * capacity) + set.reserveCapacity(2 * capacity) + expectEqual(set.__unstable.scale, scale2) + expectEqual(set.__unstable.reservedScale, scale) + let minimum2 = OrderedSet._minimumCapacity(forScale: scale2) + expectEqual(set.__unstable.minimumCapacity, (scale == scale2 ? 0 : minimum2)) + + let expectedScale3 = OrderedSet._scale(forCapacity: 2 * capacity + 100) + set.reserveCapacity(2 * capacity + 100) + expectEqual(set.__unstable.scale, expectedScale3) + expectEqual(set.__unstable.reservedScale, scale) + let minimum3 = OrderedSet._minimumCapacity(forScale: expectedScale3) + expectEqual(set.__unstable.minimumCapacity, minimum3) + + set.reserveCapacity(0) + expectEqual(set.__unstable.scale, scale) + expectEqual(set.__unstable.reservedScale, scale) + expectEqual(set.__unstable.minimumCapacity, 0) + } + } + + func test_reserveCapacity_behavior() { + let scale1 = 6 + let range1 = 16 ... 48 + let count1 = 32 + + let scale2 = 8 + let range2 = 64 ... 192 + let count2 = 128 + + var set = OrderedSet(0 ..< count1) + expectEqual(set.__unstable.scale, scale1) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, range1.lowerBound) + expectEqual(set.__unstable.capacity, range1.upperBound) + + set.__unstable.reserveCapacity(count2, persistent: false) + expectEqual(set.__unstable.scale, scale2) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, + OrderedSet._minimumCapacity(forScale: scale2)) + expectEqual(set.__unstable.capacity, range2.upperBound) + + set.__unstable.reserveCapacity(count2, persistent: true) + expectEqual(set.__unstable.scale, scale2) + expectEqual(set.__unstable.reservedScale, scale2) + expectEqual(set.__unstable.minimumCapacity, 0) + expectEqual(set.__unstable.capacity, range2.upperBound) + + set.append(contentsOf: count1 ..< count2) + expectEqual(set.__unstable.scale, scale2) + expectEqual(set.__unstable.reservedScale, scale2) + expectEqual(set.__unstable.minimumCapacity, 0) + expectEqual(set.__unstable.capacity, range2.upperBound) + + set.__unstable.reserveCapacity(0, persistent: false) + expectEqual(set.__unstable.scale, scale2) + expectEqual(set.__unstable.reservedScale, scale2) + expectEqual(set.__unstable.minimumCapacity, 0) + expectEqual(set.__unstable.capacity, range2.upperBound) + + set.removeSubrange(set._indexRange(at: count1...)) + expectEqual(set.__unstable.scale, scale2) + expectEqual(set.__unstable.reservedScale, scale2) + expectEqual(set.__unstable.minimumCapacity, 0) + expectEqual(set.__unstable.capacity, range2.upperBound) + + set.__unstable.reserveCapacity(0, persistent: true) + expectEqual(set.__unstable.scale, scale1) + expectEqual(set.__unstable.reservedScale, 0) + expectEqual(set.__unstable.minimumCapacity, range1.lowerBound) + expectEqual(set.__unstable.capacity, range1.upperBound) + } + + func withSampleRanges( + file: StaticString = #file, + line: UInt = #line, + _ body: (Range, Range) throws -> Void + ) rethrows { + for c1 in [0, 10, 32, 64, 128, 256] { + for c2 in [0, 10, 32, 64, 128, 256] { + for overlap in Set([0, 1, c1 / 2, c1, -5]) { + let r1 = 0 ..< c1 + let r2 = c1 - overlap ..< c1 - overlap + c2 + if r1.lowerBound <= r2.lowerBound { + let e1 = context.push("range1: \(r1)", file: file, line: line) + let e2 = context.push("range2: \(r2)", file: file, line: line) + defer { + context.pop(e2) + context.pop(e1) + } + try body(r1, r2) + } else { + let e1 = context.push("range1: \(r2)", file: file, line: line) + let e2 = context.push("range2: \(r1)", file: file, line: line) + defer { + context.pop(e2) + context.pop(e1) + } + try body(r2, r1) + } + } + } + } + } + + func test_union_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + let actual1 = u1.union(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.union(u2).union(u1) + expectEqualElements(actual2, expected) + } + } + + func test_formUnion_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + + var res: OrderedSet = [] + + let u1 = OrderedSet(r1) + res.formUnion(u1) + expectEqualElements(res, r1) + + let u2 = OrderedSet(r2) + res.formUnion(u2) + expectEqualElements(res, expected) + + res.formUnion(u1) + res.formUnion(u2) + expectEqualElements(res, expected) + } + } + + func test_union_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + let u1 = OrderedSet(r1) + let u2 = u1.union(r2) + expectEqualElements(u2, expected) + + let u3 = u2.union(r1) + expectEqualElements(u3, expected) + } + } + + func test_formUnion_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + + var res = OrderedSet() + + res.formUnion(r1) + expectEqualElements(res, r1) + + res.formUnion(r2) + expectEqualElements(res, expected) + + res.formUnion(r1) + res.formUnion(r2) + expectEqualElements(res, expected) + } + } + + func test_intersection_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + let actual1 = u1.intersection(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.intersection(r1) + expectEqualElements(actual2, expected) + } + } + + func test_formIntersection_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + var res = u1 + res.formIntersection(u2) + expectEqualElements(res, expected) + expectEqualElements(u1, r1) + + res.formIntersection(u1) + res.formIntersection(u2) + expectEqualElements(res, expected) + } + } + + func test_intersection_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + let u1 = OrderedSet(r1) + let actual1 = u1.intersection(r2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.intersection(r1).intersection(r2) + expectEqualElements(actual2, expected) + } + } + + func test_formIntersection_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + var res = OrderedSet(r1) + res.formIntersection(r2) + expectEqualElements(res, expected) + + res.formIntersection(r1) + res.formIntersection(r2) + expectEqualElements(res, expected) + } + } + + func test_symmetricDifference_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + let actual1 = u1.symmetricDifference(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.symmetricDifference(u1).symmetricDifference(u2) + expectEqual(actual2.count, 0) + } + } + + func test_formSymmetricDifference_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + var res = u1 + res.formSymmetricDifference(u2) + expectEqualElements(res, expected) + expectEqualElements(u1, r1) + + res.formSymmetricDifference(u1) + res.formSymmetricDifference(u2) + expectEqual(res.count, 0) + } + } + + func test_symmetricDifference_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + let u1 = OrderedSet(r1) + let actual1 = u1.symmetricDifference(r2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.symmetricDifference(r1).symmetricDifference(r2) + expectEqual(actual2.count, 0) + } + } + + func test_formSymmetricDifference_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + var res = OrderedSet(r1) + res.formSymmetricDifference(r2) + expectEqualElements(res, expected) + + res.formSymmetricDifference(r1) + res.formSymmetricDifference(r2) + expectEqual(res.count, 0) + } + } + + func test_subtracting_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + let actual1 = u1.subtracting(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.subtracting(u2) + expectEqualElements(actual2, expected) + } + } + + func test_subtract_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + let u1 = OrderedSet(r1) + let u2 = OrderedSet(r2) + var res = u1 + res.subtract(u2) + expectEqualElements(res, expected) + expectEqualElements(u1, r1) + + res.subtract(u2) + expectEqualElements(res, expected) + } + } + + func test_subtracting_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + let u1 = OrderedSet(r1) + let actual1 = u1.subtracting(r2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.subtracting(r2) + expectEqualElements(actual2, expected) + } + } + + func test_subtract_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + var res = OrderedSet(r1) + res.subtract(r2) + expectEqualElements(res, expected) + + res.subtract(r2) + expectEqualElements(res, expected) + } + } + + struct SampleRanges { + let unit: Int + + init(unit: Int) { + self.unit = unit + } + + var empty: Range { unit ..< unit } + + var a: Range { 0 ..< unit } + var b: Range { unit ..< 2 * unit } + var c: Range { 2 * unit ..< 3 * unit } + + var ab: Range { 0 ..< 2 * unit } + var bc: Range { unit ..< 3 * unit } + + var abc: Range { 0 ..< 3 * unit } + + var ranges: [Range] { [empty, a, b, c, ab, bc, abc] } + + func withEveryPair( + _ body: (Range, Range) throws -> Void + ) rethrows { + try withEvery("range1", in: ranges) { range1 in + try withEvery("range2", in: ranges) { range2 in + try body(range1, range2) + } + } + } + } + + func test_isSubset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSubset(of: r2) + let a = OrderedSet(r1) + let b = OrderedSet(r2) + expectEqual(a.isSubset(of: b), expected) + } + } + } + + func test_isSubset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSubset(of: r2) + let a = OrderedSet(r1) + let b = Set(r2) + expectEqual(a.isSubset(of: b), expected) + } + } + } + + func test_isSubset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSubset(of: r2) + let a = OrderedSet(r1) + let b = r2 + expectEqual(a.isSubset(of: b), expected) + } + } + } + + func test_isSuperset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSuperset(of: r2) + let a = OrderedSet(r1) + let b = OrderedSet(r2) + expectEqual(a.isSuperset(of: b), expected) + } + } + } + + func test_isSuperset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSuperset(of: r2) + let a = OrderedSet(r1) + let b = Set(r2) + expectEqual(a.isSuperset(of: b), expected) + } + } + } + + func test_isSuperset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSuperset(of: r2) + let a = OrderedSet(r1) + let b = r2 + expectEqual(a.isSuperset(of: b), expected) + } + } + } + + func test_isStrictSubset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSubset(of: r2) + let a = OrderedSet(r1) + let b = OrderedSet(r2) + expectEqual(a.isStrictSubset(of: b), expected) + } + } + } + + func test_isStrictSubset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSubset(of: r2) + let a = OrderedSet(r1) + let b = Set(r2) + expectEqual(a.isStrictSubset(of: b), expected) + } + } + } + + func test_isStrictSubset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSubset(of: r2) + let a = OrderedSet(r1) + let b = r2 + expectEqual(a.isStrictSubset(of: b), expected) + } + } + } + + func test_isStrictSuperset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSuperset(of: r2) + let a = OrderedSet(r1) + let b = OrderedSet(r2) + expectEqual(a.isStrictSuperset(of: b), expected) + } + } + } + + func test_isStrictSuperset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSuperset(of: r2) + let a = OrderedSet(r1) + let b = Set(r2) + expectEqual(a.isStrictSuperset(of: b), expected) + } + } + } + + func test_isStrictSuperset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSuperset(of: r2) + let a = OrderedSet(r1) + let b = r2 + expectEqual(a.isStrictSuperset(of: b), expected) + } + } + } + + func test_isDisjoint_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isDisjoint(with: r2) + let a = OrderedSet(r1) + let b = OrderedSet(r2) + expectEqual(a.isDisjoint(with: b), expected) + } + } + } + + func test_isDisjoint_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isDisjoint(with: r2) + let a = OrderedSet(r1) + let b = Set(r2) + expectEqual(a.isDisjoint(with: b), expected) + } + } + } + + func test_isDisjoint_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isDisjoint(with: r2) + let a = OrderedSet(r1) + let b = r2 + expectEqual(a.isDisjoint(with: b), expected) + } + } + } +} diff --git a/Tests/OrderedCollectionsTests/OrderedSet/RandomAccessCollection+Offsets.swift b/Tests/OrderedCollectionsTests/OrderedSet/RandomAccessCollection+Offsets.swift new file mode 100644 index 00000000..79db7ede --- /dev/null +++ b/Tests/OrderedCollectionsTests/OrderedSet/RandomAccessCollection+Offsets.swift @@ -0,0 +1,61 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension RandomAccessCollection { + @inline(__always) + internal func _index(at offset: Int) -> Index { + index(startIndex, offsetBy: offset) + } + + @inline(__always) + internal func _offset(of index: Index) -> Int { + distance(from: startIndex, to: index) + } + + @inline(__always) + internal func _indexRange(at offsets: Range) -> Range { + _index(at: offsets.lowerBound) ..< _index(at: offsets.upperBound) + } + + @inline(__always) + internal func _indexRange(at offsets: R) -> Range + where R.Bound == Int { + return _indexRange(at: offsets.relative(to: 0 ..< self.count)) + } + + @inline(__always) + internal func _offsetRange(of range: Range) -> Range { + _offset(of: range.lowerBound) ..< _offset(of: range.upperBound) + } + + @inline(__always) + internal func _offsetRange(of range: R) -> Range + where R.Bound == Index { + return _offsetRange(of: range.relative(to: self)) + } + + @inline(__always) + internal subscript(_offset offset: Int) -> Element { + self[_index(at: offset)] + } + + @inline(__always) + internal subscript(_offsets range: Range) -> SubSequence { + self[_indexRange(at: range)] + } + + @inline(__always) + internal subscript(_offsets range: R) -> SubSequence + where R.Bound == Int { + self[_offsets: range.relative(to: 0 ..< count)] + } +} + diff --git a/Tests/UniquedTests/BItsetTests.swift b/Tests/UniquedTests/BItsetTests.swift new file mode 100644 index 00000000..a9be8382 --- /dev/null +++ b/Tests/UniquedTests/BItsetTests.swift @@ -0,0 +1,187 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#if DEBUG // These unit tests need access to Uniqued internals +import XCTest +import CollectionsTestSupport +@_spi(Testing) @testable import UniquedModule + +class BitsetTests: CollectionTestCase { + typealias Word = _UnsafeBitset.Word + + func test_empty() { + withEvery("capacity", in: 0 ..< 500) { capacity in + _UnsafeBitset.withTemporaryBitset(capacity: capacity) { bitset in + expectGreaterThanOrEqual(bitset.capacity, capacity) + expectEqual(bitset.count, 0) + expectEqual(bitset._actualCount, 0) + withEvery("i", in: 0 ..< capacity) { i in + expectFalse(bitset.contains(i)) + } + } + } + } + + func test_insert() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withEvery("seed", in: 0 ..< 3) { seed in + var rng = RepeatableRandomNumberGenerator(seed: seed) + let items = (0 ..< capacity).shuffled(using: &rng) + _UnsafeBitset.withTemporaryBitset(capacity: capacity) { bitset in + var c = 0 + withEvery("item", in: items) { item in + expectFalse(bitset.contains(item)) + expectTrue(bitset.insert(item)) + + expectTrue(bitset.contains(item)) + expectFalse(bitset.insert(item)) + + c += 1 + expectEqual(bitset.count, c) + } + } + } + } + } + + func withRandomBitsets( + capacity: Int, + loadFactor: Double, + body: (inout _UnsafeBitset, inout Set) throws -> Void + ) rethrows { + precondition(loadFactor >= 0 && loadFactor <= 1) + try withEvery("seed", in: 0 ..< 10) { seed in + var rng = RepeatableRandomNumberGenerator(seed: seed) + var items = (0 ..< capacity).shuffled(using: &rng) + items.removeLast(Int((1 - loadFactor) * Double(capacity))) + try _UnsafeBitset.withTemporaryBitset(capacity: capacity) { bitset in + for item in items { + bitset.insert(item) + } + var set = Set(items) + try body(&bitset, &set) + } + } + } + + func test_remove() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + var c = contents.count + withEvery("item", in: 0 ..< capacity) { item in + if contents.contains(item) { + expectTrue(bitset.remove(item)) + expectFalse(bitset.contains(item)) + c -= 1 + expectEqual(bitset.count, c) + } else { + expectFalse(bitset.remove(item)) + expectEqual(bitset.count, c) + } + } + expectEqual(bitset.count, 0) + withEvery("item", in: 0 ..< capacity) { item in + expectFalse(bitset.contains(item)) + } + } + } + } + + func test_clear() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + bitset.clear() + expectEqual(bitset.count, 0) + withEvery("item", in: 0 ..< capacity) { item in + expectFalse(bitset.contains(item)) + } + } + } + } + + func test_insertAll_upTo() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + + let cutoff = capacity / 2 + bitset.insertAll(upTo: cutoff) + expectEqual( + bitset.count, + capacity / 2 + contents.lazy.filter { $0 >= cutoff }.count) + withEvery("item", in: 0 ..< capacity) { item in + if item < cutoff { + expectTrue(bitset.contains(item)) + } else { + expectEqual(bitset.contains(item), contents.contains(item)) + } + } + + bitset.insertAll(upTo: capacity) + expectEqual(bitset.count, capacity) + withEvery("item", in: 0 ..< capacity) { item in + expectTrue(bitset.contains(item)) + } + } + } + } + + func test_removeAll_upTo() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + + let cutoff = capacity / 2 + bitset.removeAll(upTo: cutoff) + expectEqual( + bitset.count, + contents.lazy.filter { $0 >= cutoff }.count) + withEvery("item", in: 0 ..< capacity) { item in + if item < cutoff { + expectFalse(bitset.contains(item)) + } else { + expectEqual(bitset.contains(item), contents.contains(item)) + } + } + + bitset.removeAll(upTo: capacity) + expectEqual(bitset.count, 0) + withEvery("item", in: 0 ..< capacity) { item in + expectFalse(bitset.contains(item)) + } + } + } + } + + func test_Sequence() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + expectEqual(bitset.underestimatedCount, contents.count) + let expected = contents.sorted() + var actual: [Int] = [] + actual.reserveCapacity(bitset.count) + for item in bitset { + actual.append(item) + } + expectEqual(actual, expected) + } + } + } + + func test_max() { + withEvery("capacity", in: [16, 64, 100, 128, 1000, 1024]) { capacity in + withRandomBitsets(capacity: capacity, loadFactor: 0.5) { bitset, contents in + let max = bitset.max() + expectEqual(max, contents.max()) + } + } + } + +} +#endif // DEBUG diff --git a/Tests/UniquedTests/HashTableTests.swift b/Tests/UniquedTests/HashTableTests.swift new file mode 100644 index 00000000..f168a479 --- /dev/null +++ b/Tests/UniquedTests/HashTableTests.swift @@ -0,0 +1,607 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +#if DEBUG // These unit tests need access to Uniqued internals +import XCTest +import CollectionsTestSupport +@_spi(Testing) @testable import UniquedModule + +class HashTableTests: CollectionTestCase { + func test_capacity() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let scale = _UnsafeHashTable.scale(forCapacity: capacity) + let maximumCapacity = _UnsafeHashTable.maximumCapacity(forScale: scale) + let minimumCapacity = _UnsafeHashTable.minimumCapacity(forScale: scale) + + if scale == 0 { + expectEqual(minimumCapacity, 0) + expectEqual(maximumCapacity, _UnsafeHashTable.maximumUnhashedCount) + expectGreaterThanOrEqual(maximumCapacity, capacity) + } else { + let bucketCount = 1 &<< scale + expectGreaterThanOrEqual(scale, _UnsafeHashTable.minimumScale) + expectLessThan(scale, _UnsafeHashTable.maximumScale) + expectGreaterThanOrEqual(maximumCapacity, capacity) + expectGreaterThan(bucketCount, maximumCapacity) + expectLessThan(minimumCapacity, maximumCapacity) + expectLessThanOrEqual(minimumCapacity, capacity) + expectGreaterThan(minimumCapacity, 0) + } + } + } + + func test_Storage_create() { + let s5 = _HashTableStorage.create(scale: 5) + expectEqual(s5.header.scale, 5) + expectEqual(s5.header.reservedScale, 0) + expectTrue(s5.description.starts(with: "_HashTableStorage(scale: 5, reservedScale: 0, bias: 0, seed: ")) + expectTrue(s5.header.description.starts(with: "_HashTableHeader(scale: 5, reservedScale: 0, bias: 0, seed: ")) + s5.read { hashTable in + for i in 0 ..< 32 { + let bucket = _Bucket(offset: i) + expectNil(hashTable[bucket], "\(bucket.offset)") + } + } + + let s6 = _HashTableStorage.create(scale: 6) + expectEqual(s6.header.scale, 6) + expectEqual(s6.header.reservedScale, 0) + expectTrue(s6.description.starts(with: "_HashTableStorage(scale: 6, reservedScale: 0, bias: 0, seed: ")) + expectTrue(s6.header.description.starts(with: "_HashTableHeader(scale: 6, reservedScale: 0, bias: 0, seed: ")) + s6.read { hashTable in + for i in 0 ..< 64 { + let bucket = _Bucket(offset: i) + expectNil(hashTable[bucket], "\(bucket.offset)") + } + } + + expectNotEqual(s6.header.seed, s5.header.seed) // This is somewhat shaky b/c we're losing address bits + + expectEqual(s5.header.capacity, 24) // 0.75 * 2^5 + expectEqual(s6.header.capacity, 48) // 0.75 * 2^6 + } + + func test_Storage_read() { + let s5 = _HashTableStorage.create(scale: 5) + s5.read { hashTable in + expectEqual(hashTable.scale, 5) + expectEqual(hashTable.reservedScale, 0) + expectEqual(hashTable.seed, s5.header.seed) + expectTrue(hashTable.description.starts(with: "_UnsafeHashTable(scale: 5, reservedScale: 0, bias: 0, seed: ")) + } + let s6 = _HashTableStorage.create(scale: 6) + s6.read { hashTable in + expectEqual(hashTable.scale, 6) + expectEqual(hashTable.reservedScale, 0) + expectEqual(hashTable.seed, s6.header.seed) + expectTrue(hashTable.description.starts(with: "_UnsafeHashTable(scale: 6, reservedScale: 0, bias: 0, seed: ")) + } + } + + func test_counts() { + let s5 = _HashTableStorage.create(scale: 5) + s5.read { hashTable in + expectEqual(hashTable.bucketCount, 32) + expectEqual(hashTable.bitCount, 5 * 32) + expectEqual(hashTable.wordCount, 3) // 2.5 rounded up + expectEqual(hashTable.capacity, 24) // 0.75 * 32 + } + let s6 = _HashTableStorage.create(scale: 6) + s6.read { hashTable in + expectEqual(hashTable.bucketCount, 64) + expectEqual(hashTable.bitCount, 6 * 64) + expectEqual(hashTable.wordCount, 6) + expectEqual(hashTable.capacity, 48) // 0.75 * 64 + } + let s12 = _HashTableStorage.create(scale: 12) + s12.read { hashTable in + expectEqual(hashTable.bucketCount, 4096) + expectEqual(hashTable.bitCount, 12 * 4096) + expectEqual(hashTable.wordCount, 768) + expectEqual(hashTable.capacity, 3072) // 0.75 * 4096 + } + } + + func test_bucket_after() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + storage.read { hashTable in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let input = _Bucket(offset: offset) + let expected = _Bucket(offset: offset == hashTable.bucketCount - 1 ? 0 : offset + 1) + let actual = hashTable.bucket(after: input) + expectEqual(actual, expected) + } + } + } + } + func test_bucket_before() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + storage.read { hashTable in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let input = _Bucket(offset: offset) + let expected = _Bucket(offset: offset == 0 ? hashTable.bucketCount - 1 : offset - 1) + let actual = hashTable.bucket(before: input) + expectEqual(actual, expected) + } + } + } + } + func test_word_after() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + storage.read { hashTable in + withEvery("input", in: 0 ..< hashTable.wordCount) { input in + let expected = (input == hashTable.wordCount - 1 ? 0 : input + 1) + let actual = hashTable.word(after: input) + expectEqual(actual, expected) + } + } + } + } + func test_word_before() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + storage.read { hashTable in + withEvery("input", in: 0 ..< hashTable.wordCount) { input in + let expected = (input == 0 ? hashTable.wordCount - 1 : input - 1) + let actual = hashTable.word(before: input) + expectEqual(actual, expected) + } + } + } + } + func test_coordinates_for_bucket() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + storage.read { hashTable in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let (word, bit) = hashTable.position(of: _Bucket(offset: offset)) + expectGreaterThanOrEqual(bit, 0) + expectGreaterThanOrEqual(word, 0) + expectLessThan(bit, 64) + expectLessThan(word, hashTable.wordCount) + let pos = 64 * word + bit + expectEqual(pos % scale, 0) + expectEqual(pos / scale, offset) + } + } + } + } + + func test_bucketContents_forValue() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + storage.read { hashTable in + expectEqual(hashTable._bucketContents(for: nil), 0) + expectEqual(hashTable._value(forBucketContents: 0), nil) + withEvery("value", in: 0 ..< hashTable.bucketCount - 1) { value in + let contents = hashTable._bucketContents(for: value) + expectEqual(hashTable._value(forBucketContents: contents), value) + } + } + } + } + + func test_subscript_by_bucket() { + withEvery("scale", in: [5, 6, 12]) { scale in + let storage = _HashTableStorage.create(scale: scale) + let bucketCount = 1 << scale + let contents: [Int?] = Array(0 ..< bucketCount - 1) + [nil] + storage.update { hashTable in + for offset in 0 ..< bucketCount { + let bucket = _Bucket(offset: offset) + hashTable[bucket] = contents[offset] + } + } + storage.read { hashTable in + withEvery("offset", in: 0 ..< bucketCount) { offset in + let bucket = _Bucket(offset: offset) + expectEqual(hashTable[bucket], contents[offset]) + } + } + } + } + + /// Create hash table storage of scale `scale`, filled with equal-sized lookup chains + /// of length `chainLength`, separated by holes of length `holeLength`, with the + /// first chain starting at `startOffset`. The chains contain bucket values that + /// sequentially count up from 0. + func sampleStorage( + scale: Int, + chainLength: Int, + holeLength: Int, + startingAt startOffset: Int + ) -> (storage: _HashTableStorage, contents: [Int?]) { + let bucketCount = 1 << scale + + var contents: [Int?] = [] + contents.reserveCapacity(bucketCount + chainLength + holeLength) + contents.append(contentsOf: repeatElement(nil, count: startOffset)) + var i = 0 + while contents.count < bucketCount { + contents.append(contentsOf: (i ..< i + chainLength).map { $0 }) + i += chainLength + contents.append(contentsOf: repeatElement(nil, count: holeLength)) + } + contents.removeLast(contents.count - bucketCount) + + let storage = _HashTableStorage.create(scale: scale) + storage.update { hashTable in + for offset in 0 ..< bucketCount { + let bucket = _Bucket(offset: offset) + hashTable[bucket] = contents[offset] + } + } + return (storage, contents) + } + + /// Call `body` with a hash table of scale `scale`, filled with equal-sized lookup chains + /// of length `chainLength`, separated by holes of length `holeLength`, with the + /// first chain starting at `startOffset`. The chains contain bucket values that + /// sequentially count up from 0. + func withSampleHashTable( + scale: Int, + chainLength: Int, + holeLength: Int, + startingAt startOffset: Int, + body: (_UnsafeHashTable, [Int?]) throws -> R + ) rethrows -> R { + let (storage, contents) = sampleStorage( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset) + return try storage.update { hashTable in + try body(hashTable, contents) + } + } + + /// Create hash table storage of scale `scale`, filled with a single huge lookup chain + /// of buckets counting sequentially up starting at 0, terminating with the penultimate + /// bucket. The last bucket remains unoccupied. + /// + /// This is useful for testing all possible bucket values. + func sampleStorage(scale: Int) -> (storage: _HashTableStorage, contents: [Int?]) { + sampleStorage(scale: scale, chainLength: (1 << scale) - 1, holeLength: 1, startingAt: 0) + } + + /// Call `body` with a hash table of scale `scale`, filled with a single huge lookup chain + /// of buckets counting sequentially up starting at 0, terminating with the penultimate + /// bucket. The last bucket remains unoccupied. + /// + /// This is useful for testing all possible bucket values. + func withSampleHashTable( + scale: Int, + body: (_UnsafeHashTable, [Int?]) throws -> R + ) rethrows -> R { + let (storage, contents) = sampleStorage(scale: scale) + return try storage.update { hashTable in + try body(hashTable, contents) + } + } + + func test_bucketIterator_read() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withSampleHashTable(scale: scale) { hashTable, contents in + // Start an iterator at the first bucket and cycle through + // all buckets twice, checking the values we see at every step. + let bucket = _Bucket(offset: 0) + var it = hashTable.bucketIterator(startingAt: bucket) + expectEqual(it.currentBucket, bucket) + expectEqual(it.isOccupied, contents[bucket.offset] != nil) + expectEqual(it.currentValue, contents[bucket.offset]) + withEvery("iteration", in: 0 ..< 2) { _ in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let expected = contents[offset] + expectEqual(it.currentBucket, _Bucket(offset: offset)) + expectEqual(it.isOccupied, expected != nil) + expectEqual(it.currentValue, expected) + it.advance() + } + } + } + } + } + + func test_bucketIterator_read_with_holes() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + // Start an iterator at the first bucket and cycle through + // all buckets twice, checking the values we see at every step. + let bucket = _Bucket(offset: 0) + var it = hashTable.bucketIterator(startingAt: bucket) + expectEqual(it.currentBucket, bucket) + expectEqual(it.isOccupied, contents[bucket.offset] != nil) + expectEqual(it.currentValue, contents[bucket.offset]) + withEvery("iteration", in: 0 ..< 2) { _ in + withEvery("offset", in: 0 ..< hashTable.bucketCount) { offset in + let expected = contents[offset] + expectEqual(it.currentBucket, _Bucket(offset: offset)) + expectEqual(it.isOccupied, expected != nil) + expectEqual(it.currentValue, expected) + it.advance() + } + } + } + } + } + } + } + } + + func test_bucketIterator_start_in_middle() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withSampleHashTable(scale: scale) { hashTable, contents in + var expected = hashTable.bucketIterator(startingAt: _Bucket(offset: 0)) + // Start a new iterator at every bucket and check that its initial + // state is match exactly what we'd get by starting at the first + // bucket and advancing step by step to the same position. + withEvery("start", in: 0 ..< hashTable.bucketCount) { start in + let bucket = _Bucket(offset: start) + let actual = hashTable.bucketIterator(startingAt: bucket) + + expectEqual(expected.currentBucket, bucket) + expectEqual(expected.currentValue, contents[start]) + + expectEqual(actual.currentBucket, bucket) + expectEqual(actual.currentValue, contents[start]) + + expectEqual(actual._currentBucket, expected._currentBucket) + expectEqual(actual._currentRawValue, expected._currentRawValue) + expectEqual(actual._nextBits, expected._nextBits) + expectEqual(actual._remainingBitCount, expected._remainingBitCount) + + expected.advance() + } + } + } + } + + func test_bucketIterator_start_in_middle_with_holes() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + var expected = hashTable.bucketIterator(startingAt: _Bucket(offset: 0)) + // Start a new iterator at every bucket and check that its initial + // state is match exactly what we'd get by starting at the first + // bucket and advancing step by step to the same position. + withEvery("start", in: 0 ..< hashTable.bucketCount) { start in + let bucket = _Bucket(offset: start) + let actual = hashTable.bucketIterator(startingAt: bucket) + + expectEqual(expected.currentBucket, bucket) + expectEqual(expected.currentValue, contents[start]) + + expectEqual(actual.currentBucket, bucket) + expectEqual(actual.currentValue, contents[start]) + + expectEqual(actual._currentBucket, expected._currentBucket) + expectEqual(actual._currentRawValue, expected._currentRawValue) + expectEqual(actual._nextBits, expected._nextBits) + expectEqual(actual._remainingBitCount, expected._remainingBitCount) + + expected.advance() + } + } + } + } + } + } + } + + func test_bucketIterator_advance_until() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + var offset = 0 + var it = hashTable.bucketIterator(startingAt: _Bucket(offset: offset)) + let step = 2 + + for _ in 0 ..< hashTable.bucketCount { + if let value = contents[offset] { + // `advance(until:)` should not move if we're already on the right value. + it.advance(until: value) + expectEqual(it.currentBucket.offset, offset) + + // `advance(until:)` should stop when it find the value we're looking for, + // or at the next hole, whichever comes first. + it.advance(until: value + step) + expectTrue(it.currentValue == nil || it.currentValue == value + step) + var o = offset + while true { + o += 1 + if o == contents.count { o = 0 } + if o == it.currentBucket.offset { break } + expectNotNil(contents[o]) + } + offset = o + } else { + // `advance(until:)` should not move if we're on a hole. + it.advance(until: 0) + expectEqual(it.currentBucket.offset, offset) + + // Move to the next bucket. + offset += 1 + if offset == contents.count { offset = 0 } + it.advance() + } + } + } + } + } + } + } + } + + func test_bucketIterator_advance_toNextUnoccupiedBucket() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withEvery("chainLength", in: [1, 2, 3, 4]) { chainLength in + withEvery("holeLength", in: [1, 2, 3]) { holeLength in + withEvery("startOffset", in: 0 ... chainLength) { startOffset in + withSampleHashTable( + scale: scale, + chainLength: chainLength, + holeLength: holeLength, + startingAt: startOffset + ) { hashTable, contents in + var offset = 0 + var it = hashTable.bucketIterator(startingAt: _Bucket(offset: offset)) + + for _ in 0 ..< hashTable.bucketCount { + if contents[offset] != nil { + it.advanceToNextUnoccupiedBucket() + + expectNil(it.currentValue) + + while contents[offset] != nil { + offset += 1 + if offset == contents.count { offset = 0 } + } + expectEqual(it.currentBucket.offset, offset) + } else { + // `advanceToNextUnoccupiedBucket()` should not move if we're already on a hole. + it.advanceToNextUnoccupiedBucket() + expectEqual(it.currentBucket.offset, offset) + + // Move to the next bucket. + offset += 1 + if offset == contents.count { offset = 0 } + it.advance() + } + } + } + } + } + } + } + } + + func test_bucketIterator_write() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + withSampleHashTable(scale: scale) { hashTable, contents in + let storage = _HashTableStorage.create(scale: scale) + let bucketCount = 1 << scale + let contents: [Int?] = Array(0 ..< bucketCount - 1) + [nil] + storage.update { hashTable in + // Start an iterator at the first bucket and cycle through + // all buckets, updating values at every step. + let bucket = _Bucket(offset: 0) + var it = hashTable.bucketIterator(startingAt: bucket) + withEvery("writeOffset", in: 0 ..< contents.count) { writeOffset in + it.currentValue = contents[writeOffset] + it.advance() + } + // Cycle through one more time, verifying that contents match. + withEvery("readOffset", in: 0 ..< contents.count) { readOffset in + expectEqual(it.currentValue, contents[readOffset]) + it.advance() + } + } + } + } + } + + func test_Storage_copy() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (s1, contents) = sampleStorage(scale: scale) + let s2 = s1.copy() + s1.read { original in + s2.read { copy in + expectEqual(copy.scale, original.scale) + expectEqual(copy.reservedScale, original.reservedScale) + expectEqual(copy.seed, original.seed) + var it = copy.bucketIterator(startingAt: _Bucket(offset: 0)) + withEvery("offset", in: 0 ..< contents.count) { offset in + expectEqual(it.currentValue, contents[offset]) + it.advance() + } + } + } + } + } + + func test_bias() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (storage, contents) = sampleStorage(scale: scale) + withEvery("bias", in: [0, 1, -1, 2, -2, 30, -30]) { bias in + storage.update { hashTable in hashTable.bias = bias } + storage.read { hashTable in + var it = hashTable.bucketIterator(startingAt: _Bucket(offset: 0)) + repeat { + if let v = contents[it.currentBucket.offset] { + let m = hashTable.bucketCount - 1 + var expected = (v + bias) % m + if expected < 0 { expected += m } + expectEqual(it.currentValue, expected) + } else { + expectNil(it.currentValue) + } + it.advance() + } while it.currentBucket.offset != 0 + } + } + } + } + + func test_rawSubscript() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (storage, contents) = sampleStorage(scale: scale) + storage.read { hashTable in + var bucket = _Bucket(offset: 0) + repeat { + let expected = hashTable._bucketContents(for: contents[bucket.offset]) + expectEqual(hashTable[raw: bucket], expected) + bucket = hashTable.bucket(after: bucket) + } while bucket.offset != 0 + } + } + } + + func test_isOccupied() { + withEvery("scale", in: [5, 6, 7, 8, 12]) { scale in + let (storage, contents) = sampleStorage(scale: scale) + storage.read { hashTable in + var bucket = _Bucket(offset: 0) + repeat { + expectEqual(hashTable.isOccupied(bucket), contents[bucket.offset] != nil) + bucket = hashTable.bucket(after: bucket) + } while bucket.offset != 0 + } + } + } + +} + +#endif diff --git a/Tests/UniquedTests/RandomAccessCollection+Offsets.swift b/Tests/UniquedTests/RandomAccessCollection+Offsets.swift new file mode 100644 index 00000000..79db7ede --- /dev/null +++ b/Tests/UniquedTests/RandomAccessCollection+Offsets.swift @@ -0,0 +1,61 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +extension RandomAccessCollection { + @inline(__always) + internal func _index(at offset: Int) -> Index { + index(startIndex, offsetBy: offset) + } + + @inline(__always) + internal func _offset(of index: Index) -> Int { + distance(from: startIndex, to: index) + } + + @inline(__always) + internal func _indexRange(at offsets: Range) -> Range { + _index(at: offsets.lowerBound) ..< _index(at: offsets.upperBound) + } + + @inline(__always) + internal func _indexRange(at offsets: R) -> Range + where R.Bound == Int { + return _indexRange(at: offsets.relative(to: 0 ..< self.count)) + } + + @inline(__always) + internal func _offsetRange(of range: Range) -> Range { + _offset(of: range.lowerBound) ..< _offset(of: range.upperBound) + } + + @inline(__always) + internal func _offsetRange(of range: R) -> Range + where R.Bound == Index { + return _offsetRange(of: range.relative(to: self)) + } + + @inline(__always) + internal subscript(_offset offset: Int) -> Element { + self[_index(at: offset)] + } + + @inline(__always) + internal subscript(_offsets range: Range) -> SubSequence { + self[_indexRange(at: range)] + } + + @inline(__always) + internal subscript(_offsets range: R) -> SubSequence + where R.Bound == Int { + self[_offsets: range.relative(to: 0 ..< count)] + } +} + diff --git a/Tests/UniquedTests/Uniqued.UnorderedView Tests.swift b/Tests/UniquedTests/Uniqued.UnorderedView Tests.swift new file mode 100644 index 00000000..69a13c25 --- /dev/null +++ b/Tests/UniquedTests/Uniqued.UnorderedView Tests.swift @@ -0,0 +1,82 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import UniquedModule +import CollectionsTestSupport + +class UniquedUnorderedViewTests: CollectionTestCase { + typealias MinimalImmutableBase = MinimalRandomAccessCollection + typealias MinimalBase = MinimalRangeReplaceableRandomAccessCollection + typealias MinimalMutableBase = MinimalMutableRangeReplaceableRandomAccessCollection + + func test_unordered_insert() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + withLifetimeTracking { tracker in + let input = (0 ..< dupes * count) + .map { tracker.instance(for: $0 / dupes) } + .shuffled() + let reference: [Int: LifetimeTracked] = + .init(input.lazy.map { ($0.payload, $0) }, + uniquingKeysWith: { a, b in a }) + var set = Uniqued>>() + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let ref = reference[item.payload] + let (inserted, member) = set.unordered.insert(item) + expectEqual(inserted, ref === item) + expectEqual(member, item) + expectIdentical(member, ref) + expectTrue(set.contains(item)) + } + } + } + } + // Check CoW copying behavior + do { + var set = Uniqued>(0 ..< 30) + let copy = set + expectTrue(set.unordered.insert(30).inserted) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } + + func test_unordered_update() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + withLifetimeTracking { tracker in + let input = (0 ..< dupes * count) + .map { tracker.instance(for: $0 / dupes) } + .shuffled() + var reference: [Int: LifetimeTracked] = [:] + var set = Uniqued>>() + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let old = set.unordered.update(with: item) + expectIdentical(old, reference[item.payload]) + reference[item.payload] = item + expectTrue(set.contains(item)) + } + } + } + } + // Check CoW copying behavior + do { + var set = Uniqued>(0 ..< 30) + let copy = set + expectNil(set.unordered.update(with: 30)) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } +} diff --git a/Tests/UniquedTests/UniquedInternals.swift b/Tests/UniquedTests/UniquedInternals.swift new file mode 100644 index 00000000..531c17d6 --- /dev/null +++ b/Tests/UniquedTests/UniquedInternals.swift @@ -0,0 +1,81 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import CollectionsTestSupport +@_spi(Testing) import UniquedModule + +struct UniquedLayout: Hashable, CustomStringConvertible { + let scale: Int + let bias: Int + let count: Int + + var description: String { + "UniquedLayout(scale: \(scale), bias: \(bias), count: \(count))" + } +} + +func withUniquedLayouts( + scales: [Int], + file: StaticString = #file, + line: UInt = #line, + run body: (UniquedLayout) throws -> Void +) rethrows { + for scale in scales { + for count in _interestingCounts(forScale: scale) { + for bias in _interestingBiases(forScale: scale) { + let layout = UniquedLayout(scale: scale, bias: bias, count: count) + let entry = TestContext.current.push("layout: \(layout)") + defer { TestContext.current.pop(entry) } + try body(layout) + } + } + } +} + +func _interestingCounts(forScale scale: Int) -> [Int] { + precondition(scale == 0 || scale >= _UnsafeHashTable.minimumScale) + let min = _UnsafeHashTable.minimumCapacity(forScale: scale) + let max = _UnsafeHashTable.maximumCapacity(forScale: scale) + return [min, min + (max - min) / 2, max] +} + +func _interestingBiases(forScale scale: Int) -> [Int] { + // If we have no hash table, we can only use a bias of 0. + if scale < _UnsafeHashTable.minimumScale { return [0] } + let range = _UnsafeHashTable.biasRange(scale: scale) + // For the minimum scale, try all biases. + if scale == _UnsafeHashTable.minimumScale { return Array(range) } + // Otherwise try 3 biases each from the start, middle, and end of range. + var result: [Int] = [] + result += range.prefix(3) + result += range.prefix(range.count / 2 + 1).suffix(3) + result += range.suffix(3) + return result +} + +extension Uniqued { + init(layout: UniquedLayout, contents: Base) { + self.init(_scale: layout.scale, bias: layout.bias, contents: contents) + } +} + +extension Uniqued where Base: RangeReplaceableCollection { + init(layout: UniquedLayout, contents: C) + where C.Element == Element { + self.init(_scale: layout.scale, bias: layout.bias, contents: contents) + } +} + +extension Uniqued where Element == Int, Base: RangeReplaceableCollection { + init(layout: UniquedLayout) { + self.init(layout: layout, contents: 0 ..< layout.count) + } +} diff --git a/Tests/UniquedTests/UniquedTests.swift b/Tests/UniquedTests/UniquedTests.swift new file mode 100644 index 00000000..918ca741 --- /dev/null +++ b/Tests/UniquedTests/UniquedTests.swift @@ -0,0 +1,1487 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021 Apple Inc. and the Swift project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +import XCTest +@_spi(Testing) import UniquedModule +import DequeModule +import CollectionsTestSupport + +class UniquedTests: CollectionTestCase { + typealias MinimalImmutableBase = MinimalRandomAccessCollection + typealias MinimalBase = MinimalRangeReplaceableRandomAccessCollection + typealias MinimalMutableBase = MinimalMutableRangeReplaceableRandomAccessCollection + + func test_init_uncheckedUniqueElements_concrete() { + withEvery("count", in: 0 ..< 20) { count in + let contents = MinimalImmutableBase(0 ..< count) + let set = Uniqued(uncheckedUniqueElements: contents) + expectEqual(set.count, count) + expectEqual(set.isEmpty, count == 0) + expectEqualElements(set, 0 ..< count) + for i in 0 ..< count { + expectTrue(set.contains(i)) + } + } + } + + func test_init_uncheckedUniqueElements_generic() { + withEvery("count", in: 0 ..< 20) { count in + let set = Uniqued>(uncheckedUniqueElements: 0 ..< count) + expectEqual(set.count, count) + expectEqual(set.isEmpty, count == 0) + expectEqualElements(set, 0 ..< count) + for i in 0 ..< count { + expectTrue(set.contains(i)) + } + } + } + + func test_init_uniqueElements_concrete() { + withEvery("count", in: 0 ..< 20) { count in + let contents = MinimalImmutableBase(0 ..< count) + let set = Uniqued(uniqueElements: contents) + expectEqual(set.count, count) + expectEqual(set.isEmpty, count == 0) + expectEqualElements(set, 0 ..< count) + for i in 0 ..< count { + expectTrue(set.contains(i)) + } + } + } + + func test_init_uniqueElements_generic() { + withEvery("count", in: 0 ..< 20) { count in + let set = Uniqued>(uniqueElements: 0 ..< count) + expectEqual(set.count, count) + expectEqual(set.isEmpty, count == 0) + expectEqualElements(set, 0 ..< count) + for i in 0 ..< count { + expectTrue(set.contains(i)) + } + } + } + + func test_init_empty() { + let set = Uniqued>() + expectEqual(set.count, 0) + expectTrue(set.isEmpty) + expectEqualElements(set, []) + } + + func test_init_self() { + withEvery("count", in: 0 ..< 20) { count in + let set = Uniqued>(0 ..< count) + let copy = Uniqued(set) + expectEqualElements(copy, set) + expectEqual(set._hashTableIdentity, copy._hashTableIdentity) + } + } + + func test_init_set() { + withEvery("count", in: 0 ..< 20) { count in + let set = Set(0 ..< count) + let ordered = Uniqued>(set) + expectEqual(ordered.count, count) + expectEqualElements(ordered, set) + } + } + + func test_init_dictionary_keys() { + withEvery("count", in: 0 ..< 20) { count in + let dict: [Int: Int] + = .init(uniqueKeysWithValues: (0 ..< count).lazy.map { (key: $0, value: 2 * $0) }) + let ordered = Uniqued>(dict.keys) + expectEqual(ordered.count, count) + expectEqualElements(ordered, dict.keys) + } + } + + /// Create a new `Uniqued` instance using the generic initializer. + static func _genericInitializer( + _ type: T.Type = T.self, + from elements: S + ) -> Uniqued + where T: RandomAccessCollection & RangeReplaceableCollection, + T.Element == S.Element + { + return Uniqued.init(elements) + } + + + func test_generic_init_self() { + withEvery("count", in: 0 ..< 20) { count in + let set = Uniqued>(0 ..< count) + let copy: Uniqued> = Self._genericInitializer(from: set) + expectEqualElements(copy, set) + expectEqual(set._hashTableIdentity, copy._hashTableIdentity) + } + } + + func test_generic_init_set() { + withEvery("count", in: 0 ..< 20) { count in + let expected = Set(0 ..< count) + let actual = Self._genericInitializer(MinimalBase.self, from: expected) + expectEqualElements(actual, expected) + } + } + + func test_generic_init_array() { + withEvery("count", in: 0 ..< 20) { count in + let expected = Array(0 ..< count) + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) } + let actual = Self._genericInitializer(MinimalBase.self, from: input) + expectEqualElements(actual, expected) + } + } + } + + func test_firstIndexOf_lastIndexOf() { + withEvery("count", in: 0 ..< 20) { count in + let contents = Array(0 ..< count) + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) } + let set = Uniqued<[Int]>(input) + withEvery("item", in: contents) { item in + expectNotNil(set.firstIndex(of: item)) { index in + expectEqual(set[index], item) + expectEqual(contents[index], item) + expectEqual(set.lastIndex(of: item), index) + } + } + expectNil(set.firstIndex(of: count)) + expectNil(set.lastIndex(of: count)) + } + } + } + + func test_Collection() { + withEvery("count", in: [0, 1, 15, 16, 20]) { count in + let scale = _UnsafeHashTable.scale(forCapacity: count) + withEvery("bias", in: _UnsafeHashTable.biasRange(scale: scale)) { bias in + let contents = Array(0 ..< count) + let set = Uniqued<[Int]>(_scale: scale, bias: bias, contents: contents) + checkBidirectionalCollection(set, expectedContents: contents) + } + } + } + + func test_CustomStringConvertible() { + let a: Uniqued> = [] + expectEqual(a.description, "[]") + + let b: Uniqued> = [0] + expectEqual(b.description, "[0]") + + let c: Uniqued> = [0, 1, 2, 3, 4] + expectEqual(c.description, "[0, 1, 2, 3, 4]") + } + + func test_CustomDebugStringConvertible() { + let a: Uniqued> = [] + expectEqual(a.debugDescription, "OrderedSet([])") + + let b: Uniqued> = [0] + expectEqual(b.debugDescription, "OrderedSet([0])") + + let c: Uniqued> = [0, 1, 2, 3, 4] + expectEqual(c.debugDescription, "OrderedSet([0, 1, 2, 3, 4])") + + let d: Uniqued> = [] + expectEqual(d.debugDescription, "Uniqued>([])") + + let e: Uniqued> = [0] + expectEqual(e.debugDescription, "Uniqued>([0])") + + let f: Uniqued> = [0, 1, 2, 3, 4] + expectEqual(f.debugDescription, "Uniqued>([0, 1, 2, 3, 4])") + } + + func test_customReflectable() { + do { + let set: Uniqued<[Int]> = [1, 2, 3] + let mirror = Mirror(reflecting: set) + expectEqual(mirror.displayStyle, .collection) + expectNil(mirror.superclassMirror) + expectTrue(mirror.children.compactMap { $0.label }.isEmpty) // No label + expectEqualElements(mirror.children.map { $0.value as? Int }, set.map { $0 }) + } + + do { + let set: Uniqued> = [1, 2, 3] + let mirror = Mirror(reflecting: set) + expectEqual(mirror.displayStyle, .collection) + expectNil(mirror.superclassMirror) + expectTrue(mirror.children.compactMap { $0.label }.isEmpty) // No label + expectEqualElements(mirror.children.map { $0.value as? Int }, set.map { $0 }) + } + } + + func test_Equatable_Hashable() { + let samples: [[Uniqued<[Int]>]] = [ + [[1, 2, 3], + [1, 2, 3]], + [[3, 2, 1], + [3, 2, 1]], + [[1, 1, 1], + [1, 1, 1], + [1, 1], + [1]], + [[1, 2], + [1, 2, 2], + [1, 1, 2], + [1, 1, 2, 2]], + ] + checkHashable(equivalenceClasses: samples) + + // Check that hash encoding matches that of the underlying arrays. + for equivalenceClass in samples { + for item in equivalenceClass { + expectEqual(item.hashValue, item.contents.hashValue) + } + } + } + + func test_ExpressibleByArrayLiteral() { + do { + let set: Uniqued<[Int]> = [] + expectEqualElements(set, [] as [Int]) + } + + do { + let set: Uniqued<[Int]> = [1, 2, 3] + expectEqualElements(set, 1 ... 3) + } + + do { + let set: Uniqued<[Int]> = [ + 1, 2, 3, 4, 5, 6, 7, 8, + 1, 2, 3, 4, 5, 6, 7, 8, + 1, 2, 3, 4, 5, 6, 7, 8, + 1, 2, 3, 4, 5, 6, 7, 8, + ] + expectEqualElements(set, 1 ... 8) + } + + do { + let set: Uniqued<[Int]> = [ + 1, 1, 1, 1, + 2, 2, 2, 2, + 3, 3, 3, 3, + 4, 4, 4, 4, + 5, 5, 5, 5, + 6, 6, 6, 6, + 7, 7, 7, 7, + 8, 8, 8, 8, + ] + expectEqualElements(set, 1 ... 8) + } + + do { + let set: Uniqued<[Int]> = [ + 1, 2, 3, 4, 5, 6, 7, 8, + 9, 10, 11, 12, 13, 14, 15, 16, + 17, 18, 19, 20, 21, 22, 23, 24, + 25, 26, 27, 28, 29, 30, 31, 32] + expectEqualElements(set, 1 ... 32) + } + } + + func test_Encodable() throws { + let s1: Uniqued<[Int]> = [] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalEncoder.encode(s1), v1) + + let s2: Uniqued<[Int]> = [0, 1, 2, 3] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalEncoder.encode(s2), v2) + + let s3: Uniqued<[Int]> = [3, 2, 1, 0] + let v3: MinimalEncoder.Value = .array([.int(3), .int(2), .int(1), .int(0)]) + expectEqual(try MinimalEncoder.encode(s3), v3) + + let s4 = Uniqued<[Int]>(0 ..< 100) + let v4: MinimalEncoder.Value = .array((0 ..< 100).map { .int($0) }) + expectEqual(try MinimalEncoder.encode(s4), v4) + } + + func test_Decodable() throws { + let s1: Uniqued<[Int]> = [] + let v1: MinimalEncoder.Value = .array([]) + expectEqual(try MinimalDecoder.decode(v1, as: Uniqued<[Int]>.self), s1) + + let s2: Uniqued<[Int]> = [0, 1, 2, 3] + let v2: MinimalEncoder.Value = .array([.int(0), .int(1), .int(2), .int(3)]) + expectEqual(try MinimalDecoder.decode(v2, as: Uniqued<[Int]>.self), s2) + + let s3 = Uniqued<[Int]>(0 ..< 100) + let v3: MinimalEncoder.Value = .array((0 ..< 100).map { .int($0) }) + expectEqual(try MinimalDecoder.decode(v3, as: Uniqued<[Int]>.self), s3) + + expectThrows(try MinimalDecoder.decode(.int(0), as: Uniqued<[Int]>.self)) + + let v4: MinimalEncoder.Value = .array([.int(0), .int(1), .int(0)]) + expectThrows(try MinimalDecoder.decode(v4, as: Uniqued<[Int]>.self)) { error in + expectNotNil(error as? DecodingError) { error in + guard case .dataCorrupted(let context) = error else { + expectFailure("Unexpected error \(error)") + return + } + expectEqual(context.debugDescription, + "Decoded elements aren't unique (first duplicate at offset 2)") + } + } + } + + func test_append_many() { + #if COLLECTIONS_INTERNAL_CHECKS + // This test just takes too long with O(n) appends. + let count = 1_000 + #else + let count = 10_000 + #endif + + var set = Uniqued>() + withEvery("item", in: 0 ..< count) { item in + let res1 = set.append(item) + expectTrue(res1.inserted) + expectEqual(set[res1.index], item) + + let res2 = set.append(item) + expectFalse(res2.inserted) + expectEqual(res2.index, res1.index) + + expectEqual(set[res1.index], item) // Original index must remain valid. + expectEqual(set[res2.index], item) + } + } + + func test_append() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) }.shuffled() + var reference: [Int: Int] = [:] // Value to expected offset + var actual = Uniqued>() + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let (inserted, index) = actual.append(item) + expectEqual(actual[index], item) + if let expectedOffset = reference[item] { + // Existing item + expectFalse(inserted) + expectEqual(index.offset, expectedOffset) + } else { + expectTrue(inserted) + expectEqual(index.offset, reference.count) + reference[item] = reference.count + } + } + } + } + // Check CoW copying behavior + do { + var set = Uniqued>(0 ..< 30) + let copy = set + expectTrue(set.append(30).inserted) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } + + func test_append_contentsOf() { + withEvery("chunkLength", in: 1 ..< 10) { chunkLength in + withEvery("chunkOverlap", in: 0 ... chunkLength) { chunkOverlap in + var actual = Uniqued>() + var chunkStart = 0 + var expectedCount = 0 + withEvery("iteration", in: 0 ..< 100) { _ in + let chunk = chunkStart ..< chunkStart + chunkLength + actual.append(contentsOf: chunk) + expectedCount = chunk.upperBound + expectEqual(actual.count, expectedCount) + chunkStart += chunkLength - chunkOverlap + } + expectEqualElements(actual, 0 ..< expectedCount) + } + } + } + + func test_prepend_many() { + #if COLLECTIONS_INTERNAL_CHECKS + // This test just takes too long with O(n) appends. + let count = 1_000 + #else + let count = 10_000 + #endif + + var set = Uniqued>() + withEvery("item", in: 0 ..< count) { item in + let res1 = set.prepend(item) + expectTrue(res1.inserted) + expectEqual(set[res1.index], item) + + let res2 = set.prepend(item) + expectFalse(res2.inserted) + expectEqual(res2.index, res1.index) + + expectEqual(set[res1.index], item) // Original index must remain valid. + expectEqual(set[res2.index], item) + } + } + + func test_prepend() { + withEvery("count", in: 0 ..< 20) { count in + withEvery("dupes", in: 1 ... 3) { dupes in + let input = (0 ..< count).flatMap { repeatElement($0, count: dupes) }.shuffled() + var reference: [Int: Int] = [:] // Value to expected offset from end + var actual = Uniqued>() + withEvery("offset", in: input.indices) { offset in + let item = input[offset] + let (inserted, index) = actual.prepend(item) + expectEqual(actual[index], item) + if let expectedOffset = reference[item] { + // Existing item + expectFalse(inserted) + expectEqual(index, actual.count - expectedOffset) + } else { + expectTrue(inserted) + expectEqual(index, 0) + reference[item] = actual.count + } + } + } + } + // Check CoW copying behavior + do { + var set = Uniqued>(0 ..< 30) + let copy = set + expectTrue(set.append(30).inserted) + expectTrue(set.contains(30)) + expectFalse(copy.contains(30)) + } + } + + func test_prepend_contentsOf() { + withEvery("chunkLength", in: 1 ..< 10) { chunkLength in + withEvery("chunkOverlap", in: 0 ... chunkLength) { chunkOverlap in + var actual = Uniqued>() + var chunkStart = 0 + var expectedCount = 0 + withEvery("iteration", in: 0 ..< 100) { _ in + let chunk = chunkStart ..< chunkStart + chunkLength + actual.prepend(contentsOf: chunk.reversed()) + expectedCount = chunk.upperBound + expectEqual(actual.count, expectedCount) + chunkStart += chunkLength - chunkOverlap + } + expectEqualElements(actual, (0 ..< expectedCount).reversed()) + } + } + } + + func test_insert_at() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + withEvery("offset", in: 0 ... count) { offset in + var set = Uniqued(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let i = set.index(set.startIndex, offsetBy: offset) + let (inserted, index) = set.insert(count, at: i) + expectTrue(inserted) + expectEqual(set.count, count + 1) + expectEqual(set[index], count) + expectEqualElements(set[...self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_update_at_with() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection & MutableCollection, + Base.Element == HashableBox + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + let count = layout.count + let contents = Base((0 ..< count).lazy.map { HashableBox($0) }) + withEvery("offset", in: 0 ..< count) { offset in + var set = Uniqued(layout: layout, contents: contents) + let index = set._index(at: offset) // This must remain valid throughout this test + let new = HashableBox(offset) + let old = set.update(at: index, with: new) + expectIdentical(old, contents[index]) + expectIdentical(set[index], new) + + let copy = set + + let old2 = set.update(at: index, with: old) + expectIdentical(old2, new) + expectIdentical(set[index], old) + expectIdentical(copy[index], new) + } + } + } + check(MinimalMutableBase>.self) + check(ContiguousArray>.self) + check(Deque>.self) + } + + func test_updateOrAppend() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection & MutableCollection, + Base.Element == HashableBox + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + let count = layout.count + let contents = Base((0 ..< count).lazy.map { HashableBox($0) }) + withEvery("offset", in: 0 ..< count) { offset in + var set = Uniqued(layout: layout, contents: contents) + let index = set._index(at: offset) // This must remain valid throughout this test + let new = HashableBox(offset) + let old = set.updateOrAppend(new) + expectNotNil(old) { old in + expectIdentical(old, contents[index]) + expectIdentical(set[index], new) + + let copy = set + + let old2 = set.updateOrAppend(old) + expectNotNil(old2) { old2 in + expectIdentical(old2, new) + expectIdentical(set[index], old) + expectIdentical(copy[index], new) + } + } + } + + // Try appending something. + var set = Uniqued(layout: layout, contents: contents) + + let new = HashableBox(count) + do { + expectNil(set.updateOrAppend(new)) + expectTrue(set.contains(new)) + expectIdentical(set.last, new) + } + + let copy = set + let new2 = HashableBox(count + 1) + do { + expectNil(set.updateOrAppend(new2)) + expectTrue(set.contains(new2)) + expectIdentical(set.last, new2) + } + + expectEqual(copy.count, count + 1) + expectIdentical(copy.last, new) + } + } + check(MinimalMutableBase>.self) + check(ContiguousArray>.self) + check(Deque>.self) + } + + + func test_swapAt() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection & MutableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + withEvery("a", in: 0 ..< count) { a in + var set = Uniqued(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let b = count - a - 1 + let ai = set._index(at: a) + let bi = set._index(at: b) + expectEqual(set[ai], a) + expectEqual(set[bi], b) + set.swapAt(ai, bi) + expectEqual(set[ai], b) + expectEqual(set[bi], a) + // Make sure we can still find these elements + expectEqual(set.firstIndex(of: a), bi) + expectEqual(set.firstIndex(of: b), ai) + } + } + } + } + } + check(MinimalMutableBase.self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_partition() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & MutableCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("offset", in: 0 ... layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + var set = Uniqued(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let pivot = set.partition(by: { $0.isMultiple(of: 2) }) + withEvery("item", in: 0 ..< count) { item in + expectNotNil(set.firstIndex(of: item)) { index in + expectEqual(set[index], item) + if item.isMultiple(of: 2) { + expectGreaterThanOrEqual(index, pivot) + } else { + expectLessThan(index, pivot) + } + } + } + } + } + } + } + } + check(MinimalMutableBase.self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_partition_extremes() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & MutableCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("offset", in: 0 ... layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + var set = Uniqued(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + do { + let pivot = set.partition(by: { _ in false }) + expectEqual(pivot, set.endIndex) + expectEqualElements(set, 0 ..< count) + } + + do { + let pivot = set.partition(by: { _ in true }) + expectEqual(pivot, set.startIndex) + expectEqualElements(set, 0 ..< count) + } + } + } + } + } + } + check(MinimalMutableBase.self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_sort() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & MutableCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + var rng = RepeatableRandomNumberGenerator(seed: seed) + let contents = (0 ..< count).shuffled(using: &rng) + var set = Uniqued(layout: layout, contents: contents) + withHiddenCopies(if: isShared, of: &set) { set in + set.sort() + expectEqualElements(set, 0 ..< count) + + set.sort(by: >) + expectEqualElements(set, (0 ..< count).reversed()) + } + } + } + } + } + check(MinimalMutableBase.self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_shuffle() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & MutableCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + guard layout.count > 1 else { return } + withEvery("seed", in: 0 ..< 10) { seed in + withEvery("isShared", in: [false, true]) { isShared in + let count = layout.count + var contents = Base(0 ..< count) + var set = Uniqued(layout: layout, contents: 0 ..< count) + withHiddenCopies(if: isShared, of: &set) { set in + var rng1 = RepeatableRandomNumberGenerator(seed: seed) + contents.shuffle(using: &rng1) + + var rng2 = RepeatableRandomNumberGenerator(seed: seed) + set.shuffle(using: &rng2) + + expectEqualElements(set, contents) + + // Check that shuffling with system RNG does permute the elements. + var success = false + for _ in 0 ..< 1000 { + set.shuffle() + if !set.elementsEqual(contents) { + success = true + break + } + } + expectTrue(success) + + } + } + } + } + } + check(MinimalMutableBase.self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_remove_at() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("offset", in: 0 ..< layout.count) { offset in + withEvery("isShared", in: [false, true]) { isShared in + var set = Uniqued(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let count = layout.count + let index = set._index(at: offset) + let old = set.remove(at: index) + expectEqual(old, offset) + expectEqualElements(set[...self) + check(ContiguousArray.self) + check(Deque.self) + } + + func test_remove_at_capacity_behavior() { + var set = Uniqued>(0 ..< 1000) + while !set.isEmpty { + let originalCount = set.count + context.withTrace("originalCount: \(originalCount)") { + let scale = set._scale + let old = set.remove(at: set.index(before: set.endIndex)) + expectEqual(old, set.count) + if originalCount == _UnsafeHashTable.minimumCapacity(forScale: scale) { + expectLessThan(set._scale, scale) + } else { + expectEqual(set._scale, scale) + } + } + } + } + + + + func test_remove_existing_element() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("item", in: 0 ..< layout.count) { item in + withEvery("isShared", in: [false, true]) { isShared in + var set = Uniqued(layout: layout) + withHiddenCopies(if: isShared, of: &set) { set in + let count = layout.count + let old = set.remove(item) + expectEqual(old, item) + expectEqualElements(set[...self) + check(ContiguousArray.self) + } + + func test_remove_nonexistent_element() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withEvery("item", in: layout.count ..< 2 * layout.count) { item in + var set = Uniqued(layout: layout) + let old = set.remove(item) + expectNil(old) + expectEqualElements(set, 0 ..< layout.count) + } + } + } + check(MinimalBase.self) + check(ContiguousArray.self) + } + + func test_remove_subrange() { + func check(_ base: Base.Type) + where Base: RandomAccessCollection & RangeReplaceableCollection, + Base.Element == Int + { + let entry = context.push("base: \(base)") + defer { context.pop(entry) } + withUniquedLayouts(scales: [0, 5, 6]) { layout in + withSomeRanges("offsetRange", in: 0 ..< layout.count) { offsetRange in + withEvery("isShared", in: [false, true]) { isShared in + var set = Uniqued(layout: layout) + let low = offsetRange.lowerBound + let high = offsetRange.upperBound + withHiddenCopies(if: isShared, of: &set) { set in + let count = layout.count + let removedRange = set._indexRange(at: low ..< high) + set.removeSubrange(removedRange) + + expectEqual(set.count, layout.count - offsetRange.count) + + if set.count < _UnsafeHashTable.minimumCapacity(forScale: layout.scale) { + expectLessThan(set._scale, layout.scale) + } + + expectEqualElements(set[_offsets: ..= offsetRange.upperBound { + expectEqual(set.firstIndex(of: i), + set._index(at: i - offsetRange.count)) + } else { + expectNil(set.firstIndex(of: i)) + } + } + } + } + } + } + } + check(MinimalBase.self) + check(ContiguousArray.self) + } + + func test_init_minimumCapacity() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let expectedScale = _UnsafeHashTable.scale(forCapacity: capacity) + let set = Uniqued>(minimumCapacity: capacity) + expectEqual(set._scale, expectedScale) + expectEqual(set._reservedScale, expectedScale) + expectEqual(set._minimumCapacity, 0) + } + } + + func test_reserveCapacity_empty() { + withEvery("capacity", in: 0 ..< 1000) { capacity in + let expectedScale = _UnsafeHashTable.scale(forCapacity: capacity) + var set = Uniqued>() + expectEqual(set._scale, 0) + expectEqual(set._reservedScale, 0) + expectEqual(set._minimumCapacity, 0) + + set.reserveCapacity(capacity) + expectEqual(set._scale, expectedScale) + expectEqual(set._reservedScale, expectedScale) + expectEqual(set._minimumCapacity, 0) + + set.reserveCapacity(0) + expectEqual(set._scale, 0) + expectEqual(set._reservedScale, 0) + expectEqual(set._minimumCapacity, 0) + } + } + + func test_reserveCapacity_behavior() { + let scale1 = 6 + let range1 = 16 ... 48 + let count1 = 32 + + let scale2 = 8 + let range2 = 64 ... 192 + let count2 = 128 + + var set = Uniqued>(0 ..< count1) + expectEqual(set._scale, scale1) + expectEqual(set._reservedScale, 0) + expectEqual(set._minimumCapacity, range1.lowerBound) + expectEqual(set._capacity, range1.upperBound) + + set.reserveCapacity(count2) + expectEqual(set._scale, scale2) + expectEqual(set._reservedScale, scale2) + expectEqual(set._minimumCapacity, 0) + expectEqual(set._capacity, range2.upperBound) + + set.append(contentsOf: count1 ..< count2) + expectEqual(set._scale, scale2) + expectEqual(set._reservedScale, scale2) + expectEqual(set._minimumCapacity, 0) + expectEqual(set._capacity, range2.upperBound) + + set.reserveCapacity(0) + expectEqual(set._scale, scale2) + expectEqual(set._reservedScale, 0) + expectEqual(set._minimumCapacity, range2.lowerBound) + expectEqual(set._capacity, range2.upperBound) + + set.removeSubrange(set._indexRange(at: count1...)) + expectEqual(set._scale, scale1) + expectEqual(set._reservedScale, 0) + expectEqual(set._minimumCapacity, range1.lowerBound) + expectEqual(set._capacity, range1.upperBound) + } + + func withSampleRanges( + file: StaticString = #file, + line: UInt = #line, + _ body: (Range, Range) throws -> Void + ) rethrows { + for c1 in [0, 10, 32, 64, 128, 256] { + for c2 in [0, 10, 32, 64, 128, 256] { + for overlap in Set([0, 1, c1 / 2, c1, -5]) { + let r1 = 0 ..< c1 + let r2 = c1 - overlap ..< c1 - overlap + c2 + if r1.lowerBound <= r2.lowerBound { + let e1 = context.push("range1: \(r1)", file: file, line: line) + let e2 = context.push("range2: \(r2)", file: file, line: line) + defer { + context.pop(e2) + context.pop(e1) + } + try body(r1, r2) + } else { + let e1 = context.push("range1: \(r2)", file: file, line: line) + let e2 = context.push("range2: \(r1)", file: file, line: line) + defer { + context.pop(e2) + context.pop(e1) + } + try body(r2, r1) + } + } + } + } + } + + func test_union_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + let actual1 = u1.union(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.union(u2).union(u1) + expectEqualElements(actual2, expected) + } + } + + func test_formUnion_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + + var res = Uniqued>() + + let u1 = Uniqued>(r1) + res.formUnion(u1) + expectEqualElements(res, r1) + + let u2 = Uniqued>(r2) + res.formUnion(u2) + expectEqualElements(res, expected) + + res.formUnion(u1) + res.formUnion(u2) + expectEqualElements(res, expected) + } + } + + func test_union_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + let u1 = Uniqued>(r1) + let u2 = u1.union(r2) + expectEqualElements(u2, expected) + + let u3 = u2.union(r1) + expectEqualElements(u3, expected) + } + } + + func test_formUnion_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).union(r2).sorted() + + var res = Uniqued>() + + res.formUnion(r1) + expectEqualElements(res, r1) + + res.formUnion(r2) + expectEqualElements(res, expected) + + res.formUnion(r1) + res.formUnion(r2) + expectEqualElements(res, expected) + } + } + + func test_intersection_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + let actual1 = u1.intersection(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.intersection(r1) + expectEqualElements(actual2, expected) + } + } + + func test_formIntersection_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + var res = u1 + res.formIntersection(u2) + expectEqualElements(res, expected) + expectEqualElements(u1, r1) + + res.formIntersection(u1) + res.formIntersection(u2) + expectEqualElements(res, expected) + } + } + + func test_intersection_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + let u1 = Uniqued>(r1) + let actual1 = u1.intersection(r2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.intersection(r1).intersection(r2) + expectEqualElements(actual2, expected) + } + } + + func test_formIntersection_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).intersection(r2).sorted() + + var res = Uniqued>(r1) + res.formIntersection(r2) + expectEqualElements(res, expected) + + res.formIntersection(r1) + res.formIntersection(r2) + expectEqualElements(res, expected) + } + } + + func test_symmetricDifference_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + let actual1 = u1.symmetricDifference(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.symmetricDifference(u1).symmetricDifference(u2) + expectEqual(actual2.count, 0) + } + } + + func test_formSymmetricDifference_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + var res = u1 + res.formSymmetricDifference(u2) + expectEqualElements(res, expected) + expectEqualElements(u1, r1) + + res.formSymmetricDifference(u1) + res.formSymmetricDifference(u2) + expectEqual(res.count, 0) + } + } + + func test_symmetricDifference_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + let u1 = Uniqued>(r1) + let actual1 = u1.symmetricDifference(r2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.symmetricDifference(r1).symmetricDifference(r2) + expectEqual(actual2.count, 0) + } + } + + func test_formSymmetricDifference_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).symmetricDifference(r2).sorted() + + var res = Uniqued>(r1) + res.formSymmetricDifference(r2) + expectEqualElements(res, expected) + + res.formSymmetricDifference(r1) + res.formSymmetricDifference(r2) + expectEqual(res.count, 0) + } + } + + func test_subtracting_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + let actual1 = u1.subtracting(u2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.subtracting(u2) + expectEqualElements(actual2, expected) + } + } + + func test_subtract_Self() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + let u1 = Uniqued>(r1) + let u2 = Uniqued>(r2) + var res = u1 + res.subtract(u2) + expectEqualElements(res, expected) + expectEqualElements(u1, r1) + + res.subtract(u2) + expectEqualElements(res, expected) + } + } + + func test_subtracting_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + let u1 = Uniqued>(r1) + let actual1 = u1.subtracting(r2) + expectEqualElements(actual1, expected) + + let actual2 = actual1.subtracting(r2) + expectEqualElements(actual2, expected) + } + } + + func test_subtract_generic() { + withSampleRanges { r1, r2 in + let expected = Set(r1).subtracting(r2).sorted() + + var res = Uniqued>(r1) + res.subtract(r2) + expectEqualElements(res, expected) + + res.subtract(r2) + expectEqualElements(res, expected) + } + } + + struct SampleRanges { + let unit: Int + + init(unit: Int) { + self.unit = unit + } + + var empty: Range { unit ..< unit } + + var a: Range { 0 ..< unit } + var b: Range { unit ..< 2 * unit } + var c: Range { 2 * unit ..< 3 * unit } + + var ab: Range { 0 ..< 2 * unit } + var bc: Range { unit ..< 3 * unit } + + var abc: Range { 0 ..< 3 * unit } + + var ranges: [Range] { [empty, a, b, c, ab, bc, abc] } + + func withEveryPair( + _ body: (Range, Range) throws -> Void + ) rethrows { + try withEvery("range1", in: ranges) { range1 in + try withEvery("range2", in: ranges) { range2 in + try body(range1, range2) + } + } + } + } + + func test_isSubset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSubset(of: r2) + let a = Uniqued>(r1) + let b = Uniqued>(r2) + expectEqual(a.isSubset(of: b), expected) + } + } + } + + func test_isSubset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSubset(of: r2) + let a = Uniqued>(r1) + let b = Set(r2) + expectEqual(a.isSubset(of: b), expected) + } + } + } + + func test_isSubset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSubset(of: r2) + let a = Uniqued>(r1) + let b = r2 + expectEqual(a.isSubset(of: b), expected) + } + } + } + + func test_isSuperset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSuperset(of: r2) + let a = Uniqued>(r1) + let b = Uniqued>(r2) + expectEqual(a.isSuperset(of: b), expected) + } + } + } + + func test_isSuperset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSuperset(of: r2) + let a = Uniqued>(r1) + let b = Set(r2) + expectEqual(a.isSuperset(of: b), expected) + } + } + } + + func test_isSuperset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isSuperset(of: r2) + let a = Uniqued>(r1) + let b = r2 + expectEqual(a.isSuperset(of: b), expected) + } + } + } + + func test_isStrictSubset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSubset(of: r2) + let a = Uniqued>(r1) + let b = Uniqued>(r2) + expectEqual(a.isStrictSubset(of: b), expected) + } + } + } + + func test_isStrictSubset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSubset(of: r2) + let a = Uniqued>(r1) + let b = Set(r2) + expectEqual(a.isStrictSubset(of: b), expected) + } + } + } + + func test_isStrictSubset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSubset(of: r2) + let a = Uniqued>(r1) + let b = r2 + expectEqual(a.isStrictSubset(of: b), expected) + } + } + } + + func test_isStrictSuperset_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSuperset(of: r2) + let a = Uniqued>(r1) + let b = Uniqued>(r2) + expectEqual(a.isStrictSuperset(of: b), expected) + } + } + } + + func test_isStrictSuperset_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSuperset(of: r2) + let a = Uniqued>(r1) + let b = Set(r2) + expectEqual(a.isStrictSuperset(of: b), expected) + } + } + } + + func test_isStrictSuperset_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isStrictSuperset(of: r2) + let a = Uniqued>(r1) + let b = r2 + expectEqual(a.isStrictSuperset(of: b), expected) + } + } + } + + func test_isDisjoint_Self() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isDisjoint(with: r2) + let a = Uniqued>(r1) + let b = Uniqued>(r2) + expectEqual(a.isDisjoint(with: b), expected) + } + } + } + + func test_isDisjoint_Set() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isDisjoint(with: r2) + let a = Uniqued>(r1) + let b = Set(r2) + expectEqual(a.isDisjoint(with: b), expected) + } + } + } + + func test_isDisjoint_generic() { + withEvery("unit", in: [1, 3, 7, 10, 20, 50]) { unit in + SampleRanges(unit: unit).withEveryPair { r1, r2 in + let expected = Set(r1).isDisjoint(with: r2) + let a = Uniqued>(r1) + let b = r2 + expectEqual(a.isDisjoint(with: b), expected) + } + } + } +} diff --git a/Utils/run-benchmarks.sh b/Utils/run-benchmarks.sh new file mode 100755 index 00000000..4f262ad9 --- /dev/null +++ b/Utils/run-benchmarks.sh @@ -0,0 +1,40 @@ +#!/bin/sh + +set -eu + +srcroot="$(dirname "$0")/.." +results="batch.results" + +command="${1:-help}" +shift || : + +run() { + local flags + flags="-c release" + flags="$flags -Xswiftc -Xllvm -Xswiftc -align-module-to-page-size" + swift run --package-path "$srcroot" $flags swift-collections-benchmark "$@" +} + +case "$command" in + batch-run) + revision="$(git rev-parse HEAD)" + run library run "$results" \ + --source-url "https://github.com/apple/swift-collections/tree/$revision" \ + --mode replace-all \ + --max-size 4M --cycles 3 \ + --amortized-cutoff 10us \ + "$@" + ;; + batch-render) + run library render "$results" \ + --min-time 100ps --max-time 10us \ + --min-size 1 --max-size 4M \ + "$@" + ;; + batch-clean) + rm -rf "$out"/results + ;; + *) + run "$command" "$@" + ;; +esac diff --git a/swift-collections.xcworkspace/contents.xcworkspacedata b/swift-collections.xcworkspace/contents.xcworkspacedata new file mode 100644 index 00000000..030db5a6 --- /dev/null +++ b/swift-collections.xcworkspace/contents.xcworkspacedata @@ -0,0 +1,10 @@ + + + + + + + diff --git a/swift-collections.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist b/swift-collections.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist new file mode 100644 index 00000000..18d98100 --- /dev/null +++ b/swift-collections.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist @@ -0,0 +1,8 @@ + + + + + IDEDidComputeMac32BitWarning + + + diff --git a/swift-collections.xcworkspace/xcshareddata/swiftpm/Package.resolved b/swift-collections.xcworkspace/xcshareddata/swiftpm/Package.resolved new file mode 100644 index 00000000..dd55e63a --- /dev/null +++ b/swift-collections.xcworkspace/xcshareddata/swiftpm/Package.resolved @@ -0,0 +1,25 @@ +{ + "object": { + "pins": [ + { + "package": "swift-argument-parser", + "repositoryURL": "https://github.com/apple/swift-argument-parser", + "state": { + "branch": null, + "revision": "831ed5e860a70e745bc1337830af4786b2576881", + "version": "0.4.1" + } + }, + { + "package": "swift-system", + "repositoryURL": "https://github.com/apple/swift-system", + "state": { + "branch": null, + "revision": "8ffa04c0a0592e6f4f9c30926dedd8fa1c5371f9", + "version": "0.0.1" + } + } + ] + }, + "version": 1 +}