From 141c3939bf9e792e6add1aaa8faddf007c36dc7f Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 6 Dec 2022 18:41:04 -0800 Subject: [PATCH 1/7] [DocC] Add documentation bundles for all three targets --- .gitignore | 1 + .../Collections.docc/Collections.md | 34 +++++ .../Collections.docc/Extensions/Deque.md | 67 +++++++++ .../Extensions/OrderedDictionary.Elements.md | 40 ++++++ .../Extensions/OrderedDictionary.Values.md | 27 ++++ .../Extensions/OrderedDictionary.md | 97 +++++++++++++ .../Extensions/OrderedSet.UnorderedView.md | 56 ++++++++ .../Collections.docc/Extensions/OrderedSet.md | 136 ++++++++++++++++++ .../DequeModule.docc/DequeModule.md | 3 + .../DequeModule.docc/Extensions/Deque.md | 64 +++++++++ .../Extensions/OrderedDictionary.Elements.md | 37 +++++ .../Extensions/OrderedDictionary.Values.md | 24 ++++ .../Extensions/OrderedDictionary.md | 94 ++++++++++++ .../Extensions/OrderedSet.UnorderedView.md | 53 +++++++ .../Extensions/OrderedSet.md | 133 +++++++++++++++++ .../OrderedCollections.md | 10 ++ Utils/generate-docs.sh | 92 ++++++++++++ 17 files changed, 968 insertions(+) create mode 100644 Sources/Collections/Collections.docc/Collections.md create mode 100644 Sources/Collections/Collections.docc/Extensions/Deque.md create mode 100644 Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Elements.md create mode 100644 Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Values.md create mode 100644 Sources/Collections/Collections.docc/Extensions/OrderedDictionary.md create mode 100644 Sources/Collections/Collections.docc/Extensions/OrderedSet.UnorderedView.md create mode 100644 Sources/Collections/Collections.docc/Extensions/OrderedSet.md create mode 100644 Sources/DequeModule/DequeModule.docc/DequeModule.md create mode 100644 Sources/DequeModule/DequeModule.docc/Extensions/Deque.md create mode 100644 Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Elements.md create mode 100644 Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Values.md create mode 100644 Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.md create mode 100644 Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.UnorderedView.md create mode 100644 Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.md create mode 100644 Sources/OrderedCollections/OrderedCollections.docc/OrderedCollections.md create mode 100755 Utils/generate-docs.sh diff --git a/.gitignore b/.gitignore index f0e519a21..397ae000f 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ xcuserdata/ .*.sw? /Benchmarks/.swiftpm /Benchmarks/.build +.docc-build diff --git a/Sources/Collections/Collections.docc/Collections.md b/Sources/Collections/Collections.docc/Collections.md new file mode 100644 index 000000000..7a0322c53 --- /dev/null +++ b/Sources/Collections/Collections.docc/Collections.md @@ -0,0 +1,34 @@ +# ``Collections`` + +**Swift Collections** is an open-source package of data structure implementations for the Swift programming language. + +This package provides separate modules 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`. + +The top-level module `Collections` imports and reexports each of these smaller packages. Importing this module is a useful shortcut if you want to import all data structures, or if you don't care about bringing in more code than you need. + +```swift +import Collections + +var deque: Deque = ["Ted", "Rebecca"] +deque.prepend("Keeley") + +let people = OrderedSet(deque) +people.contains("Rebecca") // true +``` + +#### Additional Resources + +- [`Swift Collections` on GitHub](https://github.com/apple/swift-collections/) +- [`Swift Collections` on the Swift Forums](https://forums.swift.org/c/related-projects/collections/72) + + +## Topics + +### Deque Module + +- ``Deque`` + +### Ordered Collections + +- ``OrderedSet`` +- ``OrderedDictionary`` diff --git a/Sources/Collections/Collections.docc/Extensions/Deque.md b/Sources/Collections/Collections.docc/Extensions/Deque.md new file mode 100644 index 000000000..c65ac432a --- /dev/null +++ b/Sources/Collections/Collections.docc/Extensions/Deque.md @@ -0,0 +1,67 @@ +# ``Collections/Deque`` + + + + +## Topics + +### Creating a Deque + +- ``init()`` +- ``init(_:)-8tyaw`` +- ``init(_:)-1tqf4`` +- ``init(minimumCapacity:)`` +- ``init(repeating:count:)-4v1gt`` +- ``init(unsafeUninitializedCapacity:initializingWith:)`` + +### Inspecting a Deque + +- ``count-8wcnm`` +- ``isEmpty`` + +### Manipulating Elements at the Front + +- ``first`` +- ``prepend(_:)`` +- ``prepend(contentsOf:)-96y15`` +- ``prepend(contentsOf:)-51zn6`` +- ``removeFirst()-1vdmt`` +- ``removeFirst(_:)-2vuji`` +- ``popFirst()`` +- ``prefix(_:)`` + +### Manipulating Elements at the End + +- ``last`` +- ``append(_:)-9h4m7`` +- ``append(contentsOf:)-8rqnl`` +- ``append(contentsOf:)-29aoh`` +- ``removeLast()`` +- ``removeLast(_:)`` +- ``popLast()`` +- ``suffix(_:)`` + +### Manipulating Elements Elsewhere + +- ``subscript(_:)-9nk44`` +- ``subscript(_:)-6ee8i`` +- ``subscript(_:)-1klky`` +- ``subscript(_:)-ejld`` +- ``insert(_:at:)-9hsp7`` +- ``insert(contentsOf:at:)-1d60f`` +- ``replaceSubrange(_:with:)-5rtzd`` +- ``remove(at:)-3imgi`` + +### Reordering Elements + +- ``swapAt(_:_:)-7910s`` +- ``sort()`` +- ``sort(by:)`` +- ``reverse()`` +- ``shuffle()`` +- ``shuffle(using:)`` +- ``partition(by:)-90y0t`` + +### Memory Management + +- ``reserveCapacity(_:)`` diff --git a/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Elements.md b/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Elements.md new file mode 100644 index 000000000..8e77d4269 --- /dev/null +++ b/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Elements.md @@ -0,0 +1,40 @@ +# ``Collections/OrderedDictionary/Elements-swift.struct`` + + + + +## Topics + +### Inspecting an Elements View + +- ``isEmpty`` +- ``count`` + +### Accessing Elements + +- ``subscript(_:)-4xwc2`` +- ``keys`` +- ``values`` +- ``index(forKey:)`` + +### Removing Elements + +- ``remove(at:)`` +- ``removeSubrange(_:)-5x7oo`` +- ``removeSubrange(_:)-7wdak`` +- ``removeAll(keepingCapacity:)`` +- ``removeAll(where:)`` +- ``removeFirst()`` +- ``removeFirst(_:)`` +- ``removeLast()`` +- ``removeLast(_:)`` + +### Reordering Elements + +- ``swapAt(_:_:)`` +- ``reverse()`` +- ``sort()`` +- ``sort(by:)`` +- ``partition(by:)`` +- ``shuffle()`` +- ``shuffle(using:)`` diff --git a/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Values.md b/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Values.md new file mode 100644 index 000000000..3ef31e8b1 --- /dev/null +++ b/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Values.md @@ -0,0 +1,27 @@ +# ``Collections/OrderedDictionary/Values-swift.struct`` + + + + +## Topics + +### Inspecting a Values Collection + +- ``isEmpty`` +- ``count`` + +### Accessing Elements + +- ``subscript(_:)-25vfz`` +- ``elements`` +- ``withUnsafeBufferPointer(_:)`` +- ``withUnsafeMutableBufferPointer(_:)`` + +### Reordering Elements + +- ``swapAt(_:_:)-77eiy`` +- ``partition(by:)-9x0i5`` +- ``sort()`` +- ``sort(by:)`` +- ``shuffle()`` +- ``shuffle(using:)`` diff --git a/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.md b/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.md new file mode 100644 index 000000000..1db1199db --- /dev/null +++ b/Sources/Collections/Collections.docc/Extensions/OrderedDictionary.md @@ -0,0 +1,97 @@ +# ``Collections/OrderedDictionary`` + + + + +## Topics + +### Creating a Dictionary + +- ``init()`` +- ``init(minimumCapacity:persistent:)`` +- ``init(uniqueKeysWithValues:)-5ux9r`` +- ``init(uniqueKeysWithValues:)-88mzi`` +- ``init(uncheckedUniqueKeysWithValues:)-6gxhj`` +- ``init(uncheckedUniqueKeysWithValues:)-2j0dw`` +- ``init(uncheckedUniqueKeysWithValues:)-6gxhj`` +- ``init(uniqueKeys:values:)`` +- ``init(uncheckedUniqueKeys:values:)`` +- ``init(_:uniquingKeysWith:)-2y39b`` +- ``init(_:uniquingKeysWith:)-zhfp`` +- ``init(grouping:by:)-6mahw`` +- ``init(grouping:by:)-6m2zw`` + +### Inspecting a Dictionary + +- ``isEmpty`` +- ``count`` + +### Accessing Keys and Values + +- ``subscript(_:)`` +- ``subscript(_:default:)`` +- ``index(forKey:)`` + +### Collection Views + +- ``keys`` +- ``values-swift.property`` +- ``elements-swift.property`` + +### Updating Values + +- ``updateValue(_:forKey:)`` +- ``updateValue(_:forKey:insertingAt:)`` +- ``updateValue(forKey:default:with:)`` +- ``updateValue(forKey:insertingDefault:at:with:)`` + +### Removing Keys and Values + +- ``removeValue(forKey:)`` +- ``remove(at:)`` +- ``filter(_:)`` +- ``removeAll(where:)`` +- ``removeAll(keepingCapacity:)`` +- ``removeFirst()`` +- ``removeLast()`` +- ``removeFirst(_:)`` +- ``removeLast(_:)`` +- ``removeSubrange(_:)-512n3`` +- ``removeSubrange(_:)-8rmzx`` + +### Combining Dictionaries + +- ``merge(_:uniquingKeysWith:)-6ka2i`` +- ``merge(_:uniquingKeysWith:)-9wkad`` +- ``merging(_:uniquingKeysWith:)-4z49c`` +- ``merging(_:uniquingKeysWith:)-2e0xa`` + +### Comparing Dictionaries + +- ``==(_:_:)`` + +### Reordering Elements + +- ``swapAt(_:_:)`` +- ``reverse()`` +- ``sort()`` +- ``sort(by:)`` +- ``reverse()`` +- ``shuffle()`` +- ``shuffle(using:)`` +- ``partition(by:)`` + +### Transforming a Dictionary + +- ``mapValues(_:)`` +- ``compactMapValues(_:)`` + +### Memory Management + +- ``reserveCapacity(_:)`` + +### Supporting Types + +- ``Index`` +- ``Values-swift.struct`` +- ``Elements-swift.struct`` diff --git a/Sources/Collections/Collections.docc/Extensions/OrderedSet.UnorderedView.md b/Sources/Collections/Collections.docc/Extensions/OrderedSet.UnorderedView.md new file mode 100644 index 000000000..6e2681dce --- /dev/null +++ b/Sources/Collections/Collections.docc/Extensions/OrderedSet.UnorderedView.md @@ -0,0 +1,56 @@ +# ``Collections/OrderedSet/UnorderedView`` + + + + +## Topics + +### Binary Set Operations + +- ``intersection(_:)-3q45l`` +- ``intersection(_:)-6ee3o`` + +- ``union(_:)-79uk3`` +- ``union(_:)-23dm1`` + +- ``subtracting(_:)-3ct1b`` +- ``subtracting(_:)-8e6mw`` + +- ``symmetricDifference(_:)-6aed7`` +- ``symmetricDifference(_:)-7r79p`` + +- ``formIntersection(_:)-4ow38`` +- ``formIntersection(_:)-80iht`` + +- ``formUnion(_:)-6ijb`` +- ``formUnion(_:)-8tuol`` + +- ``subtract(_:)-627eq`` +- ``subtract(_:)-4pjhu`` + +- ``formSymmetricDifference(_:)-8pkt5`` +- ``formSymmetricDifference(_:)-75z52`` + +### Binary Set Predicates + +- ``==(_:_:)`` + +- ``isSubset(of:)-2dx31`` +- ``isSubset(of:)-801lo`` +- ``isSubset(of:)-952h5`` + +- ``isSuperset(of:)-9t33p`` +- ``isSuperset(of:)-2vtig`` +- ``isSuperset(of:)-9krpz`` + +- ``isStrictSubset(of:)-9o6mg`` +- ``isStrictSubset(of:)-91par`` +- ``isStrictSubset(of:)-7n66e`` + +- ``isStrictSuperset(of:)-89ig3`` +- ``isStrictSuperset(of:)-1e0xt`` +- ``isStrictSuperset(of:)-5dsfd`` + +- ``isDisjoint(with:)-3wuso`` +- ``isDisjoint(with:)-25vmx`` +- ``isDisjoint(with:)-8nfqs`` diff --git a/Sources/Collections/Collections.docc/Extensions/OrderedSet.md b/Sources/Collections/Collections.docc/Extensions/OrderedSet.md new file mode 100644 index 000000000..a47d51f19 --- /dev/null +++ b/Sources/Collections/Collections.docc/Extensions/OrderedSet.md @@ -0,0 +1,136 @@ +# ``Collections/OrderedSet`` + + + + +## Topics + +### Creating a Set + +- ``init()`` +- ``init(_:)-5zktd`` +- ``init(_:)-3d7qr`` +- ``init(_:)-68j7`` +- ``init(_:)-8zm9d`` +- ``init(_:)-7rt2h`` +- ``init(_:)-8tli8`` +- ``init(_:)-2d3a9`` +- ``init(uncheckedUniqueElements:)`` +- ``init(minimumCapacity:persistent:)`` + +### Collection Views + +- ``UnorderedView`` +- ``unordered`` +- ``elements`` + +### Finding Elements + +- ``contains(_:)`` +- ``firstIndex(of:)`` +- ``lastIndex(of:)`` + +### Adding and Updating Elements + +- ``append(_:)`` +- ``insert(_:at:)`` +- ``append(contentsOf:)`` +- ``updateOrAppend(_:)`` +- ``updateOrInsert(_:at:)`` +- ``update(_:at:)`` + +### Removing Elements + +- ``filter(_:)`` +- ``removeAll(where:)`` +- ``remove(_:)`` +- ``remove(at:)`` +- ``removeAll(keepingCapacity:)`` +- ``removeFirst()`` +- ``removeLast()`` +- ``removeFirst(_:)`` +- ``removeLast(_:)`` +- ``removeSubrange(_:)-62u6a`` +- ``removeSubrange(_:)-2fqke`` + +### Combining Sets + +- ``intersection(_:)-4o09a`` +- ``intersection(_:)-9yzg3`` +- ``intersection(_:)-80md4`` + +- ``union(_:)-67y2h`` +- ``union(_:)-3lt5i`` +- ``union(_:)-2939h`` + +- ``subtracting(_:)-5graf`` +- ``subtracting(_:)-7kl8r`` +- ``subtracting(_:)-1gl4y`` + +- ``symmetricDifference(_:)-1810l`` +- ``symmetricDifference(_:)-8dvm6`` +- ``symmetricDifference(_:)-9huk7`` + +- ``formIntersection(_:)-43o1u`` +- ``formIntersection(_:)-2a4y4`` +- ``formIntersection(_:)-7odn2`` + +- ``formUnion(_:)-6pksr`` +- ``formUnion(_:)-3dkzw`` +- ``formUnion(_:)-59end`` + +- ``subtract(_:)-3b6nj`` +- ``subtract(_:)-9rtmd`` +- ``subtract(_:)-9wmg8`` + +- ``formSymmetricDifference(_:)-96csi`` +- ``formSymmetricDifference(_:)-2ll2z`` +- ``formSymmetricDifference(_:)-391sm`` + +### Comparing Sets + +- ``==(_:_:)`` + +- ``isSubset(of:)-ptij`` +- ``isSubset(of:)-3mw6r`` +- ``isSubset(of:)-8yb29`` +- ``isSubset(of:)-9hxl4`` + +- ``isSuperset(of:)-4rrsh`` +- ``isSuperset(of:)-2bbv8`` +- ``isSuperset(of:)-7xvog`` +- ``isSuperset(of:)-7oow7`` + +- ``isStrictSubset(of:)-8m21h`` +- ``isStrictSubset(of:)-9lv3x`` +- ``isStrictSubset(of:)-4efhn`` +- ``isStrictSubset(of:)-10abw`` + +- ``isStrictSuperset(of:)-7u97x`` +- ``isStrictSuperset(of:)-3kfwa`` +- ``isStrictSuperset(of:)-98d9s`` +- ``isStrictSuperset(of:)-5e6d5`` + +- ``isDisjoint(with:)-6vmoh`` +- ``isDisjoint(with:)-4tsmx`` +- ``isDisjoint(with:)-54iy6`` +- ``isDisjoint(with:)-7nqur`` + +### Reordering Elements + +- ``swapAt(_:_:)`` +- ``sort()`` +- ``sort(by:)`` +- ``reverse()`` +- ``shuffle()`` +- ``shuffle(using:)`` +- ``partition(by:)`` + +### Creating and Applying Differences + +- ``difference(from:)-30bkk`` +- ``applying(_:)`` + +### Memory Management + +- ``reserveCapacity(_:)`` diff --git a/Sources/DequeModule/DequeModule.docc/DequeModule.md b/Sources/DequeModule/DequeModule.docc/DequeModule.md new file mode 100644 index 000000000..0746973eb --- /dev/null +++ b/Sources/DequeModule/DequeModule.docc/DequeModule.md @@ -0,0 +1,3 @@ +# ``DequeModule`` + +This module is dedicated to providing ``Deque``, a double-ended analogue of the standard `Array` type. diff --git a/Sources/DequeModule/DequeModule.docc/Extensions/Deque.md b/Sources/DequeModule/DequeModule.docc/Extensions/Deque.md new file mode 100644 index 000000000..4d3a8362e --- /dev/null +++ b/Sources/DequeModule/DequeModule.docc/Extensions/Deque.md @@ -0,0 +1,64 @@ +# ``DequeModule/Deque`` + +## Topics + +### Creating a Deque + +- ``init()`` +- ``init(_:)-8tyaw`` +- ``init(_:)-1tqf4`` +- ``init(minimumCapacity:)`` +- ``init(repeating:count:)-4v1gt`` +- ``init(unsafeUninitializedCapacity:initializingWith:)`` + +### Inspecting a Deque + +- ``count-8wcnm`` +- ``isEmpty`` + +### Manipulating Elements at the Front + +- ``first`` +- ``prepend(_:)`` +- ``prepend(contentsOf:)-96y15`` +- ``prepend(contentsOf:)-51zn6`` +- ``removeFirst()-1vdmt`` +- ``removeFirst(_:)-2vuji`` +- ``popFirst()`` +- ``prefix(_:)`` + +### Manipulating Elements at the End + +- ``last`` +- ``append(_:)-9h4m7`` +- ``append(contentsOf:)-8rqnl`` +- ``append(contentsOf:)-29aoh`` +- ``removeLast()`` +- ``removeLast(_:)`` +- ``popLast()`` +- ``suffix(_:)`` + +### Manipulating Elements Elsewhere + +- ``subscript(_:)-9nk44`` +- ``subscript(_:)-6ee8i`` +- ``subscript(_:)-1klky`` +- ``subscript(_:)-ejld`` +- ``insert(_:at:)-9hsp7`` +- ``insert(contentsOf:at:)-1d60f`` +- ``replaceSubrange(_:with:)-5rtzd`` +- ``remove(at:)-3imgi`` + +### Reordering Elements + +- ``swapAt(_:_:)-7910s`` +- ``sort()`` +- ``sort(by:)`` +- ``reverse()`` +- ``shuffle()`` +- ``shuffle(using:)`` +- ``partition(by:)-90y0t`` + +### Memory Management + +- ``reserveCapacity(_:)`` diff --git a/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Elements.md b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Elements.md new file mode 100644 index 000000000..752f3f5c0 --- /dev/null +++ b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Elements.md @@ -0,0 +1,37 @@ +# ``OrderedCollections/OrderedDictionary/Elements-swift.struct`` + +## Topics + +### Inspecting an Elements View + +- ``isEmpty`` +- ``count`` + +### Accessing Elements + +- ``subscript(_:)-4xwc2`` +- ``keys`` +- ``values`` +- ``index(forKey:)`` + +### Removing Elements + +- ``remove(at:)`` +- ``removeSubrange(_:)-5x7oo`` +- ``removeSubrange(_:)-7wdak`` +- ``removeAll(keepingCapacity:)`` +- ``removeAll(where:)`` +- ``removeFirst()`` +- ``removeFirst(_:)`` +- ``removeLast()`` +- ``removeLast(_:)`` + +### Reordering Elements + +- ``swapAt(_:_:)`` +- ``reverse()`` +- ``sort()`` +- ``sort(by:)`` +- ``partition(by:)`` +- ``shuffle()`` +- ``shuffle(using:)`` diff --git a/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Values.md b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Values.md new file mode 100644 index 000000000..6e50c1f4f --- /dev/null +++ b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.Values.md @@ -0,0 +1,24 @@ +# ``OrderedCollections/OrderedDictionary/Values-swift.struct`` + +## Topics + +### Inspecting a Values Collection + +- ``isEmpty`` +- ``count`` + +### Accessing Elements + +- ``subscript(_:)-25vfz`` +- ``elements`` +- ``withUnsafeBufferPointer(_:)`` +- ``withUnsafeMutableBufferPointer(_:)`` + +### Reordering Elements + +- ``swapAt(_:_:)-77eiy`` +- ``partition(by:)-9x0i5`` +- ``sort()`` +- ``sort(by:)`` +- ``shuffle()`` +- ``shuffle(using:)`` diff --git a/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.md b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.md new file mode 100644 index 000000000..7e0845ee6 --- /dev/null +++ b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedDictionary.md @@ -0,0 +1,94 @@ +# ``OrderedCollections/OrderedDictionary`` + +## Topics + +### Creating a Dictionary + +- ``init()`` +- ``init(minimumCapacity:persistent:)`` +- ``init(uniqueKeysWithValues:)-5ux9r`` +- ``init(uniqueKeysWithValues:)-88mzi`` +- ``init(uncheckedUniqueKeysWithValues:)-6gxhj`` +- ``init(uncheckedUniqueKeysWithValues:)-2j0dw`` +- ``init(uncheckedUniqueKeysWithValues:)-6gxhj`` +- ``init(uniqueKeys:values:)`` +- ``init(uncheckedUniqueKeys:values:)`` +- ``init(_:uniquingKeysWith:)-2y39b`` +- ``init(_:uniquingKeysWith:)-zhfp`` +- ``init(grouping:by:)-6mahw`` +- ``init(grouping:by:)-6m2zw`` + +### Inspecting a Dictionary + +- ``isEmpty`` +- ``count`` + +### Accessing Keys and Values + +- ``subscript(_:)`` +- ``subscript(_:default:)`` +- ``index(forKey:)`` + +### Collection Views + +- ``keys`` +- ``values-swift.property`` +- ``elements-swift.property`` + +### Updating Values + +- ``updateValue(_:forKey:)`` +- ``updateValue(_:forKey:insertingAt:)`` +- ``updateValue(forKey:default:with:)`` +- ``updateValue(forKey:insertingDefault:at:with:)`` + +### Removing Keys and Values + +- ``removeValue(forKey:)`` +- ``remove(at:)`` +- ``filter(_:)`` +- ``removeAll(where:)`` +- ``removeAll(keepingCapacity:)`` +- ``removeFirst()`` +- ``removeLast()`` +- ``removeFirst(_:)`` +- ``removeLast(_:)`` +- ``removeSubrange(_:)-512n3`` +- ``removeSubrange(_:)-8rmzx`` + +### Combining Dictionaries + +- ``merge(_:uniquingKeysWith:)-6ka2i`` +- ``merge(_:uniquingKeysWith:)-9wkad`` +- ``merging(_:uniquingKeysWith:)-4z49c`` +- ``merging(_:uniquingKeysWith:)-2e0xa`` + +### Comparing Dictionaries + +- ``==(_:_:)`` + +### Reordering Elements + +- ``swapAt(_:_:)`` +- ``reverse()`` +- ``sort()`` +- ``sort(by:)`` +- ``reverse()`` +- ``shuffle()`` +- ``shuffle(using:)`` +- ``partition(by:)`` + +### Transforming a Dictionary + +- ``mapValues(_:)`` +- ``compactMapValues(_:)`` + +### Memory Management + +- ``reserveCapacity(_:)`` + +### Supporting Types + +- ``Index`` +- ``Values-swift.struct`` +- ``Elements-swift.struct`` diff --git a/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.UnorderedView.md b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.UnorderedView.md new file mode 100644 index 000000000..ebc2c8892 --- /dev/null +++ b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.UnorderedView.md @@ -0,0 +1,53 @@ +# ``OrderedCollections/OrderedSet/UnorderedView`` + +## Topics + +### Binary Set Operations + +- ``intersection(_:)-3q45l`` +- ``intersection(_:)-6ee3o`` + +- ``union(_:)-79uk3`` +- ``union(_:)-23dm1`` + +- ``subtracting(_:)-3ct1b`` +- ``subtracting(_:)-8e6mw`` + +- ``symmetricDifference(_:)-6aed7`` +- ``symmetricDifference(_:)-7r79p`` + +- ``formIntersection(_:)-4ow38`` +- ``formIntersection(_:)-80iht`` + +- ``formUnion(_:)-6ijb`` +- ``formUnion(_:)-8tuol`` + +- ``subtract(_:)-627eq`` +- ``subtract(_:)-4pjhu`` + +- ``formSymmetricDifference(_:)-8pkt5`` +- ``formSymmetricDifference(_:)-75z52`` + +### Binary Set Predicates + +- ``==(_:_:)`` + +- ``isSubset(of:)-2dx31`` +- ``isSubset(of:)-801lo`` +- ``isSubset(of:)-952h5`` + +- ``isSuperset(of:)-9t33p`` +- ``isSuperset(of:)-2vtig`` +- ``isSuperset(of:)-9krpz`` + +- ``isStrictSubset(of:)-9o6mg`` +- ``isStrictSubset(of:)-91par`` +- ``isStrictSubset(of:)-7n66e`` + +- ``isStrictSuperset(of:)-89ig3`` +- ``isStrictSuperset(of:)-1e0xt`` +- ``isStrictSuperset(of:)-5dsfd`` + +- ``isDisjoint(with:)-3wuso`` +- ``isDisjoint(with:)-25vmx`` +- ``isDisjoint(with:)-8nfqs`` diff --git a/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.md b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.md new file mode 100644 index 000000000..eac28040b --- /dev/null +++ b/Sources/OrderedCollections/OrderedCollections.docc/Extensions/OrderedSet.md @@ -0,0 +1,133 @@ +# ``OrderedCollections/OrderedSet`` + +## Topics + +### Creating a Set + +- ``init()`` +- ``init(_:)-5zktd`` +- ``init(_:)-3d7qr`` +- ``init(_:)-68j7`` +- ``init(_:)-8zm9d`` +- ``init(_:)-7rt2h`` +- ``init(_:)-8tli8`` +- ``init(_:)-2d3a9`` +- ``init(uncheckedUniqueElements:)`` +- ``init(minimumCapacity:persistent:)`` + +### Collection Views + +- ``UnorderedView`` +- ``unordered`` +- ``elements`` + +### Finding Elements + +- ``contains(_:)`` +- ``firstIndex(of:)`` +- ``lastIndex(of:)`` + +### Adding and Updating Elements + +- ``append(_:)`` +- ``insert(_:at:)`` +- ``append(contentsOf:)`` +- ``updateOrAppend(_:)`` +- ``updateOrInsert(_:at:)`` +- ``update(_:at:)`` + +### Removing Elements + +- ``filter(_:)`` +- ``removeAll(where:)`` +- ``remove(_:)`` +- ``remove(at:)`` +- ``removeAll(keepingCapacity:)`` +- ``removeFirst()`` +- ``removeLast()`` +- ``removeFirst(_:)`` +- ``removeLast(_:)`` +- ``removeSubrange(_:)-62u6a`` +- ``removeSubrange(_:)-2fqke`` + +### Combining Sets + +- ``intersection(_:)-4o09a`` +- ``intersection(_:)-9yzg3`` +- ``intersection(_:)-80md4`` + +- ``union(_:)-67y2h`` +- ``union(_:)-3lt5i`` +- ``union(_:)-2939h`` + +- ``subtracting(_:)-5graf`` +- ``subtracting(_:)-7kl8r`` +- ``subtracting(_:)-1gl4y`` + +- ``symmetricDifference(_:)-1810l`` +- ``symmetricDifference(_:)-8dvm6`` +- ``symmetricDifference(_:)-9huk7`` + +- ``formIntersection(_:)-43o1u`` +- ``formIntersection(_:)-2a4y4`` +- ``formIntersection(_:)-7odn2`` + +- ``formUnion(_:)-6pksr`` +- ``formUnion(_:)-3dkzw`` +- ``formUnion(_:)-59end`` + +- ``subtract(_:)-3b6nj`` +- ``subtract(_:)-9rtmd`` +- ``subtract(_:)-9wmg8`` + +- ``formSymmetricDifference(_:)-96csi`` +- ``formSymmetricDifference(_:)-2ll2z`` +- ``formSymmetricDifference(_:)-391sm`` + +### Comparing Sets + +- ``==(_:_:)`` + +- ``isSubset(of:)-ptij`` +- ``isSubset(of:)-3mw6r`` +- ``isSubset(of:)-8yb29`` +- ``isSubset(of:)-9hxl4`` + +- ``isSuperset(of:)-4rrsh`` +- ``isSuperset(of:)-2bbv8`` +- ``isSuperset(of:)-7xvog`` +- ``isSuperset(of:)-7oow7`` + +- ``isStrictSubset(of:)-8m21h`` +- ``isStrictSubset(of:)-9lv3x`` +- ``isStrictSubset(of:)-4efhn`` +- ``isStrictSubset(of:)-10abw`` + +- ``isStrictSuperset(of:)-7u97x`` +- ``isStrictSuperset(of:)-3kfwa`` +- ``isStrictSuperset(of:)-98d9s`` +- ``isStrictSuperset(of:)-5e6d5`` + +- ``isDisjoint(with:)-6vmoh`` +- ``isDisjoint(with:)-4tsmx`` +- ``isDisjoint(with:)-54iy6`` +- ``isDisjoint(with:)-7nqur`` + +### Reordering Elements + +- ``swapAt(_:_:)`` +- ``sort()`` +- ``sort(by:)`` +- ``reverse()`` +- ``shuffle()`` +- ``shuffle(using:)`` +- ``partition(by:)`` + +### Creating and Applying Differences + +- ``difference(from:)-30bkk`` +- ``applying(_:)`` + +### Memory Management + +- ``reserveCapacity(_:)`` diff --git a/Sources/OrderedCollections/OrderedCollections.docc/OrderedCollections.md b/Sources/OrderedCollections/OrderedCollections.docc/OrderedCollections.md new file mode 100644 index 000000000..dcc7288a0 --- /dev/null +++ b/Sources/OrderedCollections/OrderedCollections.docc/OrderedCollections.md @@ -0,0 +1,10 @@ +# ``OrderedCollections`` + +The `OrderedCollections` module provides hashed collection types that work like the standard `Set` and `Dictionary`, but maintain their elements in a particular user-specified order. + +## Topics + +### Structures + +- ``OrderedSet`` +- ``OrderedDictionary`` diff --git a/Utils/generate-docs.sh b/Utils/generate-docs.sh new file mode 100755 index 000000000..86506af13 --- /dev/null +++ b/Utils/generate-docs.sh @@ -0,0 +1,92 @@ +#!/bin/sh +#===---------------------------------------------------------------------- +# +# This source file is part of the Swift Collections open source project +# +# Copyright (c) 2022 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 +# +#===---------------------------------------------------------------------- + +set -eu + +shopt -s nullglob +cd "$(dirname $0)/.." + +if [ "$(uname)" = "Darwin" ]; then + swift="xcrun swift" + export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render" +else + swift="swift" +fi + +build_dir="$(mktemp -d "/tmp/$(basename $0).XXXXX")" +echo "Build directory: $build_dir" + +output_dir_base=/tmp/foo + +rm -rf "$output_dir_base" + +components="DequeModule OrderedCollections" + +if [ $# -eq 0 ]; then + targets="Collections $components" +else + targets="$@" +fi + +for target in $targets; do + if [ "$target" = "Collections" ]; then + # Update extensions under Collections.docc + rm -rf Sources/Collections/Collections.docc/Extensions/*.md + for component in $components; do + for file in Sources/"$component"/"$component".docc/Extensions/*.md; do + output="Sources/Collections/Collections.docc/Extensions/$(basename $file)" + blurb="" + sed 's?^# ``[^/]*/\(.*\)``?# ``Collections/\1``\n\n'"$blurb"'\n?' "$file" > "$output" + done + done + fi + + mkdir -p "$build_dir/$target/build" + mkdir -p "$build_dir/$target/symbol-graphs" + mkdir -p "$build_dir/$target/docc" + $swift build --target "$target" \ + --build-path "$build_dir/$target/build" \ + -Xswiftc -emit-symbol-graph \ + -Xswiftc -emit-symbol-graph-dir \ + -Xswiftc "$build_dir/$target/symbol-graphs" + + # Prevent DocC from getting confused by too much data :-/ + cp \ + "$build_dir/$target/symbol-graphs/$target.symbols.json" \ + "$build_dir/$target/docc" + extrafile="$build_dir/$target/symbol-graphs/${target}@Swift.symbols.json" + if [ -r "$extrafile" ]; then + cp "$extrafile" "$build_dir/$target/docc" + fi + + mkdir -p "$output_dir_base/$target" + xcrun docc convert \ + --analyze \ + --fallback-display-name "$target" \ + --fallback-bundle-identifier "org.swift.swift-collections.$target" \ + --fallback-bundle-version 1.1.0 \ + --default-code-listing-language swift \ + --additional-symbol-graph-dir "$build_dir/$target/docc" \ + --transform-for-static-hosting \ + --output-path "$output_dir_base/$target" \ + --hosting-base-path "/swift-collections/$target" \ + "Sources/$target/$target.docc" +done + +if [ $# -eq 1 ]; then + module="$1" + xcrun docc preview "Sources/$module/$module.docc" \ + --fallback-display-name "Swift Collections" \ + --fallback-bundle-identifier "org.swift.swift-collections.$module" \ + --fallback-bundle-version 1.1.0 \ + --additional-symbol-graph-dir "$build_dir/$module/docc" +fi From 08b38129b9d2b584d7447d79ce7a00867d601410 Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 6 Dec 2022 18:41:29 -0800 Subject: [PATCH 2/7] [OrderedSet] Fix outdated documentation --- Sources/OrderedCollections/OrderedSet/OrderedSet.swift | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet.swift index 83ca98a39..ef0e0ab94 100644 --- a/Sources/OrderedCollections/OrderedSet/OrderedSet.swift +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet.swift @@ -66,10 +66,11 @@ /// 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: Int) -> (inserted: Bool, index: Int) /// func append(_ item: Element) -> (inserted: Bool, index: Int) -/// func update(at index: Int, with item: Element) -> Element +/// func insert(_ item: Element, at index: Int) -> (inserted: Bool, index: Int) /// func updateOrAppend(_ item: Element) -> Element? +/// func updateOrInsert(_ item: Element, at index: Int) -> (originalMember: Element?, index: Int) +/// func update(_ item: Element, at index: Int) -> Element /// /// Additionally,`OrderedSet` has an order-sensitive definition of equality (see /// above) that is incompatible with `SetAlgebra`'s documented semantic From a874de5f7f7c95d1a439169f10a4b0289a936627 Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 6 Dec 2022 19:00:59 -0800 Subject: [PATCH 3/7] [OrderedCollections] Refresh some docs with DocC links --- ...Dictionary+Partial MutableCollection.swift | 2 +- .../OrderedDictionary/OrderedDictionary.swift | 66 +++++++------------ .../OrderedSet/OrderedSet.swift | 64 +++++++----------- 3 files changed, 50 insertions(+), 82 deletions(-) diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift index f43d69935..35970a7f3 100644 --- a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary+Partial MutableCollection.swift @@ -132,7 +132,7 @@ extension OrderedDictionary { /// Use the `shuffle()` method to randomly reorder the elements of an ordered /// dictionary. /// - /// This method is equivalent to calling `shuffle(using:)`, passing in the + /// 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. diff --git a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift index f32222d3f..34e0e3ba5 100644 --- a/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift +++ b/Sources/OrderedCollections/OrderedDictionary/OrderedDictionary.swift @@ -93,13 +93,14 @@ /// /// (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(_:)`). +/// The `Dictionary` type's original ``updateValue(_:forKey:)`` method is also +/// available, and so is ``index(forKey:)``, grouping/uniquing initializers +/// (``init(uniqueKeysWithValues:)-5ux9r``, ``init(_:uniquingKeysWith:)-2y39b``, +/// ``init(grouping:by:)-6mahw``), methods for merging one dictionary with +/// another (``merge(_:uniquingKeysWith:)-6ka2i``, +/// ``merging(_:uniquingKeysWith:)-4z49c``), filtering dictionary entries +/// (``filter(_:)``), transforming values (``mapValues(_:)``), +/// and a combination of these two (``compactMapValues(_:)``). /// /// ### Sequence and Collection Operations /// @@ -107,60 +108,43 @@ /// 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: +/// random-access collection view over its key-value pairs, called +/// ``elements-swift.property``: /// /// 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: +/// `OrderedDictionary` nor its ``elements-swift.property`` 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: 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) -/// -/// // 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 -/// -/// `OrderedDictionary` also implements `reserveCapacity(_)` from +/// `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. +/// Like the standard `Dictionary`, `OrderedDictionary` provides ``keys`` and +/// ``values-swift.property`` 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. +/// 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 +/// 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: +/// The ``values-swift.property`` property returns a mutable random-access +/// collection of the values in the dictionary: /// /// d.values // "two", "one", "zero" /// d.values[2] = "nada" @@ -169,7 +153,7 @@ /// // `d` is now [2: "nada", 1: "one", 0: "two"] /// /// Both views store their contents in regular `Array` values, accessible -/// through their `elements` property. +/// through their own `elements` property. /// /// ## Performance /// diff --git a/Sources/OrderedCollections/OrderedSet/OrderedSet.swift b/Sources/OrderedCollections/OrderedSet/OrderedSet.swift index ef0e0ab94..5f0fbf70e 100644 --- a/Sources/OrderedCollections/OrderedSet/OrderedSet.swift +++ b/Sources/OrderedCollections/OrderedSet/OrderedSet.swift @@ -44,9 +44,9 @@ /// # 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:)`. +/// particular, it supports the membership test ``contains(_:)`` as well as all +/// high-level set operations such as ``union(_:)-67y2h``, +/// ``intersection(_:)-4o09a`` or ``isSubset(of:)-ptij``. /// /// buildingMaterials.contains("glass") // false /// buildingMaterials.intersection(["brick", "straw"]) // ["straw", "brick"] @@ -56,15 +56,15 @@ /// 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: +/// On the other hand, predicates such as ``isSubset(of:)-ptij`` 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: +/// `OrderedSet` does not implement `insert(_:)` nor `update(with:)` from +/// `SetAlgebra` -- it provides its own variants for insertion that are more +/// explicit about where in the collection new elements gets inserted: /// /// func append(_ item: Element) -> (inserted: Bool, index: Int) /// func insert(_ item: Element, at index: Int) -> (inserted: Bool, index: Int) @@ -82,8 +82,9 @@ /// 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. +/// `SetAlgebra`. This view is accessed through the ``unordered`` property, and +/// it 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] @@ -127,34 +128,17 @@ /// 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. +/// `RangeReplaceableCollection`'s `replaceSubrange` method 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 +/// namely, is supports mutation operations that merely change the +/// order of elements (such as ``sort()`` or ``swapAt(_:_:)``, or just remove +/// some subset of existing members (such as ``remove(at:)`` or +/// ``removeAll(where:)``). +/// +/// `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.) @@ -165,7 +149,7 @@ /// 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 using its ``elements`` property. `OrderedSet` uses a standard array /// value for element storage, so extracting the array value has minimal /// overhead. /// @@ -176,14 +160,14 @@ /// 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 +/// ``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 +/// 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 +/// ``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. /// From 847b548a03c8db491150820e0b97cdf286b4a3fe Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 6 Dec 2022 19:39:08 -0800 Subject: [PATCH 4/7] [Manifest] Exclude documentation bundles from 5.3 manifest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We should have a separate Package@swift-5.5.swift manifest that removes these exclusions; however, that requires some additional validation testing — let’s do that later. --- Package.swift | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Package.swift b/Package.swift index 52ecce537..04ea57660 100644 --- a/Package.swift +++ b/Package.swift @@ -63,7 +63,7 @@ let package = Package( "OrderedCollections", ], path: "Sources/Collections", - exclude: ["CMakeLists.txt"], + exclude: ["CMakeLists.txt", "Collections.docc"], swiftSettings: settings), // Testing support module @@ -85,7 +85,7 @@ let package = Package( // Deque .target( name: "DequeModule", - exclude: ["CMakeLists.txt"], + exclude: ["CMakeLists.txt", "DequeModule.docc"], swiftSettings: settings), .testTarget( name: "DequeTests", @@ -95,7 +95,7 @@ let package = Package( // OrderedSet, OrderedDictionary .target( name: "OrderedCollections", - exclude: ["CMakeLists.txt"], + exclude: ["CMakeLists.txt", "OrderedCollections.docc"], swiftSettings: settings), .testTarget( name: "OrderedCollectionsTests", From e14a0359ca4aeee4e9ceb5339592a1dbce9a7289 Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 6 Dec 2022 21:02:09 -0800 Subject: [PATCH 5/7] Add a configuration file for the Swift Package Index --- .spi.yml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .spi.yml diff --git a/.spi.yml b/.spi.yml new file mode 100644 index 000000000..adcda23e8 --- /dev/null +++ b/.spi.yml @@ -0,0 +1,4 @@ +version: 1 +builder: + configs: + - documentation_targets: [Collections, DequeModule, OrderedCollections] From b4c1070741a119654864b736268c3f03f6799a1b Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 6 Dec 2022 21:02:34 -0800 Subject: [PATCH 6/7] [Docs] Update high-level Collections docs --- .../Collections.docc/Collections.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/Sources/Collections/Collections.docc/Collections.md b/Sources/Collections/Collections.docc/Collections.md index 7a0322c53..1d2cc0130 100644 --- a/Sources/Collections/Collections.docc/Collections.md +++ b/Sources/Collections/Collections.docc/Collections.md @@ -2,9 +2,23 @@ **Swift Collections** is an open-source package of data structure implementations for the Swift programming language. -This package provides separate modules 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`. +The package currently provides the following implementations: -The top-level module `Collections` imports and reexports each of these smaller packages. Importing this module is a useful shortcut if you want to import all data structures, or if you don't care about bringing in more code than you need. +- ``Deque``, a double-ended queue backed by a ring buffer. Deques are range-replaceable, mutable, random-access collections. + +- ``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``, an ordered variant of the standard `Dictionary`, providing similar benefits. + +## Modules + +This package provides separate products for each group of data structures it implements: + +- ``Collections``. This is an umbrella module that exports every other public module in the package. +- ``DequeModule``. Defines ``Deque``. +- ``OrderedCollections``. Defines the ordered collection types ``OrderedSet`` and ``OrderedDictionary``. + +If you aren't constrained by code size limitations, then importing ``Collections`` is the simplest way to start using the package. ```swift import Collections @@ -21,7 +35,6 @@ people.contains("Rebecca") // true - [`Swift Collections` on GitHub](https://github.com/apple/swift-collections/) - [`Swift Collections` on the Swift Forums](https://forums.swift.org/c/related-projects/collections/72) - ## Topics ### Deque Module From 089666b32ba82c06a166e072ebcdf988108b66b7 Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Wed, 7 Dec 2022 14:25:12 -0800 Subject: [PATCH 7/7] Add a separate package manifest for Swift 5.5+ --- Package@swift-5.5.swift | 100 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 Package@swift-5.5.swift diff --git a/Package@swift-5.5.swift b/Package@swift-5.5.swift new file mode 100644 index 000000000..7deefc6b5 --- /dev/null +++ b/Package@swift-5.5.swift @@ -0,0 +1,100 @@ +// swift-tools-version:5.5 +//===----------------------------------------------------------------------===// +// +// This source file is part of the Swift Collections open source project +// +// Copyright (c) 2021-2022 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"), +] + +let package = Package( + name: "swift-collections", + products: [ + .library(name: "Collections", targets: ["Collections"]), + .library(name: "DequeModule", targets: ["DequeModule"]), + .library(name: "OrderedCollections", targets: ["OrderedCollections"]), + ], + targets: [ + .target( + name: "Collections", + dependencies: [ + "DequeModule", + "OrderedCollections", + ], + path: "Sources/Collections", + exclude: ["CMakeLists.txt"], + swiftSettings: settings), + + // Testing support module + .target( + name: "_CollectionsTestSupport", + dependencies: [], + swiftSettings: settings, + linkerSettings: [ + .linkedFramework( + "XCTest", + .when(platforms: [.macOS, .iOS, .watchOS, .tvOS])), + ] + ), + .testTarget( + name: "CollectionsTestSupportTests", + dependencies: ["_CollectionsTestSupport"], + swiftSettings: settings), + + // Deque + .target( + name: "DequeModule", + exclude: ["CMakeLists.txt"], + swiftSettings: settings), + .testTarget( + name: "DequeTests", + dependencies: ["DequeModule", "_CollectionsTestSupport"], + swiftSettings: settings), + + // OrderedSet, OrderedDictionary + .target( + name: "OrderedCollections", + exclude: ["CMakeLists.txt"], + swiftSettings: settings), + .testTarget( + name: "OrderedCollectionsTests", + dependencies: ["OrderedCollections", "_CollectionsTestSupport"], + swiftSettings: settings), + ] +)