Compare commits

...
20 Commits
Author SHA1 Message Date
Nate Cook e84988b833 Merge branch 'main' into nate/pdqsort 2024-11-14 21:40:40 -06:00
Nate Cook 34eec0dd27 Update project to depend on Swift 5.7 (#240) 2024-08-21 17:19:30 -05:00
Guillaume Lessard 09dc5e4354 Merge pull request #227 from CheATSlark/main
Update Suffix.md
2024-06-25 11:01:42 -07:00
slark 0a01f21eae Merge branch 'main' into main 2024-06-25 15:46:29 +08:00
Jed Fox 34b1705efd Clarify the docs for partitioned(by:) (#228) 2024-05-07 12:53:17 -07:00
jerry ae92f2b33f Update Suffix.md
Fix 'Suffix.md'  example code
2024-04-12 16:09:42 +08:00
Marcos Griselli 33abb69428 Remove @_implementationOnly annotations (#225)
Signed-off-by: Marcos Griselli <marcosg@lyft.com>
2024-03-09 13:35:42 -06:00
Takumi Muraishi 82ee335a48 Fix typo in TestUtilities.swift (#223) 2024-02-17 00:58:00 -06:00
Dimitris Apostolou 9e3900be49 Fix typos (#222) 2024-02-07 00:18:57 -06:00
Dave Abrahams 9dd88e5eaf CombinationsSequence: underestimatedCount == count (#220)
Not doing this makes it needlessly costly to create an Array of the
results.
2024-01-20 10:04:45 -06:00
Kenny c3b3acbca3 Fix Typo in README Xocde -> Xcode 2023-11-26 13:32:29 -06:00
Nate Cook f6919dfc30 Documentation improvements
- Restructure the project README, moving the list of guides into a
README in the `Guides` directory
- Curate the `keyed(by:)` and `grouped(by:)` methods
2023-11-14 21:50:39 -06:00
Nate Cook f2fd047eed Update changelog for 1.2.0 release 2023-11-14 21:50:39 -06:00
Nate Cook 5c54f200e7 Update guide/docs/tests. 2023-11-14 13:00:34 -06:00
Matthew Young 2e71e228c0 Update Suffix.swift
Change `endOfPrefix(while:)` and `startOfSuffix(while:)` from internal to public
2023-11-14 13:00:34 -06:00
Alexander Momchilov 328631d60c Add grouped(by:) and keyed(by:) (#197)
* Add Grouped and Keyed

* Add `Key` to `combine` closure

* Split `keyed(by:)` into two overloads

* Rename uniquingKeysWith → resolvingConflictsWith

* Keep latest instead of throwing on collision
2023-11-07 14:29:10 -06:00
Stephen Canon 0ebed148c2 Merge pull request #210 from amomchilov/tweak-docs
[Docs] Add link and remove redundant doc line
2023-11-01 11:57:28 -04:00
Alexander Momchilov c8ae549e42 [Docs] Add link and remove redundant doc line 2023-10-31 20:25:50 -04:00
Taras Tsugrii dd4e0e70ff [minmax] Do nothing for empty suffix/prefix. (#202)
It's a semantical noop but slightly more efficient for the case when max/min is requested for an empty Collection.
2023-10-31 11:03:19 -05:00
Gwynne Raskind 9a8cbc61e0 Specify dependency URL in consistent fashion (#194) 2023-07-16 23:37:38 -05:00
30 changed files with 1265 additions and 154 deletions

No files matched your search

+36 -2
View File
@@ -10,9 +10,35 @@ This project follows semantic versioning.
*No new changes.*
## [1.2.0] - 2023-11-14
### Additions
- Sequences have new `grouped(by:)` and `keyed(by:)` methods, which simplify
building dictionaries based on sequence elements: ([#197])
```swift
let evensOdds = (1...10).grouped(by: { $0.isMultiple(of: 2) ? "even" : "odd" })
// ["even": [2, 4, 6, 8, 10], "odd": [1, 3, 5, 7, 9]]
let animals = ["Aardvark", "Alpaca", "Armadillo", "Barracuda", "Buffalo", ...]
let alphaAnimals = animals.keyed(by: \.first!, resolvingConflictsWith: { _, first, _ in first })
// ["A": "Aardvark", "B": "Barracuda", ...]
```
- The `endOfPrefix(while:)` and `startOfSuffix(while)` methods are now public.
These methods were previously implementation details of the `trimming` group
of methods. ([#211])
### Fixes
- Documentation and performance improvements. ([#202], [#210])
The 1.2.0 release includes contributions from [amomchilov], [mattyoung], [natecook1000], [stephentyrone], and [ttsugriy].
Thank you!
---
## [1.1.0] - 2023-08-24
## [1.1.0] - 2023-10-05
### Additions
@@ -312,7 +338,8 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
<!-- Link references for releases -->
[Unreleased]: https://github.com/apple/swift-algorithms/compare/1.1.0...HEAD
[Unreleased]: https://github.com/apple/swift-algorithms/compare/1.2.0...HEAD
[1.2.0]: https://github.com/apple/swift-algorithms/compare/1.1.0...1.2.0
[1.1.0]: https://github.com/apple/swift-algorithms/compare/1.0.0...1.1.0
[1.0.0]: https://github.com/apple/swift-algorithms/compare/0.2.1...1.0.0
[0.2.1]: https://github.com/apple/swift-algorithms/compare/0.2.0...0.2.1
@@ -354,9 +381,14 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
[#138]: https://github.com/apple/swift-algorithms/pull/138
[#152]: https://github.com/apple/swift-algorithms/pull/152
[#162]: https://github.com/apple/swift-algorithms/pull/162
[#197]: https://github.com/apple/swift-algorithms/pull/197
[#202]: https://github.com/apple/swift-algorithms/pull/202
[#210]: https://github.com/apple/swift-algorithms/pull/210
[#211]: https://github.com/apple/swift-algorithms/pull/211
<!-- Link references for contributors -->
[amomchilov]: https://github.com/apple/swift-algorithms/commits?author=amomchilov
[AustinConlon]: https://github.com/apple/swift-algorithms/commits?author=AustinConlon
[benrimmington]: https://github.com/apple/swift-algorithms/commits?author=benrimmington
[bjhomer]: https://github.com/apple/swift-algorithms/commits?author=bjhomer
@@ -376,6 +408,7 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
[LemonSpike]: https://github.com/apple/swift-algorithms/commits?author=LemonSpike
[LucianoPAlmeida]: https://github.com/apple/swift-algorithms/commits?author=LucianoPAlmeida
[markuswntr]: https://github.com/apple/swift-algorithms/commits?author=markuswntr
[mattyoung]: https://github.com/apple/swift-algorithms/commits?author=mattyoung
[mdznr]: https://github.com/apple/swift-algorithms/commits?author=mdznr
[michiboo]: https://github.com/apple/swift-algorithms/commits?author=michiboo
[mpangburn]: https://github.com/apple/swift-algorithms/commits?author=mpangburn
@@ -393,3 +426,4 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
[stephentyrone]: https://github.com/apple/swift-algorithms/commits?author=stephentyrone
[timvermeulen]: https://github.com/apple/swift-algorithms/commits?author=timvermeulen
[toddthomas]: https://github.com/apple/swift-algorithms/commits?author=toddthomas
[ttsugriy]: https://github.com/apple/swift-algorithms/commits?author=ttsugriy
-3
View File
@@ -5,9 +5,6 @@
Lazily iterates over tuples of adjacent elements.
This operation is available for any sequence by calling the `adjacentPairs()`
method.
```swift
let numbers = (1...5)
let pairs = numbers.adjacentPairs()
+1 -1
View File
@@ -86,7 +86,7 @@ call to `CombinationsSequence.Iterator.next()` is an O(_n_) operation.
### Naming
The parameter label in `combination(ofCount:)` is the best match for the
Swift API guidelines. A few other options were considered:
[Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/). A few other options were considered:
- When the standard library uses `of` as a label, the parameter is generally
the object of the operation, as in `type(of:)` and `firstIndex(of:)`, and
+68
View File
@@ -0,0 +1,68 @@
# Grouped
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Grouped.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/GroupedTests.swift)]
Groups up elements of a sequence into a new Dictionary, whose values are Arrays of grouped elements, each keyed by the result of the given closure.
```swift
let fruits = ["Apricot", "Banana", "Apple", "Cherry", "Avocado", "Coconut"]
let fruitsByLetter = fruits.grouped(by: { $0.first! })
// Results in:
// [
// "B": ["Banana"],
// "A": ["Apricot", "Apple", "Avocado"],
// "C": ["Cherry", "Coconut"],
// ]
```
If you wish to achieve a similar effect but for single values (instead of Arrays of grouped values), see [`keyed(by:)`](Keyed.md).
## Detailed Design
The `grouped(by:)` method is declared as a `Sequence` extension returning
`[GroupKey: [Element]]`.
```swift
extension Sequence {
public func grouped<GroupKey>(
by keyForValue: (Element) throws -> GroupKey
) rethrows -> [GroupKey: [Element]]
}
```
### Complexity
Calling `grouped(by:)` is an O(_n_) operation.
### Comparison with other languages
| Language | Grouping API |
|---------------|--------------|
| Java | [`groupingBy`](https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/util/stream/Collectors.html#groupingBy(java.util.function.Function)) |
| Kotlin | [`groupBy`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/group-by.html) |
| C# | [`GroupBy`](https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.groupby?view=net-7.0#system-linq-enumerable-groupby) |
| Rust | [`group_by`](https://doc.rust-lang.org/std/primitive.slice.html#method.group_by) |
| Ruby | [`group_by`](https://ruby-doc.org/3.2.2/Enumerable.html#method-i-group_by) |
| Python | [`groupby`](https://docs.python.org/3/library/itertools.html#itertools.groupby) |
| PHP (Laravel) | [`groupBy`](https://laravel.com/docs/10.x/collections#method-groupby) |
#### Naming
All the surveyed languages name this operation with a variant of "grouped" or "grouping". The past tense `grouped(by:)` best fits [Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).
#### Customization points
Java and C# are interesting in that they provide multiple overloads with several points of customization:
1. Changing the type of the groups.
1. E.g. the groups can be Sets instead of Arrays.
1. Akin to calling `.transformValues { group in Set(group) }` on the resultant dictionary, but avoiding the intermediate allocation of Arrays of each group.
2. Picking which elements end up in the groupings.
1. The default is the elements of the input sequence, but can be changed.
2. Akin to calling `.transformValues { group in group.map(someTransform) }` on the resultant dictionary, but avoiding the intermediate allocation of Arrays of each group.
3. Changing the type of the outermost collection.
1. E.g using an `OrderedDictionary`, `SortedDictionary` or `TreeDictionary` instead of the default (hashed, unordered) `Dictionary`.
2. There's no great way to achieve this with the `grouped(by:)`. One could wrap the resultant dictionary in an initializer to one of the other dictionary types, but that isn't sufficient: Once the `Dictionary` loses the ordering, there's no way to get it back when constructing one of the ordered dictionary variants.
It is not clear which of these points of customization are worth supporting, or what the best way to express them might be.
+78
View File
@@ -0,0 +1,78 @@
# Keyed
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Keyed.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/KeyedTests.swift)]
Stores the elements of a sequence as the values of a Dictionary, keyed by the result of the given closure.
```swift
let fruits = ["Apricot", "Banana", "Apple", "Cherry", "Blackberry", "Avocado", "Coconut"]
let fruitByLetter = fruits.keyed(by: { $0.first! })
// Results in:
// [
// "A": "Avocado",
// "B": "Blackberry",
// "C": "Coconut",
// ]
```
On a key-collision, the latest element is kept by default. Alternatively, you can provide a closure which specifies which value to keep:
```swift
let fruits = ["Apricot", "Banana", "Apple", "Cherry", "Blackberry", "Avocado", "Coconut"]
let fruitsByLetter = fruits.keyed(
by: { $0.first! },
resolvingConflictsWith: { key, old, new in old } // Always pick the first fruit
)
// Results in:
// [
// "A": "Apricot",
// "B": "Banana",
// "C": "Cherry",
// ]
```
## Detailed Design
The `keyed(by:)` and `keyed(by:resolvingConflictsWith:)` methods are declared in an `Sequence` extension, both returning `[Key: Element]`.
```swift
extension Sequence {
public func keyed<Key>(
by keyForValue: (Element) throws -> Key
) rethrows -> [Key: Element]
public func keyed<Key>(
by keyForValue: (Element) throws -> Key,
resolvingConflictsWith resolve: ((Key, Element, Element) throws -> Element)? = nil
) rethrows -> [Key: Element]
}
```
### Complexity
Calling `keyed(by:)` is an O(_n_) operation.
### Comparison with other languages
| Language | "Keying" API |
|---------------|-------------|
| Java | [`toMap`](https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/util/stream/Collectors.html#toMap(java.util.function.Function,java.util.function.Function)) |
| Kotlin | [`associatedBy`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/associate-by.html) |
| C# | [`ToDictionary`](https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.todictionary?view=net-7.0#system-linq-enumerable-todictionary) |
| Ruby (ActiveSupport) | [`index_by`](https://rubydoc.info/gems/activesupport/7.0.5/Enumerable#index_by-instance_method) |
| PHP (Laravel) | [`keyBy`](https://laravel.com/docs/10.x/collections#method-keyby) |
#### Rejected alternative names
1. Java's `toMap` is referring to `Map`/`HashMap`, their naming for Dictionaries and other associative collections. It's easy to confuse with the transformation function, `Sequence.map(_:)`.
2. C#'s `toXXX()` naming doesn't suite Swift well, which tends to prefer `Foo.init` over `toFoo()` methods.
3. Ruby's `index_by` naming doesn't fit Swift well, where "index" is a specific term (e.g. the `associatedtype Index` on `Collection`). There is also a [`index(by:)`](Index.md) method in swift-algorithms, is specifically to do with matching elements up with their indices, and not any arbitrary derived value.
#### Alternative names
Kotlin's `associatedBy` naming is a good alternative, and matches the past tense of [Swift's API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/), though perhaps we'd spell it `associated(by:)`.
#### Customization points
Java and C# are interesting in that they provide overloads that let you customize the type of the outermost collection. E.g. using an `OrderedDictionary` instead of the default (hashed, unordered) `Dictionary`.
+53
View File
@@ -0,0 +1,53 @@
# Guides
These guides describe the design and intention behind the APIs included in the `Algorithms` library. For further reading, see the [announcement on swift.org](https://swift.org/blog/swift-algorithms/) and the [official documentation](https://swiftpackageindex.com/apple/swift-algorithms/documentation/algorithms).
## Contents
#### Combinations / permutations
- [`combinations(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Combinations.md): Combinations of particular sizes of the elements in a collection.
- [`permutations(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Permutations.md): Permutations of a particular size of the elements in a collection, or of the full collection.
- [`uniquePermutations(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Permutations.md): Permutations of a collection's elements, skipping any duplicate permutations.
#### Mutating algorithms
- [`rotate(toStartAt:)`, `rotate(subrange:toStartAt:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Rotate.md): In-place rotation of elements.
- [`stablePartition(by:)`, `stablePartition(subrange:by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Partition.md): A partition that preserves the relative order of the resulting prefix and suffix.
#### Combining collections
- [`chain(_:_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md): Concatenates two collections with the same element type.
- [`cycled()`, `cycled(times:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Cycle.md): Repeats the elements of a collection forever or a set number of times.
- [`joined(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Joined.md): Concatenate sequences of sequences, using an element or sequence as a separator, or using a closure to generate each separator.
- [`product(_:_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Product.md): Iterates over all the pairs of two collections; equivalent to nested `for`-`in` loops.
#### Subsetting operations
- [`compacted()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Compacted.md): Drops the `nil`s from a sequence or collection, unwrapping the remaining elements.
- [`partitioned(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Partition.md): Returns the elements in a sequence or collection that do and do not match a given predicate.
- [`randomSample(count:)`, `randomSample(count:using:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/RandomSampling.md): Randomly selects a specific number of elements from a collection.
- [`randomStableSample(count:)`, `randomStableSample(count:using:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/RandomSampling.md): Randomly selects a specific number of elements from a collection, preserving their original relative order.
- [`striding(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Stride.md): Returns every nth element of a collection.
- [`suffix(while:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Suffix.md): Returns the suffix of a collection where all element pass a given predicate.
- [`trimmingPrefix(while:)`, `trimmingSuffix(while)`, `trimming(while:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Trim.md): Returns a slice by trimming elements from a collection's start, end, or both. The mutating `trim...` methods trim a collection in place.
- [`uniqued()`, `uniqued(on:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Unique.md): The unique elements of a collection, preserving their order.
- [`minAndMax()`, `minAndMax(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/MinMax.md): Returns the smallest and largest elements of a sequence.
#### Partial sorting
- [`min(count:)`, `max(count:)`, `min(count:sortedBy:)`, `max(count:sortedBy:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/MinMax.md): Returns the smallest or largest elements of a collection, sorted by a predicate.
#### Other useful operations
- [`adjacentPairs()`](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md): Lazily iterates over tuples of adjacent elements.
- [`chunked(by:)`, `chunked(on:)`, `chunks(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md): Eager and lazy operations that break a collection into chunks based on either a binary predicate or when the result of a projection changes or chunks of a given count.
- [`firstNonNil(_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/FirstNonNil.md): Returns the first non-`nil` result from transforming a sequence's elements.
- [`grouped(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Grouped.md): Group up elements using the given closure, returning a Dictionary of those groups, keyed by the results of the closure.
- [`indexed()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Indexed.md): Iterate over tuples of a collection's indices and elements.
- [`interspersed(with:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Intersperse.md): Place a value between every two elements of a sequence.
- [`keyed(by:)`, `keyed(by:resolvingConflictsBy:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Keyed.md): Returns a Dictionary that associates elements of a sequence with the keys returned by the given closure.
- [`partitioningIndex(where:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Partition.md): Returns the starting index of the partition of a collection that matches a predicate.
- [`reductions(_:)`, `reductions(_:_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Reductions.md): Returns all the intermediate states of reducing the elements of a sequence or collection.
- [`split(maxSplits:omittingEmptySubsequences:whereSeparator)`, `split(separator:maxSplits:omittingEmptySubsequences)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Split.md): Lazy versions of the Standard Library's eager operations that split sequences and collections into subsequences separated by the specified separator element.
- [`windows(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Windows.md): Breaks a collection into overlapping subsequences where elements are slices from the original collection.
+1 -1
View File
@@ -9,7 +9,7 @@ collection until predicate returns `false` and skipping the remaining elements.
This example uses `suffix(while: )` to iterate through collection of integers
from the end until the predicate returns false, in this case when `$0 <= 5`
```swift
(0...10).suffix(while: { $0 > 5 } // == [6,7,8,9,10]
(0...10).suffix(while: { $0 > 5 }) // == [6,7,8,9,10]
```
## Detailed Design
+50 -29
View File
@@ -3,8 +3,8 @@
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Trim.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/TrimTests.swift)]
Returns a `SubSequence` formed by discarding all elements at the start and end
of the collection which satisfy the given predicate.
A group of methods that return the `SubSequence` formed by discarding elements
at the start and/or end of the collection which satisfy the given predicate.
This example uses `trimming(while:)` to get a substring without the white space
at the beginning and end of the string.
@@ -17,24 +17,44 @@ let results = [2, 10, 11, 15, 20, 21, 100].trimming(while: { $0.isMultiple(of: 2
print(results) // [11, 15, 20, 21]
```
The `Algorithms` library also includes methods that trim from each end,
as well as mutating versions of all three methods.
## Detailed Design
A new method is added to `BidirectionalCollection`:
New methods are added to `Collection` and `BidirectionalCollection`:
```swift
extension Collection {
func trimmingPrefix(while predicate: (Element) throws -> Bool) rethrows -> SubSequence
}
extension BidirectionalCollection {
public func trimming(while predicate: (Element) throws -> Bool) rethrows -> SubSequence
func trimmingSuffix(while predicate: (Element) throws -> Bool) rethrows -> SubSequence
func trimming(while predicate: (Element) throws -> Bool) rethrows -> SubSequence
}
extension Collection where Self: RangeReplaceableCollection {
mutating func trimPrefix(while predicate: (Element) throws -> Bool) rethrows
}
extension BidirectionalCollection where Self: RangeReplaceableCollection {
mutating func trimSuffix(while predicate: (Element) throws -> Bool) rethrows
mutating func trim(while predicate: (Element) throws -> Bool) rethrows
}
```
This method requires `BidirectionalCollection` for an efficient implementation
which visits as few elements as possible.
There are also overloads of the mutating methods when `Self == Self.SubSequence`,
for non-range-replaceable self-slicing types.
A less-efficient implementation is _possible_ for any `Collection`, which would
involve always traversing the entire collection. This implementation is not
provided, as it would mean developers of generic algorithms who forget to add
the `BidirectionalCollection` constraint will receive that inefficient
implementation:
Though the `trimming` and `trimmingSuffix` methods are declared on
`BidirectionalCollection`, a less-efficient implementation is _possible_ for
any `Collection`, which would involve always traversing the entire collection.
This implementation is not provided, as it would mean developers of generic
algorithms who forget to add the `BidirectionalCollection` constraint will
receive that inefficient implementation:
```swift
func myAlgorithm<Input>(input: Input) where Input: Collection {
@@ -50,28 +70,29 @@ Swift provides the `BidirectionalCollection` protocol for marking types which
support reverse traversal, and generic types and algorithms which want to make
use of that should add it to their constraints.
### >= 0.3.0
#### Supporting Methods
In `v0.3.0` new methods are added to allow discarding all the elements matching
the predicate at the beginning (prefix) or at the ending (suffix) of the
collection.
- `trimmingSuffix(while:)` can only be run on collections conforming to the
`BidirectionalCollection` protocol.
- `trimmingPrefix(while:)` can be run also on collections conforming to the
`Collection` protocol.
The `endOfPrefix(while:)` and `startOfSuffix(while:)` methods are used
in the implementation of the trimming methods described above. As these
supporting methods are independently useful, they are included in the library
as well.
```swift
let myString = " hello, world "
print(myString.trimmingPrefix(while: \.isWhitespace)) // "hello, world "
extension Collection {
/// Returns the exclusive upper bound of the prefix of elements that satisfy
/// the predicate.
func endOfPrefix(
while predicate: (Element) throws -> Bool
) rethrows -> Index
}
print(myString.trimmingSuffix(while: \.isWhitespace)) // " hello, world"
```
Also mutating variants for all the methods already existing and the new ones are
added.
```swift
var myString = " hello, world "
myString.trim(while: \.isWhitespace)
print(myString) // "hello, world"
extension BidirectionalCollection {
/// Returns the inclusive lower bound of the suffix of elements that satisfy
/// the predicate.
func startOfSuffix(
while predicate: (Element) throws -> Bool
) rethrows -> Index
}
```
### Complexity
+7 -2
View File
@@ -1,4 +1,4 @@
// swift-tools-version:5.4
// swift-tools-version:5.7
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms open source project
@@ -27,7 +27,12 @@ let package = Package(
name: "Algorithms",
dependencies: [
.product(name: "RealModule", package: "swift-numerics"),
]),
],
swiftSettings: [
.define("INSERTION_TEMP"),
// .define("INSERTION_MAX_32"),
]
),
.testTarget(
name: "SwiftAlgorithmsTests",
dependencies: ["Algorithms"]),
+26 -42
View File
@@ -2,55 +2,35 @@
**Swift Algorithms** is an open-source package of sequence and collection algorithms, along with their related types.
Read more about the package, and the intent behind it, in the [announcement on swift.org](https://swift.org/blog/swift-algorithms/).
## Overview
## Contents
The Algorithms package provides a variety of sequence and collection operations, letting you cycle over a collection's elements, find combinations and permutations, create a random sample, and more.
#### Combinations / permutations
For example, the package includes a group of "chunking" methods, each of which breaks a collection into consecutive subsequences. One version tests adjacent elements to find the breaking point between chunks — you can use it to quickly separate an array into ascending runs:
- [`combinations(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Combinations.md): Combinations of particular sizes of the elements in a collection.
- [`permutations(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Permutations.md): Permutations of a particular size of the elements in a collection, or of the full collection.
- [`uniquePermutations(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Permutations.md): Permutations of a collection's elements, skipping any duplicate permutations.
```swift
let numbers = [10, 20, 30, 10, 40, 40, 10, 20]
let chunks = numbers.chunked(by: { $0 <= $1 })
// [[10, 20, 30], [10, 40, 40], [10, 20]]
```
#### Mutating algorithms
Another version looks for a change in the transformation of each successive value. You can use that to separate a list of names into groups by the first character:
- [`rotate(toStartAt:)`, `rotate(subrange:toStartAt:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Rotate.md): In-place rotation of elements.
- [`stablePartition(by:)`, `stablePartition(subrange:by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Partition.md): A partition that preserves the relative order of the resulting prefix and suffix.
```swift
let names = ["Cassie", "Chloe", "Jasmine", "Jordan", "Taylor"]
let chunks = names.chunked(on: \.first)
// [["Cassie", "Chloe"], ["Jasmine", "Jordan"], ["Taylor"]]
```
#### Combining collections
Explore more chunking methods and the remainder of the `Algorithms` package in the links below.
- [`chain(_:_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md): Concatenates two collections with the same element type.
- [`cycled()`, `cycled(times:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Cycle.md): Repeats the elements of a collection forever or a set number of times.
- [`joined(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Joined.md): Concatenate sequences of sequences, using an element or sequence as a separator, or using a closure to generate each separator.
- [`product(_:_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Product.md): Iterates over all the pairs of two collections; equivalent to nested `for`-`in` loops.
## Documentation
#### Subsetting operations
For API documentation, see the library's official documentation in Xcode or on the Web.
- [`compacted()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Compacted.md): Drops the `nil`s from a sequence or collection, unwrapping the remaining elements.
- [`partitioned(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Partition.md): Returns the elements in a sequence or collection that do and do not match a given predicate.
- [`randomSample(count:)`, `randomSample(count:using:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/RandomSampling.md): Randomly selects a specific number of elements from a collection.
- [`randomStableSample(count:)`, `randomStableSample(count:using:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/RandomSampling.md): Randomly selects a specific number of elements from a collection, preserving their original relative order.
- [`striding(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Stride.md): Returns every nth element of a collection.
- [`suffix(while:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Suffix.md): Returns the suffix of a collection where all element pass a given predicate.
- [`trimmingPrefix(while:)`, `trimmingSuffix(while)`, `trimming(while:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Trim.md): Returns a slice by trimming elements from a collection's start, end, or both. The mutating `trim...` methods trim a collection in place.
- [`uniqued()`, `uniqued(on:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Unique.md): The unique elements of a collection, preserving their order.
- [`minAndMax()`, `minAndMax(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/MinMax.md): Returns the smallest and largest elements of a sequence.
#### Partial sorting
- [`min(count:)`, `max(count:)`, `min(count:sortedBy:)`, `max(count:sortedBy:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/MinMax.md): Returns the smallest or largest elements of a collection, sorted by a predicate.
#### Other useful operations
- [`adjacentPairs()`](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md): Lazily iterates over tuples of adjacent elements.
- [`chunked(by:)`, `chunked(on:)`, `chunks(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md): Eager and lazy operations that break a collection into chunks based on either a binary predicate or when the result of a projection changes or chunks of a given count.
- [`firstNonNil(_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/FirstNonNil.md): Returns the first non-`nil` result from transforming a sequence's elements.
- [`indexed()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Indexed.md): Iterate over tuples of a collection's indices and elements.
- [`interspersed(with:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Intersperse.md): Place a value between every two elements of a sequence.
- [`partitioningIndex(where:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Partition.md): Returns the starting index of the partition of a collection that matches a predicate.
- [`reductions(_:)`, `reductions(_:_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Reductions.md): Returns all the intermediate states of reducing the elements of a sequence or collection.
- [`split(maxSplits:omittingEmptySubsequences:whereSeparator)`, `split(separator:maxSplits:omittingEmptySubsequences)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Split.md): Lazy versions of the Standard Library's eager operations that split sequences and collections into subsequences separated by the specified separator element.
- [`windows(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Windows.md): Breaks a collection into overlapping subsequences where elements are slices from the original collection.
- [API documentation][docs]
- [Swift.org announcement][announcement]
- [API Proposals/Guides][guides]
## Adding Swift Algorithms as a Dependency
@@ -58,7 +38,7 @@ To use the `Algorithms` library in a SwiftPM project,
add the following line to the dependencies in your `Package.swift` file:
```swift
.package(url: "https://github.com/apple/swift-algorithms", from: "1.0.0"),
.package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
```
Include `"Algorithms"` as a dependency for your executable target:
@@ -75,8 +55,12 @@ Finally, add `import Algorithms` to your source code.
The Swift Algorithms package is source stable; version numbers follow [Semantic Versioning](https://semver.org/). Source breaking changes to public API can only land in a new major version.
The public API of version 1.0 of the `swift-algorithms` package consists of non-underscored declarations that are marked `public` in the `Algorithms` module. Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
The public API of the `swift-algorithms` package consists of non-underscored declarations that are marked `public` in the `Algorithms` module. Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
Future minor versions of the package may introduce changes to these rules as needed.
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. Requiring a new Swift release will only require a minor version bump.
[docs]: https://swiftpackageindex.com/apple/swift-algorithms/documentation/algorithms
[announcement]: https://swift.org/blog/swift-algorithms/
[guides]: https://github.com/apple/swift-algorithms/tree/main/Guides
+4
View File
@@ -78,6 +78,10 @@ public struct CombinationsSequence<Base: Collection> {
binomial(n: n, k: $0)
}.reduce(0, +)
}
/// The total number of combinations.
@inlinable
public var underestimatedCount: Int { count }
}
extension CombinationsSequence: Sequence {
@@ -33,6 +33,7 @@ Explore more chunking methods and the remainder of the Algorithms package, group
- <doc:Joining>
- <doc:Extending>
- <doc:Trimming>
- <doc:Keying>
- <doc:Sampling>
- <doc:MinAndMax>
- <doc:Selecting>
@@ -0,0 +1,14 @@
# Keying and Grouping
Convert a sequence to a dictionary, providing keys to individual elements or to use as grouping values.
## Topics
### Creating a Keyed Dictionary
- ``Swift/Sequence/keyed(by:)``
- ``Swift/Sequence/keyed(by:resolvingConflictsWith:)``
### Grouping Elements by Key
- ``Swift/Sequence/grouped(by:)``
@@ -16,7 +16,7 @@ or a specific number of elements at the minimum and maximum.
- ``Swift/Sequence/max(count:sortedBy:)``
- ``Swift/Collection/max(count:sortedBy:)``
### Finding the Minimum and Maximum Elements Simulataneously
### Finding the Minimum and Maximum Elements Simultaneously
- ``Swift/Sequence/minAndMax()``
- ``Swift/Sequence/minAndMax(by:)``
@@ -25,3 +25,8 @@ Remove unwanted elements from the start, the end, or both ends of a collection.
### Finding the Suffix of a Collection
- ``Swift/BidirectionalCollection/suffix(while:)``
### Finding Boundaries within a Collection
- ``Swift/Collection/endOfPrefix(while:)``
- ``Swift/BidirectionalCollection/startOfSuffix(while:)``
+25
View File
@@ -0,0 +1,25 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms 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 Sequence {
/// Groups up elements of `self` into a new Dictionary,
/// whose values are Arrays of grouped elements,
/// each keyed by the group key returned by the given closure.
/// - Parameters:
/// - keyForValue: A closure that returns a key for each element in
/// `self`.
/// - Returns: A dictionary containing grouped elements of self, keyed by
/// the keys derived by the `keyForValue` closure.
@inlinable
public func grouped<GroupKey>(by keyForValue: (Element) throws -> GroupKey) rethrows -> [GroupKey: [Element]] {
try Dictionary(grouping: self, by: keyForValue)
}
}
+65
View File
@@ -0,0 +1,65 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 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 Sequence {
/// Creates a new Dictionary from the elements of `self`, keyed by the
/// results returned by the given `keyForValue` closure.
///
/// If the key derived for a new element collides with an existing key from a previous element,
/// the latest value will be kept.
///
/// - Parameters:
/// - keyForValue: A closure that returns a key for each element in `self`.
@inlinable
public func keyed<Key>(
by keyForValue: (Element) throws -> Key
) rethrows -> [Key: Element] {
return try self.keyed(by: keyForValue, resolvingConflictsWith: { _, old, new in new })
}
/// Creates a new Dictionary from the elements of `self`, keyed by the
/// results returned by the given `keyForValue` closure. As the dictionary is
/// built, the initializer calls the `resolve` closure with the current and
/// new values for any duplicate keys. Pass a closure as `resolve` 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.
///
/// - Parameters:
/// - keyForValue: A closure that returns a key for each element in `self`.
/// - resolve: 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.
@inlinable
public func keyed<Key>(
by keyForValue: (Element) throws -> Key,
resolvingConflictsWith resolve: (Key, Element, Element) throws -> Element
) rethrows -> [Key: Element] {
var result = [Key: Element]()
for element in self {
let key = try keyForValue(element)
if let oldValue = result.updateValue(element, forKey: key) {
let valueToKeep = try resolve(key, oldValue, element)
// This causes a second look-up for the same key. The standard library can avoid that
// by calling `mutatingFind` to get access to the bucket where the value will end up,
// and updating in place.
// Swift Algorithms doesn't have access to that API, so we make do.
// When this gets merged into the standard library, we should optimize this.
result[key] = valueToKeep
}
}
return result
}
}
+10 -10
View File
@@ -256,13 +256,13 @@ extension Collection {
"""
)
// Do nothing if we're prefixing nothing.
guard count > 0 else {
return []
}
// Make sure we are within bounds.
let prefixCount = Swift.min(count, self.count)
// Do nothing if we're prefixing nothing.
guard prefixCount > 0 else {
return []
}
// If we're attempting to prefix more than 10% of the collection, it's
// faster to sort everything.
@@ -310,13 +310,13 @@ extension Collection {
"""
)
// Do nothing if we're suffixing nothing.
guard count > 0 else {
return []
}
// Make sure we are within bounds.
let suffixCount = Swift.min(count, self.count)
// Do nothing if we're suffixing nothing.
guard suffixCount > 0 else {
return []
}
// If we're attempting to prefix more than 10% of the collection, it's
// faster to sort everything.
+539
View File
@@ -0,0 +1,539 @@
extension Int {
@inlinable
internal var _log2: Int {
Self.bitWidth - leadingZeroBitCount
}
}
@inlinable internal var _partialInsertionSortSwapLimit: Int { 8 }
@inlinable internal var _insertionSortMaxCount: Int {
#if INSERTION_MAX_32
32
#else
20
#endif
}
@inlinable internal var _medianOfMediansMinCount: Int { 200 }
extension MutableCollection where Self: BidirectionalCollection {
@inlinable
internal mutating func _partialInsertionSort(
within range: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> Bool {
if range.isEmpty {
return true
}
var sortedEnd = index(after: range.lowerBound)
var swaps = 0
// Continue sorting until the sorted elements cover the whole sequence.
while sortedEnd != range.upperBound {
var i = sortedEnd
// Look backwards for `self[i]`'s position in the sorted sequence,
// moving each element forward to make room.
repeat {
let j = index(before: i)
// If `self[i]` doesn't belong before `self[j]`, we've found
// its position.
if try !areInIncreasingOrder(self[i], self[j]) {
break
}
swapAt(i, j)
i = j
// Quit if we've completed more than the swap limit.
swaps += 1
if swaps > _partialInsertionSortSwapLimit { return false }
} while i != range.lowerBound
formIndex(after: &sortedEnd)
}
return true
}
/// Sorts `self[range]` according to `areInIncreasingOrder`. Stable.
///
/// - Precondition: `sortedEnd != range.lowerBound`
/// - Precondition: `elements[..<sortedEnd]` are already in order.
@inlinable
public
mutating func _insertionSort(
within range: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
if range.isEmpty {
return
}
var sortedEnd = index(after: range.lowerBound)
// Continue sorting until the sorted elements cover the whole sequence.
while sortedEnd != range.upperBound {
var i = sortedEnd
#if INSERTION_TEMP
let temp = self[i]
#endif
// Look backwards for `self[i]`'s position in the sorted sequence,
// moving each element forward to make room.
repeat {
let j = index(before: i)
// If `self[i]` doesn't belong before `self[j]`, we've found
// its position.
#if INSERTION_TEMP
if try !areInIncreasingOrder(temp, self[j]) {
break
}
self[j] = self[i]
#else
if try !areInIncreasingOrder(self[i], self[j]) {
break
}
swapAt(i, j)
#endif
i = j
} while i != range.lowerBound
#if INSERTION_TEMP
self[i] = temp
#endif
formIndex(after: &sortedEnd)
}
}
@inlinable
internal mutating func _sort2(
_ a: Index, _ b: Index,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
if try areInIncreasingOrder(self[b], self[a]) {
swapAt(a, b)
}
}
@inlinable
internal mutating func _sort3a(
_ a: Index, _ b: Index, _ c: Index,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
try _sort2(a, b, by: areInIncreasingOrder)
try _sort2(b, c, by: areInIncreasingOrder)
try _sort2(a, b, by: areInIncreasingOrder)
}
/// Sorts the elements at `elements[a]`, `elements[b]`, and `elements[c]` to
/// match the relative order of `a`, `b`, and `c`.
@inlinable
internal mutating func _sort3(
_ a: Index, _ b: Index, _ c: Index,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
// There are thirteen possible permutations for the original ordering of
// the elements at indices `a`, `b`, and `c`. The comments in the code below
// show the relative ordering of the three elements using a three-digit
// number as shorthand for the position and comparative relationship of
// each element. For example, "312" indicates that the element at `a` is the
// largest of the three, the element at `b` is the smallest, and the element
// at `c` is the median. This hypothetical input array has a 312 ordering for
// `a`, `b`, and `c`:
//
// [ 7, 4, 3, 9, 2, 0, 3, 7, 6, 5 ]
// ^ ^ ^
// a b c
//
// - If each of the three elements is distinct, they could be ordered as any
// of the permutations of 1, 2, and 3: 123, 132, 213, 231, 312, or 321.
// - If two elements are equivalent and one is distinct, they could be
// ordered as any permutation of 1, 1, and 2 or 1, 2, and 2: 112, 121, 211,
// 122, 212, or 221.
// - If all three elements are equivalent, they are already in order: 111.
switch try (areInIncreasingOrder(self[b], self[a]),
areInIncreasingOrder(self[c], self[b])) {
case (false, false):
// 0 swaps: 123, 112, 122, 111
break
case (true, true):
// 1 swap: 321
// swap(a, c): 312->123
swapAt(a, c)
case (true, false):
// 1 swap: 213, 212 --- 2 swaps: 312, 211
// swap(a, b): 213->123, 212->122, 312->132, 211->121
swapAt(a, b)
if try areInIncreasingOrder(self[c], self[b]) {
// 132 (started as 312), 121 (started as 211)
// swap(b, c): 132->123, 121->112
swapAt(b, c)
}
case (false, true):
// 1 swap: 132, 121 --- 2 swaps: 231, 221
// swap(b, c): 132->123, 121->112, 231->213, 221->212
swapAt(b, c)
if try areInIncreasingOrder(self[b], self[a]) {
// 213 (started as 231), 212 (started as 221)
// swap(a, b): 213->123, 212->122
swapAt(a, b)
}
}
}
}
extension MutableCollection where Self: RandomAccessCollection {
@inlinable
internal mutating func _siftDown(
_ idx: Index,
within range: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
var idx = idx
var countToIndex = distance(from: range.lowerBound, to: idx)
var countFromIndex = distance(from: idx, to: range.upperBound)
// Check if left child is within bounds. If not, stop iterating, because
// there are no children of the given node in the heap.
while countToIndex + 1 < countFromIndex {
let left = index(idx, offsetBy: countToIndex + 1)
var largest = idx
if try areInIncreasingOrder(self[largest], self[left]) {
largest = left
}
// Check if right child is also within bounds before trying to examine it.
if countToIndex + 2 < countFromIndex {
let right = index(after: left)
if try areInIncreasingOrder(self[largest], self[right]) {
largest = right
}
}
// If a child is bigger than the current node, swap them and continue
// sifting down.
if largest != idx {
swapAt(idx, largest)
idx = largest
countToIndex = distance(from: range.lowerBound, to: idx)
countFromIndex = distance(from: idx, to: range.upperBound)
} else {
break
}
}
}
@inlinable
internal mutating func _heapify(
within range: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
// Here we build a heap starting from the lowest nodes and moving to the
// root. On every step we sift down the current node to obey the max-heap
// property:
// parent >= max(leftChild, rightChild)
//
// We skip the rightmost half of the array, because these nodes don't have
// any children.
let root = range.lowerBound
let half = distance(from: range.lowerBound, to: range.upperBound) / 2
var node = index(root, offsetBy: half)
while node != root {
formIndex(before: &node)
try _siftDown(node, within: range, by: areInIncreasingOrder)
}
}
@inlinable
internal mutating func _heapSort(
within range: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
var hi = range.upperBound
let lo = range.lowerBound
try _heapify(within: range, by: areInIncreasingOrder)
formIndex(before: &hi)
while hi != lo {
swapAt(lo, hi)
try _siftDown(lo, within: lo..<hi, by: areInIncreasingOrder)
formIndex(before: &hi)
}
}
}
extension MutableCollection where Self: BidirectionalCollection {
@inlinable
public // testing
mutating func _partitionLeft(
subrange: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> Index {
assert(distance(from: subrange.lowerBound, to: subrange.upperBound) >= 2)
var (low, high) = (subrange.lowerBound, subrange.upperBound)
let pivot = self[subrange.lowerBound]
// Search from end for last element equal to or less than pivot.
repeat {
formIndex(before: &high)
// Don't need a separate `high > low` check, since self[low] == pivot,
// which is a terminating condition based on comparison above.
} while try areInIncreasingOrder(pivot, self[high])
// Search from beginning for first element greater than pivot.
if high == index(before: subrange.upperBound) {
while low < high {
formIndex(after: &low)
guard try !areInIncreasingOrder(pivot, self[low]) else {
break
}
}
} else {
repeat {
formIndex(after: &low)
} while try !areInIncreasingOrder(pivot, self[low])
}
// Swap remaining elements as needed.
while low < high {
swapAt(low, high)
repeat {
formIndex(before: &high)
} while try areInIncreasingOrder(pivot, self[high])
repeat {
formIndex(after: &low)
} while try !areInIncreasingOrder(pivot, self[low])
}
// Move pivot to end of lower partition and return its position.
swapAt(subrange.lowerBound, high)
return high
}
@inlinable
public // testing
mutating func _partitionRight(
subrange: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> (Index, alreadyPartitioned: Bool) {
assert(distance(from: subrange.lowerBound, to: subrange.upperBound) >= 2)
var (low, high) = (subrange.lowerBound, subrange.upperBound)
let pivot = self[subrange.lowerBound]
// Search from start for first element greater than or equal to pivot.
repeat {
formIndex(after: &low)
} while try areInIncreasingOrder(self[low], pivot)
// Search from end for last element less than pivot.
if low == index(after: subrange.lowerBound) {
while low < high {
formIndex(before: &high)
guard try !areInIncreasingOrder(self[high], pivot) else {
break
}
}
} else {
repeat {
formIndex(before: &high)
} while try !areInIncreasingOrder(self[high], pivot)
}
let noSwapsRequired = low >= high
// Swap remaining elements as needed.
while low < high {
swapAt(low, high)
repeat {
formIndex(after: &low)
} while try areInIncreasingOrder(self[low], pivot)
repeat {
formIndex(before: &high)
} while try !areInIncreasingOrder(self[high], pivot)
}
// Move pivot to start of upper partition and return its position.
let result = index(before: low)
swapAt(subrange.lowerBound, result)
return (result, noSwapsRequired)
}
}
extension MutableCollection where Self: RandomAccessCollection {
@inlinable
public // testing
mutating func _preparePivot(
subrange: Range<Index>,
count: Int,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
let low = subrange.lowerBound
let high = index(before: subrange.upperBound)
let mid = index(low, offsetBy: count / 2)
if count > _medianOfMediansMinCount {
// Sort three "letter groups" of elements:
// [A1, B1, C1, ..., A2, B2, C2, ..., C3, B3, A3]
let low2 = index(after: low)
let high2 = index(before: high)
let midLo = index(before: mid)
let midHi = index(after: mid)
try _sort3(low, midLo, high, by: areInIncreasingOrder)
try _sort3(low2, mid, high2, by: areInIncreasingOrder)
try _sort3(
index(after: low2), midHi, index(before: high2),
by: areInIncreasingOrder)
// After sorting, each lettered group of elements is sorted, so the
// middle three elements are the three medians. Sort those three.
try _sort3(midLo, mid, midHi, by: areInIncreasingOrder)
// The median of medians is the pivot; move it to the front.
swapAt(low, mid)
} else {
// Note the order of index parameters; the smallest element will be at `mid`,
// the middle element at `low`, and the largest element at `high`:
try _sort3(mid, low, high, by: areInIncreasingOrder)
}
}
@inlinable
internal mutating func _shuffleElements(subrange: Range<Index>, count: Int) {
guard count > _insertionSortMaxCount else { return }
var low = subrange.lowerBound
var lowQuarter = index(low, offsetBy: count / 4)
var high = index(before: subrange.upperBound)
var highQuarter = index(high, offsetBy: -count / 4)
swapAt(low, lowQuarter)
swapAt(high, highQuarter)
if count > _insertionSortMaxCount {
for _ in 0..<2 {
formIndex(after: &low)
formIndex(before: &lowQuarter)
formIndex(before: &high)
formIndex(after: &highQuarter)
swapAt(low, lowQuarter)
swapAt(high, highQuarter)
}
}
}
@inlinable
internal mutating func _pdqSortImpl(
subrange: Range<Index>,
count: Int,
isLeftmost: Bool,
remainingBadPartitions: Int,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
guard count > _insertionSortMaxCount else {
try _insertionSort(within: subrange, by: areInIncreasingOrder)
return
}
try _preparePivot(subrange: subrange, count: count, by: areInIncreasingOrder)
if !isLeftmost {
let predecessor = index(before: subrange.lowerBound)
if try !areInIncreasingOrder(self[predecessor], self[subrange.lowerBound]) {
let newLow = try _partitionLeft(subrange: subrange, by: areInIncreasingOrder)
try _pdqSortImpl(
subrange: newLow..<subrange.upperBound,
count: distance(from: newLow, to: subrange.upperBound),
isLeftmost: false,
remainingBadPartitions: remainingBadPartitions,
by: areInIncreasingOrder)
return
}
}
let (pivot, alreadyPartitioned) = try _partitionRight(
subrange: subrange, by: areInIncreasingOrder)
let startOfUpper = index(after: pivot)
let lowerCount = distance(from: subrange.lowerBound, to: pivot)
let upperCount = count - lowerCount - 1
let minPartitionSize = count / 8
let isBadPartition = lowerCount < minPartitionSize || upperCount < minPartitionSize
var remainingBadPartitions = remainingBadPartitions
if isBadPartition {
// If we've had too many bad partitions, fall back to heap sort.
remainingBadPartitions -= 1
guard remainingBadPartitions > 0 else {
try _heapSort(within: subrange, by: areInIncreasingOrder)
return
}
// Try shuffling elements within the partition to decrease chance of poor
// pivot selection.
_shuffleElements(subrange: subrange.lowerBound..<pivot, count: lowerCount)
_shuffleElements(subrange: startOfUpper..<subrange.upperBound, count: upperCount)
} else {
// If there were no swaps required, use insertion sort to scan for already
// sorted partitions, including some minor fix-ups.
if alreadyPartitioned {
if try _partialInsertionSort(within: subrange.lowerBound..<pivot, by: areInIncreasingOrder)
&& _partialInsertionSort(within: startOfUpper..<subrange.upperBound, by: areInIncreasingOrder) {
return
}
}
}
try _pdqSortImpl(
subrange: subrange.lowerBound..<pivot,
count: lowerCount,
isLeftmost: isLeftmost,
remainingBadPartitions: remainingBadPartitions,
by: areInIncreasingOrder)
try _pdqSortImpl(
subrange: startOfUpper..<subrange.upperBound,
count: upperCount,
isLeftmost: false,
remainingBadPartitions: remainingBadPartitions,
by: areInIncreasingOrder)
}
@inlinable
public mutating func sortUnstable(
subrange: Range<Index>,
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
let count = distance(from: subrange.lowerBound, to: subrange.upperBound)
try _pdqSortImpl(
subrange: subrange,
count: count,
isLeftmost: true,
remainingBadPartitions: count._log2,
by: areInIncreasingOrder)
}
@inlinable
public mutating func sortUnstable(
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows {
try sortUnstable(subrange: startIndex..<endIndex, by: areInIncreasingOrder)
}
}
extension MutableCollection where Self: RandomAccessCollection, Element: Comparable {
@inlinable
public mutating func sortUnstable(subrange: Range<Index>) {
sortUnstable(subrange: subrange, by: <)
}
@inlinable
public mutating func sortUnstable() {
sortUnstable(by: <)
}
}
+10 -6
View File
@@ -210,8 +210,8 @@ extension Collection {
//===----------------------------------------------------------------------===//
extension Sequence {
/// Returns two arrays containing, in order, the elements of the sequence that
/// do and don’t satisfy the given predicate.
/// Returns two arrays containing the elements of the sequence that
/// don’t and do satisfy the given predicate, respectively.
///
/// In this example, `partitioned(by:)` is used to separate the input based on
/// whether a name is shorter than five characters:
@@ -230,7 +230,9 @@ extension Sequence {
///
/// - Returns: Two arrays with all of the elements of the receiver. The
/// first array contains all the elements that `predicate` didn’t allow, and
/// the second array contains all the elements that `predicate` allowed.
/// the second array contains all the elements that `predicate` allowed. The
/// order of the elements in the arrays matches the order of the elements in
/// the original sequence.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
@inlinable
@@ -253,8 +255,8 @@ extension Sequence {
}
extension Collection {
/// Returns two arrays containing, in order, the elements of the collection
/// that do and don’t satisfy the given predicate.
/// Returns two arrays containing the elements of the collection that
/// don’t and do satisfy the given predicate, respectively.
///
/// In this example, `partitioned(by:)` is used to separate the input based on
/// whether a name is shorter than five characters.
@@ -273,7 +275,9 @@ extension Collection {
///
/// - Returns: Two arrays with all of the elements of the receiver. The
/// first array contains all the elements that `predicate` didn’t allow, and
/// the second array contains all the elements that `predicate` allowed.
/// the second array contains all the elements that `predicate` allowed. The
/// order of the elements in the arrays matches the order of the elements in
/// the original collection.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
+6
View File
@@ -10,8 +10,14 @@
//===----------------------------------------------------------------------===//
// For log(_:) and root(_:_:)
#if swift(>=5.11)
internal import RealModule
#elseif swift(>=5.10)
import RealModule
#else
@_implementationOnly
import RealModule
#endif
//===----------------------------------------------------------------------===//
// randomStableSample(count:)
+1 -1
View File
@@ -512,7 +512,7 @@ extension SplitCollection: Collection {
var subsequenceStart = i.baseRange.upperBound
if subsequenceStart < base.endIndex {
// If we're not already at the end of the base collection, the previous
// susequence ended with a separator. Start searching for the next
// subsequence ended with a separator. Start searching for the next
// subsequence at the following element.
subsequenceStart = base.index(after: i.baseRange.upperBound)
}
+2 -2
View File
@@ -46,7 +46,7 @@ extension Collection {
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
internal func endOfPrefix(
public func endOfPrefix(
while predicate: (Element) throws -> Bool
) rethrows -> Index {
var index = startIndex
@@ -72,7 +72,7 @@ extension BidirectionalCollection {
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
internal func startOfSuffix(
public func startOfSuffix(
while predicate: (Element) throws -> Bool
) rethrows -> Index {
var index = endIndex
+6 -6
View File
@@ -32,7 +32,7 @@ extension Collection {
while predicate: (Element) throws -> Bool
) rethrows -> SubSequence {
let start = try endOfPrefix(while: predicate)
return self[start...]
return self[start..<endIndex]
}
}
@@ -61,8 +61,8 @@ extension Collection where Self: RangeReplaceableCollection {
public mutating func trimPrefix(
while predicate: (Element) throws -> Bool
) rethrows {
let end = try endOfPrefix(while: predicate)
removeSubrange(startIndex..<end)
let startOfResult = try endOfPrefix(while: predicate)
removeSubrange(startIndex..<startOfResult)
}
}
@@ -135,7 +135,7 @@ extension BidirectionalCollection {
while predicate: (Element) throws -> Bool
) rethrows -> SubSequence {
let end = try startOfSuffix(while: predicate)
return self[..<end]
return self[startIndex..<end]
}
}
@@ -188,8 +188,8 @@ extension BidirectionalCollection where Self: RangeReplaceableCollection {
public mutating func trimSuffix(
while predicate: (Element) throws -> Bool
) rethrows {
let start = try startOfSuffix(while: predicate)
removeSubrange(start..<endIndex)
let endOfResult = try startOfSuffix(while: predicate)
removeSubrange(endOfResult..<endIndex)
}
}
@@ -15,57 +15,63 @@ import Algorithms
final class CombinationsTests: XCTestCase {
func testCount() {
let c = "ABCD"
let c0 = c.combinations(ofCount: 0).count
XCTAssertEqual(c0, 1)
let c1 = c.combinations(ofCount: 1).count
XCTAssertEqual(c1, 4)
let c2 = c.combinations(ofCount: 2).count
XCTAssertEqual(c2, 6)
let c3 = c.combinations(ofCount: 3).count
XCTAssertEqual(c3, 4)
let c4 = c.combinations(ofCount: 4).count
XCTAssertEqual(c4, 1)
let c5 = c.combinations(ofCount: 0...0).count
XCTAssertEqual(c5, 1)
let c6 = c.combinations(ofCount: 1...1).count
XCTAssertEqual(c6, 4)
let c7 = c.combinations(ofCount: 1...2).count
XCTAssertEqual(c7, 10)
let c8 = c.combinations(ofCount: 1...3).count
XCTAssertEqual(c8, 14)
let c9 = c.combinations(ofCount: 2...4).count
XCTAssertEqual(c9, 11)
/// XCTAsserts that `x`'s `count` and `underestimatedCount` are both `l` at
/// the given `file` and `line`.
func check(
_ x: CombinationsSequence<String>, countsAre l: Int,
file: StaticString, line: UInt)
{
XCTAssertEqual(x.count, l, "unexpected count", file: file, line: line)
XCTAssertEqual(
x.underestimatedCount, l, "unexpected underestimatedCount",
file: file, line: line)
}
/// XCTAsserts that the `count` and `underestimatedCount` of
/// `c.combinations(ofCount: l)` are both `n` at the given `file` and
/// `line`.
func check(
cHas n: Int,
combinationsOfLength l: Int,
file: StaticString = #filePath, line: UInt = #line)
{
check(c.combinations(ofCount: l), countsAre: n, file: file, line: line)
}
/// XCTAsserts that the `count` and `underestimatedCount` of
/// `c.combinations(ofCount: l)` are both `n` at the given `file` and
/// `line`.
func check<R: RangeExpression>(
cHas n: Int,
combinationsOfLengths l: R,
file: StaticString = #filePath, line: UInt = #line) where R.Bound == Int
{
check(c.combinations(ofCount: l), countsAre: n, file: file, line: line)
}
check(cHas: 1, combinationsOfLength: 0)
check(cHas: 4, combinationsOfLength: 1)
check(cHas: 6, combinationsOfLength: 2)
check(cHas: 1, combinationsOfLength: 4)
check(cHas: 1, combinationsOfLengths: 0...0)
check(cHas: 4, combinationsOfLengths: 1...1)
check(cHas: 10, combinationsOfLengths: 1...2)
check(cHas: 14, combinationsOfLengths: 1...3)
check(cHas: 11, combinationsOfLengths: 2...4)
// `k` greater than element count results in same number of combinations
check(cHas: 5, combinationsOfLengths: 3...10)
// `k` greater than element count results in same number of combinations
let c10 = c.combinations(ofCount: 3...10).count
XCTAssertEqual(c10, 5)
// `k` greater than element count results in same number of combinations
let c11 = c.combinations(ofCount: 4...10).count
XCTAssertEqual(c11, 1)
check(cHas: 1, combinationsOfLengths: 4...10)
// `k` entirely greater than element count results in no combinations
let c12 = c.combinations(ofCount: 5...10).count
XCTAssertEqual(c12, 0)
check(cHas: 0, combinationsOfLengths: 5...10)
let c13 = c.combinations(ofCount: 0...).count
XCTAssertEqual(c13, 16)
let c14 = c.combinations(ofCount: ...3).count
XCTAssertEqual(c14, 15)
let c15 = c.combinations(ofCount: 0...).count
XCTAssertEqual(c15, 16)
check(cHas: 16, combinationsOfLengths: 0...)
check(cHas: 15, combinationsOfLengths: ...3)
}
func testCombinations() {
@@ -0,0 +1,46 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 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 Algorithms
final class GroupedTests: XCTestCase {
private class SampleError: Error {}
// Based on https://github.com/apple/swift/blob/4d1d8a9de5ebc132a17aee9fc267461facf89bf8/validation-test/stdlib/Dictionary.swift#L1974-L1988
func testGroupedBy() {
let r = 0..<10
let d1 = r.grouped(by: { $0 % 3 })
XCTAssertEqual(3, d1.count)
XCTAssertEqual(d1[0]!, [0, 3, 6, 9])
XCTAssertEqual(d1[1]!, [1, 4, 7])
XCTAssertEqual(d1[2]!, [2, 5, 8])
let d2 = r.grouped(by: { $0 })
XCTAssertEqual(10, d2.count)
let d3 = (0..<0).grouped(by: { $0 })
XCTAssertEqual(0, d3.count)
}
func testThrowingFromKeyFunction() {
let input = ["Apple", "Banana", "Cherry"]
let error = SampleError()
XCTAssertThrowsError(
try input.grouped(by: { (_: String) -> Character in throw error })
) { thrownError in
XCTAssertIdentical(error, thrownError as? SampleError)
}
}
}
@@ -0,0 +1,88 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 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 Algorithms
final class KeyedTests: XCTestCase {
private class SampleError: Error {}
func testUniqueKeys() {
let d = ["Apple", "Banana", "Cherry"].keyed(by: { $0.first! })
XCTAssertEqual(d.count, 3)
XCTAssertEqual(d["A"]!, "Apple")
XCTAssertEqual(d["B"]!, "Banana")
XCTAssertEqual(d["C"]!, "Cherry")
XCTAssertNil(d["D"])
}
func testEmpty() {
let d = EmptyCollection<String>().keyed(by: { $0.first! })
XCTAssertEqual(d.count, 0)
}
func testNonUniqueKeys() throws {
let d = ["Apple", "Avocado", "Banana", "Cherry"].keyed(by: { $0.first! })
XCTAssertEqual(d.count, 3)
XCTAssertEqual(d["A"]!, "Avocado", "On a key-collision, keyed(by:) should take the latest value.")
XCTAssertEqual(d["B"]!, "Banana")
XCTAssertEqual(d["C"]!, "Cherry")
}
func testNonUniqueKeysWithMergeFunction() {
var resolveCallHistory = [(key: Character, current: String, new: String)]()
let expectedCallHistory = [
(key: "A", current: "Apple", new: "Avocado"),
(key: "C", current: "Cherry", new: "Coconut"),
]
let d = ["Apple", "Avocado", "Banana", "Cherry", "Coconut"].keyed(
by: { $0.first! },
resolvingConflictsWith: { key, older, newer in
resolveCallHistory.append((key, older, newer))
return "\(older)-\(newer)"
}
)
XCTAssertEqual(d.count, 3)
XCTAssertEqual(d["A"]!, "Apple-Avocado")
XCTAssertEqual(d["B"]!, "Banana")
XCTAssertEqual(d["C"]!, "Cherry-Coconut")
XCTAssertNil(d["D"])
XCTAssertEqual(
resolveCallHistory.map(String.init(describing:)), // quick/dirty workaround: tuples aren't Equatable
expectedCallHistory.map(String.init(describing:))
)
}
func testThrowingFromKeyFunction() {
let input = ["Apple", "Banana", "Cherry"]
let error = SampleError()
XCTAssertThrowsError(
try input.keyed(by: { (_: String) -> Character in throw error })
) { thrownError in
XCTAssertIdentical(error, thrownError as? SampleError)
}
}
func testThrowingFromCombineFunction() {
let input = ["Apple", "Avocado", "Banana", "Cherry"]
let error = SampleError()
XCTAssertThrowsError(
try input.keyed(by: { $0.first! }, resolvingConflictsWith: { _, _, _ in throw error })
) { thrownError in
XCTAssertIdentical(error, thrownError as? SampleError)
}
}
}
@@ -0,0 +1,68 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 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 Algorithms
final class PDQSortTests: XCTestCase {
func testPartitionLeft() {
for _ in 1...1000 {
var a = (0...20).map { _ in Int.random(in: 1...5) }
a._preparePivot(subrange: a.indices, count: a.indices.count, by: <)
let pivot = a._partitionLeft(subrange: a.indices, by: <)
for x in a[..<pivot] {
XCTAssertLessThanOrEqual(x, a[pivot])
}
for x in a[(pivot + 1)...] {
XCTAssertGreaterThan(x, a[pivot])
}
}
}
func testPartitionRight() {
for _ in 1...1000 {
var a = (0...20).map { _ in Int.random(in: 1...5) }
a._preparePivot(subrange: a.indices, count: a.indices.count, by: <)
let (pivot, _) = a._partitionRight(subrange: a.indices, by: <)
for x in a[..<pivot] {
XCTAssertLessThan(x, a[pivot])
}
for x in a[(pivot + 1)...] {
XCTAssertGreaterThanOrEqual(x, a[pivot])
}
}
}
func testSort() {
var empty: [Int] = []
empty.sortUnstable()
var inOrder = Array(1...1000)
inOrder.sortUnstable()
XCTAssert(inOrder.isSorted())
var reversed = Array((1...1000).reversed())
reversed.sortUnstable()
XCTAssert(reversed.isSorted())
for _ in 1...1000 {
var a = (0...Int.random(in: 100...1000)).map { _ in Int.random(in: 1...50) }
a.sortUnstable()
XCTAssert(a.isSorted())
}
}
func testSpecialCase() {
var a = (1...10).shuffled() + [20] + (31...40).shuffled()
a.sortUnstable()
XCTAssert(a.isSorted())
}
}
+1 -1
View File
@@ -10,7 +10,7 @@
//===----------------------------------------------------------------------===//
import XCTest
@testable import Algorithms
import Algorithms
final class SuffixTests: XCTestCase {
func testSuffix() {
@@ -216,7 +216,7 @@ extension IndexValidator {
/// - expectedCount:
///
/// - Complexity: O(*n*^3) where *n* is the length of the collection if the
/// collection conforms to `RandomAccesCollection`, otherwise O(*n*^4).
/// collection conforms to `RandomAccessCollection`, otherwise O(*n*^4).
func validate(
_ collection: C,
expectedCount: Int? = nil,