Compare commits

...
136 Commits
Author SHA1 Message Date
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
Nate Cook bcd4f369ac Update changelog for 1.1.0 release (#206) 2023-10-05 14:45:17 -05:00
Nate Cook 4f53c9cf40 Finish sub-page documentation updates (#204)
* Finish sub-page documentation updates

Some of these pages could use introductions, but the current state is
ready for publication.

* Add SPI yaml file for building docs
2023-10-05 13:10:03 -05:00
Nate Cook 0d6f943832 Increase the package version to 5.4 (#205)
The latest Swift versions appear to have a problem with the
LinuxMain.swift again, which we haven't needed for quite some time.
Linux test autodiscovery has been enabled since 5.4, so we can
update to that version and drop the file.
2023-10-05 13:03:25 -05:00
Nate Cook fc8fdfd4dc Curate documentation for Algorithms module (#201) 2023-08-24 14:17:38 -05:00
Matt Zanchelli bfcaaa8758 Correct Chunked documentation (#182)
* Clarify that the determining factor for being grouped is equality (`Equatable`), which doesn’t necessarily mean the _same_ value (identity)
* Correct algorithmic complexity documentation on the lazy Chunked functions
* Document `belongInSameGroup` and `projection`
2023-08-02 10:18:17 -05:00
Nate Cook 0f81ef4a70 Chunked type / documentation cleanup (#200)
This change improves the documentation for `evenlyChunked(in:)` and
`chunks(ofCount:)` and renames `EvenChunksCollection` to
`EvenlyChunkedCollection` to follow the pattern of wrapper type
names matching their producing functions.
2023-07-26 13:15:35 -05:00
Tim VermeulenandTim Vermeulen de3efbc567 Evenly divide a collection into chunks (#96)
Adds `evenlyChunked(in:)` as a `Collection` method that divides a
collection into a specific number of chunks as evenly as possible.

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>
2023-07-26 11:17:25 -05:00
Gwynne Raskind df51f1780b Specify dependency URL in consistent fashion (#194) 2023-07-03 15:15:33 -05:00
Matt Dickoff 288d8b00f2 Merge pull request #191 from dickoff/dickoff/fix-max-code-documentation
Corrects variable name in documentation for max functions to better reflect usage
2022-12-07 13:27:05 -06:00
Matt Dickoff aa6349dea0 Corrects variable name in max functions to better reflect usage
The variable smallestThree should really be named largestThree. Looks
like this was originally a copy paste error from the min documentation.
2022-12-01 11:37:32 -06:00
Matt ZanchelliandMatt Zanchelli 195e0316d7 Update comments in Chunked.swift (#179)
* Use back ticks around code references

* Add missing spaces before parenthesis

* Use “passed” instead of “past”
Add missing comma
Add back ticks around code references
Add missing space before parenthesis

* Consistently use spaces around `%` operator

Co-authored-by: Matt Zanchelli <mattt@apple.com>
2022-02-23 13:07:19 -06:00
Matt Zanchelli da475ea9af Clarify endIndex behavior of partitioningIndex(where:) in documentation (Resolves #170) (#171)
The returned index isn’t necessarily an index of an element. In the case where it returns `endIndex`, it’s not valid for subscripting the collection.
2021-12-16 07:10:17 -06:00
Matt Zanchelli 19c1d00177 Remove the last element before determining the insertion index (#173)
This could result in fewer comparisons.

Additionally, it ensures that the insertion index is valid for insertion. The `removeLast()` documentation states:
> Calling this method may invalidate all saved indices of this collection. Do not rely on a previously stored index value after altering a collection with any operation that can change its length.
2021-12-04 00:25:02 -06:00
e2fa131d62 Add partitioned(by:) (#152)
* Add `partitioned(_:)`

`partitioned(_:)` works like `filter(_:)`, but also returns the excluded elements by returning a tuple of two `Array`s

* For collections with fewer than 8 elements, use the `Sequence`-based implementation

This constant was determined using benchmarking. More information: https://github.com/apple/swift-algorithms/pull/152#issuecomment-887130149

* Remove check for collections fewer than 8 elements

* Make `_partitioned` `internal`

* Prefer `Array` over `ContiguousArray`

* Document `partitioned(_:)` on `Collection`

* Remove `partitioned(upTo:)`

* Remove `_tupleMap`

* Remove `_partitioned` and use it inline (since it’s no longer used by the `Collection` implementation

* Remove unnecessary conversation of `Array` to `Array`

* Correct indentation

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>

* Consistent syntax

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>

* Add an external `by:` label to `partitioned`

* Add labels to returned tuple `falseElements`, `trueElements`

* Correct function signature

* Rename `belongsInSecondCollection` parameter name to simply `predicate`

The parameter name was potentially confusing. Unlike the other `partition` functions, this function can rely on its named tuple to clarify its behavior.

* Update copyright information

Co-authored-by: Nate Cook <natecook@apple.com>

* Update documentation

Co-authored-by: Nate Cook <natecook@apple.com>

* Update comment

* Add a precondition to ensure that the count matches up with the number of actual elements found while iterating

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
Co-authored-by: Nate Cook <natecook@apple.com>
2021-10-20 22:21:39 +02:00
Ole Begemann aeead5ab20 Fix typo in readme
Looks like a copy/paste oversight.
2021-09-13 14:22:39 -07:00
Tim Vermeulen c5ea9e3e36 Prepare for Swift Algorithms 1.0 (#167)
* Rename types to include a Sequence or Collection suffix, and clean up some guides

* Various refactors

* Replace `validateIndexTraversals` test method with `IndexValidator` type

* Add LazySequenceProtocol to StridingSequence, StridingCollection

* Update the Numerics dependency to 1.0

* Set `IndexedCollection.Indices` to `Base.Indices`

* Remove deprecations

* Update the changelog/README for the 1.0.0 release

* Fix compiler error on Linux

* Rename `WindowsCollection` to `WindowsOfCountCollection`
2021-09-09 01:01:36 +02:00
Stephen Canon e195266e1f Make Algorithms depend on Numerics product instead of RealModule. (#164)
The RealModule _library product_ will be removed from Numerics at some future point (the _module_ will continue to exist). Update Package.swift to depend on the Numerics library instead.
2021-08-26 18:51:34 +02:00
Tim Vermeulen 9f628005fe Ensure chunked(by:) always compares consecutive elements (#162) 2021-08-18 00:22:36 +02:00
Matt Zanchelli dcc3c82b0a Remove extraneous space in inline documentation (#159) 2021-08-05 18:40:16 +02:00
Iain Smith 50be2c8b3f Remove compilation bottleneck for Swift 5.3.2 builds (#147)
Benchmarks on Xcode 12.4 showed compiling / type checking
StrideCollection.offsetBackward was the bottleneck for building
the package. Replacing the ternary operator in that function
with an explicit if/else removes the bottleneck.
2021-06-21 11:17:42 -05:00
Nate Cook 2327673b0e Update the changelog/README for the 0.2.1 release (#145) 2021-06-01 15:46:56 -05:00
Tim Vermeulen 4b779b8b3b Add joined(by:) (#138) 2021-06-01 10:14:34 -05:00
Federico Ciardi 0e2941ef50 Add trimmingSuffix, trimmingPrefix and mutating variants (#104) 2021-05-25 12:50:03 -05:00
Nate Cook e25cf27e57 Update changelog for 0.2.0 release (#144) 2021-05-17 13:08:39 -05:00
Nate Cook 3484ac31f6 Make chunked(on:) include subject value in Element type (#142) 2021-05-16 15:02:03 -05:00
Nate Cook f9f3a5ccc4 Minor revisions to minAndMax() (#143)
* Settle on 2-way approach (s/o to @NevinBR)
* Add tests for predicate usage and stability
* Update the return value semantics
2021-05-13 12:31:13 -05:00
Daryle Walker 4038b5da40 Simultaneous Minimum and Maximum Evaluation (#90)
* Add function to find MIN and MAX in one pass

Add a method extending sequences that finds both the minimal and maximal elements of the receiver in a single pass, based off a given ordering predicate.  Add an overload that defaults the comparison predicate to the standard less-than operator.
2021-05-12 16:11:33 -05:00
Nate CookandTim Vermeulen 65ef6cb966 Update AdjacentPairs implementations and tests (#139)
* Update AdjacentPairs implementations and tests

* Add conditional lazy conformances

* Apply suggestions from code review

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>
2021-05-05 19:15:47 +02:00
Michael Pangburn 0f27d99c89 Introduce adjacentPairs (#119) 2021-05-04 13:08:33 -05:00
66a56e36e7 Add new heading and description for partitionIndex 🤷‍♂️. (#137)
* Add new heading and description for partitionIndex 🤷‍♂️.

* Move into Other useful ops.

* Update README.md

Co-authored-by: Nate Cook <natecook@apple.com>

* Update README.md

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>

Co-authored-by: Nate Cook <natecook@apple.com>
Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-05-03 13:30:25 -05:00
Pranav KasettiandImgBotApp 9901a50b03 [ImgBot] Optimize images (#133)
*Total -- 151.00kb -> 133.25kb (11.75%)

/Guides/Resources/SortedPrefix/FewElements.png -- 73.60kb -> 64.27kb (12.67%)
/Guides/Resources/SortedPrefix/ManyElements.png -- 77.40kb -> 68.98kb (10.87%)

Signed-off-by: ImgBotApp <ImgBotHelp@gmail.com>

Co-authored-by: ImgBotApp <ImgBotHelp@gmail.com>
2021-04-29 15:49:40 -05:00
Pranav KasettiandXiaodi Wu 061501a712 PR template Contribution Guidelines link doesn't work (#136)
* Fix template relative URLs.

* Update .github/PULL_REQUEST_TEMPLATE.md

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>

* Fix indent

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-04-23 11:14:44 +02:00
Nate Cook dbc48be5dd Update changelog for 0.1.1 release (#132) 2021-04-16 13:22:28 -05:00
Tim Vermeulen 04d91803a2 Fix associated type inference error in release build (#130) 2021-04-14 16:32:47 -07:00
Nate Cook 36bcc5581b Update changelog for 0.1.0 release (#128) 2021-04-13 23:53:07 -05:00
Nate Cook 31d600a4f1 Light revisions to guides (#127) 2021-04-13 16:34:17 -05:00
Luciano Almeida 0e44ceb7bb [NFC] Fixing typos on guides (#126) 2021-04-09 16:52:13 -07:00
Tim Vermeulen 78dd4b5b93 Make the base property of UniquePermutations internal (#125) 2021-04-09 14:50:18 -05:00
Tim Vermeulen abc5559ef6 Remove collection conformances to Equatable and Hashable (#124) 2021-04-09 14:44:16 -05:00
Pranav Kasetti bcdbac800a Add new FiniteCycle type as the return type of Collection.cycled(times:) (#106) 2021-04-07 14:57:26 -05:00
Tim Vermeulen 718220d0f8 Make uniqued() lazy by default (#71)
* Make `uniqued()` lazy by default
2021-04-07 14:51:11 -05:00
Tim Vermeulen 551b4af927 Simplify Chain's index offsetting (#116)
* Use the offsetting structure from `Product2`

* Rename `convertIndex` to `normalizeIndex`
2021-04-07 19:52:49 +02:00
Tim Vermeulen dca25448e0 Rename the LazyChunked type to Chunked (#121)
* Rename LazyChunked -> Chunked
* Add deprecated typealias for `LazyChunked`
2021-04-07 09:43:37 -05:00
Luciano Almeida 1639c1e2c3 [tests] Ensure correct implementation of hash for ChunkedByCount (#123) 2021-04-07 09:42:28 -05:00
Luciano Almeida a61c3db4fb Making base properties on collection wrappers all internal (#85) 2021-04-06 13:38:55 -05:00
Luciano Almeida 198eee004e [Compacted] Adding compacted() method to remove all nils in a sequence or collection (#112) 2021-04-05 09:52:53 -05:00
Nate Cook 4cca4895cc Update changelog for 0.0.4 release (#120) 2021-03-29 14:25:46 -05:00
Tim Vermeulen 001247f8a5 Expand the firstNonNil(_:) docs (#115)
* Fix indentation

* Improve documentation
2021-03-29 19:18:56 +02:00
Kyle Macomber 0065c60a22 Remove the inout on reductions(into:_:) to be consistent with the stdlib reduce(into:_) (#118) 2021-03-27 07:17:34 -07:00
Daniel Tull 5cde0b1b67 Inline all the reductions things! (#114) 2021-03-25 16:54:54 +01:00
Matt Zanchelli 220649e999 Correct typos (#113)
largets -> largest
2021-03-25 00:05:49 -07:00
Daniel Tull b171b81577 Add reductions(_:_:) (#46)
* Add scan function

* Add initial conditional conformances to Collection and BidirectionalCollection

* Rename scan to reductions

* Add information to the readme about the reductions name

* Add eager API

* Remove Reductions' conformance to BidirectionalCollection

* Implement Reductions subscript such that it occurs in constant time

* Add a variant which includes the given initial result

* Add a variant which takes no initial result value

* Add excluding label to show the initial result is not included

* Test lazy implementations

* Remove reductions(including:_:)

* Add conformance to LazySequenceProtocol and LazyCollectionProtocol when the base sequence conforms

* Fix implementation of lazy reductions

* Add test cases for sequences with one element

* Tidy up tests

* Improve ergonomics of no initial value eager reductions call and provide it as an extension on Sequence

* Add lazy InclusiveReductions sequence

* Rename Reductions to ExclusiveReductions

* Add Collection implementation for InclusiveReductions

* Update guide

* Add links for C++ implementations

* Add conformance to Collection for ExclusiveReductions

* Improve ergonomics of ExclusiveReductions' index representation

* Improve ergonomics of InclusiveReductions' index representation by sharing the Index implementation

* Tidy up internal function

* Add exclusive eager version of reductions(into:_:)

* Use new lazy assertion functions

* Correct the complexity claims for reductions

* Separate the index types

This will allow for future changes to either implementation without causing a breakage for the other.

* Update guide to reflect that arrays are returned directly

* Add scan as deprecated methods

* Add lazy overload of reductions(into:_:)

* Add the reductions(into:_:) functions

* More succinctly introduce reductions

* Add a note about the deprecated scan functions

* Update documentation

* Add @inlinable and @usableFromInline

* Copy documentation to all variants of reductions

* Test the value after the function is complete

* Just use the += operator

* Add an example for reductions(into:_:)

* Improve the documentation of the return value

* Update complexity note

* Use the reduce documentation for inspiration for the discussion of reductions
2021-03-24 17:10:09 +01:00
Nate CookandTim Vermeulen e652f01949 Add uniquePermutations as wrapper for nextPermutation (#91)
* Add uniquePermutations as wrapper for nextPermutation

* Implement uniquePermutations(ofCount:) variants

* Simplify UniquePermutations.Iterator.next()

* Add tests for uniquePermutations

* Move to a predicate-based uniquePermutations

* Add method documentation

* Convert to Hashable-based uniquing instead of Comparable

* Streamline tests, cover uniqueness

* Use optional count to collapse no-count method

* Update API documentation

* Remove leftover version of nextPermutation()

* Remove Hashable requirement from the UniquePermutations type

* Update documentation

* Apply Tim's great revisions

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>

* Add lazy conformance to UniquePermutations

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>
2021-03-24 15:17:27 +01:00
Karl 9783c1be91 Inline all the things! 🎨 (#109)
* Make suffix functions inlinable

* Inline all the things!
2021-03-23 15:00:09 -05:00
Charles Maria TorandXiaodi Wu e64cff7e1d Add Sequence.firstNonNil(_:) (#31)
* Add Sequence.firstNonNil(of:) and associated tests

* Rename First.swift to FirstTests.swift

* Address PR comments by adding guide and changing naming

* Address PR comments by changing name

* Update Guides/FirstNonNil.md

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>

* Update Sources/Algorithms/FirstNonNil.swift

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>

Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-03-23 19:55:33 +01:00
Kyle Macomber 98b6e26d8d Remove .xcodesamplecode.plist, which prevents editing markdown from Xcode (#111) 2021-03-23 13:20:39 -05:00
Luciano Almeida ca8af77420 [test] Adding missing BidirectionalCollection::partition(subrange:) and MutableCollection::partition(subrange:) unit tests (#95) 2021-03-23 13:20:21 -05:00
Ahmad Alhashemi e077f67639 Improve XCTAssertEqualSequences to log difference (#105) 2021-03-23 07:52:56 -07:00
BJ Homer ed38a2dac4 Fix a broken link (#98) 2021-03-11 20:57:54 +01:00
Oliver AtkinsonandTim Vermeulen 18ec8500b7 Improve the performance of Stride when Base isa Collection (#88)
* Implement StrideSequence so that the default implementation for collection uses IndexingIterator

* Update Sources/Algorithms/Stride.swift

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>

* reinstate documentation for Sequence and remove explicit Sequence conformance on Stride

* documentation

* rename Stride to StrideCollection

Co-authored-by: Tim Vermeulen <tvermeulen@apple.com>
2021-03-10 18:20:00 +01:00
Tim Vermeulen ab0ec2adf4 Internally add Collection.endOfPrefix(while:) and BidirectionalCollection.startOfSuffix(while:) (#92)
* Add endOfPrefix(while:) and startOfSuffix(while:) internally

* Add tests

* Use these methods throughout the package
2021-03-09 20:03:55 +01:00
Todd Thomas e7c6716499 Add lazy split implementation. (#78)
`split(maxSplits:omittingEmptySubsequences:whereSeparator:)`

and

`split(separator:maxSplits:omittingEmptySubsequences:)`

now operate lazily when called on `LazySequenceProtocol`- or
`LazyCollectionProtocol`-conforming values. In the latter case,
no additional storage is allocated on the heap.
2021-03-09 01:48:58 -06:00
Matt Zanchelli d2546b8740 Correct link to Windows.md (#87) 2021-03-04 09:39:04 -06:00
Nate Cook 1e761dd787 Update changelog for 0.0.3 release (#86) 2021-02-26 14:03:33 -06:00
Nate Cook bd64bef3d2 Rename sortedPrefix methods (#77)
This renames sortedPrefix to min(count:), adds max(count:),
and moves both methods down to Sequence.

In order to still provide the optimization when `count` is close to
a collection's length, we include a Collection-specific overload of
all methods. These won't be accessed when in a Sequence-generic context,
but it's the best we can do without adding these methods as protocol
requirements.
2021-02-26 13:57:55 -06:00
Ben Rimmington 32837b9ad6 Rename trimming(where:) to trimming(while:) 2021-02-26 10:38:50 -06:00
Nate Cook f91638bba6 Add new methods to the README 2021-02-23 17:18:33 -06:00
Luciano Almeida 914e626e23 Audit public functions and properties that could be inlinable (#83) 2021-02-23 11:48:57 -06:00
Dhruv Shah d91723bd4b Create Suffix.md (#82)
Guide for suffix(while: ) function
2021-02-22 01:07:41 -06:00
Nate Cook 63311ae0ab Merge pull request #79 from apple/nate/just_windows
Rename slidingWindows back to windows(ofCount:)
2021-02-18 17:07:27 -06:00
Nate Cook cc20b55cc6 Rename slidingWindows back to windows(ofCount:) 2021-02-18 12:31:58 -06:00
Nate Cook 5be792abcf Add additional tests to rotate functions, clarify variable names (#75)
* Avoid ambiguous single-letter variable names
* Use consistent variable names
* Add unit tests for documented examples of rotate functions
* Add unit tests for reverse functions
2021-02-16 09:11:19 -06:00
Matt Zanchelli bf1de3240d Add unit tests for reverse functions 2021-02-15 13:31:34 -08:00
Matt Zanchelli dd564ca517 Add unit tests for documented examples of rotate functions 2021-02-15 13:31:22 -08:00
Matt Zanchelli 44d359b429 Use consistent variable names 2021-02-15 13:29:43 -08:00
Matt Zanchelli bdf36ad23d Avoid ambiguous single-letter variable names 2021-02-15 13:29:41 -08:00
Tim Vermeulen 7ca12bed60 Precompute LazyChunked's startIndex (#68) 2021-02-12 07:02:26 -08:00
Tim Vermeulen 4f7cd340cd Index offsetting for Product2 (#66) 2021-02-12 06:48:40 -08:00
Iceman 1a3c7061de Fix RandomSample crash when 0 was out from random. (#70) 2021-02-12 06:41:26 -08:00
Matt Zanchelli d8a11e0d51 All permutations (#56)
Adds the ability to easily get permutations of a range of sizes, like #51 did for Combinations.
2021-02-12 06:32:32 -08:00
Matt Zanchelli d2a1ca5f7b Lowercase suffix(while:) to match the case of the actual function name (#76) 2021-02-10 20:45:56 -06:00
Nate Cook 52e1e0e45a add suffix:while method (#65) 2021-02-09 13:00:17 -06:00
michiboo 3b511072a6 Fix suffix tests 2021-02-09 12:56:08 -06:00
Nate Cook cda6fddada Merge pull request #61 from LucianoPAlmeida/normalizing-assert
[NFC] Using precondition instead of assert in calls that do not allow negative values
2021-01-28 10:08:09 -06:00
michibooandXiaodi Wu f9a4f79027 Update Sources/Algorithms/Suffix.swift
Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-01-28 15:22:18 +02:00
michibooandXiaodi Wu 2f8f798d0c Update Sources/Algorithms/Suffix.swift
Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-01-24 21:54:14 +08:00
michibooandXiaodi Wu 60bad3bbf4 Update Sources/Algorithms/Suffix.swift
Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-01-23 14:39:02 +08:00
michiboo 08e424ea07 add doc on suffix method 2021-01-23 08:38:12 +02:00
michiboo 813ea7905e add more test for suffix Tests 2021-01-22 16:17:28 +02:00
michiboo 1acc2136d9 add test for suffix 2021-01-20 15:23:38 +02:00
michiboo 9ef531f23f add suffix while method 2021-01-20 15:16:25 +02:00
Nate Cook d872b648f4 Merge pull request #57 from ollieatkinson/patch-1
Update README.md to add slidingWindows(ofCount:) and striding(by:)
2021-01-15 22:49:04 -06:00
Nate Cook 9836a4f80b [Chunked] Add chunks(of:) variant that divides a collection in chunks of a given size (#54) 2021-01-15 22:43:13 -06:00
Luciano Almeida 34d7a55d1a [NFC] Using precondition instead of assert in calls that do not allow negative values 2021-01-15 20:15:52 -03:00
Luciano Almeida ad8d6ed7a1 [Chunks] Add chunks(ofCount:) in the readme 2021-01-15 07:53:21 -03:00
Luciano Almeida 14f09e4228 [Chunked] Improving index(offset:limit:) to avoid distance call 2021-01-15 07:48:11 -03:00
Luciano Almeida 622703b97f [Chunked] Improve tests for ChunksOfCount traversal 2021-01-14 22:56:28 -03:00
Matt Zanchelli 5b7993ca8d All combinations (#51)
Add an overload of combinations(ofCount:) that accepts a range.
2021-01-14 13:32:47 -06:00
Oliver AtkinsonandXiaodi Wu b18a659ab5 Update README.md
Co-authored-by: Xiaodi Wu <13952+xwu@users.noreply.github.com>
2021-01-14 17:26:41 +00:00
Luciano Almeida f89fe8fad1 [Chunked] Code review adjustments 2021-01-13 23:06:19 -03:00
Oliver Atkinson f0dba1433f Update README.md
Adds `slidingWindows(ofCount:)` and `striding(by:)` to README.md
2021-01-12 20:07:01 +00:00
Luciano Almeida 05df988369 [Chunked] Minor adjustments on tests 2021-01-10 17:18:49 -03:00
Luciano Almeida afac704540 [Chunked] Implemeting of ChunkedByCount index(offsetBy:) 2021-01-09 00:17:49 -03:00
Luciano Almeida 79aeb24e9d Fixing review comments 2021-01-08 08:21:01 -03:00
Luciano Almeida 3092eb1304 [Chucked] Add chunks(ofCount:) information on the Chunked guides 2021-01-08 00:09:07 -03:00
Luciano Almeida e0fed41419 [Chunked] Adding tests for chunks of count collection implementation 2021-01-08 00:08:21 -03:00
Luciano Almeida 505b57369f [Chunked] Implementing chunked collection by a given count 2021-01-08 00:07:46 -03:00
Rafael Machado 3864606e00 Add "sortedPrefix(_:by)" to Collection (#9) 2020-12-04 10:20:28 -06:00
Nate Cook e1c421c568 Fix typo 2020-12-04 10:16:09 -06:00
Nate Cook 638869256a Add a few missing doc comments. 2020-12-02 16:28:23 -06:00
Tim Vermeulen 99152ecc68 Unify chunked(by:) and chunked(on:) (#44)
* Unify the eager `chunked(on:)` and `chunked(by:)`

* Unify the lazy `chunked(on:)` and `chunked(by:)`

* Trap when going past the end

* Add preconditions in `index(before:)`/`index(after:)`
2020-12-02 15:25:50 -06:00
Markus Winter 7af7ac2599 Clean up some comments (#49) 2020-12-02 10:21:06 -06:00
Nate Cook ff01a02c07 Add Stride for Collection (#24) 2020-12-01 17:54:00 -06:00
Daniel Tull 93c8724c72 Add conformances to LazySequenceProtocol and LazyCollectionProtocol (#47)
* Conform Intersperse to LazySequenceProtocol when the base sequence does

* Add conformance to LazyCollectionProtocol

* Conform Indexed to LazyCollectionProtocol when Base conforms

* Rename XCTAssertLazy to XCTAssertLazySequence

* Add XCTAssertLazyCollection

* Add lazy test for Intersperse

* Update Indexed guide

* Add lazy conformances to SlidingWindows

* Update SlidingWindows guide
2020-12-01 15:47:13 -06:00
Tim Vermeulen ad6dc7a143 Add random-access methods to SlidingWindows (#42) 2020-11-12 11:30:32 -06:00
Daniel Tull fd189aa078 Add interspersed(with:) (#35) 2020-11-09 09:44:23 -06:00
Tim Vermeulen 6933a3157b Avoid unnecessary computations in Product.distance(from:to:) (#40) 2020-11-06 15:06:23 -06:00
Oliver Atkinson dfcc611e1d consistant negative stride 2020-11-06 15:52:42 +00:00
Oliver Atkinson 3669ff0c11 offsetBackward n is positive and remove init? from Index 2020-11-06 15:33:03 +00:00
Oliver Atkinson 0a6bcc3c68 compute the stride only when the next element is requested 2020-11-06 15:25:34 +00:00
Oliver Atkinson 92b2846345 Add unbounded striding tests to check empty and sequence implementation 2020-11-06 10:42:38 +00:00
Oliver Atkinson 377bb72f0a small documentation tweek collection -> sequence 2020-11-06 10:31:40 +00:00
Oliver Atkinson 28bbed8776 Add implementation for Sequence iterator 2020-11-06 10:13:29 +00:00
Oliver Atkinson 6f7148d966 Implementation of feedback from @timvermeulen 2020-11-06 09:46:06 +00:00
Oliver Atkinson dcdef508c0 make base and stride internal 2020-11-02 10:02:17 +00:00
Oliver Atkinson 4a194ca811 remove redundant limit 2020-11-01 20:39:18 +00:00
Oliver Atkinson 6df6133ab7 Refactor to index(_:offsetBy:limitedBy:) and utilise the new test utilities for validateIndexTraversals 2020-11-01 20:30:17 +00:00
Oliver Atkinson 17cb07e38f Add Stride for Collection 2020-11-01 20:30:10 +00:00
108 changed files with 12802 additions and 1160 deletions

No files matched your search

+1 -1
View File
@@ -16,7 +16,7 @@ about: Something isn't working as expected
Replace this paragraph with a short description of the incorrect incorrect behavior. If this is a regression, please note the last version that the behavior was correct in addition to your current version.
**Swift Algorithms version:** `0.0.1` or the `main` branch, for example.
**Swift Algorithms version:** `1.0.0` or the `main` branch, for example.
**Swift version:** Paste the output of `swift --version` here.
### Checklist
+1 -1
View File
@@ -17,5 +17,5 @@ Replace this paragraph with a description of your changes and rationale. Provide
### Checklist
- [ ] I've added at least one test that validates that my change is working, if appropriate
- [ ] I've followed the code style of the rest of the project
- [ ] I've read the [Contribution Guidelines](../CONTRIBUTING.md)
- [ ] I've read the [Contribution Guidelines](../blob/main/CONTRIBUTING.md)
- [ ] I've updated the documentation if necessary
+1 -1
View File
@@ -34,5 +34,5 @@ What is the impact of this change on existing users? Does it deprecate or remove
### Checklist
- [ ] I've added at least one test that validates that my change is working, if appropriate
- [ ] I've followed the code style of the rest of the project
- [ ] I've read the [Contribution Guidelines](../../CONTRIBUTING.md)
- [ ] I've read the [Contribution Guidelines](../../blob/main/CONTRIBUTING.md)
- [ ] I've updated the documentation if necessary
+5
View File
@@ -0,0 +1,5 @@
version: 1
builder:
configs:
- documentation_targets: [Algorithms]
-5
View File
@@ -1,5 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array/>
</plist>
+361 -8
View File
@@ -4,18 +4,301 @@
Add new items at the end of the relevant section under **Unreleased**.
-->
This project follows semantic versioning. While still in major version `0`,
source-stability is only guaranteed within minor versions (e.g. between
`0.0.3` and `0.0.4`). If you want to guard against potentially source-breaking
package updates, you can specify your package dependency using
`.upToNextMinor(from: "0.0.1")` as the requirement.
This project follows semantic versioning.
## [Unreleased]
*No changes yet.*
*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-10-05
### Additions
- New nonmutating `partitioned(by:)` methods that return both the failing and passing elements of a sequence or collection in separate arrays. ([#152])
```swift
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let (longNames, shortNames) = cast.partitioned(by: { $0.count < 5 })
print(longNames)
// Prints "["Vivien", "Marlon"]"
print(shortNames)
// Prints "["Kim", "Karl"]"
```
- A new `evenlyChunked(in:)` method that chunks a sequence or collection into the specified number of evenly-sized subsequences. ([#96])
```swift
let numbers = Array(0..<10)
for chunk in numbers.evenlyChunked(in: 4) {
print(chunk)
}
// Prints:
// [0, 1, 2]
// [3, 4, 5]
// [6, 7]
// [8, 9]
```
### Changes
- The package now has a minimum Swift version of Swift 5.4.
### Fixes
- Improvements to documentation, including a new DocC-based documentation structure.
The 1.1.0 release includes contributions from [dickoff], [gwynne], [mdznr], [natecook1000], [ole], [stephentyrone], and [timvermeulen].
Thank you!
---
## [1.0.0] - 2021-09-08
### Changes
- Most sequence and collection types have been renamed, following a more
consistent naming structure:
- The `Lazy` prefix was dropped.
- Either a `Sequence` or `Collection` suffix was added depending on whether or
not the type is unconditionally a collection.
- The base name was derived from the name of the method that produces it,
including an argument label to disambiguate if necessary.
```
Chain2 -> Chain2Sequence
ChunkedBy -> ChunkedByCollection
ChunkedOn -> ChunkedOnCollection
ChunkedByCount -> ChunksOfCountCollection
Combinations -> CombinationsSequence
Cycle -> CycledSequence
FiniteCycle -> CycledTimesCollection
Indexed -> IndexedCollection
Intersperse -> InterspersedSequence
LazySplitSequence -> SplitSequence
LazySplitCollection -> SplitCollection
Permutations -> PermutationsSequence
UniquePermutations -> UniquePermutationsSequence
Product2 -> Product2Sequence
ExclusiveReductions -> ExclusiveReductionsSequence
InclusiveReductions -> InclusiveReductionsSequence
StrideSequence -> StridingSequence
StrideCollection -> StridingCollection
Uniqued -> UniquedSequence
Windows -> WindowsOfCountCollection
```
- Types that can only be produced from a lazy sequence chain now unconditionally
conform to `LazySequenceProtocol` and wrap the base sequence instead of the
lazy wrapper, making some return types slightly simpler.
- e.g. `[1, 2, 3].lazy.reductions(+)` now returns
`ExclusiveReductionsSequence<[Int]>`, not
`ExclusiveReductionsSequence<LazySequence<[Int]>>`.
- This concerns `JoinedByClosureSequence`, `JoinedByClosureCollection`,
`ExclusiveReductionsSequence`, `InclusiveReductionsSequence`.
- The generic parameters of the `ExclusiveReductions` type have been swapped,
putting the base collection first and the result type second.
- The `Indices` associated type of `IndexedCollection` now matches
`Base.Indices`.
### Removals
- Previously deprecated type and method names have been removed:
- The `Chain` type alias for `Chain2Sequence`
- The `chained(with:)` method which was replaced with the `chain(_:_:)` free
function
- The `LazyChunked` and `Chunked` type aliases for `ChunkedByCollection`
- The `rotate(subrange:at:)` and `rotate(at:)` methods which were renamed to
`rotate(subrange:toStartAt:)` and `rotate(toStartAt:)` respectively
### Fixes
- The `StridingSequence` and `StridingCollection` types now conditionally
conform to `LazySequenceProtocol`, allowing the `striding(by:)` method to
properly propagate laziness in a lazy sequence chain.
- Fixed `chunked(by:)` to always compare two consecutive elements rather than
each element with the first element of the current chunk. ([#162])
The 1.0.0 release includes contributions from [iainsmith], [mdznr], and
[timvermeulen]. Thank you!
## [0.2.1] - 2021-06-01
### Additions
Expanded versatility for two existing operations:
- A series of `joined(by:)` overloads concatenate a sequence of sequences using
an element or a collection, either passed in or generated from consecutive
elements via a closure. ([#138])
- Additional `trimming(while:)` methods for trimming only the start or end of a
collection, as well as mutating versions of all three variants. ([#104])
The 0.2.1 release includes contributions from [fedeci] and [timvermeulen].
Thank you!
## [0.2.0] - 2021-05-17
### Additions
Two new additions to the list of algorithms:
- `adjacentPairs()` lazily iterates over tuples of adjacent elements of a
sequence. ([#119])
- `minAndMax()` finds both the smallest and largest elements of a sequence in
a single pass. ([#90])
### Changes
- When calling `chunked(on:)`, the resulting collection has an element type of
`(Subject, SubSequence)` instead of just `SubSequence`, making the subject
value available when iterating.
```swift
let numbers = [5, 6, -3, -9, -11, 2, 7, 6]
for (signum, values) in numbers.chunked(on: { $0.signum() }) {
print(signum, values)
}
// 1 [5, 6]
// -1 [-3, -9, -11]
// 1 [2, 7, 6]
```
### Fixes
- Improvements to the documentation and PR templates.
The 0.2.0 release includes contributions from [CTMacUser], [LemonSpike],
[mpangburn], and [natecook1000]. Thank you!
---
## [0.1.1] - 2021-04-14
### Fixes
- `Product2` associated type inference error in release build ([#130])
## [0.1.0] - 2021-04-13
### Additions
- The `compacted()` method lazily finds the non-`nil` elements of a sequence or
collection ([#112]).
### Changes
- The `uniqued()` method now lazily computes the unique elements of a sequence
or a collection ([#71]). Pass this resulting sequence to an `Array`
initializer to recover the behavior of the previous release.
- Calling `cycled(times:)` now returns a new `FiniteCycle` type, which has the
same conformances as its underlying collection ([#106]).
- The base collections of the sequence and collection wrapper types are no
longer public ([#85], [#125]), and the wrapper types no longer conform to the
`Equatable` or `Hashable` protocols ([#124]). If you need those conformances,
convert the wrapper type to an `Array` or other collection currrency type
before storing. Please file an issue if these changes pose a problem for your
use case.
The 0.1.0 release includes contributions from [LemonSpike], [LucianoPAlmeida],
[natecook1000], and [timvermeulen]. Thank you!
---
## [0.0.4] - 2021-03-29
### Additions
More new algorithms to join the party:
- A lazy version of the standard library's two `split` methods. ([#78])
- `firstNonNil(_:)` returns the first non-`nil` element from an
optional-generating transform. ([#31])
- `uniquePermutations()` skips duplicates when generating permutations of a
collection. ([#91])
- The `reductions` methods return all the in-between states of reducing a
sequence or collection. ([#46])
### Fixes
- Methods and computed properties are more consistently marked as inlinable,
resolving a performance regression.
- The `Stride` type now efficiently calculates distances between positions,
supported by the underlying collection.
- Better test coverage and improved diagnostics for comparing sequences.
- Fixed links and improved documentation.
The 0.0.4 release includes contributions from [bjhomer], [danielctull],
[hashemi], [karwa], [kylemacomber], [LucianoPAlmeida], [mdznr], [natecook1000],
[ollieatkinson], [Qata], [timvermeulen], and [toddthomas]. Thank you!
## [0.0.3] - 2021-02-26
### Additions
An exciting group of new algorithms, contributed by the community:
- `trimming(while:)` returns a subsequence of a bidirectional collection with
the matching elements removed from the start and end. ([#4])
- `min(ofCount:)` and `max(ofCount:)` find the smallest or largest elements in
a collection. ([#9], [#77])
- `windows(ofCount:)` lets you iterate over all the overlapping subsequences of
a particular length. ([#20])
- `striding(by:)` iterates over every *n*th element of a sequence or collection.
([#24])
- `interspersed(with:)` places a new element between every pair of elements in
a sequence or collection. ([#35])
- `chunks(ofCount:)` breaks a collection into subsequences of the given number
of elements. ([#54])
- `suffix(while:)` matches the standard library's `prefix(while:)`, by
returning the suffix of all matching elements from a bidirectional collection.
([#65])
- Variations of `combinations(ofCount:)` and `permutations(ofCount:)` that take
a range expression as a parameter, returning combinations and permutations of
multiple lengths. ([#51], [#56])
### Changes
- The `LazyChunked` type now precomputes its `startIndex`, making performance
more predictable when using the collection.
### Fixes
- `randomSample(count:)` no longer traps in rare circumstances.
- Index calculations have been improved in a variety of collection wrappers.
- A variety of documentation improvements and corrections.
The 0.0.3 release includes contributions from [benrimmington], [danielctull],
[dhruvshah8], [karwa], [LucianoPAlmeida], [markuswntr], [mdznr], [michiboo],
[natecook1000], [ollieatkinson], [rakaramos], [rockbruno], [Roshankumar350],
[sidepelican], and [timvermeulen]. Thank you!
## [0.0.2] - 2020-10-23
### Changes
@@ -32,7 +315,7 @@ package updates, you can specify your package dependency using
### Fixes
- Swift Algorithms now builds under SwiftPM on Windows.
- `Algorithms` now builds under SwiftPM on Windows.
- A wide variety of errors, misspellings, and ommissions in the documentation
and guides have been fixed.
- Index/distance calculations for the `Product2` and `Chain` types have been
@@ -44,6 +327,7 @@ The 0.0.2 release includes contributions from [AustinConlon], [egorzhdan],
[IanKeen], [iSame7], [karwa], [kylemacomber], [natecook1000], [nordicio],
[pmtao], [schlagelk], [stephentyrone], and [timvermeulen]. Thank you!
## [0.0.1] - 2020-10-07
- **Swift Algorithms** initial release.
@@ -54,23 +338,92 @@ 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/0.0.2...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
[0.2.0]: https://github.com/apple/swift-algorithms/compare/0.1.1...0.2.0
[0.1.1]: https://github.com/apple/swift-algorithms/compare/0.1.0...0.1.1
[0.1.0]: https://github.com/apple/swift-algorithms/compare/0.0.4...0.1.0
[0.0.4]: https://github.com/apple/swift-algorithms/compare/0.0.3...0.0.4
[0.0.3]: https://github.com/apple/swift-algorithms/compare/0.0.2...0.0.3
[0.0.2]: https://github.com/apple/swift-algorithms/compare/0.0.1...0.0.2
[0.0.1]: https://github.com/apple/swift-algorithms/releases/tag/0.0.1
<!-- Link references for pull requests -->
[#4]: https://github.com/apple/swift-algorithms/pull/4
[#9]: https://github.com/apple/swift-algorithms/pull/9
[#20]: https://github.com/apple/swift-algorithms/pull/20
[#24]: https://github.com/apple/swift-algorithms/pull/24
[#31]: https://github.com/apple/swift-algorithms/pull/31
[#35]: https://github.com/apple/swift-algorithms/pull/35
[#46]: https://github.com/apple/swift-algorithms/pull/46
[#51]: https://github.com/apple/swift-algorithms/pull/51
[#54]: https://github.com/apple/swift-algorithms/pull/54
[#56]: https://github.com/apple/swift-algorithms/pull/56
[#65]: https://github.com/apple/swift-algorithms/pull/65
[#71]: https://github.com/apple/swift-algorithms/pull/71
[#77]: https://github.com/apple/swift-algorithms/pull/77
[#78]: https://github.com/apple/swift-algorithms/pull/78
[#85]: https://github.com/apple/swift-algorithms/pull/85
[#90]: https://github.com/apple/swift-algorithms/pull/90
[#91]: https://github.com/apple/swift-algorithms/pull/91
[#96]: https://github.com/apple/swift-algorithms/pull/96
[#104]: https://github.com/apple/swift-algorithms/pull/104
[#106]: https://github.com/apple/swift-algorithms/pull/106
[#112]: https://github.com/apple/swift-algorithms/pull/112
[#119]: https://github.com/apple/swift-algorithms/pull/119
[#124]: https://github.com/apple/swift-algorithms/pull/124
[#125]: https://github.com/apple/swift-algorithms/pull/125
[#130]: https://github.com/apple/swift-algorithms/pull/130
[#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
[CTMacUser]: https://github.com/apple/swift-algorithms/commits?author=CTMacUser
[danielctull]: https://github.com/apple/swift-algorithms/commits?author=danielctull
[dhruvshah8]: https://github.com/apple/swift-algorithms/commits?author=dhruvshah8
[dickoff]: https://github.com/apple/swift-algorithms/commits?author=dickoff
[egorzhdan]: https://github.com/apple/swift-algorithms/commits?author=egorzhdan
[fedeci]: https://github.com/apple/swift-algorithms/commits?author=fedeci
[gwynne]: https://github.com/apple/swift-algorithms/commits?author=gwynne
[hashemi]: https://github.com/apple/swift-algorithms/commits?author=hashemi
[iainsmith]: https://github.com/apple/swift-algorithms/commits?author=iainsmith
[IanKeen]: https://github.com/apple/swift-algorithms/commits?author=IanKeen
[iSame7]: https://github.com/apple/swift-algorithms/commits?author=iSame7
[karwa]: https://github.com/apple/swift-algorithms/commits?author=karwa
[kylemacomber]: https://github.com/apple/swift-algorithms/commits?author=kylemacomber
[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
[natecook1000]: https://github.com/apple/swift-algorithms/commits?author=natecook1000
[nordicio]: https://github.com/apple/swift-algorithms/commits?author=nordicio
[ole]: https://github.com/apple/swift-algorithms/commits?author=ole
[ollieatkinson]: https://github.com/apple/swift-algorithms/commits?author=ollieatkinson
[pmtao]: https://github.com/apple/swift-algorithms/commits?author=pmtao
[Qata]: https://github.com/apple/swift-algorithms/commits?author=Qata
[rakaramos]: https://github.com/apple/swift-algorithms/commits?author=rakaramos
[rockbruno]: https://github.com/apple/swift-algorithms/commits?author=rockbruno
[Roshankumar350]: https://github.com/apple/swift-algorithms/commits?author=Roshankumar350
[schlagelk]: https://github.com/apple/swift-algorithms/commits?author=schlagelk
[sidepelican]: https://github.com/apple/swift-algorithms/commits?author=sidepelican
[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
+60
View File
@@ -0,0 +1,60 @@
# AdjacentPairs
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/AdjacentPairs.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/AdjacentPairsTests.swift)]
Lazily iterates over tuples of adjacent elements.
```swift
let numbers = (1...5)
let pairs = numbers.adjacentPairs()
// Array(pairs) == [(1, 2), (2, 3), (3, 4), (4, 5)]
```
## Detailed Design
The `adjacentPairs()` method is declared as a `Sequence` extension returning
`AdjacentPairsSequence` and as a `Collection` extension returning
`AdjacentPairsCollection`.
```swift
extension Sequence {
public func adjacentPairs() -> AdjacentPairsSequence<Self>
}
```
```swift
extension Collection {
public func adjacentPairs() -> AdjacentPairsCollection<Self>
}
```
The `AdjacentPairsSequence` type is a sequence, and the
`AdjacentPairsCollection` type is a collection with conditional conformance to
`BidirectionalCollection` and `RandomAccessCollection` when the underlying
collection conforms.
### Complexity
Calling `adjacentPairs` is an O(1) operation.
### Naming
This method is named for clarity while remaining agnostic to any particular
domain of programming. In natural language processing, this operation is akin to
computing a list of bigrams; however, this algorithm is not specific to this use
case.
### Comparison with other languages
This function is often written as a `zip` of a sequence together with itself,
minus its first element.
**Haskell:** This operation is spelled ``s `zip` tail s``.
**Python:** Python users may write `zip(s, s[1:])` for a list with at least one
element. For natural language processing, the `nltk` package offers a `bigrams`
function akin to this method.
Note that in Swift, the spelling `zip(s, s.dropFirst())` is undefined behavior
for a single-pass sequence `s`.
+4 -4
View File
@@ -25,13 +25,13 @@ the shared conformances of the two underlying types.
The `chain(_:_:)` function takes two sequences as arguments:
```swift
public func chain<S1, S2>(_ s1: S1, _ s2: S2) -> Chain2<S1, S2>
public func chain<S1, S2>(_ s1: S1, _ s2: S2) -> Chain2Sequence<S1, S2>
where S1.Element == S2.Element
```
The resulting `Chain2` type is a sequence, with conditional conformance to
`Collection`, `BidirectionalCollection`, and `RandomAccessCollection` when both
the first and second arguments conform.
The resulting `Chain2Sequence` type is a sequence, with conditional conformance
to `Collection`, `BidirectionalCollection`, and `RandomAccessCollection` when
both the first and second arguments conform.
### Naming
+80 -30
View File
@@ -3,13 +3,16 @@
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Chunked.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/ChunkedTests.swift)]
Break a collection into subsequences where consecutive elements pass a binary
predicate, or where all elements in each chunk project to the same value.
Break a collection into nonoverlapping subsequences:
There are two variations of the `chunked` method: `chunked(by:)` and
`chunked(on:)`. `chunked(by:)` uses a binary predicate to test consecutive
elements, separating chunks where the predicate returns `false`. For example,
you can chunk a collection into ascending sequences using this method:
* `chunked(by:)` forms chunks of consecutive elements that pass a binary predicate,
* `chunked(on:)` forms chunks of consecutive elements that project to equal values,
* `chunks(ofCount:)` forms chunks of a given size, and
* `evenlyChunked(in:)` forms a given number of equally-sized chunks.
`chunked(by:)` uses a binary predicate to test consecutive elements, separating
chunks where the predicate returns `false`. For example, you can chunk a
collection into ascending sequences using this method:
```swift
let numbers = [10, 20, 30, 10, 40, 40, 10, 20]
@@ -17,20 +20,51 @@ let chunks = numbers.chunked(by: { $0 <= $1 })
// [[10, 20, 30], [10, 40, 40], [10, 20]]
```
The `chunk(on:)` method, by contrast, takes a projection of each element and
The `chunked(on:)` method, by contrast, takes a projection of each element and
separates chunks where the projection of two consecutive elements is not equal.
The result includes both the projected value and the subsequence that groups
elements with that projected value:
```swift
let names = ["David", "Kyle", "Karoy", "Nate"]
let chunks = names.chunked(on: \.first!)
// [["David"], ["Kyle", "Karoy"], ["Nate"]]
// [("D", ["David"]), ("K", ["Kyle", "Karoy"]), ("N", ["Nate"])]
```
These methods are related to the [existing SE proposal][proposal] for chunking a
collection into subsequences of a particular size, potentially named something
like `chunked(length:)`. Unlike the `split` family of methods, the entire
collection is included in the chunked result — joining the resulting chunks
recreates the original collection.
The `chunks(ofCount:)` method takes a `count` parameter (required to be > 0) and
separates the collection into chunks of this given count. If the length of the
collection is a multiple of the `count` parameter, all chunks will have the
a count equal to the parameter. Otherwise, the last chunk will contain the remaining elements.
```swift
let names = ["David", "Kyle", "Karoy", "Nate"]
let evenly = names.chunks(ofCount: 2)
// equivalent to [["David", "Kyle"], ["Karoy", "Nate"]]
let remaining = names.chunks(ofCount: 3)
// equivalent to [["David", "Kyle", "Karoy"], ["Nate"]]
```
The `chunks(ofCount:)` method was previously [proposed](proposal) for inclusion
in the standard library.
The `evenlyChunked(in:)` method takes a `count` parameter and divides the
collection into `count` number of equally-sized chunks. If the length of the
collection is not a multiple of the `count` parameter, the chunks at the start
will be longer than the chunks at the end.
```swift
let evenChunks = (0..<15).evenlyChunked(in: 3)
// equivalent to [0..<5, 5..<10, 10..<15]
let nearlyEvenChunks = (0..<15).evenlyChunked(in: 4)
// equivalent to [0..<4, 4..<8, 8..<12, 12..<15]
```
When "chunking" a collection, the entire collection is included in the result,
unlike the `split` family of methods, where separators are dropped.
Joining the result of a chunking method call results in a collection equivalent
to the original.
```swift
c.elementsEqual(c.chunked(...).joined())
@@ -41,8 +75,9 @@ c.elementsEqual(c.chunked(...).joined())
## Detailed Design
The two methods are added as extension to `Collection`, with two matching
versions that return a lazy wrapper added to `LazyCollectionProtocol`.
The four methods are added to `Collection`, with matching versions of
`chunked(by:)` and `chunked(on:)` that return a lazy wrapper added to
`LazyCollectionProtocol`.
```swift
extension Collection {
@@ -51,41 +86,56 @@ extension Collection {
) -> [SubSequence]
public func chunked<Subject: Equatable>(
on projection: (Element) -> Subject
on projection: (Element) -> Subject
) -> [SubSequence]
}
public func chunks(ofCount count: Int) -> ChunkedByCount<Self>
public func evenlyChunked(in count: Int) -> EvenlyChunkedCollection<Self>
}
extension LazyCollectionProtocol {
extension LazyCollectionProtocol {
public func chunked(
by belongInSameGroup: @escaping (Element, Element) -> Bool
) -> LazyChunked<Elements>
) -> ChunkedByCollection<Elements>
public func chunked<Subject: Equatable>(
on projection: @escaping (Element) -> Subject
) -> LazyChunked<Elements>
) -> ChunkedOnCollection<Elements, Subject>
}
```
The `LazyChunked` type is bidirectional when the wrapped collection is
bidirectional.
Each of the "chunked" collection types are bidirectional when the wrapped
collection is bidirectional. `ChunksOfCountCollection` and
`EvenlyChunkedCollection` also conform to `RandomAccessCollection` and
`LazySequenceProtocol` when their base collections conform.
### Complexity
The eager methods are O(_n_), the lazy methods are O(_1_).
The eager methods are O(_n_) where _n_ is the number of elements in the
collection. The lazy methods are O(_n_) because the start index is pre-computed.
### Naming
The operation performed by these methods is similar to other ways of breaking a collection up into subsequences. In particular, the predicate-based `split(where:)` method looks similar to `chunked(on:)`. You can draw a distinction between these different operations based on the resulting subsequences:
- `split`: *In the standard library.* Breaks a collection into subsequences, removing any elements that are considered "separators". The original collection cannot be recovered from the result of splitting.
- `chunked`: *In this package.* Breaks a collection into subsequences, preserving each element in its initial ordering. Joining the resulting subsequences re-forms the original collection.
- `sliced`: *Not included in this package or the stdlib.* Breaks a collection into potentially overlapping subsequences.
The operation performed by these methods is similar to other ways of breaking a
collection up into subsequences. In particular, the predicate-based
`split(where:)` method looks similar to `chunked(on:)`. You can draw a
distinction between these different operations based on the resulting
subsequences:
- `split`: *In the standard library.* Breaks a collection into subsequences,
removing any elements that are considered "separators". The original collection
cannot be recovered from the result of splitting.
- `chunked`: *In this package.* Breaks a collection into subsequences,
preserving each element in its initial ordering. Joining the resulting
subsequences re-forms the original collection.
- `sliced`: *Not included in this package or the stdlib.* Breaks a collection
into potentially overlapping subsequences.
### Comparison with other languages
**Ruby:** Ruby’s `Enumerable` class defines `chunk_while` and `chunk`, which map
to the proposed `chunked(by:)` and `chunked(on:)` methods.
**Rust:** Rust defines a variety of size-based `chunks` methods, but doesn’t
include any with the functionality described here.
**Rust:** Rust defines a variety of size-based `chunks` methods, of which the
standard version corresponds to the `chunks(ofCount:)` method defined here.
+35 -13
View File
@@ -36,35 +36,57 @@ for combo in numbers2.combinations(ofCount: 2) {
// [10, 10]
```
Given a range, the `combinations(ofCount:)` method returns a sequence of all
the different combinations of the given sizes of a collection’s elements in
increasing order of size.
```swift
let numbers = [10, 20, 30, 40]
for combo in numbers.combinations(ofCount: 2...3) {
print(combo)
}
// [10, 20]
// [10, 30]
// [10, 40]
// [20, 30]
// [20, 40]
// [30, 40]
// [10, 20, 30]
// [10, 20, 40]
// [10, 30, 40]
// [20, 30, 40]
```
## Detailed Design
The `combinations(ofCount:)` method is declared as a `Collection` extension,
and returns a `Combinations` type:
and returns a `CombinationsSequence` type:
```swift
extension Collection {
public func combinations(ofCount k: Int) -> Combinations<Self>
public func combinations(ofCount k: Int) -> CombinationsSequence<Self>
}
```
Since the `Combinations` type needs to store an array of the collection’s
indices and mutate the array to generate each permutation, `Combinations` only
has `Sequence` conformance. Adding `Collection` conformance would require
storing the array in the index type, which would in turn lead to copying the
array at every index advancement. `Combinations` does conform to
`LazySequenceProtocol` when the base type conforms.
Since the `CombinationsSequence` type needs to store an array of the
collection’s indices and mutate the array to generate each permutation,
`CombinationsSequence` only has `Sequence` conformance. Adding `Collection`
conformance would require storing the array in the index type, which would in
turn lead to copying the array at every index advancement.
`CombinationsSequence` does conform to `LazySequenceProtocol` when the base type
conforms.
### Complexity
Calling `combinations(ofCount:)` accesses the count of the collection, so it’s an
O(1) operation for random-access collections, or an O(_n_) operation otherwise.
Creating the iterator for a `Combinations` instance and each call to
`Combinations.Iterator.next()` is an O(_n_) operation.
Calling `combinations(ofCount:)` accesses the count of the collection, so it’s
an O(1) operation for random-access collections, or an O(_n_) operation
otherwise. Creating the iterator for a `CombinationsSequence` instance and each
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
+48
View File
@@ -0,0 +1,48 @@
# Compacted
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Compacted.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/CompactedTests.swift)]
A convenience method that lazily flattens the `nil`s out of a sequence
or collection.
The new method matches one of the most common uses of `compactMap`,
which is to only remove `nil`s without transforming the elements
(e.g. `collection.lazy.compactMap { $0 }`).
```swift
let array: [Int?] = [10, nil, 30, nil, 2, 3, nil, 5]
let withNoNils = array.compacted()
// Array(withNoNils) == [10, 30, 2, 3, 5]
```
The type returned by `compacted()` lazily computes the non-`nil` elements
without requiring a user to provide a closure or use the `.lazy` property.
## Detailed Design
The `compacted()` methods has two overloads:
```swift
extension Sequence {
public func compacted<Unwrapped>() -> CompactedSequence<Self, Unwrapped>
where Element == Unwrapped?
}
extension Collection {
public func compacted<Unwrapped>() -> CompactedCollection<Self, Unwrapped>
where Element == Unwrapped?
}
```
The `Sequence` version of `compacted()` returns a `CompactedSequence` type,
while the `Collection` version returns `CompactedCollection`. The collection
has conditional conformance to `BidirectionalCollection` when the base
collection conforms, and both have conditional conformance to
`LazySequenceProtocol` when the base collection conforms.
### Naming
The name `compacted()` matches the existing method `compactMap`,
which is commonly used to extract only the non-`nil` values
without mapping them to a different type.
+13 -12
View File
@@ -16,9 +16,9 @@ for x in (1...3).cycled(times: 3) {
// Prints 1 through 3 three times
```
`cycled(times:)` combines two other existing standard library functions
(`repeatElement` and `joined`) to provide a more expressive way of repeating a
collection's elements a limited number of times.
`cycled(times:)` provides a more expressive way of repeating a
collection's elements a limited number of times than
combining `repeatElement(_:count:)` and `joined()`.
## Detailed Design
@@ -26,19 +26,20 @@ Two new methods are added to collections:
```swift
extension Collection {
func cycled() -> Cycle<Self>
func cycled() -> CycledSequence<Self>
func cycled(times: Int) -> FlattenSequence<Repeated<Self>>
func cycled(times: Int) -> CycledTimesCollection<Self>
}
```
The new `Cycle` type is a sequence only, given that the `Collection` protocol
design makes infinitely large types impossible/impractical. `Cycle` also
conforms to `LazySequenceProtocol` when the base type conforms.
The new `CycledSequence` type is a sequence only, given that the `Collection`
protocol design makes infinitely large types impossible/impractical.
`CycledSequence` also conforms to `LazySequenceProtocol` when the base type
conforms.
Note that despite its name, the returned `FlattenSequence` will always have
`Collection` conformance, and will have `BidirectionalCollection` conformance
when called on a bidirectional collection.
The `CycledTimesCollection` type always has `Collection` conformance, with
`BidirectionalCollection`, `RandomAccessCollection`, and `LazySequenceProtocol`
conformance when the base type conforms.
### Complexity
@@ -61,4 +62,4 @@ anything that matches the `cycled(times:)` behavior.
`cycled(times:)` here.
**Python:** Python’s `itertools` includes a `cycle` method, which caches the
elements of the iterator on the first pass.
elements of the iterator on the first pass.
+85
View File
@@ -0,0 +1,85 @@
# First Non-Nil
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/FirstNonNil.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/FirstNonNilTests.swift)]
Returns the first non-`nil` result obtained from applying the given
transformation to the elements of the sequence.
```swift
let strings = ["three", "3.14", "-5", "2"]
if let firstInt = strings.firstNonNil({ Int($0) }) {
print(firstInt)
// -5
}
```
Like `first(where:)`, this method stops iterating the sequence once a match is
found. Use `firstNonNil(_:)` to avoid having to apply a transformation twice:
```swift
let strings = ["three", "3.14", "-5", "2"]
if let firstIntAsString = strings.first(where: { Int($0) != nil }) {
let firstInt = Int(firstIntAsString)! // :(
// ...
}
```
This method's behavior can also be approximated using `compactMap(_:)`:
```swift
let strings = ["three", "3.14", "-5", "2"]
if let firstInt = strings.compactMap({ Int($0) }).first {
// ...
}
```
However, unlike `firstNonNil(_:)` and `first(where:)`, `compactMap(_:)` does not
stop iterating the sequence once the first match is found. Adding `.lazy` fixes
this, at the cost of requiring an escaping closure that you cannot `throw` from:
```swift
let strings = ["three", "3.14", "-5", "2"]
if let firstInt = strings.lazy.compactMap({ Int($0) }).first {
// ...
}
```
## Detailed Design
The `firstNonNil(_:)` method is added as an extension method on the `Sequence`
protocol:
```swift
public extension Sequence {
func firstNonNil<Result>(
_ transform: (Element) throws -> Result?
) rethrows -> Result?
}
```
### Complexity
`firstNonNil(_:)` is an O(*n*) operation, where *n* is the number of
elements at the start of the sequence that result in `nil` when applying the
transformation.
### Naming
Some alternative names were considered:
* `compactMapFirst(_:)`
* `first(mapping:)`
* `firstSome(_:)`
* `firstMap(_:)`
### Comparison with other languages
**Haskell**: Haskell includes the `firstJust` method, which has the same
semantics as the `firstNonNil(_:)` method.
**Rust**: Rust includes the `find_map` method, which has the same semantics as
the `firstNonNil(_:)` method.
**Scala**: Scala includes the `collectFirst` method, which has the same
semantics as the `firstNonNil(_:)` method.
+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.
+5 -5
View File
@@ -21,15 +21,15 @@ for (i, n) in numbers.indexed() {
## Detailed Design
The `indexed` method returns an `Indexed` type:
The `indexed` method returns an `IndexedCollection` type:
```swift
extension Collection {
func indexed() -> Indexed<Self>
func indexed() -> IndexedCollection<Self>
}
```
`Indexed` scales from a collection up to a random-access collection, depending on
its base type. `Indexed` also conforms to `LazySequenceProtocol` when the base type
conforms.
`IndexedCollection` scales from a collection up to a random-access collection,
depending on its base type. `Indexed` also conforms to `LazySequenceProtocol`
when the base type conforms.
+58
View File
@@ -0,0 +1,58 @@
# Intersperse
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Intersperse.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/IntersperseTests.swift)]
Place a given value in between each element of the sequence.
```swift
let numbers = [1, 2, 3].interspersed(with: 0)
// Array(numbers) == [1, 0, 2, 0, 3]
let letters = "ABCDE".interspersed(with: "-")
// String(letters) == "A-B-C-D-E"
let empty = [].interspersed(with: 0)
// Array(empty) == []
```
`interspersed(with:)` takes a separator value and inserts it in between every
element in the sequence.
## Detailed Design
A new method is added to sequence:
```swift
extension Sequence {
func interspersed(with separator: Element) -> InterspersedSequence<Self>
}
```
The new `InterspersedSequence` type represents the sequence when the separator
is inserted between each element. `InterspersedSequence` conforms to
`Collection`, `BidirectionalCollection`, `RandomAccessCollection` and
`LazySequenceProtocol` when the base sequence conforms to those respective
protocols.
### Complexity
Calling these methods is O(_1_).
### Naming
This method’s and type’s name match the term of art used in other languages
and libraries.
### Comparison with other languages
**[Haskell][Haskell]:** Has an `intersperse` function which takes an element
and a list and 'intersperses' that element between the elements of the list.
**[Rust][Rust]:** Has a function called `intersperse` to insert a particular
value between each element.
<!-- Link references for other languages -->
[Haskell]: https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-List.html#v:intersperse
[Rust]: https://docs.rs/itertools/0.9.0/itertools/trait.Itertools.html#method.intersperse
+100
View File
@@ -0,0 +1,100 @@
# Joined
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Joined.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/JoinedTests.swift)]
Concatenate a sequence of sequences, inserting a separator between each element.
The separator can be either a single element or a sequence of elements, and it
can optionally depend on the sequences right before and after it by returning it
from a closure:
```swift
for number in [[1], [2, 3], [4, 5, 6]].joined(by: 100) {
print(number)
}
// 1, 100, 2, 3, 100, 4, 5, 6
for number in [[10], [20, 30], [40, 50, 60]].joined(by: { [$0.count, $1.count] }) {
print(number)
}
// 10, 1, 2, 20, 30, 2, 3, 40, 50, 60
```
## Detailed Design
The versions that take a closure are executed eagerly and are defined on
`Sequence`:
```swift
extension Sequence where Element: Sequence {
public func joined(
by separator: (Element, Element) throws -> Element.Element
) rethrows -> [Element.Element]
public func joined<Separator>(
by separator: (Element, Element) throws -> Separator
) rethrows -> [Element.Element]
where Separator: Sequence, Separator.Element == Element.Element
}
```
The versions that do not take a closure are defined on both `Sequence` and
`Collection` because the resulting collections need to precompute their start
index to ensure O(1) access:
```swift
extension Sequence where Element: Sequence {
public func joined(by separator: Element.Element)
-> JoinedBySequence<Self, CollectionOfOne<Element.Element>>
public func joined<Separator>(
by separator: Separator
) -> JoinedBySequence<Self, Separator>
where Separator: Collection, Separator.Element == Element.Element
}
extension Collection where Element: Sequence {
public func joined(by separator: Element.Element)
-> JoinedByCollection<Self, CollectionOfOne<Element.Element>>
public func joined<Separator>(
by separator: Separator
) -> JoinedByCollection<Self, Separator>
where Separator: Collection, Separator.Element == Element.Element
}
```
Note that the sequence separator of the closure-less version defined on
`Sequence` is required to be a `Collection`, because a plain `Sequence` cannot in
general be iterated over multiple times.
The closure-based versions also have lazy variants that are defined on both
lazy sequences and collections for the same reason as explained above:
```swift
extension LazySequenceProtocol where Element: Sequence {
public func joined(
by separator: @escaping (Element, Element) -> Element.Element
) -> JoinedByClosureSequence<Self, CollectionOfOne<Element.Element>>
public func joined<Separator>(
by separator: @escaping (Element, Element) -> Separator
) -> JoinedByClosureSequence<Self, Separator>
}
extension LazySequenceProtocol where Self: Collection, Element: Collection {
public func joined(
by separator: @escaping (Element, Element) -> Element.Element
) -> JoinedByClosureCollection<Self, CollectionOfOne<Element.Element>>
public func joined<Separator>(
by separator: @escaping (Element, Element) -> Separator
) -> JoinedByClosureCollection<Self, Separator>
}
```
`JoinedBySequence`, `JoinedByClosureSequence`, `JoinedByCollection`, and
`JoinedByClosureCollection` conform to `LazySequenceProtocol` when the base
sequence conforms. `JoinedByCollection` and `JoinedByClosureCollection` also
conform to `BidirectionalCollection` when the base collection conforms.
+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 alterative, 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`.
+109
View File
@@ -0,0 +1,109 @@
# Minima and/or Maxima
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/MinMax.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/MinMaxTests.swift)]
Returns the smallest or largest elements of this collection, sorted by a
predicate or in the order defined by `Comparable` conformance.
If you need to sort a collection but only need access to a prefix or suffix of
the sorted elements, using these methods can give you a performance boost over
sorting the entire collection. The order of equal elements is guaranteed to be
preserved.
```swift
let numbers = [7, 1, 6, 2, 8, 3, 9]
let smallestThree = numbers.min(count: 3, sortedBy: <)
// [1, 2, 3]
```
Return the smallest and largest elements of this sequence, determined by a
predicate or in the order defined by `Comparable` conformance.
If you need both the minimum and maximum values of a collection, using these
methods can give you a performance boost over running the `min` method followed
by the `max` method. Plus they work with single-pass sequences.
```swift
let numbers = [7, 1, 6, 2, 8, 3, 9]
if let (smallest, largest) = numbers.minAndMax(by: <) {
// Work with 1 and 9....
}
```
## Detailed Design
This adds the `Collection` methods shown below:
```swift
extension Collection {
public func min(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element]
public func max(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element]
}
```
And the `Sequence` method:
```swift
extension Sequence {
public func minAndMax(
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> (min: Element, max: Element)?
}
```
Additionally, versions of these methods for `Comparable` types are also
provided:
```swift
extension Collection where Element: Comparable {
public func min(count: Int) -> [Element]
public func max(count: Int) -> [Element]
}
extension Sequence where Element: Comparable {
public func minAndMax() -> (min: Element, max: Element)?
}
```
### Complexity
The algorithm used for minimal- or maximal-ordered subsets is based on
[Soroush Khanlou's research on this matter](https://khanlou.com/2018/12/analyzing-complexity/).
The total complexity is `O(k log k + nk)`, which will result in a runtime close
to `O(n)` if *k* is a small amount. If *k* is a large amount (more than 10% of
the collection), we fall back to sorting the entire array. Realistically, this
means the worst case is actually `O(n log n)`.
Here are some benchmarks we made that demonstrates how this implementation
(SmallestM) behaves when *k* increases (before implementing the fallback):
![Benchmark](Resources/SortedPrefix/FewElements.png)
![Benchmark 2](Resources/SortedPrefix/ManyElements.png)
The algorithm used for simultaneous minimum and maximum is slightly optimized.
At each iteration, two elements are read, their relative order is determined,
then each is compared against exactly one of the current extrema for potential
replacement. When a comparison predicate has to analyze every component of both
operands, the optimized algorithm isn't much faster than the straightforward
approach. But when a predicate only needs to compare a small part of each
instance, the optimization shines through.
### Comparison with other languages
**C++:** The `<algorithm>` library defines a `partial_sort` function where the
entire array is returned using a partial heap sort. It also defines a
`minmax_element` function that scans a range for its minimal and maximal
elements.
**Python:** Defines a `heapq` priority queue that can be used to manually
achieve the same result.
+24 -1
View File
@@ -42,6 +42,20 @@ let p = numbers.partitioningIndex(where: { $0.isMultiple(of: 20) })
// numbers[p...] = [20, 40, 60]
```
The standard library’s existing `filter(_:)` method provides functionality to
get the elements that do match a given predicate. `partitioned(by:)` returns
both the elements that match the predicate as well as those that don’t, as a
tuple.
```swift
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let (longNames, shortNames) = cast.partitioned(by: { $0.count < 5 })
print(longNames)
// Prints "["Vivien", "Marlon"]"
print(shortNames)
// Prints "["Kim", "Karl"]"
```
## Detailed Design
All mutating methods are declared as extensions to `MutableCollection`.
@@ -69,11 +83,17 @@ extension Collection {
where belongsInSecondPartition: (Element) throws -> Bool
) rethrows -> Index
}
extension Sequence {
public func partitioned(
by predicate: (Element) throws -> Bool
) rethrows -> (falseElements: [Element], trueElements: [Element])
}
```
### Complexity
The existing partition is an O(_n_) operations, where _n_ is the length of the
The existing partition is an O(_n_) operation, where _n_ is the length of the
range to be partitioned, while the stable partition is O(_n_ log _n_). Both
partitions have algorithms with improved performance for bidirectional
collections, so it would be ideal for those to be customization points were they
@@ -82,6 +102,9 @@ to eventually land in the standard library.
`partitioningIndex(where:)` is a slight generalization of a binary search, and
is an O(log _n_) operation for random-access collections; O(_n_) otherwise.
`partitioned(by:)` is an O(_n_) operation, where _n_ is the number of elements
in the original sequence.
### Comparison with other languages
**C++:** The `<algorithm>` library defines `partition`, `stable_partition`, and
+64 -15
View File
@@ -3,7 +3,7 @@
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Permutations.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/PermutationsTests.swift)]
A type that computes permutations of a collection’s elements, or of a subset of
Methods that compute permutations of a collection’s elements, or of a subset of
those elements.
The `permutations(ofCount:)` method, when called without the `ofCount`
@@ -60,29 +60,79 @@ for perm in numbers2.permutations() {
// [10, 10, 20]
```
To generate only unique permutations, use the `uniquePermutations(ofCount:)` method:
```swift
for perm in numbers2.uniquePermutations() {
print(perm)
}
// [20, 10, 10]
// [10, 20, 10]
// [10, 10, 20]
```
Given a range, the methods return a sequence of all the different permutations of the given sizes of a collection’s elements in increasing order of size.
```swift
let numbers = [10, 20, 30]
for perm in numbers.permutations(ofCount: 0...) {
print(perm)
}
// []
// [10]
// [20]
// [30]
// [10, 20]
// [10, 30]
// [20, 10]
// [20, 30]
// [30, 10]
// [30, 20]
// [10, 20, 30]
// [10, 30, 20]
// [20, 10, 30]
// [20, 30, 10]
// [30, 10, 20]
// [30, 20, 10]
```
## Detailed Design
The `permutations(ofCount:)` method is declared as a `Collection` extension,
and returns a `Permutations` type:
The `permutations(ofCount:)` and `uniquePermutations(ofCount:)` methods are
declared as `Collection` extensions, and return `PermutationsSequence` and
`UniquePermutationsSequence` instances, respectively:
```swift
extension Collection {
public func permutations(ofCount k: Int? = nil) -> Permutations<Self>
public func permutations(ofCount k: Int? = nil) -> PermutationsSequence<Self>
public func permutations<R>(ofCount kRange: R) -> PermutationsSequence<Self>
where R: RangeExpression, R.Bound == Int
}
extension Collection where Element: Hashable {
public func uniquePermutations(ofCount k: Int? = nil) -> UniquePermutationsSequence<Self>
public func uniquePermutations<R>(ofCount kRange: R) -> UniquePermutationsSequence<Self>
where R: RangeExpression, R.Bound == Int
}
```
Since the `Permutations` type needs to store an array of the collection’s
indices and mutate the array to generate each permutation, `Permutations` only
has `Sequence` conformance. Adding `Collection` conformance would require
Since both result types need to store an array of the collection’s
indices and mutate the array to generate each permutation, they only
have `Sequence` conformance. Adding `Collection` conformance would require
storing the array in the index type, which would in turn lead to copying the
array at every index advancement. `Combinations` does conform to
`LazySequenceProtocol` when the base type conforms.
array at every index advancement. The `PermutationsSequence` and
`UniquePermutationsSequence` types conforms to `LazySequenceProtocol` when their
base type conforms.
### Complexity
Calling `permutations()` is an O(1) operation. Creating the iterator for a
`Permutations` instance and each call to `Permutations.Iterator.next()` is an
O(_n_) operation.
`PermutationsSequence` instance and each call to
`PermutationsSequence.Iterator.next()` is an O(_n_) operation.
Calling `uniquePermutations()` is an O(_n_) operation, because it preprocesses
the collection to find duplicate elements. Creating the iterator for and each
call to `next()` is also an O(_n_) operation.
### Naming
@@ -92,9 +142,8 @@ See the ["Naming" section for `combinations(ofCount:)`](Combinations.md#naming)
**C++:** The `<algorithm>` library defines a `next_permutation` function that
advances an array of comparable values through their lexicographic orderings.
This function is tricky to use and understand, so while it’s included in
`swift-algorithms` as an implementation detail of the `Permutations` type, it
isn’t public.
This function is very similar to the `uniquePermutations(ofCount:)` method.
**Rust/Ruby/Python:** Rust, Ruby, and Python all define functions with
essentially the same semantics as the method described here.
essentially the same semantics as the `permutations(ofCount:)` method
described here.
+7 -7
View File
@@ -25,26 +25,26 @@ When either collection is empty, the resulting wrapper collection is also empty.
## Detailed Design
The `product` function takes (at minimum) a sequence and a collection and
returns a `Product2` type:
returns a `Product2Sequence` type:
```swift
public func product<Base1: Sequence, Base2: Collection>(
_ s1: Base1, _ s2: Base2
) -> Product2<Base1, Base2>
) -> Product2Sequence<Base1, Base2>
```
We require `Collection` conformance for `Base2`, since it needs to be iterated
over multiple times. `Base1`, by contrast, is only iterated over a single time,
so it can be a sequence.
The `Product2` type wraps the base sequence and collection, and acts as a
sequence in the base case, upgrading to a collection, a bidirectional
The `Product2Sequence` type wraps the base sequence and collection, and acts as
a sequence in the base case, upgrading to a collection, a bidirectional
collection, and a random-access collection when both base collections have those
conformances.
We don't provide higher arities (like `Product3`, `Product4`, etc.) at this
time to match the standard library's `Zip2` type. Users can compose multiple
calls to `product` if they would like higher arities.
We don't provide higher arities (like `Product3Sequence`, `Product4Sequence`,
etc.) at this time to match the standard library's `Zip2Sequence` type. Users
can compose multiple calls to `product` if they would like higher arities.
### Complexity
+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.
+2 -2
View File
@@ -17,7 +17,7 @@ source.randomSample(count: 4)
// e.g. [30, 10, 70, 50]
source.randomStableSample(count: 4)
// e.g. [20, 30, 80, 100]
//
var rng = SplitMix64(seed: 0)
source.randomSample(count: 4, using: &rng)
```
@@ -146,4 +146,4 @@ performance characteristics as the collection itself, so a user can call
The stable version of sampling could theoretically return a lazy wrapper
instead of eagerly creating the sample. However, this isn’t well-motivated and
poses some challenges, such as needing to store a copy of the random generator
and potentially needing to cache the randomly-generated values.
and potentially needing to cache the randomly-generated values.
+133
View File
@@ -0,0 +1,133 @@
# Reductions
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Reductions.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/ReductionsTests.swift)]
Produces all the intermediate results of reducing a sequence's elements using a
closure.
```swift
let exclusiveRunningTotal = (1...5).reductions(0, +)
print(exclusiveRunningTotal)
// prints [0, 1, 3, 6, 10, 15]
let intoRunningTotal = (1...5).reductions(into: 0, +=)
print(intoRunningTotal)
// prints [0, 1, 3, 6, 10, 15]
let inclusiveRunningTotal = (1...5).reductions(+)
print(inclusiveRunningTotal)
// prints [1, 3, 6, 10, 15]
```
## Detailed Design
One trio of methods are added to `LazySequenceProtocol` for a lazily evaluated
sequence and another trio are added to `Sequence` which are eagerly evaluated.
```swift
extension LazySequenceProtocol {
public func reductions<Result>(
_ initial: Result,
_ transform: @escaping (Result, Element) -> Result
) -> ExclusiveReductionsSequence<Result, Self>
public func reductions<Result>(
into initial: Result,
_ transform: @escaping (inout Result, Element) -> Void
) -> ExclusiveReductionsSequence<Result, Self>
public func reductions(
_ transform: @escaping (Element, Element) -> Element
) -> InclusiveReductionsSequence<Self>
}
```
```swift
extension Sequence {
public func reductions<Result>(
_ initial: Result,
_ transform: (Result, Element) throws -> Result
) rethrows -> [Result]
public func reductions<Result>(
into initial: Result,
_ transform: (inout Result, Element) throws -> Void
) rethrows -> [Result]
public func reductions(
_ transform: (Element, Element) throws -> Element
) rethrows -> [Element]
}
```
### Complexity
Calling the lazy methods, those defined on `LazySequenceProtocol`, is O(_1_).
Calling the eager methods, those returning an array, is O(_n_).
### Naming
While the name `scan` is the term of art for this function, it has been
discussed that `reductions` aligns better with the existing `reduce` function
and will aid newcomers that might not know the existing `scan` term.
Deprecated `scan` methods have been added for people who are familiar with the
term, so they can easily discover the `reductions` methods via compiler
deprecation warnings.
Below are two quotes from the Swift forum [discussion about SE-0045][SE-0045]
which proposed adding `scan` to the standard library and one from
[issue #25][Issue 25] on the swift-algorithms GitHub project. These provide
the reasoning to use the name `reductions`.
[Brent Royal-Gordon][Brent_Royal-Gordon]:
> I really like the `reduce`/`reductions` pairing instead of `reduce`/`scan`;
it does a really good job of explaining the relationship between the two
functions.
[David Rönnqvist][David Rönnqvist]:
> As other have already pointed out, I also feel that `scan` is the least
intuitive name among these and that the `reduce`/`reductions` pairing would do
a good job at explaining the relation between the two.
[Kyle Macomber][Kyle Macomber]:
> As someone unfamiliar with the prior art, `reductions` strikes me as very
approachable—I feel like I can extrapolate the expected behavior purely from my
familiarity with `reduce`.
As part of early discussions, it was decided to have two variants, one which
takes an initial value to use for the first element in the returned sequence,
and another which uses the first value of the base sequence as the initial
value. C++ calls these variants exclusive and inclusive respectively and so
these terms carry through as the name for the lazy sequences;
`ExclusiveReductionsSequence` and `InclusiveReductionsSequence`.
[SE-0045]: https://forums.swift.org/t/review-se-0045-add-scan-prefix-while-drop-while-and-iterate-to-the-stdlib/2382
[Issue 25]: https://github.com/apple/swift-algorithms/issues/25
[Brent_Royal-Gordon]: https://forums.swift.org/t/review-se-0045-add-scan-prefix-while-drop-while-and-iterate-to-the-stdlib/2382/6
[David Rönnqvist]: https://forums.swift.org/t/review-se-0045-add-scan-prefix-while-drop-while-and-iterate-to-the-stdlib/2382/8
[Kyle Macomber]: https://github.com/apple/swift-algorithms/issues/25#issuecomment-709317894
### Comparison with other languages
**C++:** As of C++17, the `<algorithm>` library includes both
[`exclusive_scan`][C++ Exclusive] and [`inclusive_scan`][C++ Inclusive]
functions.
**[Clojure][Clojure]:** Clojure 1.2 added a `reductions` function.
**[Haskell][Haskell]:** Haskell includes a `scan` function for its
`Traversable` type, which is akin to Swift's `Sequence`.
**Python:** Python’s `itertools` includes an `accumulate` method. In version
3.3, a function parameter was added. Version 3.8 added the optional initial
parameter.
**[Rust][Rust]:** Rust provides a `scan` function.
[C++ Exclusive]: https://en.cppreference.com/w/cpp/algorithm/exclusive_scan
[C++ Inclusive]: https://en.cppreference.com/w/cpp/algorithm/inclusive_scan
[Clojure]: http://clojure.github.io/clojure/clojure.core-api.html#clojure.core/reductions
[Haskell]: http://hackage.haskell.org/package/base-4.8.2.0/docs/Prelude.html#v:scanl
[Rust]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.scan
Binary file not shown.

After

Width:  |  Height:  |  Size: 64 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

-64
View File
@@ -1,64 +0,0 @@
# SlidingWindows
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/SlidingWindows.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/SlidingWindowsTests.swift)]
Break a collection into overlapping contiguous window subsequences where
elements are slices from the original collection.
The `slidingWindows(ofCount:)` method takes in a integer size and returns a collection
of subsequences.
```swift
let swift = "swift"
let windowed = swift.slidingWindows(ofCount: 2)
// windowed == [ "sw", "wi", "if", "ft" ]
```
## Detailed Design
The `slidingWindows(ofCount:)` is added as a method on an extension of `Collection`
```swift
extension Collection {
public func slidingWindows(ofCount count: Int) -> SlidingWindows<Self> {
SlidingWindows(base: self, size: count)
}
}
```
If a size larger than the collection length is specified, an empty collection is returned.
The first upper bound is computed eagerly because it determines if the collection
`startIndex` returns `endIndex`.
```swift
[1, 2, 3].slidingWindows(ofCount: 5).isEmpty // true
```
The resulting `SlidingWindows` type is a collection, with conditional conformance to the
`BidirectionalCollection`, and `RandomAccessCollection` when the base collection
conforms.
### Complexity
The call to `slidingWindows(ofCount: k)` is O(_1_) if the collection conforms to
`RandomAccessCollection`, otherwise O(_k_). Access to the next window is O(_1_).
### Naming
The type `SlidingWindows` takes its name from the algorithm, similarly the method takes
it's name from it too `slidingWindows(ofCount: k)`.
The label on the method `ofCount` was chosen to create a consistent feel to the API
available in swift-algorithms repository. Inspiration was taken from
`combinations(ofCount:)` and `permutations(ofCount:)`.
Previously the name `windows` was considered but was deemed to potentially create
ambiguity with the Windows operating system.
### Comparison with other languages
[rust](https://doc.rust-lang.org/std/slice/struct.Windows.html) has
`std::slice::Windows` which is a method available on slices. It has the same
semantics as described here.
+79
View File
@@ -0,0 +1,79 @@
# Split
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Split.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/SplitTests.swift)]
Lazily-evaluating versions of
[`split(maxSplits:omittingEmptySubsequences:whereSeparator:)`](https://developer.apple.com/documentation/swift/sequence/3128814-split)
and [`split(separator:maxSplits:omittingEmptySubsequences:)`](https://developer.apple.com/documentation/swift/sequence/3128818-split),
performing the same operation as their counterparts defined on
`Sequence` and `Collection`, are added to `LazySequence` and
`LazyCollection`. The `LazyCollection` methods allow splitting a
collection without allocating additional storage on the heap.
```swift
// Splitting a lazy sequence.
let numbers = stride(from: 1, through: 16, by: 1)
for subsequence in numbers.lazy.split(
whereSeparator: { $0 % 3 == 0 || $0 % 5 == 0 }
) {
print(subsequence)
}
/* Prints:
[1, 2]
[4]
[7, 8]
[11]
[13, 14]
[16]
*/
// Splitting a lazy collection.
let line = "BLANCHE: I don't want realism. I want magic!"
for subsequence in line.lazy.split(separator: " ") {
print(subsequence)
}
/* Prints
BLANCHE:
I
don't
want
realism.
I
want
magic!
*/
```
## Detailed Design
`LazySequence` and `LazyCollection` are each extended with
`split(maxSplits:omittingEmptySubsequences:whereSeparator:)` and
`split(separator:maxSplits:omittingEmptySubsequences:)`.
The `LazySequence` versions of those methods return an instance of
`SplitSequence`. The `LazyCollection` versions return an instance of
`SplitCollection`.
`SplitSequence` wraps the sequence to be split, and provides an iterator whose
`next` method returns a newly-allocated array containing the elements of each
subsequence in the split sequence in turn.
`SplitCollection` wraps the collection to be split. Its `Index` wraps a range of
base collection indices. `startIndex` is computed at initialization.
Subscripting a `SplitCollection` instance returns the slice of the original
collection which is the subsequence of the split collection at the given index's
position.
### Complexity
Iterating a `SplitSequence` instance is O(_n_) in time and space, since each
subsequence returned is a newly-allocated array.
Iterating a `SplitCollection` instance is O(_n_) in time and O(1) in space,
since each subsequence returned is a slice of the base collection. Since
`startIndex` is computed at initialization, some or all of the time cost may be
paid at initialization. For example, if the base collection contains no elements
determined to be separators, it will be iterated entirely on initialization of
the split collection, and all subsequent operations on the split collection,
such as `index(after:)`, will have complexity O(1).
+70
View File
@@ -0,0 +1,70 @@
# Stride
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Stride.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/StrideTests.swift)]
Step over the elements of a sequence elements by a specified amount.
This is available through the `striding(by:)` method on any `Sequence`.
```swift
(0...10).striding(by: 2) // == [0, 2, 4, 6, 8, 10]
```
If the stride is larger than the length of the sequence, the resulting wrapper
only contains the first element.
The stride amount must be a positive value.
## Detailed Design
The `striding(by:)` method is declared in extension of both `Sequence` and
`Collection`:
```swift
extension Sequence {
public func striding(by step: Int) -> StridingSequence<Self>
}
extension Collection {
public func striding(by step: Int) -> StridingCollection<Self>
}
```
The reason for this distinction is subtle. The `StridingSequence.Iterator` type
is unable to skip over multiple elements of the wrapped iterator at once since
that's not part of `IteratorProtocol`'s interface. In order to efficiently
stride over collections that provide a fast way of skipping multiple elements at
once, the `StridingCollection` type was added which does not provide a custom
`Iterator` type and therefore always strides over the underlying collection in
the fastest way possible. See the related
[GitHub issue](https://github.com/apple/swift-algorithms/issues/63) for more
information.
A careful thought was given to the composition of these strides by giving a
custom implementation to `index(_:offsetBy:limitedBy)` which multiplies the
offset by the stride amount.
```swift
base.index(i.base, offsetBy: distance * stride, limitedBy: base.endIndex)
```
The following two lines of code are equivalent, including performance:
```swift
(0...10).striding(by: 6)
(0...10).striding(by: 2).stride(by: 3)
```
### Complexity
The call to `striding(by: k)` is always O(_1_) and access to the next value in
the stride is O(_1_) if the collection conforms to `RandomAccessCollection`,
otherwise O(_k_).
### Comparison with other languages
[rust has `Strided`](https://docs.rs/strided/0.2.9/strided/) available in a crate.
[c++ has std::slice::stride](http://www.cplusplus.com/reference/valarray/slice/stride/)
The semantics of `striding` described in this documentation are equivalent.
+39
View File
@@ -0,0 +1,39 @@
# Suffix
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Suffix.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/SuffixTests.swift)]
This function returns a subsequence containing the elements from the end of the
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]
```
## Detailed Design
The `suffix(while:)` function is added as a method on an extension of
`BidirectionalCollection`.
```swift
extension BidirectionalCollection {
public func suffix(while predicate: (Element) throws -> Bool) rethrows -> SubSequence
}
```
This method requires `BidirectionalCollection` for an efficient implementation
which visits as few elements as possible. Swift's protocol allows for backward
traversal of a collection as well as access to *last* property of a collection.
### Complexity
Calling this method is O(*n*), where *n* is the length of the collection.
### Naming
The function's name resembles that of an existing Swift function
`prefix(while:)`, which performs same operation however in the forward direction
of the collection. Hence, as this function traverses from the end of the
collection, `suffix(while:)` is an appropriate name.
+92 -36
View File
@@ -3,50 +3,97 @@
[[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(where:)` to get a substring without the white space at the beginning and end of the string.
This example uses `trimming(while:)` to get a substring without the white space
at the beginning and end of the string.
```swift
let myString = " hello, world "
print(myString.trimming(where: \.isWhitespace)) // "hello, world"
print(myString.trimming(while: \.isWhitespace)) // "hello, world"
let results = [2, 10, 11, 15, 20, 21, 100].trimming(where: { $0.isMultiple(of: 2) })
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 BidirectionalCollection {
extension Collection {
func trimmingPrefix(while predicate: (Element) throws -> Bool) rethrows -> SubSequence
}
public func trimming(where predicate: (Element) throws -> Bool) rethrows -> SubSequence
extension BidirectionalCollection {
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 {
let trimmedInput = input.trimming(where: { ... }) // Uses least-efficient implementation.
let trimmedInput = input.trimming(while: { ... }) // Uses least-efficient implementation.
}
func myAlgorithm2<Input>(input: Input) where Input: BidirectionalCollection {
let trimmedInput = input.trimming(where: { ... }) // Uses most-efficient implementation.
let trimmedInput = input.trimming(while: { ... }) // Uses most-efficient implementation.
}
```
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.
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.
#### Supporting Methods
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
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
}
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
@@ -54,7 +101,8 @@ Calling this method is O(_n_).
### Naming
The name `trim` has precedent in other programming languages. Another popular alternative might be `strip`.
The name `trim` has precedent in other programming languages. Another popular
alternative might be `strip`.
| Example usage | Languages |
|-|-|
@@ -79,36 +127,44 @@ The name `trim` has precedent in other programming languages. Another popular al
| TRIM(''string'') | SQL |
| String.trim ''string'' | OCaml 4+ |
Note: This is an abbreviated list from Wikipedia. [Full table](https://en.wikipedia.org/wiki/Comparison_of_programming_languages_(string_functions)#trim)
Note: This is an abbreviated list from Wikipedia.
[Full table](https://en.wikipedia.org/wiki/Comparison_of_programming_languages_(string_functions)#trim)
The standard library includes a variety of methods which perform similar operations:
The standard library includes a variety of methods which perform similar
operations:
- Firstly, there are `dropFirst(Int)` and `dropLast(Int)`. These return slices but do not support user-defined predicates.
If the collection's `count` is less than the number of elements to drop, they return an empty slice.
- Secondly, there is `drop(while:)`, which also returns a slice and is equivalent to a 'left-trim' (trimming from the head but not the tail).
If the entire collection is dropped, this method returns an empty slice.
- Thirdly, there are `removeFirst(Int)` and `removeLast(Int)` which do not return slices and actually mutate the collection.
If the collection's `count` is less than the number of elements to remove, this method triggers a runtime error.
- Lastly, there are the `popFirst()` and `popLast()` methods, which work like `removeFirst()` and `removeLast()`,
except they do not trigger a runtime error for empty collections.
- Firstly, there are `dropFirst(Int)` and `dropLast(Int)`. These return slices
but do not support user-defined predicates. If the collection's `count` is less
than the number of elements to drop, they return an empty slice.
- Secondly, there is `drop(while:)`, which also returns a slice and is
equivalent to a 'left-trim' (trimming from the head but not the tail). If the
entire collection is dropped, this method returns an empty slice.
- Thirdly, there are `removeFirst(Int)` and `removeLast(Int)` which do not
return slices and actually mutate the collection. If the collection's `count` is
less than the number of elements to remove, this method triggers a runtime
error.
- Lastly, there are the `popFirst()` and `popLast()` methods, which work like
`removeFirst()` and `removeLast()`, except they do not trigger a runtime error
for empty collections.
The closest neighbours to this function would be the `drop` family of methods. Unfortunately, unlike `dropFirst(Int)`,
the name `drop(while:)` does not specify which end(s) of the collection it operates on. Moreover, one could easily
The closest neighbours to this function would be the `drop` family of methods.
Unfortunately, unlike `dropFirst(Int)`,the name `drop(while:)` does not specify
which end(s) of the collection it operates on. Moreover, one could easily
mistake code such as:
```swift
let result = myString.drop(while: \.isWhitespace)
```
With a lazy filter that drops _all_ whitespace characters regardless of where they are in the string.
Besides that, the root `trim` leads to clearer, more conscise code, which is more aligned with other programming
languages:
With a lazy filter that drops _all_ whitespace characters regardless of where
they are in the string. Besides that, the root `trim` leads to clearer, more
concise code, which is more aligned with other programming languages:
```swift
// Does `result` contain the input, trimmed of certain elements?
// Or does this code mutate `input` in-place and return the elements which were dropped?
let result = input.dropFromBothEnds(where: { ... })
let result = input.dropFromBothEnds(while: { ... })
// No such ambiguity here.
let result = input.trimming(where: { ... })
let result = input.trimming(while: { ... })
```
+18 -12
View File
@@ -5,38 +5,44 @@
Methods to strip repeated elements from a sequence or collection.
The `uniqued()` method returns an array, dropping duplicate elements
from a sequence. The `uniqued(on:)` method does the same, using
the result of the given closure to determine the "uniqueness" of each
element.
The `uniqued()` method returns a sequence, dropping duplicate elements from a
sequence. The `uniqued(on:)` method does the same, using the result of the given
closure to determine the "uniqueness" of each element.
```swift
let numbers = [1, 2, 3, 3, 2, 3, 3, 2, 2, 2, 1]
let unique = numbers.uniqued()
// unique == [1, 2, 3]
// Array(unique) == [1, 2, 3]
```
## Detailed Design
Both methods are available for sequences, with the simplest limited to
when the element type conforms to `Hashable`. Both methods preserve
the relative order of the elements.
Both methods are available for sequences, with the simplest limited to when the
element type conforms to `Hashable`. Both methods preserve the relative order of
the elements. `uniqued(on:)` has a matching lazy version that is added to
`LazySequenceProtocol`.
```swift
extension Sequence where Element: Hashable {
func uniqued() -> [Element]
func uniqued() -> UniquedSequence<Self, Element>
}
extension Sequence {
func uniqued<T>(on: (Element) throws -> T) rethrows -> [Element]
where T: Hashable
func uniqued<Subject>(on projection: (Element) throws -> Subject) rethrows -> [Element]
where Subject: Hashable
}
extension LazySequenceProtocol {
func uniqued<Subject>(on projection: @escaping (Element) -> Subject) -> UniquedSequence<Self, Subject>
where Subject: Hashable
}
```
### Complexity
The `uniqued` methods are O(_n_) in both time and space complexity.
The eager `uniqued(on:)` method is O(_n_) in both time and space complexity. The
lazy versions are O(_1_).
### Comparison with other languages
+59
View File
@@ -0,0 +1,59 @@
# Windows
[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Windows.swift) |
[Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/WindowsTests.swift)]
Break a collection into overlapping subsequences where
elements are slices from the original collection.
The `windows(ofCount:)` method takes a size as a parameter and returns a
collection of subsequences. Each element of the returned collection is a
successive overlapping slice of the given size.
```swift
let swift = "swift"
let windowed = swift.windows(ofCount: 2)
// Array(windowed) == [ "sw", "wi", "if", "ft" ]
```
## Detailed Design
The `windows(ofCount:)` method is added as an extension `Collection` method:
```swift
extension Collection {
public func windows(ofCount count: Int) -> WindowsOfCountCollection<Self>
}
```
If a size larger than the collection's length is specified, the returned
collection is empty.
```swift
[1, 2, 3].windows(ofCount: 5).isEmpty // true
```
The resulting `WindowsOfCountCollection` type is a collection, with conditional
conformance to the `BidirectionalCollection`, `RandomAccessCollection`, and
`LazySequenceProtocol` protocols when the base collection conforms.
### Complexity
The call to `windows(ofCount: k)` is O(1) if the collection conforms to
`RandomAccessCollection`, otherwise O(_k_). Access to each successive window is
O(1).
### Naming
The method and type name take their names from the sliding windows algorithm.
The `ofCount` parameter label was chosen to create a consistent feel with other
APIs in the `Algorithms` package, specifically with `combinations(ofCount:)`
and `permutations(ofCount:)`.
### Comparison with other languages
[rust](https://doc.rust-lang.org/std/slice/struct.Windows.html) has
`std::slice::Windows` which is a method available on slices. It has the same
semantics as described here.
+2 -2
View File
@@ -1,4 +1,4 @@
// swift-tools-version:5.1
// swift-tools-version:5.4
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Algorithms open source project
@@ -20,7 +20,7 @@ let package = Package(
targets: ["Algorithms"]),
],
dependencies: [
.package(url: "https://github.com/apple/swift-numerics", from: "0.0.1"),
.package(url: "https://github.com/apple/swift-numerics.git", from: "1.0.0"),
],
targets: [
.target(
+39 -45
View File
@@ -2,38 +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 a particular size 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.
```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.
- [`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.
- [`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.
## Documentation
#### Subsetting operations
- [`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.
- [`uniqued()`, `uniqued(on:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Unique.md): The unique elements of a collection, preserving their order.
#### Other useful operations
- [`chunked(by:)`, `chunked(on:)`](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.
- [`indexed()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Indexed.md): Iterate over tuples of a collection's indices and elements.
- [`trimming(where:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Trim.md): Returns a slice by trimming elements from a collection's start and end.
For API documentation, see the library's official documentation in Xocde or on the Web.
- [API documentation][docs]
- [Swift.org announcement][announcement]
- [API Proposals/Guides][guides]
## Adding Swift Algorithms as a Dependency
@@ -41,32 +38,29 @@ 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: "0.0.1"),
.package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
```
Because `Algorithms` is under active development,
source-stability is only guaranteed within minor versions (e.g. between `0.0.3` and `0.0.4`).
If you don't want potentially source-breaking package updates,
use this dependency specification instead:
Include `"Algorithms"` as a dependency for your executable target:
```swift
.package(url: "https://github.com/apple/swift-algorithms", .upToNextMinor(from: "0.0.1")),
.target(name: "<target>", dependencies: [
.product(name: "Algorithms", package: "swift-algorithms"),
]),
```
Finally, include `"Algorithms"` as a dependency for your executable target:
Finally, add `import Algorithms` to your source code.
```swift
let package = Package(
// name, platforms, products, etc.
dependencies: [
.package(url: "https://github.com/apple/swift-algorithms", from: "0.0.1"),
// other dependencies
],
targets: [
.target(name: "<target>", dependencies: [
.product(name: "Algorithms", package: "swift-algorithms"),
]),
// other targets
]
)
```
## Source Stability
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 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
+309
View File
@@ -0,0 +1,309 @@
//===----------------------------------------------------------------------===//
//
// 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 {
/// Returns a sequence of overlapping adjacent pairs of the elements of this
/// sequence.
///
/// In the `AdjacentPairsSequence` returned by this method, the elements of
/// the *i*th pair are the *i*th and *(i+1)*th elements of the underlying
/// sequence. The following example uses the `adjacentPairs()` method to
/// iterate over adjacent pairs of integers:
///
/// for pair in (1...).prefix(5).adjacentPairs() {
/// print(pair)
/// }
/// // Prints "(1, 2)"
/// // Prints "(2, 3)"
/// // Prints "(3, 4)"
/// // Prints "(4, 5)"
///
/// The resulting sequence is empty when called on an empty or single-element
/// sequence.
///
/// - Complexity: O(1)
@inlinable
public func adjacentPairs() -> AdjacentPairsSequence<Self> {
AdjacentPairsSequence(base: self)
}
}
extension Collection {
/// Returns a collection of overlapping adjacent pairs of the elements of this
/// collection.
///
/// In an `AdjacentPairsCollection`, the elements of the *i*th pair are the
/// *i*th and *(i+1)*th elements of the underlying sequence. The following
/// example uses the `adjacentPairs()` method to iterate over adjacent pairs
/// of integers:
///
/// for pair in (1...5).adjacentPairs() {
/// print(pair)
/// }
/// // Prints "(1, 2)"
/// // Prints "(2, 3)"
/// // Prints "(3, 4)"
/// // Prints "(4, 5)"
///
/// The resulting collection is empty when called on an empty or
/// single-element collection.
///
/// - Complexity: O(1)
@inlinable
public func adjacentPairs() -> AdjacentPairsCollection<Self> {
AdjacentPairsCollection(base: self)
}
}
/// A sequence of adjacent pairs of elements built from an underlying sequence.
///
/// Use the `adjacentPairs()` method on a sequence to create an
/// `AdjacentPairsSequence` instance.
public struct AdjacentPairsSequence<Base: Sequence> {
@usableFromInline
internal let base: Base
/// Creates an instance that makes pairs of adjacent elements from `base`.
@inlinable
internal init(base: Base) {
self.base = base
}
}
extension AdjacentPairsSequence {
/// The iterator for an `AdjacentPairsSequence` or `AdjacentPairsCollection`
/// instance.
public struct Iterator {
@usableFromInline
internal var base: Base.Iterator
@usableFromInline
internal var previousElement: Base.Element?
@inlinable
internal init(base: Base.Iterator) {
self.base = base
}
}
}
extension AdjacentPairsSequence.Iterator: IteratorProtocol {
public typealias Element = (Base.Element, Base.Element)
@inlinable
public mutating func next() -> Element? {
if previousElement == nil {
previousElement = base.next()
}
guard let previous = previousElement, let next = base.next() else {
return nil
}
previousElement = next
return (previous, next)
}
}
extension AdjacentPairsSequence: Sequence {
@inlinable
public func makeIterator() -> Iterator {
Iterator(base: base.makeIterator())
}
@inlinable
public var underestimatedCount: Int {
Swift.max(0, base.underestimatedCount - 1)
}
}
extension AdjacentPairsSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
/// A collection of adjacent pairs of elements built from an underlying
/// collection.
///
/// Use the `adjacentPairs()` method on a collection to create an
/// `AdjacentPairsCollection` instance.
public struct AdjacentPairsCollection<Base: Collection> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let secondBaseIndex: Base.Index
@inlinable
internal init(base: Base) {
self.base = base
self.secondBaseIndex = base.isEmpty
? base.endIndex
: base.index(after: base.startIndex)
}
}
extension AdjacentPairsCollection {
/// A position in an `AdjacentPairsCollection` instance.
public struct Index: Comparable {
@usableFromInline
internal var first: Base.Index
@usableFromInline
internal var second: Base.Index
@inlinable
internal init(first: Base.Index, second: Base.Index) {
self.first = first
self.second = second
}
@inlinable
public static func == (lhs: Index, rhs: Index) -> Bool {
lhs.first == rhs.first
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
lhs.first < rhs.first
}
}
}
extension AdjacentPairsCollection: Collection {
@inlinable
public var startIndex: Index {
Index(
first: secondBaseIndex == base.endIndex ? base.endIndex : base.startIndex,
second: secondBaseIndex)
}
@inlinable
public var endIndex: Index {
Index(first: base.endIndex, second: base.endIndex)
}
@inlinable
public subscript(position: Index) -> (Base.Element, Base.Element) {
(base[position.first], base[position.second])
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i != endIndex, "Can't advance beyond endIndex")
let next = base.index(after: i.second)
return next == base.endIndex
? endIndex
: Index(first: i.second, second: next)
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return i }
guard let result = distance > 0
? offsetForward(i, by: distance, limitedBy: endIndex)
: offsetBackward(i, by: -distance, limitedBy: startIndex)
else { fatalError("Index out of bounds") }
return result
}
@inlinable
public func index(
_ i: Index, offsetBy distance: Int, limitedBy limit: Index
) -> Index? {
guard distance != 0 else { return i }
guard limit != i else { return nil }
if distance > 0 {
let limit = limit > i ? limit : endIndex
return offsetForward(i, by: distance, limitedBy: limit)
} else {
let limit = limit < i ? limit : startIndex
return offsetBackward(i, by: -distance, limitedBy: limit)
}
}
@inlinable
internal func offsetForward(
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit > i)
guard let newFirst = base.index(i.second, offsetBy: distance - 1, limitedBy: limit.first),
newFirst != base.endIndex
else { return nil }
let newSecond = base.index(after: newFirst)
precondition(newSecond <= base.endIndex, "Can't advance beyond endIndex")
return newSecond == base.endIndex
? endIndex
: Index(first: newFirst, second: newSecond)
}
@inlinable
internal func offsetBackward(
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit < i)
let offset = i == endIndex ? 0 : 1
guard let newSecond = base.index(
i.first,
offsetBy: -(distance - offset),
limitedBy: limit.second)
else { return nil }
let newFirst = base.index(newSecond, offsetBy: -1)
precondition(newFirst >= base.startIndex, "Can't move before startIndex")
return Index(first: newFirst, second: newSecond)
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
// While there's a 2-step gap between the `first` base index values in
// `endIndex` and the penultimate index of this collection, the `second`
// base index values are consistently one step apart throughout the
// entire collection.
base.distance(from: start.second, to: end.second)
}
@inlinable
public var count: Int {
Swift.max(0, base.count - 1)
}
}
extension AdjacentPairsCollection: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
public func index(before i: Index) -> Index {
precondition(i != startIndex, "Can't offset before startIndex")
let second = i == endIndex
? base.index(before: base.endIndex)
: i.first
let first = base.index(before: second)
return Index(first: first, second: second)
}
}
extension AdjacentPairsCollection: RandomAccessCollection
where Base: RandomAccessCollection {}
extension AdjacentPairsCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
extension AdjacentPairsCollection.Index: Hashable where Base.Index: Hashable {
@inlinable
public func hash(into hasher: inout Hasher) {
hasher.combine(first)
}
}
+84 -90
View File
@@ -10,23 +10,26 @@
//===----------------------------------------------------------------------===//
/// A concatenation of two sequences with the same element type.
public struct Chain2<Base1: Sequence, Base2: Sequence>
public struct Chain2Sequence<Base1: Sequence, Base2: Sequence>
where Base1.Element == Base2.Element
{
/// The first sequence in this chain.
public let base1: Base1
@usableFromInline
internal let base1: Base1
/// The second sequence in this chain.
public let base2: Base2
@usableFromInline
internal let base2: Base2
@inlinable
internal init(base1: Base1, base2: Base2) {
self.base1 = base1
self.base2 = base2
}
}
extension Chain2: Sequence {
/// The iterator for a `Chain` sequence.
extension Chain2Sequence: Sequence {
/// The iterator for a `Chain2Sequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var iterator1: Base1.Iterator
@@ -34,8 +37,8 @@ extension Chain2: Sequence {
@usableFromInline
internal var iterator2: Base2.Iterator
@usableFromInline
internal init(_ concatenation: Chain2) {
@inlinable
internal init(_ concatenation: Chain2Sequence) {
iterator1 = concatenation.base1.makeIterator()
iterator2 = concatenation.base2.makeIterator()
}
@@ -52,8 +55,8 @@ extension Chain2: Sequence {
}
}
extension Chain2: Collection where Base1: Collection, Base2: Collection {
/// A position in a `Chain` collection.
extension Chain2Sequence: Collection where Base1: Collection, Base2: Collection {
/// A position in a `Chain2Sequence` instance.
public struct Index: Comparable {
// The internal index representation, which can either be an index of the
// first collection or the second. The `endIndex` of the first collection
@@ -61,7 +64,7 @@ extension Chain2: Collection where Base1: Collection, Base2: Collection {
// from the penultimate index of the first collection to the start of the
// second.
@usableFromInline
internal enum Representation : Equatable {
internal enum Representation: Equatable {
case first(Base1.Index)
case second(Base2.Index)
}
@@ -70,13 +73,13 @@ extension Chain2: Collection where Base1: Collection, Base2: Collection {
internal let position: Representation
/// Creates a new index into the first underlying collection.
@usableFromInline
@inlinable
internal init(first i: Base1.Index) {
position = .first(i)
}
/// Creates a new index into the second underlying collection.
@usableFromInline
@inlinable
internal init(second i: Base2.Index) {
position = .second(i)
}
@@ -98,8 +101,8 @@ extension Chain2: Collection where Base1: Collection, Base2: Collection {
/// Converts an index of `Base1` to the corresponding `Index` by mapping
/// `base1.endIndex` to `base2.startIndex`.
@usableFromInline
internal func convertIndex(_ i: Base1.Index) -> Index {
@inlinable
internal func normalizeIndex(_ i: Base1.Index) -> Index {
i == base1.endIndex ? Index(second: base2.startIndex) : Index(first: i)
}
@@ -107,12 +110,12 @@ extension Chain2: Collection where Base1: Collection, Base2: Collection {
public var startIndex: Index {
// if `base1` is empty, this will return `base2.startIndex` - if `base2` is
// also empty, this will correctly equal `base2.endIndex`
convertIndex(base1.startIndex)
normalizeIndex(base1.startIndex)
}
@inlinable
public var endIndex: Index {
return Index(second: base2.endIndex)
Index(second: base2.endIndex)
}
@inlinable
@@ -130,109 +133,116 @@ extension Chain2: Collection where Base1: Collection, Base2: Collection {
switch i.position {
case let .first(i):
assert(i != base1.endIndex)
return convertIndex(base1.index(after: i))
return normalizeIndex(base1.index(after: i))
case let .second(i):
return Index(second: base2.index(after: i))
}
}
@inlinable
public func index(_ i: Index, offsetBy n: Int) -> Index {
if n == 0 { return i }
return n > 0
? offsetForward(i, by: n, limitedBy: endIndex)!
: offsetBackward(i, by: -n, limitedBy: startIndex)!
public func index(_ i: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return i }
return distance > 0
? offsetForward(i, by: distance)
: offsetBackward(i, by: -distance)
}
@inlinable
public func index(
_ i: Index,
offsetBy n: Int,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
if n == 0 { return i }
return n > 0
? offsetForward(i, by: n, limitedBy: limit)
: offsetBackward(i, by: -n, limitedBy: limit)
if distance >= 0 {
return limit >= i
? offsetForward(i, by: distance, limitedBy: limit)
: offsetForward(i, by: distance)
} else {
return limit <= i
? offsetBackward(i, by: -distance, limitedBy: limit)
: offsetBackward(i, by: -distance)
}
}
@usableFromInline
@inlinable
internal func offsetForward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetForward(i, by: distance, limitedBy: endIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetBackward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetBackward(i, by: distance, limitedBy: startIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetForward(
_ i: Index, by n: Int, limitedBy limit: Index
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance >= 0)
assert(limit >= i)
switch (i.position, limit.position) {
case let (.first(i), .first(limit)):
if limit >= i {
// `limit` is relevant, so `base2` cannot be reached
return base1.index(i, offsetBy: n, limitedBy: limit)
.map(Index.init(first:))
} else if let j = base1.index(i, offsetBy: n, limitedBy: base1.endIndex) {
// the offset stays within the bounds of `base1`
return convertIndex(j)
} else {
// the offset overflows the bounds of `base1` by `n - d`
let d = base1.distance(from: i, to: base1.endIndex)
return Index(second: base2.index(base2.startIndex, offsetBy: n - d))
}
return base1.index(i, offsetBy: distance, limitedBy: limit)
.map(Index.init(first:))
case let (.first(i), .second(limit)):
if let j = base1.index(i, offsetBy: n, limitedBy: base1.endIndex) {
if let j = base1.index(i, offsetBy: distance, limitedBy: base1.endIndex) {
// the offset stays within the bounds of `base1`
return convertIndex(j)
return normalizeIndex(j)
} else {
// the offset overflows the bounds of `base1` by `n - d`
let d = base1.distance(from: i, to: base1.endIndex)
return base2.index(base2.startIndex, offsetBy: n - d, limitedBy: limit)
return base2.index(base2.startIndex, offsetBy: distance - d, limitedBy: limit)
.map(Index.init(second:))
}
case let (.second(i), .first):
// `limit` has no effect here
return Index(second: base2.index(i, offsetBy: n))
case (.second, .first):
// impossible because `limit >= i`
fatalError()
case let (.second(i), .second(limit)):
return base2.index(i, offsetBy: n, limitedBy: limit)
return base2.index(i, offsetBy: distance, limitedBy: limit)
.map(Index.init(second:))
}
}
@usableFromInline
@inlinable
internal func offsetBackward(
_ i: Index, by n: Int, limitedBy limit: Index
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance >= 0)
assert(limit <= i)
switch (i.position, limit.position) {
case let (.first(i), .first(limit)):
return base1.index(i, offsetBy: -n, limitedBy: limit)
return base1.index(i, offsetBy: -distance, limitedBy: limit)
.map(Index.init(first:))
case let (.first(i), .second):
// `limit` has no effect here
return Index(first: base1.index(i, offsetBy: -n))
case (.first, .second):
// impossible because `limit <= i`
fatalError()
case let (.second(i), .first(limit)):
if let j = base2.index(i, offsetBy: -n, limitedBy: base2.startIndex) {
if let j = base2.index(i, offsetBy: -distance, limitedBy: base2.startIndex) {
// the offset stays within the bounds of `base2`
return Index(second: j)
} else {
// the offset overflows the bounds of `base2` by `n - d`
let d = base2.distance(from: base2.startIndex, to: i)
return base1.index(base1.endIndex, offsetBy: -(n - d), limitedBy: limit)
return base1.index(base1.endIndex, offsetBy: -(distance - d), limitedBy: limit)
.map(Index.init(first:))
}
case let (.second(i), .second(limit)):
if limit <= i {
// `limit` is relevant, so `base1` cannot be reached
return base2.index(i, offsetBy: -n, limitedBy: limit)
.map(Index.init(second:))
} else if let j = base2.index(i, offsetBy: -n, limitedBy: base2.startIndex) {
// the offset stays within the bounds of `base2`
return Index(second: j)
} else {
// the offset overflows the bounds of `base2` by `n - d`
let d = base2.distance(from: base2.startIndex, to: i)
return Index(first: base1.index(base1.endIndex, offsetBy: -(n - d)))
}
// `limit` is relevant, so `base1` cannot be reached
return base2.index(i, offsetBy: -distance, limitedBy: limit)
.map(Index.init(second:))
}
}
@@ -253,7 +263,7 @@ extension Chain2: Collection where Base1: Collection, Base2: Collection {
}
}
extension Chain2: BidirectionalCollection
extension Chain2Sequence: BidirectionalCollection
where Base1: BidirectionalCollection, Base2: BidirectionalCollection
{
@inlinable
@@ -270,12 +280,9 @@ extension Chain2: BidirectionalCollection
}
}
extension Chain2: RandomAccessCollection
extension Chain2Sequence: RandomAccessCollection
where Base1: RandomAccessCollection, Base2: RandomAccessCollection {}
extension Chain2: Equatable where Base1: Equatable, Base2: Equatable {}
extension Chain2: Hashable where Base1: Hashable, Base2: Hashable {}
//===----------------------------------------------------------------------===//
// chain(_:_:)
//===----------------------------------------------------------------------===//
@@ -306,20 +313,7 @@ extension Chain2: Hashable where Base1: Hashable, Base2: Hashable {}
/// then over the elements of `s2`.
///
/// - Complexity: O(1)
public func chain<S1, S2>(_ s1: S1, _ s2: S2) -> Chain2<S1, S2> {
Chain2(base1: s1, base2: s2)
}
// MARK: - Deprecations
@available(*, deprecated, renamed: "Chain2")
public typealias Chain = Chain2
extension Sequence {
@available(*, deprecated, message: "Use the chain(_:_:) function, instead.")
public func chained<S: Sequence>(with other: S) -> Chain2<Self, S>
where Element == S.Element
{
Chain2(base1: self, base2: other)
}
@inlinable
public func chain<S1, S2>(_ s1: S1, _ s2: S2) -> Chain2Sequence<S1, S2> {
Chain2Sequence(base1: s1, base2: s2)
}
+755 -97
View File
@@ -9,208 +9,866 @@
//
//===----------------------------------------------------------------------===//
public struct LazyChunked<Base: Collection> {
/// A collection wrapper that breaks a collection into chunks based on a
/// predicate.
///
/// Call `lazy.chunked(by:)` on a collection to create an instance of this type.
public struct ChunkedByCollection<Base: Collection, Subject> {
/// The collection that this instance provides a view onto.
public let base: Base
@usableFromInline
internal let base: Base
/// The projection function.
@usableFromInline
internal var belongInSameGroup: (Base.Element, Base.Element) -> Bool
internal let projection: (Base.Element) -> Subject
/// The predicate.
@usableFromInline
internal init(base: Base, belongInSameGroup: @escaping (Base.Element, Base.Element) -> Bool) {
internal let belongInSameGroup: (Subject, Subject) -> Bool
/// The end index of the first chunk.
@usableFromInline
internal var endOfFirstChunk: Base.Index
@inlinable
internal init(
base: Base,
projection: @escaping (Base.Element) -> Subject,
belongInSameGroup: @escaping (Subject, Subject) -> Bool
) {
self.base = base
self.projection = projection
self.belongInSameGroup = belongInSameGroup
self.endOfFirstChunk = base.startIndex
if !base.isEmpty {
endOfFirstChunk = endOfChunk(startingAt: base.startIndex)
}
}
}
extension LazyChunked: LazyCollectionProtocol {
extension ChunkedByCollection: Collection {
/// A position in a chunked collection.
public struct Index: Comparable {
/// The lower bound of the chunk at this position.
/// The range corresponding to the chunk at this position.
@usableFromInline
internal var lowerBound: Base.Index
internal var baseRange: Range<Base.Index>
/// The upper bound of the chunk at this position.
///
/// `upperBound` is optional so that computing `startIndex` can be an O(1)
/// operation. When `upperBound` is `nil`, the actual upper bound is found
/// when subscripting or calling `index(after:)`.
@usableFromInline
internal var upperBound: Base.Index?
@usableFromInline
internal init(lowerBound: Base.Index, upperBound: Base.Index? = nil) {
self.lowerBound = lowerBound
self.upperBound = upperBound
@inlinable
internal init(_ baseRange: Range<Base.Index>) {
self.baseRange = baseRange
}
@inlinable
public static func == (lhs: Index, rhs: Index) -> Bool {
// Only use the lower bound to test for equality, since sometimes the
// `startIndex` will have an upper bound of `nil` and sometimes it won't,
// such as when retrieved by:
// `c.index(before: c.index(after: c.startIndex))`.
//
// Since each index represents the range of a disparate chunk, no two
// unique indices will have the same lower bound.
lhs.lowerBound == rhs.lowerBound
lhs.baseRange.lowerBound == rhs.baseRange.lowerBound
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
// Only use the lower bound to test for ordering, as above.
lhs.lowerBound < rhs.lowerBound
lhs.baseRange.lowerBound < rhs.baseRange.lowerBound
}
}
/// Returns the index in the base collection for the first element that
/// doesn't match the current chunk.
@usableFromInline
internal func endOfChunk(from i: Base.Index) -> Base.Index {
guard i != base.endIndex else { return base.endIndex }
return base[base.index(after: i)...]
.firstIndex(where: { !belongInSameGroup($0, base[i]) }) ?? base.endIndex
/// Returns the index in the base collection of the end of the chunk starting
/// at the given index.
@inlinable
internal func endOfChunk(startingAt start: Base.Index) -> Base.Index {
var subject = projection(base[start])
return base[base.index(after: start)...].endOfPrefix(while: { element in
let nextSubject = projection(element)
defer { subject = nextSubject }
return belongInSameGroup(subject, nextSubject)
})
}
@inlinable
public var startIndex: Index {
Index(lowerBound: base.startIndex)
Index(base.startIndex..<endOfFirstChunk)
}
@inlinable
public var endIndex: Index {
Index(lowerBound: base.endIndex, upperBound: base.endIndex)
Index(base.endIndex..<base.endIndex)
}
@inlinable
public func index(after i: Index) -> Index {
let upperBound = i.upperBound ?? endOfChunk(from: i.lowerBound)
let end = endOfChunk(from: upperBound)
return Index(lowerBound: upperBound, upperBound: end)
precondition(i != endIndex, "Can't advance past endIndex")
let upperBound = i.baseRange.upperBound
guard upperBound != base.endIndex else { return endIndex }
let end = endOfChunk(startingAt: upperBound)
return Index(upperBound..<end)
}
@inlinable
public subscript(position: Index) -> Base.SubSequence {
let upperBound = position.upperBound
?? endOfChunk(from: position.lowerBound)
return base[position.lowerBound..<upperBound]
precondition(position != endIndex, "Can't subscript using endIndex")
return base[position.baseRange]
}
}
extension LazyChunked.Index: Hashable where Base.Index: Hashable {}
extension ChunkedByCollection.Index: Hashable where Base.Index: Hashable {}
extension LazyChunked: BidirectionalCollection
extension ChunkedByCollection: BidirectionalCollection
where Base: BidirectionalCollection
{
/// Returns the index in the base collection for the element that starts
/// the chunk ending at the given index.
@usableFromInline
/// Returns the index in the base collection of the start of the chunk ending
/// at the given index.
@inlinable
internal func startOfChunk(endingAt end: Base.Index) -> Base.Index {
// Get the projected value of the last element in the range ending at `end`.
let lastOfPreviousChunk = base[base.index(before: end)]
let indexBeforeEnd = base.index(before: end)
var subject = projection(base[indexBeforeEnd])
// Search backward from `end` for the first element whose projection isn't
// equal to `lastOfPreviousChunk`.
if let firstMismatch = base[..<end]
.lastIndex(where: { !belongInSameGroup($0, lastOfPreviousChunk) })
{
// If we found one, that's the last element of the _next_ previous chunk,
// and therefore one position _before_ the start of this chunk.
return base.index(after: firstMismatch)
} else {
// If we didn't find such an element, this chunk extends back to the start
// of the collection.
return base.startIndex
}
return base[..<indexBeforeEnd].startOfSuffix(while: { element in
let nextSubject = projection(element)
defer { subject = nextSubject }
return belongInSameGroup(nextSubject, subject)
})
}
@inlinable
public func index(before i: Index) -> Index {
let start = startOfChunk(endingAt: i.lowerBound)
return Index(lowerBound: start, upperBound: i.lowerBound)
precondition(i != startIndex, "Can't advance before startIndex")
let start = startOfChunk(endingAt: i.baseRange.lowerBound)
return Index(start..<i.baseRange.lowerBound)
}
}
extension ChunkedByCollection: LazyCollectionProtocol {}
/// A collection wrapper that breaks a collection into chunks based on a
/// predicate.
///
/// Call `lazy.chunked(on:)` on a collection to create an instance of this type.
public struct ChunkedOnCollection<Base: Collection, Subject: Equatable> {
@usableFromInline
internal var chunked: ChunkedByCollection<Base, Subject>
@inlinable
internal init(
base: Base,
projection: @escaping (Base.Element) -> Subject
) {
self.chunked = ChunkedByCollection(
base: base,
projection: projection,
belongInSameGroup: ==)
}
}
extension ChunkedOnCollection: Collection {
public typealias Index = ChunkedByCollection<Base, Subject>.Index
@inlinable
public var startIndex: Index {
chunked.startIndex
}
@inlinable
public var endIndex: Index {
chunked.endIndex
}
@inlinable
public subscript(position: Index) -> (Subject, Base.SubSequence) {
let subsequence = chunked[position]
let subject = chunked.projection(subsequence.first!)
return (subject, subsequence)
}
@inlinable
public func index(after i: Index) -> Index {
chunked.index(after: i)
}
}
extension ChunkedOnCollection: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
public func index(before i: Index) -> Index {
chunked.index(before: i)
}
}
extension ChunkedOnCollection: LazyCollectionProtocol {}
/// A collection wrapper that evenly breaks a collection into a given number of
/// chunks.
public struct EvenlyChunkedCollection<Base: Collection> {
/// The base collection.
@usableFromInline
internal let base: Base
/// The number of equal chunks the base collection is divided into.
@usableFromInline
internal let numberOfChunks: Int
/// The count of the base collection.
@usableFromInline
internal let baseCount: Int
/// The upper bound of the first chunk.
@usableFromInline
internal var firstUpperBound: Base.Index
@inlinable
internal init(base: Base, numberOfChunks: Int) {
self.base = base
self.numberOfChunks = numberOfChunks
self.baseCount = base.count
self.firstUpperBound = base.startIndex
if numberOfChunks > 0 {
firstUpperBound = endOfChunk(startingAt: base.startIndex, offset: 0)
}
}
}
extension EvenlyChunkedCollection {
/// Returns the number of chunks with size `smallChunkSize + 1` at the start
/// of this collection.
@inlinable
internal var numberOfLargeChunks: Int {
baseCount % numberOfChunks
}
/// Returns the size of a chunk at a given offset.
@inlinable
internal func sizeOfChunk(offset: Int) -> Int {
let isLargeChunk = offset < numberOfLargeChunks
return baseCount / numberOfChunks + (isLargeChunk ? 1 : 0)
}
/// Returns the index in the base collection of the end of the chunk starting
/// at the given index.
@inlinable
internal func endOfChunk(startingAt start: Base.Index, offset: Int) -> Base.Index {
base.index(start, offsetBy: sizeOfChunk(offset: offset))
}
/// Returns the index in the base collection of the start of the chunk ending
/// at the given index.
@inlinable
internal func startOfChunk(endingAt end: Base.Index, offset: Int) -> Base.Index {
base.index(end, offsetBy: -sizeOfChunk(offset: offset))
}
/// Returns the index that corresponds to the chunk that starts at the given
/// base index.
@inlinable
internal func indexOfChunk(startingAt start: Base.Index, offset: Int) -> Index {
guard offset != numberOfChunks else { return endIndex }
let end = endOfChunk(startingAt: start, offset: offset)
return Index(start..<end, offset: offset)
}
/// Returns the index that corresponds to the chunk that ends at the given
/// base index.
@inlinable
internal func indexOfChunk(endingAt end: Base.Index, offset: Int) -> Index {
let start = startOfChunk(endingAt: end, offset: offset)
return Index(start..<end, offset: offset)
}
}
extension EvenlyChunkedCollection: Collection {
public struct Index: Comparable {
/// The range corresponding to the chunk at this position.
@usableFromInline
internal var baseRange: Range<Base.Index>
/// The offset corresponding to the chunk at this position. The first chunk
/// has offset `0` and all other chunks have an offset `1` greater than the
/// previous.
@usableFromInline
internal var offset: Int
@inlinable
internal init(_ baseRange: Range<Base.Index>, offset: Int) {
self.baseRange = baseRange
self.offset = offset
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs.offset == rhs.offset
}
@inlinable
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.offset < rhs.offset
}
}
public typealias Element = Base.SubSequence
@inlinable
public var startIndex: Index {
Index(base.startIndex..<firstUpperBound, offset: 0)
}
@inlinable
public var endIndex: Index {
Index(base.endIndex..<base.endIndex, offset: numberOfChunks)
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i != endIndex, "Can't advance past endIndex")
let start = i.baseRange.upperBound
return indexOfChunk(startingAt: start, offset: i.offset + 1)
}
@inlinable
public subscript(position: Index) -> Element {
precondition(position != endIndex)
return base[position.baseRange]
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
/// Returns the base distance between two `EvenChunksCollection` indices
/// from the end of one to the start of the other, when given their offsets.
func baseDistance(from offsetA: Int, to offsetB: Int) -> Int {
let smallChunkSize = baseCount / numberOfChunks
let numberOfChunks = (offsetB - offsetA) - 1
let largeChunksEnd = Swift.min(self.numberOfLargeChunks, offsetB)
let largeChunksStart = Swift.min(self.numberOfLargeChunks, offsetA + 1)
let numberOfLargeChunks = largeChunksEnd - largeChunksStart
return smallChunkSize * numberOfChunks + numberOfLargeChunks
}
if distance == 0 {
return i
} else if distance > 0 {
let offset = i.offset + distance
let baseOffset = baseDistance(from: i.offset, to: offset)
let start = base.index(i.baseRange.upperBound, offsetBy: baseOffset)
return indexOfChunk(startingAt: start, offset: offset)
} else {
let offset = i.offset + distance
let baseOffset = baseDistance(from: offset, to: i.offset)
let end = base.index(i.baseRange.lowerBound, offsetBy: -baseOffset)
return indexOfChunk(endingAt: end, offset: offset)
}
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int, limitedBy limit: Index) -> Index? {
if distance >= 0 {
if (0..<distance).contains(self.distance(from: i, to: limit)) {
return nil
}
} else {
if (0..<(-distance)).contains(self.distance(from: limit, to: i)) {
return nil
}
}
return index(i, offsetBy: distance)
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
end.offset - start.offset
}
}
extension EvenlyChunkedCollection.Index: Hashable where Base.Index: Hashable {}
extension EvenlyChunkedCollection: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
public func index(before i: Index) -> Index {
precondition(i != startIndex, "Can't advance before startIndex")
return indexOfChunk(endingAt: i.baseRange.lowerBound, offset: i.offset - 1)
}
}
extension EvenlyChunkedCollection: RandomAccessCollection
where Base: RandomAccessCollection {}
extension EvenlyChunkedCollection: LazySequenceProtocol
where Base: LazySequenceProtocol {}
extension EvenlyChunkedCollection: LazyCollectionProtocol
where Base: LazyCollectionProtocol {}
//===----------------------------------------------------------------------===//
// lazy.chunked(by:)
// lazy.chunked(by:) / lazy.chunked(on:)
//===----------------------------------------------------------------------===//
extension LazyCollectionProtocol {
extension LazySequenceProtocol where Self: Collection, Elements: Collection {
/// Returns a lazy collection of subsequences of this collection, chunked by
/// the given predicate.
///
/// - Complexity: O(1). When iterating over the resulting collection,
/// accessing each successive chunk has a complexity of O(*m*), where *m*
/// is the length of the chunk.
/// - Parameter belongInSameGroup: A closure that takes two adjacent elements
/// of the sequence and returns whether or not they belong in the same group.
///
/// - Complexity: O(*n*), because the start index is pre-computed.
@inlinable
public func chunked(
by belongInSameGroup: @escaping (Element, Element) -> Bool
) -> LazyChunked<Elements> {
LazyChunked(base: elements, belongInSameGroup: belongInSameGroup)
) -> ChunkedByCollection<Elements, Element> {
ChunkedByCollection(
base: elements,
projection: { $0 },
belongInSameGroup: belongInSameGroup)
}
/// Returns a lazy collection of subsequences of this collection, chunked by
/// grouping elements that project to the same value.
/// grouping elements that project to equal values.
///
/// - Complexity: O(1). When iterating over the resulting collection,
/// accessing each successive chunk has a complexity of O(*m*), where *m*
/// is the length of the chunk.
/// - Parameter projection: A closure that takes an element in the sequence
/// and returns an `Equatable` value that can be used to determine if adjacent
/// elements belong in the same group.
///
/// - Complexity: O(*n*), because the start index is pre-computed.
@inlinable
public func chunked<Subject: Equatable>(
public func chunked<Subject>(
on projection: @escaping (Element) -> Subject
) -> LazyChunked<Elements> {
LazyChunked(
) -> ChunkedOnCollection<Elements, Subject> {
ChunkedOnCollection(
base: elements,
belongInSameGroup: { projection($0) == projection($1) })
projection: projection)
}
}
//===----------------------------------------------------------------------===//
// chunked(by:)
// chunked(by:) / chunked(on:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns a collection of subsequences of this collection, chunked by
/// the given predicate.
/// Returns a collection of subsequences of this collection, chunked by the
/// given predicate.
///
/// - Parameter belongInSameGroup: A closure that takes two adjacent elements
/// of the collection and returns whether or not they belong in the same
/// group.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
@inlinable
public func chunked(
by belongInSameGroup: (Element, Element) -> Bool
) -> [SubSequence] {
by belongInSameGroup: (Element, Element) throws -> Bool
) rethrows -> [SubSequence] {
guard !isEmpty else { return [] }
var result: [SubSequence] = []
var start = startIndex
var current = startIndex
while true {
let next = index(after: current)
if next == endIndex { break }
if !belongInSameGroup(self[current], self[next]) {
result.append(self[start..<next])
start = next
var current = self[start]
for (index, element) in indexed().dropFirst() {
if try !belongInSameGroup(current, element) {
result.append(self[start..<index])
start = index
}
current = next
current = element
}
if start != endIndex {
result.append(self[start..<endIndex])
result.append(self[start...])
}
return result
}
/// Returns a collection of subsequences of this collection, chunked by
/// grouping elements that project to the same value.
/// grouping elements that project to equal values.
///
/// - Parameter projection: A closure that takes an element in the collection
/// and returns an `Equatable` value that can be used to determine if adjacent
/// elements belong in the same group.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
@inlinable
public func chunked<Subject: Equatable>(
on projection: (Element) -> Subject
) -> [SubSequence] {
chunked(by: { projection($0) == projection($1) })
on projection: (Element) throws -> Subject
) rethrows -> [(Subject, SubSequence)] {
guard !isEmpty else { return [] }
var result: [(Subject, SubSequence)] = []
var start = startIndex
var subject = try projection(self[start])
for (index, element) in indexed().dropFirst() {
let nextSubject = try projection(element)
if subject != nextSubject {
result.append((subject, self[start..<index]))
start = index
subject = nextSubject
}
}
if start != endIndex {
result.append((subject, self[start...]))
}
return result
}
}
//===----------------------------------------------------------------------===//
// chunks(ofCount:)
//===----------------------------------------------------------------------===//
/// A collection that presents the elements of its base collection in
/// `SubSequence` chunks of any given count.
///
/// A `ChunksOfCountCollection` is a lazy view on the base `Collection`, but it
/// does not implicitly confer laziness on algorithms applied to its result. In
/// other words, for ordinary collections `c`:
///
/// * `c.chunks(ofCount: 3)` does not create new storage
/// * `c.chunks(ofCount: 3).map(f)` maps eagerly and returns a new array
/// * `c.lazy.chunks(ofCount: 3).map(f)` maps lazily and returns a
/// `LazyMapCollection`
public struct ChunksOfCountCollection<Base: Collection> {
public typealias Element = Base.SubSequence
@usableFromInline
internal let base: Base
@usableFromInline
internal let chunkCount: Int
@usableFromInline
internal var endOfFirstChunk: Base.Index
/// Creates a view instance that presents the elements of `base` in
/// `SubSequence` chunks of the given count.
///
/// - Complexity: O(*n*), because the start index is pre-computed.
@inlinable
internal init(_base: Base, _chunkCount: Int) {
self.base = _base
self.chunkCount = _chunkCount
// Compute the start index upfront in order to make start index a O(1)
// lookup.
self.endOfFirstChunk = _base.index(
_base.startIndex, offsetBy: _chunkCount,
limitedBy: _base.endIndex
) ?? _base.endIndex
}
}
extension ChunksOfCountCollection: Collection {
public struct Index {
@usableFromInline
internal let baseRange: Range<Base.Index>
@inlinable
internal init(_baseRange: Range<Base.Index>) {
self.baseRange = _baseRange
}
}
/// - Complexity: O(1)
@inlinable
public var startIndex: Index {
Index(_baseRange: base.startIndex..<endOfFirstChunk)
}
@inlinable
public var endIndex: Index {
Index(_baseRange: base.endIndex..<base.endIndex)
}
/// - Complexity: O(1)
@inlinable
public subscript(i: Index) -> Element {
precondition(i != endIndex, "Index out of range")
return base[i.baseRange]
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i != endIndex, "Advancing past end index")
let baseIdx = base.index(
i.baseRange.upperBound, offsetBy: chunkCount,
limitedBy: base.endIndex
) ?? base.endIndex
return Index(_baseRange: i.baseRange.upperBound..<baseIdx)
}
}
extension ChunksOfCountCollection.Index: Comparable {
@inlinable
public static func == (lhs: ChunksOfCountCollection.Index,
rhs: ChunksOfCountCollection.Index) -> Bool {
lhs.baseRange.lowerBound == rhs.baseRange.lowerBound
}
@inlinable
public static func < (lhs: ChunksOfCountCollection.Index,
rhs: ChunksOfCountCollection.Index) -> Bool {
lhs.baseRange.lowerBound < rhs.baseRange.lowerBound
}
}
extension ChunksOfCountCollection:
BidirectionalCollection, RandomAccessCollection
where Base: RandomAccessCollection {
@inlinable
public func index(before i: Index) -> Index {
precondition(i != startIndex, "Advancing past start index")
var offset = chunkCount
if i.baseRange.lowerBound == base.endIndex {
let remainder = base.count % chunkCount
if remainder != 0 {
offset = remainder
}
}
let baseIdx = base.index(
i.baseRange.lowerBound, offsetBy: -offset,
limitedBy: base.startIndex
) ?? base.startIndex
return Index(_baseRange: baseIdx..<i.baseRange.lowerBound)
}
}
extension ChunksOfCountCollection {
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
let distance =
base.distance(from: start.baseRange.lowerBound,
to: end.baseRange.lowerBound)
let (quotient, remainder) =
distance.quotientAndRemainder(dividingBy: chunkCount)
return quotient + remainder.signum()
}
@inlinable
public var count: Int {
let (quotient, remainder) =
base.count.quotientAndRemainder(dividingBy: chunkCount)
return quotient + remainder.signum()
}
@inlinable
public func index(
_ i: Index, offsetBy offset: Int, limitedBy limit: Index
) -> Index? {
guard offset != 0 else { return i }
guard limit != i else { return nil }
if offset > 0 {
return limit > i
? offsetForward(i, offsetBy: offset, limit: limit)
: offsetForward(i, offsetBy: offset)
} else {
return limit < i
? offsetBackward(i, offsetBy: offset, limit: limit)
: offsetBackward(i, offsetBy: offset)
}
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return i }
let idx = distance > 0
? offsetForward(i, offsetBy: distance)
: offsetBackward(i, offsetBy: distance)
guard let index = idx else {
fatalError("Out of bounds")
}
return index
}
@inlinable
internal func offsetForward(
_ i: Index, offsetBy distance: Int, limit: Index? = nil
) -> Index? {
assert(distance > 0)
return makeOffsetIndex(
from: i, baseBound: base.endIndex,
distance: distance, baseDistance: distance * chunkCount,
limit: limit, by: >
)
}
// Convenience to compute offset backward base distance.
@inlinable
internal func computeOffsetBackwardBaseDistance(
_ i: Index, _ distance: Int
) -> Int {
if i == endIndex {
let remainder = base.count % chunkCount
// We have to take it into account when calculating offsets.
if remainder != 0 {
// Distance "minus" one (at this point distance is negative) because we
// need to adjust for the last position that have a variadic (remainder)
// number of elements.
return ((distance + 1) * chunkCount) - remainder
}
}
return distance * chunkCount
}
@inlinable
internal func offsetBackward(
_ i: Index, offsetBy distance: Int, limit: Index? = nil
) -> Index? {
assert(distance < 0)
let baseDistance =
computeOffsetBackwardBaseDistance(i, distance)
return makeOffsetIndex(
from: i, baseBound: base.startIndex,
distance: distance, baseDistance: baseDistance,
limit: limit, by: <
)
}
// Helper to compute `index(offsetBy:)` index.
@inlinable
internal func makeOffsetIndex(
from i: Index, baseBound: Base.Index, distance: Int, baseDistance: Int,
limit: Index?, by limitFn: (Base.Index, Base.Index) -> Bool
) -> Index? {
let baseIdx = base.index(
i.baseRange.lowerBound, offsetBy: baseDistance,
limitedBy: baseBound
)
if let limit = limit {
if baseIdx == nil {
// If we passed the bounds while advancing forward, and the limit is the
// `endIndex`, since the computation on `base` don't take into account
// the remainder, we have to make sure that passing the bound was
// because of the distance not just because of a remainder. Special
// casing is less expensive than always using `count` (which could be
// O(n) for non-random access collection base) to compute the base
// distance taking remainder into account.
if baseDistance > 0 && limit == endIndex {
if self.distance(from: i, to: limit) < distance {
return nil
}
} else {
return nil
}
}
// Checks for the limit.
let baseStartIdx = baseIdx ?? baseBound
if limitFn(baseStartIdx, limit.baseRange.lowerBound) {
return nil
}
}
let baseStartIdx = baseIdx ?? baseBound
let baseEndIdx = base.index(
baseStartIdx, offsetBy: chunkCount, limitedBy: base.endIndex
) ?? base.endIndex
return Index(_baseRange: baseStartIdx..<baseEndIdx)
}
}
extension Collection {
/// Returns a collection of subsequences, each with up to the specified
/// length.
///
/// If the number of elements in the collection is evenly divided by `count`,
/// then every chunk will have a length equal to `count`. Otherwise, every
/// chunk but the last will have a length equal to `count`, with the
/// remaining elements in the last chunk.
///
/// let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
/// for chunk in numbers.chunks(ofCount: 5) {
/// print(chunk)
/// }
/// // [1, 2, 3, 4, 5]
/// // [6, 7, 8, 9, 10]
///
/// for chunk in numbers.chunks(ofCount: 3) {
/// print(chunk)
/// }
/// // [1, 2, 3]
/// // [4, 5, 5]
/// // [7, 8, 9]
/// // [10]
///
/// - Parameter count: The desired size of each chunk.
/// - Returns: A collection of consescutive, non-overlapping subseqeunces of
/// this collection, where each subsequence (except possibly the last) has
/// the length `count`.
///
/// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`;
/// otherwise, O(*k*), where *k* is equal to `count`.
///
@inlinable
public func chunks(ofCount count: Int) -> ChunksOfCountCollection<Self> {
precondition(count > 0, "Cannot chunk with count <= 0!")
return ChunksOfCountCollection(_base: self, _chunkCount: count)
}
}
extension ChunksOfCountCollection.Index: Hashable where Base.Index: Hashable {}
extension ChunksOfCountCollection: LazySequenceProtocol
where Base: LazySequenceProtocol {}
extension ChunksOfCountCollection: LazyCollectionProtocol
where Base: LazyCollectionProtocol {}
//===----------------------------------------------------------------------===//
// evenlyChunked(in:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns a collection of evenly divided consecutive subsequences of this
/// collection.
///
/// This method divides the collection into a given number of evenly sized
/// chunks. If the length of the collection is not divisible by `count`, the
/// chunks at the start will be longer than the chunks at the end, like in
/// this example:
///
/// for chunk in "Hello, world!".evenlyChunked(in: 5) {
/// print(chunk)
/// }
/// // "Hel"
/// // "lo,"
/// // " wo"
/// // "rl"
/// // "d!"
///
/// If the number passed as `count` is greater than the number of elements in
/// the collection, the result will include one or more empty subsequences.
///
/// for chunk in "Hi!".evenlyChunked(in: 5) {
/// print(chunk)
/// }
/// // "H"
/// // "i"
/// // "!"
/// // ""
/// // ""
///
/// - Parameter count: The number of chunks to evenly divide this collection
/// into. If this collection is non-empty, `count` must be greater than
/// zero; otherwise, `count` may be zero or greater.
/// - Returns: A collection of `count` subsequences of this collection,
/// divided as evenly as possible.
///
/// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`;
/// otherwise, O(*n*), where *n* is the length of the collection.
@inlinable
public func evenlyChunked(in count: Int) -> EvenlyChunkedCollection<Self> {
precondition(count >= 0, "Can't divide into a negative number of chunks")
precondition(count > 0 || isEmpty, "Can't divide a non-empty collection into 0 chunks")
return EvenlyChunkedCollection(base: self, numberOfChunks: count)
}
}
+169 -36
View File
@@ -2,28 +2,69 @@
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 Apple Inc. and the Swift project authors
// Copyright (c) 2020-2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
public struct Combinations<Base: Collection> {
/// A collection wrapper that generates combinations of a base collection.
public struct CombinationsSequence<Base: Collection> {
/// The collection to iterate over for combinations.
public let base: Base
@usableFromInline
internal let base: Base
@usableFromInline
internal var k: Int
internal let baseCount: Int
/// The range of accepted sizes of combinations.
///
/// - Note: This may be `nil` if the attempted range entirely exceeds the
/// upper bounds of the size of the `base` collection.
@usableFromInline
internal let kRange: Range<Int>?
/// Initializes a `CombinationsSequence` for all combinations of `base` of
/// size `k`.
///
/// - Parameters:
/// - base: The collection to iterate over for combinations.
/// - k: The expected size of each combination.
@inlinable
internal init(_ base: Base, k: Int) {
self.base = base
self.k = base.count < k ? -1 : k
self.init(base, kRange: k...k)
}
/// Initializes a `CombinationsSequence` for all combinations of `base` of
/// sizes within a given range.
///
/// - Parameters:
/// - base: The collection to iterate over for combinations.
/// - kRange: The range of accepted sizes of combinations.
@inlinable
internal init<R: RangeExpression>(
_ base: Base, kRange: R
) where R.Bound == Int {
let range = kRange.relative(to: 0 ..< .max)
self.base = base
let baseCount = base.count
self.baseCount = baseCount
let upperBound = baseCount + 1
self.kRange = range.lowerBound < upperBound
? range.clamped(to: 0 ..< upperBound)
: nil
}
/// The total number of combinations.
@inlinable
public var count: Int {
guard let k = self.kRange else { return 0 }
let n = baseCount
if k == 0 ..< (n + 1) {
return 1 << n
}
func binomial(n: Int, k: Int) -> Int {
switch k {
case n, 0: return 1
@@ -33,29 +74,40 @@ public struct Combinations<Base: Collection> {
}
}
return k >= 0
? binomial(n: base.count, k: k)
: 0
return k.map {
binomial(n: n, k: $0)
}.reduce(0, +)
}
}
extension Combinations: Sequence {
extension CombinationsSequence: Sequence {
/// The iterator for a `CombinationsSequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal let base: Base
/// The current range of accepted sizes of combinations.
///
/// - Note: The range is contracted until empty while iterating over
/// combinations of different sizes. When the range is empty, iteration is
/// finished.
@usableFromInline
internal var kRange: Range<Int>
/// Whether or not iteration is finished (`kRange` is empty)
@inlinable
internal var isFinished: Bool {
return kRange.isEmpty
}
@usableFromInline
internal var indexes: [Base.Index]
@usableFromInline
internal var finished: Bool
internal init(_ combinations: Combinations) {
@inlinable
internal init(_ combinations: CombinationsSequence) {
self.base = combinations.base
self.finished = combinations.k < 0
self.indexes = combinations.k < 0
? []
: Array(combinations.base.indices.prefix(combinations.k))
self.kRange = combinations.kRange ?? 0..<0
self.indexes = Array(combinations.base.indices.prefix(kRange.lowerBound))
}
/// Advances the current indices to the next set of combinations. If
@@ -76,26 +128,37 @@ extension Combinations: Sequence {
/// [2, 3, 4] *
/// // Can't advance without needing to go past `base.endIndex`,
/// // so the iteration is finished.
@usableFromInline
@inlinable
internal mutating func advance() {
/// Advances `kRange` by incrementing its `lowerBound` until the range is
/// empty, when iteration is finished.
func advanceKRange() {
if kRange.lowerBound < kRange.upperBound {
let advancedLowerBound = kRange.lowerBound + 1
kRange = advancedLowerBound ..< kRange.upperBound
indexes.removeAll(keepingCapacity: true)
indexes.append(contentsOf: base.indices.prefix(kRange.lowerBound))
}
}
guard !indexes.isEmpty else {
// Initial state for combinations of 0 elements is an empty array with
// `finished == false`. Even though no indexes are involved, advancing
// from that state means we are finished with iterating.
finished = true
advanceKRange()
return
}
let i = indexes.count - 1
base.formIndex(after: &indexes[i])
if indexes[i] != base.endIndex { return }
var j = i
while indexes[i] == base.endIndex {
j -= 1
guard j >= 0 else {
// Finished iterating over combinations
finished = true
// Finished iterating over combinations of this size.
advanceKRange()
return
}
@@ -111,34 +174,102 @@ extension Combinations: Sequence {
@inlinable
public mutating func next() -> [Base.Element]? {
if finished { return nil }
guard !isFinished else { return nil }
defer { advance() }
return indexes.map { i in base[i] }
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(self)
}
}
extension Combinations: LazySequenceProtocol where Base: LazySequenceProtocol {}
extension Combinations: Equatable where Base: Equatable {}
extension Combinations: Hashable where Base: Hashable {}
extension CombinationsSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// combinations(count:)
// combinations(ofCount:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns a collection of combinations of this collection's elements, with
/// each combination having the specificed number of elements.
/// each combination having the specified number of elements.
///
/// This example prints the different combinations of 1 and 2 from an array of
/// four colors:
///
/// let colors = ["fuchsia", "cyan", "mauve", "magenta"]
/// for combo in colors.combinations(ofCount: 1...2) {
/// print(combo.joined(separator: ", "))
/// }
/// // fuchsia
/// // cyan
/// // mauve
/// // magenta
/// // fuchsia, cyan
/// // fuchsia, mauve
/// // fuchsia, magenta
/// // cyan, mauve
/// // cyan, magenta
/// // mauve, magenta
///
/// The returned collection presents combinations in a consistent order, where
/// the indices in each combination are in ascending lexicographical order.
/// That is, in the example above, the combinations in order are the elements
/// at `[0]`, `[1]`, `[2]`, `[3]`, `[0, 1]`, `[0, 2]`, `[0, 3]`, `[1, 2]`,
/// `[1, 3]`, and finally `[2, 3]`.
///
/// This example prints _all_ the combinations (including an empty array and
/// the original collection) from an array of numbers:
///
/// let numbers = [10, 20, 30, 40]
/// for combo in numbers.combinations(ofCount: 0...) {
/// print(combo)
/// }
/// // []
/// // [10]
/// // [20]
/// // [30]
/// // [40]
/// // [10, 20]
/// // [10, 30]
/// // [10, 40]
/// // [20, 30]
/// // [20, 40]
/// // [30, 40]
/// // [10, 20, 30]
/// // [10, 20, 40]
/// // [10, 30, 40]
/// // [20, 30, 40]
/// // [10, 20, 30, 40]
///
/// If `kRange` is `0...0`, the resulting sequence has exactly one element, an
/// empty array. The given range is limited to `0...base.count`. If the
/// limited range is empty, the resulting sequence has no elements.
///
/// - Parameter kRange: The range of numbers of elements to include in each
/// combination.
///
/// - Complexity: O(1) for random-access base collections. O(*n*) where *n*
/// is the number of elements in the base collection, since
/// `CombinationsSequence` accesses the `count` of the base collection.
@inlinable
public func combinations<R: RangeExpression>(
ofCount kRange: R
) -> CombinationsSequence<Self> where R.Bound == Int {
CombinationsSequence(self, kRange: kRange)
}
/// Returns a collection of combinations of this collection's elements, with
/// each combination having the specified number of elements.
///
/// This example prints the different combinations of three from an array of
/// four colors:
///
/// let colors = ["fuchsia", "cyan", "mauve", "magenta"]
/// for combo in colors.combinations(ofCount k: 3) {
/// for combo in colors.combinations(ofCount: 3) {
/// print(combo.joined(separator: ", "))
/// }
/// // fuchsia, cyan, mauve
@@ -157,10 +288,12 @@ extension Collection {
///
/// - Parameter k: The number of elements to include in each combination.
///
/// - Complexity: O(1)
/// - Complexity: O(1) for random-access base collections. O(*n*) where *n*
/// is the number of elements in the base collection, since
/// `CombinationsSequence` accesses the `count` of the base collection.
@inlinable
public func combinations(ofCount k: Int) -> Combinations<Self> {
assert(k >= 0, "Can't have combinations with a negative number of elements.")
return Combinations(self, k: k)
public func combinations(ofCount k: Int) -> CombinationsSequence<Self> {
precondition(k >= 0, "Can't have combinations with a negative number of elements.")
return CombinationsSequence(self, k: k)
}
}
+184
View File
@@ -0,0 +1,184 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
/// A `Sequence` that iterates over every non-nil element from the original
/// `Sequence`.
public struct CompactedSequence<Base: Sequence, Element>: Sequence
where Base.Element == Element? {
@usableFromInline
let base: Base
@inlinable
init(base: Base) {
self.base = base
}
public struct Iterator: IteratorProtocol {
@usableFromInline
var base: Base.Iterator
@inlinable
init(base: Base.Iterator) {
self.base = base
}
@inlinable
public mutating func next() -> Element? {
while let wrapped = base.next() {
guard let some = wrapped else { continue }
return some
}
return nil
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(base: base.makeIterator())
}
}
extension Sequence {
/// Returns a new `Sequence` that iterates over every non-nil element from the
/// original `Sequence`.
///
/// Produces the same result as `c.compactMap { $0 }`.
///
/// let c = [1, nil, 2, 3, nil]
/// for num in c.compacted() {
/// print(num)
/// }
/// // 1
/// // 2
/// // 3
///
/// - Returns: A `Sequence` where the element is the unwrapped original
/// element and iterates over every non-nil element from the original
/// `Sequence`.
///
/// Complexity: O(1)
@inlinable
public func compacted<Unwrapped>() -> CompactedSequence<Self, Unwrapped>
where Element == Unwrapped? {
CompactedSequence(base: self)
}
}
/// A `Collection` that iterates over every non-nil element from the original
/// `Collection`.
public struct CompactedCollection<Base: Collection, Element>: Collection
where Base.Element == Element? {
@usableFromInline
let base: Base
@inlinable
init(base: Base) {
self.base = base
let idx = base.firstIndex(where: { $0 != nil }) ?? base.endIndex
self.startIndex = Index(base: idx)
}
public struct Index {
@usableFromInline
let base: Base.Index
@inlinable
init(base: Base.Index) {
self.base = base
}
}
public var startIndex: Index
@inlinable
public var endIndex: Index { Index(base: base.endIndex) }
@inlinable
public subscript(position: Index) -> Element {
base[position.base]!
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i != endIndex, "Index out of bounds")
let baseIdx = base.index(after: i.base)
guard let idx = base[baseIdx...].firstIndex(where: { $0 != nil })
else { return endIndex }
return Index(base: idx)
}
}
extension CompactedCollection: BidirectionalCollection
where Base: BidirectionalCollection {
@inlinable
public func index(before i: Index) -> Index {
precondition(i != startIndex, "Index out of bounds")
guard let idx =
base[startIndex.base..<i.base]
.lastIndex(where: { $0 != nil })
else { fatalError("Index out of bounds") }
return Index(base: idx)
}
}
extension CompactedCollection.Index: Comparable {
@inlinable
public static func < (lhs: CompactedCollection.Index,
rhs: CompactedCollection.Index) -> Bool {
lhs.base < rhs.base
}
}
extension CompactedCollection.Index: Hashable
where Base.Index: Hashable {}
extension Collection {
/// Returns a new `Collection` that iterates over every non-nil element from
/// the original `Collection`.
///
/// Produces the same result as `c.compactMap { $0 }`.
///
/// let c = [1, nil, 2, 3, nil]
/// for num in c.compacted() {
/// print(num)
/// }
/// // 1
/// // 2
/// // 3
///
/// - Returns: A `Collection` where the element is the unwrapped original
/// element and iterates over every non-nil element from the original
/// `Collection`.
///
/// Complexity: O(*n*) where *n* is the number of elements in the
/// original `Collection`.
@inlinable
public func compacted<Unwrapped>() -> CompactedCollection<Self, Unwrapped>
where Element == Unwrapped?
{
CompactedCollection(base: self)
}
}
//===----------------------------------------------------------------------===//
// Protocol Conformances
//===----------------------------------------------------------------------===//
extension CompactedSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
extension CompactedCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
+127 -12
View File
@@ -10,21 +10,27 @@
//===----------------------------------------------------------------------===//
/// A collection wrapper that repeats the elements of a base collection.
public struct Cycle<Base: Collection> {
public struct CycledSequence<Base: Collection> {
/// The collection to repeat.
public let base: Base
@usableFromInline
internal let base: Base
@inlinable
internal init(base: Base) {
self.base = base
}
}
extension Cycle: Sequence {
/// The iterator for a `Cycle` sequence.
extension CycledSequence: Sequence {
/// The iterator for a `CycledSequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
let base: Base
internal let base: Base
@usableFromInline
var current: Base.Index
internal var current: Base.Index
@usableFromInline
@inlinable
internal init(base: Base) {
self.base = base
self.current = base.startIndex
@@ -43,12 +49,119 @@ extension Cycle: Sequence {
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(base: base)
}
}
extension Cycle: LazySequenceProtocol where Base: LazySequenceProtocol {}
extension CycledSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
/// A collection wrapper that repeats the elements of a base collection for a
/// finite number of times.
public struct CycledTimesCollection<Base: Collection> {
/// A `Product2Sequence` instance for iterating the base collection.
@usableFromInline
internal let product: Product2Sequence<Range<Int>, Base>
@inlinable
internal init(base: Base, times: Int) {
self.product = Product2Sequence(0..<times, base)
}
}
extension CycledTimesCollection: Collection {
public typealias Element = Base.Element
public struct Index: Comparable {
/// The index corresponding to the `Product2Sequence` index at this
/// position.
@usableFromInline
internal let productIndex: Product2Sequence<Range<Int>, Base>.Index
@inlinable
internal init(_ productIndex: Product2Sequence<Range<Int>, Base>.Index) {
self.productIndex = productIndex
}
@inlinable
public static func == (lhs: Index, rhs: Index) -> Bool {
lhs.productIndex == rhs.productIndex
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
lhs.productIndex < rhs.productIndex
}
}
@inlinable
public var startIndex: Index {
Index(product.startIndex)
}
@inlinable
public var endIndex: Index {
Index(product.endIndex)
}
@inlinable
public subscript(_ index: Index) -> Element {
product[index.productIndex].1
}
@inlinable
public func index(after i: Index) -> Index {
let productIndex = product.index(after: i.productIndex)
return Index(productIndex)
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
product.distance(from: start.productIndex, to: end.productIndex)
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
let productIndex = product.index(i.productIndex, offsetBy: distance)
return Index(productIndex)
}
@inlinable
public func index(
_ i: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
guard let productIndex = product.index(
i.productIndex,
offsetBy: distance,
limitedBy: limit.productIndex)
else { return nil }
return Index(productIndex)
}
@inlinable
public var count: Int {
product.count
}
}
extension CycledTimesCollection: BidirectionalCollection
where Base: BidirectionalCollection {
@inlinable
public func index(before i: Index) -> Index {
let productIndex = product.index(before: i.productIndex)
return Index(productIndex)
}
}
extension CycledTimesCollection: RandomAccessCollection
where Base: RandomAccessCollection {}
extension CycledTimesCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// cycled()
@@ -80,8 +193,9 @@ extension Collection {
/// forever.
///
/// - Complexity: O(1)
public func cycled() -> Cycle<Self> {
Cycle(base: self)
@inlinable
public func cycled() -> CycledSequence<Self> {
CycledSequence(base: self)
}
/// Returns a sequence that repeats the elements of this collection the
@@ -101,7 +215,8 @@ extension Collection {
/// times.
///
/// - Complexity: O(1)
public func cycled(times: Int) -> FlattenSequence<Repeated<Self>> {
repeatElement(self, count: times).joined()
@inlinable
public func cycled(times: Int) -> CycledTimesCollection<Self> {
CycledTimesCollection(base: self, times: times)
}
}
@@ -0,0 +1,42 @@
# ``Algorithms``
**Swift Algorithms** is an open-source package of sequence and collection algorithms,
along with their related types.
## Overview
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.
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:
```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]]
```
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:
```swift
let names = ["Cassie", "Chloe", "Jasmine", "Jordan", "Taylor"]
let chunks = names.chunked(on: \.first)
// [["Cassie", "Chloe"], ["Jasmine", "Jordan"], ["Taylor"]]
```
Explore more chunking methods and the remainder of the Algorithms package, grouped in the following topics.
## Topics
- <doc:CombinationsPermutations>
- <doc:SlicingSplitting>
- <doc:Chunking>
- <doc:Joining>
- <doc:Extending>
- <doc:Trimming>
- <doc:Keying>
- <doc:Sampling>
- <doc:MinAndMax>
- <doc:Selecting>
- <doc:Filtering>
- <doc:Reductions>
- <doc:Partitioning>
@@ -0,0 +1,40 @@
# Chunking
Break collections into consecutive chunks by length, count, or based on closure-based logic.
## Overview
_Chunking_ is the process of breaking a collection into consecutive subsequences, without dropping or duplicating any of the collection's elements. After chunking a collection, joining the resulting subsequences produces the original collection of elements, unlike _splitting_, which consumes the separator element(s).
```swift
let names = ["Ji-sun", "Jin-su", "Min-jae", "Young-ho"]
let evenlyChunked = names.chunks(ofCount: 2)
// ~ [["Ji-sun", "Jin-su"], ["Min-jae", "Young-ho"]]
let chunkedByFirstLetter = names.chunked(on: \.first)
// equivalent to [("J", ["Ji-sun", "Jin-su"]), ("M", ["Min-jae"]), ("Y", ["Young-ho"])]
```
## Topics
### Chunking a Collection by Count
- ``Swift/Collection/chunks(ofCount:)``
- ``Swift/Collection/evenlyChunked(in:)``
### Chunking a Collection by Predicate
- ``Swift/Collection/chunked(by:)``
- ``Swift/LazySequenceProtocol/chunked(by:)``
### Chunking a Collection by Subject
- ``Swift/Collection/chunked(on:)``
- ``Swift/LazySequenceProtocol/chunked(on:)``
### Supporting Types
- ``ChunkedByCollection``
- ``ChunkedOnCollection``
- ``ChunksOfCountCollection``
- ``EvenlyChunkedCollection``
@@ -0,0 +1,32 @@
# Combinations and Permutations
Find the combinations and permutations of any collection's elements,
or the product of two different collections.
## Topics
### Combinations
- ``Swift/Collection/combinations(ofCount:)-26o4x``
- ``Swift/Collection/combinations(ofCount:)-53jql``
### Permutations
- ``Swift/Collection/permutations(ofCount:)-7rc99``
- ``Swift/Collection/permutations(ofCount:)-5zvhn``
### Unique Permutations
- ``Swift/Collection/uniquePermutations(ofCount:)-2extq``
- ``Swift/Collection/uniquePermutations(ofCount:)-48r1k``
### Product
- ``product(_:_:)``
### Supporting Types
- ``CombinationsSequence``
- ``PermutationsSequence``
- ``UniquePermutationsSequence``
- ``Product2Sequence``
@@ -0,0 +1,14 @@
# DeprecatedScan
These methods are deprecated; use the `reductions` family of methods instead.
See: <doc:Reductions>
## Topics
- ``Swift/Sequence/scan(_:)``
- ``Swift/Sequence/scan(_:_:)``
- ``Swift/Sequence/scan(into:_:)``
- ``Swift/LazySequenceProtocol/scan(_:)``
- ``Swift/LazySequenceProtocol/scan(_:_:)``
- ``Swift/LazySequenceProtocol/scan(into:_:)``
@@ -0,0 +1,42 @@
# Extending
Chain two collections end-to-end,
or repeat a collection forever or a specific number of times.
## Overview
_Chaining_ two collections
```swift
let letters = chain("abcd", "EFGH")
// String(letters) == "abcdEFGH"
for (num, letter) in zip((1...3).cycled(), letters) {
print(num, letter)
}
// 1 a
// 2 b
// 3 c
// 1 d
// 2 E
// 3 F
// 1 G
// 2 H
```
## Topics
### Chaining Two Collections
- ``chain(_:_:)``
### Cycling a Collection
- ``Swift/Collection/cycled()``
- ``Swift/Collection/cycled(times:)``
### Supporting Types
- ``Chain2Sequence``
- ``CycledSequence``
- ``CycledTimesCollection``
@@ -0,0 +1,41 @@
# Filtering
Remove duplicated elements or strip the `nil` values from a sequence or collection.
## Overview
Use the _uniquing_ methods to remove duplicates from a sequence or collection, or to remove elements that have a duplicated property.
```swift
let numbers = [1, 2, 3, 3, 2, 3, 3, 2, 2, 2, 1]
let unique = numbers.uniqued()
// Array(unique) == [1, 2, 3]
```
The `compacted()` method removes all `nil` values from a sequence or collection of optionals:
```swift
let array: [Int?] = [10, nil, 30, nil, 2, 3, nil, 5]
let withNoNils = array.compacted()
// Array(withNoNils) == [10, 30, 2, 3, 5]
```
## Topics
### Uniquing Elements
- ``Swift/Sequence/uniqued()``
- ``Swift/Sequence/uniqued(on:)``
- ``Swift/LazySequenceProtocol/uniqued(on:)``
### Filtering out `nil` Elements
- ``Swift/Collection/compacted()``
- ``Swift/Sequence/compacted()``
### Supporting Types
- ``UniquedSequence``
- ``CompactedSequence``
- ``CompactedCollection``
@@ -0,0 +1,35 @@
# Joining
Join the parts of a collection of collections,
providing a connecting element or collection,
or a closure that produces the connector.
## Topics
### Joining by an Element
- ``Swift/Sequence/joined(by:)-6mrf9``
- ``Swift/Sequence/joined(by:)-9hyaf``
- ``Swift/Collection/joined(by:)-430ue``
- ``Swift/LazySequenceProtocol/joined(by:)-3yjw0``
- ``Swift/LazySequenceProtocol/joined(by:)-47xvy``
### Joining by a Collection
- ``Swift/Sequence/joined(by:)-62j1h``
- ``Swift/Sequence/joined(by:)-9b108``
- ``Swift/Collection/joined(by:)-28n3b``
- ``Swift/LazySequenceProtocol/joined(by:)-4neii``
- ``Swift/LazySequenceProtocol/joined(by:)-49xws``
### Interspersing Elements
- ``Swift/Sequence/interspersed(with:)``
### Supporting Types
- ``JoinedBySequence``
- ``JoinedByCollection``
- ``JoinedByClosureSequence``
- ``JoinedByClosureCollection``
- ``InterspersedSequence``
@@ -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:)``
@@ -0,0 +1,23 @@
# Finding the Minimum and Maximum
Find the minimum and maximum elements simultaneously,
or a specific number of elements at the minimum and maximum.
## Topics
### Finding Minimum or Maximum Elements
- ``Swift/Sequence/min(count:)``
- ``Swift/Collection/min(count:)``
- ``Swift/Sequence/min(count:sortedBy:)``
- ``Swift/Collection/min(count:sortedBy:)``
- ``Swift/Sequence/max(count:)``
- ``Swift/Collection/max(count:)``
- ``Swift/Sequence/max(count:sortedBy:)``
- ``Swift/Collection/max(count:sortedBy:)``
### Finding the Minimum and Maximum Elements Simulataneously
- ``Swift/Sequence/minAndMax()``
- ``Swift/Sequence/minAndMax(by:)``
@@ -0,0 +1,63 @@
# Partitioning and Rotating
Partition a collection according to a unary predicate,
rotate a collection around a particular index,
or find the index where a collection is already partitioned.
## Overview
A _stable partition_ maintains the relative order of elements within both partitions.
```swift
// partition(by:) - unstable ordering
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let p1 = numbers.partition(by: { $0.isMultiple(of: 20) })
// p1 == 4
// numbers == [10, 70, 30, 50, 40, 60, 20, 80]
// ^ start of second partition
// stablePartition(by:) - maintains relative ordering
numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let p2 = numbers.stablePartition(by: { $0.isMultiple(of: 20) })
// p2 == 4
// numbers == [10, 30, 50, 70, 20, 40, 60, 80]
// ^ start of second partition
```
Use the `rotate` method to shift the elements of a collection to start at a new position, moving the displaced elements to the end:
```swift
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let p = numbers.rotate(toStartAt: 2)
// numbers == [30, 40, 50, 60, 70, 80, 10, 20]
// p == 6 -- numbers[p] == 10
```
## Topics
### Stable Partition
- ``Swift/MutableCollection/stablePartition(by:)``
- ``Swift/MutableCollection/stablePartition(subrange:by:)``
- ``Swift/Sequence/partitioned(by:)``
- ``Swift/Collection/partitioned(by:)``
### Partition of Subranges
- ``Swift/MutableCollection/partition(subrange:by:)-5vdh7``
- ``Swift/MutableCollection/partition(subrange:by:)-4gpqz``
### Finding a Partition Index
- ``Swift/Collection/partitioningIndex(where:)``
### Rotation
- ``Swift/MutableCollection/rotate(toStartAt:)-9fp48``
- ``Swift/MutableCollection/rotate(toStartAt:)-2r55j``
- ``Swift/MutableCollection/rotate(subrange:toStartAt:)-ov6a``
- ``Swift/MutableCollection/rotate(subrange:toStartAt:)-5teoq``
### Reversing
- ``Swift/MutableCollection/reverse(subrange:)``
@@ -0,0 +1,35 @@
# Reductions
Find the incremental values of a sequence "reduce" operation.
## Overview
Call one of the `reductions` methods when you want the result of a `reduce` operation along with all of its intermediate values:
```swift
let exclusiveRunningTotal = (1...5).reductions(0, +)
print(exclusiveRunningTotal)
// prints [0, 1, 3, 6, 10, 15]
let inclusiveRunningTotal = (1...5).reductions(+)
print(inclusiveRunningTotal)
// prints [1, 3, 6, 10, 15]
```
## Topics
- ``Swift/Sequence/reductions(_:)``
- ``Swift/Sequence/reductions(_:_:)``
- ``Swift/Sequence/reductions(into:_:)``
- ``Swift/LazySequenceProtocol/reductions(_:)``
- ``Swift/LazySequenceProtocol/reductions(_:_:)``
- ``Swift/LazySequenceProtocol/reductions(into:_:)``
### Supporting Types
- ``InclusiveReductionsSequence``
- ``ExclusiveReductionsSequence``
### Deprecated Methods
- <doc:DeprecatedScan>
@@ -0,0 +1,17 @@
# Random Sampling
Choose a specified number of random elements from a sequence or collection.
## Topics
### Random Sampling
- ``Swift/Sequence/randomSample(count:)``
- ``Swift/Collection/randomSample(count:)``
- ``Swift/Collection/randomStableSample(count:)``
### Random Sampling with a Generator
- ``Swift/Sequence/randomSample(count:using:)``
- ``Swift/Collection/randomSample(count:using:)``
- ``Swift/Collection/randomStableSample(count:using:)``
@@ -0,0 +1,25 @@
# Selecting Elements
Select elements at a particular interval, the first mapped value,
or iterate of elements with their indices.
## Topics
### Selecting Elements at an Interval
- ``Swift/Sequence/striding(by:)``
- ``Swift/Collection/striding(by:)``
### Conditionally Finding the First Mapped Value
- ``Swift/Sequence/firstNonNil(_:)``
### Iterating Over Elements with Their Indices
- ``Swift/Collection/indexed()``
### Supporting Types
- ``IndexedCollection``
- ``StridingSequence``
- ``StridingCollection``
@@ -0,0 +1,29 @@
# Slicing and Splitting
Iterate over tuple pairs of adjacent elements, overlapping windows of a specified size, or lazily-calculated splits.
## Topics
### Adjacent Pairs
- ``Swift/Sequence/adjacentPairs()``
- ``Swift/Collection/adjacentPairs()``
### Windows
- ``Swift/Collection/windows(ofCount:)``
### Lazily Splitting a Collection
- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-4q4x8``
- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-68oqf``
- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-a46s``
- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-3rwee``
### Supporting Types
- ``AdjacentPairsSequence``
- ``AdjacentPairsCollection``
- ``WindowsOfCountCollection``
- ``SplitSequence``
- ``SplitCollection``
@@ -0,0 +1,32 @@
# Trimming
Remove unwanted elements from the start, the end, or both ends of a collection.
## Topics
### Trimming Both Ends of a Collection
- ``Swift/BidirectionalCollection/trimming(while:)``
- ``Swift/BidirectionalCollection/trim(while:)-781az``
- ``Swift/BidirectionalCollection/trim(while:)-6cbz3``
### Trimming from the Start
- ``Swift/Collection/trimmingPrefix(while:)``
- ``Swift/Collection/trimPrefix(while:)-2r8n8``
- ``Swift/Collection/trimPrefix(while:)-93obt``
### Trimming from the End
- ``Swift/BidirectionalCollection/trimmingSuffix(while:)``
- ``Swift/BidirectionalCollection/trimSuffix(while:)-33ubj``
- ``Swift/BidirectionalCollection/trimSuffix(while:)-3o6x9``
### Finding the Suffix of a Collection
- ``Swift/BidirectionalCollection/suffix(while:)``
### Finding Boundaries within a Collection
- ``Swift/Collection/endOfPrefix(while:)``
- ``Swift/BidirectionalCollection/startOfSuffix(while:)``
+200
View File
@@ -0,0 +1,200 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// Either
//===----------------------------------------------------------------------===//
/// A general-purpose sum type.
@usableFromInline
internal enum Either<Left, Right> {
case left(Left)
case right(Right)
}
extension Either: Equatable where Left: Equatable, Right: Equatable {
@usableFromInline
internal static func == (lhs: Self, rhs: Self) -> Bool {
switch (lhs, rhs) {
case let (.left(lhs), .left(rhs)):
return lhs == rhs
case let (.right(lhs), .right(rhs)):
return lhs == rhs
case (.left, .right), (.right, .left):
return false
}
}
}
extension Either: Comparable where Left: Comparable, Right: Comparable {
@usableFromInline
internal static func < (lhs: Self, rhs: Self) -> Bool {
switch (lhs, rhs) {
case let (.left(lhs), .left(rhs)):
return lhs < rhs
case let (.right(lhs), .right(rhs)):
return lhs < rhs
case (.left, .right):
return true
case (.right, .left):
return false
}
}
}
//===----------------------------------------------------------------------===//
// EitherSequence
//===----------------------------------------------------------------------===//
/// A sequence that has one of the two specified types.
@usableFromInline
internal enum EitherSequence<Left: Sequence, Right: Sequence>
where Left.Element == Right.Element
{
case left(Left)
case right(Right)
}
extension EitherSequence: Sequence {
@usableFromInline
internal struct Iterator: IteratorProtocol {
@usableFromInline
internal var left: Left.Iterator?
@usableFromInline
internal var right: Right.Iterator?
@inlinable
internal mutating func next() -> Left.Element? {
left?.next() ?? right?.next()
}
}
@usableFromInline
internal func makeIterator() -> Iterator {
switch self {
case .left(let left):
return Iterator(left: left.makeIterator(), right: nil)
case .right(let right):
return Iterator(left: nil, right: right.makeIterator())
}
}
}
extension EitherSequence: Collection
where Left: Collection, Right: Collection, Left.Element == Right.Element
{
@usableFromInline
internal typealias Index = Either<Left.Index, Right.Index>
@inlinable
internal var startIndex: Index {
switch self {
case .left(let s):
return .left(s.startIndex)
case .right(let s):
return .right(s.startIndex)
}
}
@inlinable
internal var endIndex: Index {
switch self {
case .left(let s):
return .left(s.endIndex)
case .right(let s):
return .right(s.endIndex)
}
}
@inlinable
internal subscript(position: Index) -> Element {
switch (self, position) {
case let (.left(s), .left(i)):
return s[i]
case let (.right(s), .right(i)):
return s[i]
default:
fatalError()
}
}
@inlinable
internal func index(after i: Index) -> Index {
switch (self,i) {
case let (.left(s), .left(i)):
return .left(s.index(after: i))
case let (.right(s), .right(i)):
return .right(s.index(after: i))
default:
fatalError()
}
}
@inlinable
internal func index(
_ i: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
switch (self, i, limit) {
case let (.left(s), .left(i), .left(limit)):
return s.index(i, offsetBy: distance, limitedBy: limit).map { .left($0) }
case let (.right(s), .right(i), .right(limit)):
return s.index(i, offsetBy: distance, limitedBy: limit).map { .right($0) }
default:
fatalError()
}
}
@inlinable
internal func index(_ i: Index, offsetBy distance: Int) -> Index {
switch (self, i) {
case let (.left(s), .left(i)):
return .left(s.index(i, offsetBy: distance))
case let (.right(s), .right(i)):
return .right(s.index(i, offsetBy: distance))
default:
fatalError()
}
}
@inlinable
internal func distance(from start: Index, to end: Index) -> Int {
switch (self, start, end) {
case let (.left(s), .left(i), .left(j)):
return s.distance(from: i, to: j)
case let (.right(s), .right(i), .right(j)):
return s.distance(from: i, to: j)
default:
fatalError()
}
}
}
extension EitherSequence: BidirectionalCollection
where Left: BidirectionalCollection, Right: BidirectionalCollection
{
@inlinable
internal func index(before i: Index) -> Index {
switch (self, i) {
case let (.left(s), .left(i)):
return .left(s.index(before: i))
case let (.right(s), .right(i)):
return .right(s.index(before: i))
default:
fatalError()
}
}
}
extension EitherSequence: RandomAccessCollection
where Left: RandomAccessCollection, Right: RandomAccessCollection {}
+44
View File
@@ -0,0 +1,44 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// firstNonNil(_:)
//===----------------------------------------------------------------------===//
extension Sequence {
/// Returns the first non-`nil` result obtained from applying the given
/// transformation to the elements of the sequence.
///
/// let strings = ["three", "3.14", "-5", "2"]
/// if let firstInt = strings.firstNonNil({ Int($0) }) {
/// print(firstInt)
/// // -5
/// }
///
/// - Parameter transform: A closure that takes an element of the sequence as
/// its argument and returns an optional transformed value.
/// - Returns: The first non-`nil` return value of the transformation, or
/// `nil` if no transformation is successful.
///
/// - Complexity: O(*n*), where *n* is the number of elements at the start of
/// the sequence that result in `nil` when applying the transformation.
@inlinable
public func firstNonNil<Result>(
_ transform: (Element) throws -> Result?
) rethrows -> Result? {
for value in self {
if let value = try transform(value) {
return value
}
}
return nil
}
}
+311
View File
@@ -0,0 +1,311 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
/// A collection consisting of all the elements contained in a collection of
/// collections.
@usableFromInline
internal struct FlattenCollection<Base: Collection>
where Base.Element: Collection
{
@usableFromInline
internal let base: Base
@usableFromInline
internal let indexOfFirstNonEmptyElement: Base.Index
@inlinable
internal init(base: Base) {
self.base = base
self.indexOfFirstNonEmptyElement = base.endOfPrefix(while: { $0.isEmpty })
}
}
extension FlattenCollection: Collection {
@usableFromInline
internal struct Index: Comparable {
@usableFromInline
internal let outer: Base.Index
@usableFromInline
internal let inner: Base.Element.Index?
@inlinable
init(outer: Base.Index, inner: Base.Element.Index?) {
self.outer = outer
self.inner = inner
}
@inlinable
internal static func < (lhs: Self, rhs: Self) -> Bool {
guard lhs.outer == rhs.outer else { return lhs.outer < rhs.outer }
return lhs.inner == nil ? false : lhs.inner! < rhs.inner!
}
}
@inlinable
internal var startIndex: Index {
let outer = indexOfFirstNonEmptyElement
let inner = outer == base.endIndex ? nil : base[outer].startIndex
return Index(outer: outer, inner: inner)
}
@inlinable
internal var endIndex: Index {
Index(outer: base.endIndex, inner: nil)
}
/// Forms an index from a pair of base indices, normalizing
/// `(i, base2.endIndex)` to `(base1.index(after: i), base2.startIndex)` if
/// necessary.
@inlinable
internal func normalizeIndex(
outer: Base.Index,
inner: Base.Element.Index
) -> Index {
if inner == base[outer].endIndex {
let outer = base[base.index(after: outer)...]
.endOfPrefix(while: { $0.isEmpty })
let inner = outer == base.endIndex ? nil : base[outer].startIndex
return Index(outer: outer, inner: inner)
} else {
return Index(outer: outer, inner: inner)
}
}
@inlinable
internal func index(after index: Index) -> Index {
let element = base[index.outer]
let nextInner = element.index(after: index.inner!)
return normalizeIndex(outer: index.outer, inner: nextInner)
}
@inlinable
internal subscript(position: Index) -> Base.Element.Element {
base[position.outer][position.inner!]
}
@inlinable
internal func distance(from start: Index, to end: Index) -> Int {
guard start.outer <= end.outer
else { return -distance(from: end, to: start) }
guard let startInner = start.inner
else { return 0 }
guard start.outer != end.outer
else {
return base[start.outer].distance(from: startInner, to: end.inner!)
}
let firstPart = base[start.outer][startInner...].count
let middlePart = base[start.outer..<end.outer].dropFirst()
.reduce(0, { $0 + $1.count })
let lastPart = end.inner.map { base[end.outer][..<$0].count } ?? 0
return firstPart + middlePart + lastPart
}
@inlinable
internal func index(_ index: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return index }
return distance > 0
? offsetForward(index, by: distance)
: offsetBackward(index, by: -distance)
}
@inlinable
internal func index(
_ index: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
guard distance != 0 else { return index }
if distance > 0 {
return limit >= index
? offsetForward(index, by: distance, limitedBy: limit)
: offsetForward(index, by: distance)
} else {
return limit <= index
? offsetBackward(index, by: -distance, limitedBy: limit)
: offsetBackward(index, by: -distance)
}
}
@inlinable
internal func offsetForward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetForward(i, by: distance, limitedBy: endIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetBackward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetBackward(i, by: distance, limitedBy: startIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetForward(
_ index: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit >= index)
if index.outer == limit.outer {
if let indexInner = index.inner, let limitInner = limit.inner {
return base[index.outer]
.index(indexInner, offsetBy: distance, limitedBy: limitInner)
.map { inner in Index(outer: index.outer, inner: inner) }
} else {
// `index` and `limit` are both `endIndex`
return nil
}
}
// `index <= limit` and `index.outer != limit.outer`, so `index != endIndex`
let indexInner = index.inner!
let element = base[index.outer]
if let inner = element.index(
indexInner,
offsetBy: distance,
limitedBy: element.endIndex
) {
return normalizeIndex(outer: index.outer, inner: inner)
}
var remainder = distance - element[indexInner...].count
var outer = base.index(after: index.outer)
while outer != limit.outer {
let element = base[outer]
if let inner = element.index(
element.startIndex,
offsetBy: remainder,
limitedBy: element.endIndex
) {
return normalizeIndex(outer: outer, inner: inner)
}
remainder -= element.count
base.formIndex(after: &outer)
}
if let limitInner = limit.inner {
let element = base[outer]
return element.index(
element.startIndex,
offsetBy: remainder,
limitedBy: limitInner)
.map { inner in Index(outer: outer, inner: inner) }
} else {
return nil
}
}
@inlinable
internal func offsetBackward(
_ index: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit <= index)
if index.outer == limit.outer {
if let indexInner = index.inner, let limitInner = limit.inner {
return base[index.outer]
.index(indexInner, offsetBy: -distance, limitedBy: limitInner)
.map { inner in Index(outer: index.outer, inner: inner) }
} else {
// `index` and `limit` are both `endIndex`
return nil
}
}
var remainder = distance
if let indexInner = index.inner {
let element = base[index.outer]
if let inner = element.index(
indexInner,
offsetBy: -remainder,
limitedBy: element.startIndex
) {
return Index(outer: index.outer, inner: inner)
}
remainder -= element[..<indexInner].count
}
var outer = base.index(index.outer, offsetBy: -1)
while outer != limit.outer {
let element = base[outer]
if let inner = element.index(
element.endIndex,
offsetBy: -remainder,
limitedBy: element.startIndex
) {
return Index(outer: outer, inner: inner)
}
remainder -= element.count
base.formIndex(&outer, offsetBy: -1)
}
let element = base[outer]
return element.index(
element.endIndex,
offsetBy: -remainder,
limitedBy: limit.inner!
).map { inner in Index(outer: outer, inner: inner) }
}
}
extension FlattenCollection: BidirectionalCollection
where Base: BidirectionalCollection, Base.Element: BidirectionalCollection
{
@inlinable
internal func index(before index: Index) -> Index {
if let inner = index.inner {
let element = base[index.outer]
if inner != element.startIndex {
let previousInner = element.index(before: inner)
return Index(outer: index.outer, inner: previousInner)
}
}
let previousOuter = base[..<index.outer].lastIndex(where: { !$0.isEmpty })!
let element = base[previousOuter]
let previousInner = element.index(before: element.endIndex)
return Index(outer: previousOuter, inner: previousInner)
}
}
extension FlattenCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol, Base.Element: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// joined()
//===----------------------------------------------------------------------===//
extension Collection where Element: Collection {
/// Returns the concatenation of the elements in this collection of
/// collections.
@inlinable
internal func joined() -> FlattenCollection<Self> {
FlattenCollection(base: self)
}
}
+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)
}
}
+33 -16
View File
@@ -11,20 +11,21 @@
/// A collection wrapper that iterates over the indices and elements of a
/// collection together.
public struct Indexed<Base: Collection> {
/// The element type for an `Indexed` collection.
public typealias Element = (index: Base.Index, element: Base.Element)
public struct IndexedCollection<Base: Collection> {
/// The base collection.
public let base: Base
@usableFromInline
internal let base: Base
@inlinable
internal init(base: Base) {
self.base = base
}
}
extension Indexed: Collection {
extension IndexedCollection: Collection {
/// The element type for an `IndexedCollection` collection.
public typealias Element = (index: Base.Index, element: Base.Element)
@inlinable
public var startIndex: Base.Index {
base.startIndex
@@ -51,7 +52,11 @@ extension Indexed: Collection {
}
@inlinable
public func index(_ i: Base.Index, offsetBy distance: Int, limitedBy limit: Base.Index) -> Base.Index? {
public func index(
_ i: Base.Index,
offsetBy distance: Int,
limitedBy limit: Base.Index
) -> Base.Index? {
base.index(i, offsetBy: distance, limitedBy: limit)
}
@@ -59,19 +64,27 @@ extension Indexed: Collection {
public func distance(from start: Base.Index, to end: Base.Index) -> Int {
base.distance(from: start, to: end)
}
@inlinable
public var indices: Base.Indices {
base.indices
}
}
extension Indexed: BidirectionalCollection where Base: BidirectionalCollection {
extension IndexedCollection: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
public func index(before i: Base.Index) -> Base.Index {
base.index(before: i)
}
}
extension Indexed: RandomAccessCollection where Base: RandomAccessCollection {}
extension Indexed: LazySequenceProtocol where Base: LazySequenceProtocol {}
extension Indexed: Equatable where Base: Equatable {}
extension Indexed: Hashable where Base: Hashable {}
extension IndexedCollection: RandomAccessCollection
where Base: RandomAccessCollection {}
extension IndexedCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// indexed()
@@ -81,6 +94,10 @@ extension Collection {
/// Returns a collection of pairs *(i, x)*, where *i* represents an index of
/// the collection, and *x* represents an element.
///
/// The `indexed()` method is similar to the standard library's `enumerated()`
/// method, but provides the index with each element instead of a zero-based
/// counter.
///
/// This example iterates over the indices and elements of a set, building an
/// array consisting of indices of names with five or fewer letters.
///
@@ -92,9 +109,9 @@ extension Collection {
/// }
/// }
///
/// Returns: A collection of paired indices and elements of this collection.
/// - Returns: A collection of paired indices and elements of this collection.
@inlinable
public func indexed() -> Indexed<Self> {
Indexed(base: self)
public func indexed() -> IndexedCollection<Self> {
IndexedCollection(base: self)
}
}
+669
View File
@@ -0,0 +1,669 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// Intersperse
//===----------------------------------------------------------------------===//
/// A sequence that presents the elements of a base sequence of elements with a
/// separator between each of those elements.
public struct InterspersedSequence<Base: Sequence> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let separator: Base.Element
@inlinable
internal init(base: Base, separator: Base.Element) {
self.base = base
self.separator = separator
}
}
extension InterspersedSequence: Sequence {
/// The iterator for an `InterspersedSequence` sequence.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal enum State {
case start
case element(Base.Element)
case separator
}
@usableFromInline
internal var iterator: Base.Iterator
@usableFromInline
internal let separator: Base.Element
@usableFromInline
internal var state = State.start
@inlinable
internal init(iterator: Base.Iterator, separator: Base.Element) {
self.iterator = iterator
self.separator = separator
}
@inlinable
public mutating func next() -> Base.Element? {
// After the start, the state flips between element and separator. Before
// returning a separator, a check is made for the next element as a
// separator is only returned between two elements. The next element is
// stored to allow it to be returned in the next iteration.
switch state {
case .start:
state = .separator
return iterator.next()
case .separator:
guard let next = iterator.next() else { return nil }
state = .element(next)
return separator
case .element(let element):
state = .separator
return element
}
}
}
@inlinable
public func makeIterator() -> InterspersedSequence<Base>.Iterator {
Iterator(iterator: base.makeIterator(), separator: separator)
}
}
extension InterspersedSequence: Collection where Base: Collection {
/// A position in an `InterspersedSequence` instance.
public struct Index: Comparable {
@usableFromInline
internal enum Representation: Equatable {
case element(Base.Index)
case separator(next: Base.Index)
}
@usableFromInline
internal let representation: Representation
@inlinable
internal init(representation: Representation) {
self.representation = representation
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
switch (lhs.representation, rhs.representation) {
case let (.element(li), .element(ri)),
let (.separator(next: li), .separator(next: ri)),
let (.element(li), .separator(next: ri)):
return li < ri
case let (.separator(next: li), .element(ri)):
return li <= ri
}
}
@inlinable
internal static func element(_ index: Base.Index) -> Self {
Self(representation: .element(index))
}
@inlinable
internal static func separator(next: Base.Index) -> Self {
Self(representation: .separator(next: next))
}
}
@inlinable
public var startIndex: Index {
base.startIndex == base.endIndex ? endIndex : .element(base.startIndex)
}
@inlinable
public var endIndex: Index {
.separator(next: base.endIndex)
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i != endIndex, "Can't advance past endIndex")
switch i.representation {
case let .element(index):
return .separator(next: base.index(after: index))
case let .separator(next):
return .element(next)
}
}
@inlinable
public subscript(position: Index) -> Element {
switch position.representation {
case .element(let index): return base[index]
case .separator: return separator
}
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
switch (start.representation, end.representation) {
case let (.element(element), .separator(next: separator)):
return 2 * base.distance(from: element, to: separator) - 1
case let (.separator(next: separator), .element(element)):
return 2 * base.distance(from: separator, to: element) + 1
case let (.element(start), .element(end)),
let (.separator(start), .separator(end)):
return 2 * base.distance(from: start, to: end)
}
}
@inlinable
public func index(_ index: Index, offsetBy distance: Int) -> Index {
distance >= 0
? offsetForward(index, by: distance)
: offsetBackward(index, by: -distance)
}
@inlinable
public func index(
_ index: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
if distance >= 0 {
return limit >= index
? offsetForward(index, by: distance, limitedBy: limit)
: offsetForward(index, by: distance)
} else {
return limit <= index
? offsetBackward(index, by: -distance, limitedBy: limit)
: offsetBackward(index, by: -distance)
}
}
@inlinable
internal func offsetForward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetForward(i, by: distance, limitedBy: endIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetBackward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetBackward(i, by: distance, limitedBy: startIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetForward(
_ index: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance >= 0)
assert(limit >= index)
switch (index.representation, limit.representation, distance.isMultiple(of: 2)) {
case let (.element(index), .element(limit), true),
let (.separator(next: index), .element(limit), false):
return base.index(index, offsetBy: distance / 2, limitedBy: limit)
.map { .element($0) }
case let (.element(index), .element(limit), false),
let (.element(index), .separator(next: limit), false),
let (.separator(next: index), .element(limit), true),
let (.separator(next: index), .separator(next: limit), true):
return base.index(index, offsetBy: (distance + 1) / 2, limitedBy: limit)
.map { .separator(next: $0) }
case let (.element(index), .separator(next: limit), true),
let (.separator(next: index), .separator(next: limit), false):
return base.index(index, offsetBy: distance / 2, limitedBy: limit)
.flatMap { $0 == limit ? nil : .element($0) }
}
}
@inlinable
internal func offsetBackward(
_ index: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance >= 0)
assert(limit <= index)
switch (index.representation, limit.representation, distance.isMultiple(of: 2)) {
case let (.element(index), .element(limit), true),
let (.element(index), .separator(next: limit), true),
let (.separator(next: index), .element(limit), false),
let (.separator(next: index), .separator(next: limit), false):
return base.index(index, offsetBy: -((distance + 1) / 2), limitedBy: limit)
.map { .element($0) }
case let (.element(index), .separator(next: limit), false),
let (.separator(next: index), .separator(next: limit), true):
return base.index(index, offsetBy: -(distance / 2), limitedBy: limit)
.map { .separator(next: $0) }
case let (.element(index), .element(limit), false),
let (.separator(next: index), .element(limit), true):
return base.index(index, offsetBy: -(distance / 2), limitedBy: limit)
.flatMap { $0 == limit ? nil : .separator(next: $0) }
}
}
}
extension InterspersedSequence: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
public func index(before i: Index) -> Index {
precondition(i != startIndex, "Can't move before startIndex")
switch i.representation {
case let .element(index):
return .separator(next: index)
case let .separator(next):
return .element(base.index(before: next))
}
}
}
extension InterspersedSequence: RandomAccessCollection
where Base: RandomAccessCollection {}
extension InterspersedSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
extension InterspersedSequence: LazyCollectionProtocol
where Base: LazySequenceProtocol & Collection {}
//===----------------------------------------------------------------------===//
// InterspersedMap
//===----------------------------------------------------------------------===//
/// A sequence over the results of applying a closure to the sequence's
/// elements, with a separator that separates each pair of adjacent transformed
/// values.
@usableFromInline
internal struct InterspersedMapSequence<Base: Sequence, Result> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let transform: (Base.Element) -> Result
@usableFromInline
internal let separator: (Base.Element, Base.Element) -> Result
}
extension InterspersedMapSequence: Sequence {
@usableFromInline
internal struct Iterator: IteratorProtocol {
@usableFromInline
internal enum State {
case start
case element(Base.Element)
case separator(previous: Base.Element)
}
@usableFromInline
internal var base: Base.Iterator
@usableFromInline
internal let transform: (Base.Element) -> Result
@usableFromInline
internal let separator: (Base.Element, Base.Element) -> Result
@usableFromInline
internal var state = State.start
@inlinable
internal init(
base: Base.Iterator,
transform: @escaping (Base.Element) -> Result,
separator: @escaping (Base.Element, Base.Element) -> Result
) {
self.base = base
self.transform = transform
self.separator = separator
}
@inlinable
internal mutating func next() -> Result? {
switch state {
case .start:
guard let first = base.next() else { return nil }
state = .separator(previous: first)
return transform(first)
case .separator(let previous):
guard let next = base.next() else { return nil }
state = .element(next)
return separator(previous, next)
case .element(let element):
state = .separator(previous: element)
return transform(element)
}
}
}
@inlinable
internal func makeIterator() -> Iterator {
Iterator(
base: base.makeIterator(),
transform: transform,
separator: separator)
}
}
extension InterspersedMapSequence: Collection where Base: Collection {
@usableFromInline
internal struct Index: Comparable {
@usableFromInline
internal enum Representation {
case element(Base.Index)
case separator(previous: Base.Index, next: Base.Index)
}
@usableFromInline
internal let representation: Representation
@inlinable
internal init(representation: Representation) {
self.representation = representation
}
@inlinable
internal static func element(_ index: Base.Index) -> Self {
Self(representation: .element(index))
}
@inlinable
internal static func separator(previous: Base.Index, next: Base.Index) -> Self {
Self(representation: .separator(previous: previous, next: next))
}
@inlinable
internal static func == (lhs: Self, rhs: Self) -> Bool {
switch (lhs.representation, rhs.representation) {
case let (.element(lhs), .element(rhs)),
let (.separator(_, next: lhs), .separator(_, next: rhs)):
return lhs == rhs
case (.element, .separator), (.separator, .element):
return false
}
}
@inlinable
internal static func < (lhs: Self, rhs: Self) -> Bool {
switch (lhs.representation, rhs.representation) {
case let (.element(lhs), .element(rhs)),
let (.separator(_, next: lhs), .separator(_, next: rhs)),
let (.element(lhs), .separator(_, next: rhs)),
let (.separator(previous: lhs, _), .element(rhs)):
return lhs < rhs
}
}
}
@inlinable
internal var startIndex: Index {
base.isEmpty ? endIndex : .element(base.startIndex)
}
@inlinable
internal var endIndex: Index {
.separator(previous: base.endIndex, next: base.endIndex)
}
@inlinable
internal func index(after index: Index) -> Index {
switch index.representation {
case .element(let index):
let next = base.index(after: index)
return .separator(previous: index, next: next)
case .separator(_, let next):
return .element(next)
}
}
@inlinable
internal subscript(position: Index) -> Result {
switch position.representation {
case .element(let index):
return transform(base[index])
case let .separator(previous, next):
return separator(base[previous], base[next])
}
}
@inlinable
internal func distance(from start: Index, to end: Index) -> Int {
switch (start.representation, end.representation) {
case let (.element(lhs), .element(rhs)),
let (.separator(_, next: lhs), .separator(_, next: rhs)):
return 2 * base.distance(from: lhs, to: rhs)
case let (.element(lhs), .separator(_, next: rhs)):
return 2 * base.distance(from: lhs, to: rhs) - 1
case let (.separator(_, next: lhs), .element(rhs)):
return 2 * base.distance(from: lhs, to: rhs) + 1
}
}
@inlinable
internal func index(_ index: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return index }
return distance > 0
? offsetForward(index, by: distance)
: offsetBackward(index, by: -distance)
}
@inlinable
internal func index(
_ index: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
guard distance != 0 else { return index }
if distance > 0 {
return limit >= index
? offsetForward(index, by: distance, limitedBy: limit)
: offsetForward(index, by: distance)
} else {
return limit <= index
? offsetBackward(index, by: -distance, limitedBy: limit)
: offsetBackward(index, by: -distance)
}
}
@inlinable
internal func offsetForward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetForward(i, by: distance, limitedBy: endIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetBackward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetBackward(i, by: distance, limitedBy: startIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetForward(
_ index: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit >= index)
switch (index.representation, limit.representation, distance.isMultiple(of: 2)) {
case let (.element(index), .element(limit), true),
let (.separator(_, next: index), .element(limit), false):
return base.index(index, offsetBy: distance / 2, limitedBy: limit)
.map { .element($0) }
case let (.element(index), .element(limit), false),
let (.element(index), .separator(_, next: limit), false),
let (.separator(_, next: index), .element(limit), true),
let (.separator(_, next: index), .separator(_, next: limit), true):
return base.index(index, offsetBy: (distance - 1) / 2, limitedBy: limit)
.flatMap {
guard $0 != limit else { return nil }
let next = base.index(after: $0)
return next == base.endIndex
? endIndex
: .separator(previous: $0, next: next)
}
case let (.element(index), .separator(_, next: limit), true),
let (.separator(_, next: index), .separator(_, next: limit), false):
return base.index(index, offsetBy: distance / 2, limitedBy: limit)
.flatMap { $0 == limit ? nil : .element($0) }
}
}
@inlinable
internal func offsetBackward(
_ index: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit <= index)
switch (index.representation, limit.representation, distance.isMultiple(of: 2)) {
case let (.element(index), .element(limit), true),
let (.element(index), .separator(_, next: limit), true),
let (.separator(_, next: index), .element(limit), false),
let (.separator(_, next: index), .separator(_, next: limit), false):
return base.index(index, offsetBy: -((distance + 1) / 2), limitedBy: limit)
.map { .element($0) }
case let (.element(index), .separator(_, next: limit), false),
let (.separator(_, next: index), .separator(_, next: limit), true):
return base.index(index, offsetBy: -(distance / 2), limitedBy: limit)
.map { .separator(previous: base.index($0, offsetBy: -1), next: $0) }
case let (.element(index), .element(limit), false),
let (.separator(_, next: index), .element(limit), true):
return base.index(index, offsetBy: -(distance / 2), limitedBy: limit)
.flatMap {
$0 == limit
? nil
: .separator(previous: base.index($0, offsetBy: -1), next: $0)
}
}
}
}
extension InterspersedMapSequence: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
internal func index(before index: Index) -> Index {
switch index.representation {
case .element(let index):
let previous = base.index(before: index)
return .separator(previous: previous, next: index)
case let .separator(previous, next):
let index = next == base.endIndex ? base.index(before: next) : previous
return .element(index)
}
}
}
extension InterspersedMapSequence.Index: Hashable
where Base.Index: Hashable
{
@inlinable
internal func hash(into hasher: inout Hasher) {
switch representation {
case .element(let base):
hasher.combine(false)
hasher.combine(base)
case .separator(_, let next):
hasher.combine(true)
hasher.combine(next)
}
}
}
extension InterspersedMapSequence: LazySequenceProtocol {}
extension InterspersedMapSequence: LazyCollectionProtocol
where Base: Collection {}
//===----------------------------------------------------------------------===//
// interspersed(with:)
//===----------------------------------------------------------------------===//
extension Sequence {
/// Returns a sequence containing elements of this sequence with the given
/// separator inserted in between each element.
///
/// Any value of the sequence's element type can be used as the separator.
///
/// ```
/// for value in [1,2,3].interspersed(with: 0) {
/// print(value)
/// }
/// // 1
/// // 0
/// // 2
/// // 0
/// // 3
/// ```
///
/// The following shows a String being interspersed with a Character:
/// ```
/// let result = "ABCDE".interspersed(with: "-")
/// print(String(result))
/// // "A-B-C-D-E"
/// ```
///
/// - Parameter separator: Value to insert in between each of this sequence’s
/// elements.
/// - Returns: The interspersed sequence of elements.
///
/// - Complexity: O(1)
@inlinable
public func interspersed(
with separator: Element
) -> InterspersedSequence<Self> {
InterspersedSequence(base: self, separator: separator)
}
}
//===----------------------------------------------------------------------===//
// lazy.interspersedMap(_:with:)
//===----------------------------------------------------------------------===//
extension LazySequenceProtocol {
/// Returns a sequence over the results of applying a closure to the
/// sequence's elements, with a separator that separates each pair of adjacent
/// transformed values.
///
/// The transformation closure lets you intersperse a sequence using a
/// separator of a different type than the original's sequence's elements.
/// Each separator is produced by a closure that is given access to the
/// two elements in the original sequence right before and after it.
///
/// let strings = [1, 2, 2].interspersedMap(String.init,
/// with: { $0 == $1 ? " == " : " != " })
/// print(strings.joined()) // "1 != 2 == 2"
///
@usableFromInline
internal func interspersedMap<Result>(
_ transform: @escaping (Element) -> Result,
with separator: @escaping (Element, Element) -> Result
) -> InterspersedMapSequence<Elements, Result> {
InterspersedMapSequence(
base: elements,
transform: transform,
separator: separator)
}
}
+489
View File
@@ -0,0 +1,489 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// JoinedBySequence
//===----------------------------------------------------------------------===//
/// A sequence that presents the elements of a base sequence of sequences
/// concatenated using a given separator.
public struct JoinedBySequence<Base: Sequence, Separator: Sequence>
where Base.Element: Sequence, Base.Element.Element == Separator.Element
{
@usableFromInline
internal typealias Inner = FlattenSequence<InterspersedSequence<
LazyMapSequence<Base, EitherSequence<Base.Element, Separator>>>>
@usableFromInline
internal let inner: Inner
@inlinable
internal init(base: Base, separator: Separator) {
self.inner = base.lazy
.map(EitherSequence.left)
.interspersed(with: .right(separator))
.joined()
}
}
extension JoinedBySequence: Sequence {
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var inner: Inner.Iterator
@inlinable
internal init(inner: Inner.Iterator) {
self.inner = inner
}
@inlinable
public mutating func next() -> Base.Element.Element? {
inner.next()
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(inner: inner.makeIterator())
}
}
extension JoinedBySequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// JoinedByClosureSequence
//===----------------------------------------------------------------------===//
/// A sequence that presents the elements of a base sequence of sequences
/// concatenated using a given separator that depends on the sequences right
/// before and after it.
public struct JoinedByClosureSequence<Base: Sequence, Separator: Sequence>
where Base.Element: Sequence, Base.Element.Element == Separator.Element
{
@usableFromInline
internal typealias Inner = FlattenSequence<InterspersedMapSequence<
Base, EitherSequence<Base.Element, Separator>>>
@usableFromInline
internal let inner: Inner
@inlinable
internal init(
base: Base,
separator: @escaping (Base.Element, Base.Element) -> Separator
) {
self.inner = base.lazy
.interspersedMap(
EitherSequence.left,
with: { EitherSequence.right(separator($0, $1)) })
.joined()
}
}
extension JoinedByClosureSequence: Sequence {
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var inner: Inner.Iterator
@inlinable
internal init(inner: Inner.Iterator) {
self.inner = inner
}
@inlinable
public mutating func next() -> Base.Element.Element? {
inner.next()
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(inner: inner.makeIterator())
}
}
extension JoinedByClosureSequence: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// JoinedByCollection
//===----------------------------------------------------------------------===//
/// A collection that presents the elements of a base collection of collections
/// concatenated using a given separator.
public struct JoinedByCollection<Base: Collection, Separator: Collection>
where Base.Element: Collection, Base.Element.Element == Separator.Element
{
@usableFromInline
internal typealias Inner = FlattenCollection<InterspersedSequence<
LazyMapSequence<Base, EitherSequence<Base.Element, Separator>>>>
@usableFromInline
internal let inner: Inner
@inlinable
internal init(base: Base, separator: Separator) {
self.inner = base.lazy
.map(EitherSequence.left)
.interspersed(with: .right(separator))
.joined()
}
}
extension JoinedByCollection: Collection {
public struct Index: Comparable {
@usableFromInline
internal let inner: Inner.Index
@inlinable
internal init(_ inner: Inner.Index) {
self.inner = inner
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs.inner == rhs.inner
}
@inlinable
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.inner < rhs.inner
}
}
@inlinable
public var startIndex: Index {
Index(inner.startIndex)
}
@inlinable
public var endIndex: Index {
Index(inner.endIndex)
}
@inlinable
public func index(after index: Index) -> Index {
Index(inner.index(after: index.inner))
}
@inlinable
public subscript(position: Index) -> Base.Element.Element {
inner[position.inner]
}
@inlinable
public func index(_ index: Index, offsetBy distance: Int) -> Index {
Index(inner.index(index.inner, offsetBy: distance))
}
@inlinable
public func index(
_ index: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
inner.index(index.inner, offsetBy: distance, limitedBy: limit.inner)
.map(Index.init)
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
inner.distance(from: start.inner, to: end.inner)
}
}
extension JoinedByCollection: BidirectionalCollection
where Base: BidirectionalCollection,
Base.Element: BidirectionalCollection,
Separator: BidirectionalCollection
{
@inlinable
public func index(before index: Index) -> Index {
Index(inner.index(before: index.inner))
}
}
extension JoinedByCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// JoinedByClosureCollection
//===----------------------------------------------------------------------===//
/// A collection that presents the elements of a base collection of collections
/// concatenated using a given separator that depends on the collections right
/// before and after it.
public struct JoinedByClosureCollection<Base: Collection, Separator: Collection>
where Base.Element: Collection, Base.Element.Element == Separator.Element
{
@usableFromInline
internal typealias Inner = FlattenCollection<InterspersedMapSequence<
Base, EitherSequence<Base.Element, Separator>>>
@usableFromInline
internal let inner: Inner
@inlinable
internal init(
base: Base,
separator: @escaping (Base.Element, Base.Element) -> Separator
) {
self.inner = base.lazy
.interspersedMap(
EitherSequence.left,
with: { EitherSequence.right(separator($0, $1)) })
.joined()
}
}
extension JoinedByClosureCollection: Collection {
public struct Index: Comparable {
@usableFromInline
internal let inner: Inner.Index
@inlinable
internal init(_ inner: Inner.Index) {
self.inner = inner
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs.inner == rhs.inner
}
@inlinable
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.inner < rhs.inner
}
}
@inlinable
public var startIndex: Index {
Index(inner.startIndex)
}
@inlinable
public var endIndex: Index {
Index(inner.endIndex)
}
@inlinable
public func index(after index: Index) -> Index {
Index(inner.index(after: index.inner))
}
@inlinable
public subscript(position: Index) -> Base.Element.Element {
inner[position.inner]
}
@inlinable
public func index(_ index: Index, offsetBy distance: Int) -> Index {
Index(inner.index(index.inner, offsetBy: distance))
}
@inlinable
public func index(
_ index: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
inner.index(index.inner, offsetBy: distance, limitedBy: limit.inner)
.map(Index.init)
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
inner.distance(from: start.inner, to: end.inner)
}
}
extension JoinedByClosureCollection: BidirectionalCollection
where Base: BidirectionalCollection,
Base.Element: BidirectionalCollection,
Separator: BidirectionalCollection
{
@inlinable
public func index(before index: Index) -> Index {
Index(inner.index(before: index.inner))
}
}
extension JoinedByClosureCollection: LazyCollectionProtocol {}
//===----------------------------------------------------------------------===//
// Sequence.joined(by:)
//===----------------------------------------------------------------------===//
extension Sequence where Element: Sequence {
/// Returns the concatenation of the elements in this sequence of sequences,
/// inserting the given separator between each sequence.
///
/// for x in [[1, 2], [3, 4], [5, 6]].joined(by: 100) {
/// print(x)
/// }
/// // 1, 2, 100, 3, 4, 100, 5, 6
@inlinable
public func joined(by separator: Element.Element)
-> JoinedBySequence<Self, CollectionOfOne<Element.Element>>
{
joined(by: CollectionOfOne(separator))
}
/// Returns the concatenation of the elements in this sequence of sequences,
/// inserting the given separator between each sequence.
///
/// for x in [[1, 2], [3, 4], [5, 6]].joined(by: [100, 200]) {
/// print(x)
/// }
/// // 1, 2, 100, 200, 3, 4, 100, 200, 5, 6
@inlinable
public func joined<Separator>(
by separator: Separator
) -> JoinedBySequence<Self, Separator>
where Separator: Collection, Separator.Element == Element.Element
{
JoinedBySequence(base: self, separator: separator)
}
@inlinable
internal func _joined(
by update: (inout [Element.Element], Element, Element) throws -> Void
) rethrows -> [Element.Element] {
var iterator = makeIterator()
guard let first = iterator.next() else { return [] }
var result = Array(first)
var previous = first
while let next = iterator.next() {
try update(&result, previous, next)
result.append(contentsOf: next)
previous = next
}
return result
}
/// Returns the concatenation of the elements in this sequence of sequences,
/// inserting the separator produced by the closure between each sequence.
///
/// for x in [[1, 2], [3, 4], [5, 6]].joined(by: { $0.last! * $1.first! }) {
/// print(x)
/// }
/// // 1, 2, 6, 3, 4, 20, 5, 6
@inlinable
public func joined(
by separator: (Element, Element) throws -> Element.Element
) rethrows -> [Element.Element] {
try _joined(by: { $0.append(try separator($1, $2)) })
}
/// Returns the concatenation of the elements in this sequence of sequences,
/// inserting the separator produced by the closure between each sequence.
///
/// for x in [[1, 2], [3, 4], [5, 6]].joined(by: { [100 * $0.last!, 100 * $1.first!] }) {
/// print(x)
/// }
/// // 1, 2, 200, 300, 3, 4, 400, 500, 5, 6
@inlinable
public func joined<Separator>(
by separator: (Element, Element) throws -> Separator
) rethrows -> [Element.Element]
where Separator: Sequence, Separator.Element == Element.Element
{
try _joined(by: { $0.append(contentsOf: try separator($1, $2)) })
}
}
//===----------------------------------------------------------------------===//
// LazySequenceProtocol.joined(by:)
//===----------------------------------------------------------------------===//
extension LazySequenceProtocol where Element: Sequence {
/// Returns the concatenation of the elements in this sequence of sequences,
/// inserting the separator produced by the closure between each sequence.
@inlinable
public func joined(
by separator: @escaping (Element, Element) -> Element.Element
) -> JoinedByClosureSequence<Elements, CollectionOfOne<Element.Element>> {
joined(by: { CollectionOfOne(separator($0, $1)) })
}
/// Returns the concatenation of the elements in this sequence of sequences,
/// inserting the separator produced by the closure between each sequence.
@inlinable
public func joined<Separator>(
by separator: @escaping (Element, Element) -> Separator
) -> JoinedByClosureSequence<Elements, Separator> {
JoinedByClosureSequence(base: elements, separator: separator)
}
}
//===----------------------------------------------------------------------===//
// Collection.joined(by:)
//===----------------------------------------------------------------------===//
extension Collection where Element: Collection {
/// Returns the concatenation of the elements in this collection of
/// collections, inserting the given separator between each collection.
///
/// for x in [[1, 2], [3, 4], [5, 6]].joined(by: 100) {
/// print(x)
/// }
/// // 1, 2, 100, 3, 4, 100, 5, 6
@inlinable
public func joined(by separator: Element.Element)
-> JoinedByCollection<Self, CollectionOfOne<Element.Element>>
{
joined(by: CollectionOfOne(separator))
}
/// Returns the concatenation of the elements in this collection of
/// collections, inserting the given separator between each collection.
///
/// for x in [[1, 2], [3, 4], [5, 6]].joined(by: [100, 200]) {
/// print(x)
/// }
/// // 1, 2, 100, 200, 3, 4, 100, 200, 5, 6
@inlinable
public func joined<Separator>(by separator: Separator)
-> JoinedByCollection<Self, Separator>
{
JoinedByCollection(base: self, separator: separator)
}
}
//===----------------------------------------------------------------------===//
// LazySequenceProtocol.joined(by:) where Self: Collection
//===----------------------------------------------------------------------===//
extension LazySequenceProtocol where Elements: Collection, Element: Collection {
/// Returns the concatenation of the elements in this collection of
/// collections, inserting the separator produced by the closure between each
/// sequence.
@inlinable
public func joined(
by separator: @escaping (Element, Element) -> Element.Element
) -> JoinedByClosureCollection<Elements, CollectionOfOne<Element.Element>> {
joined(by: { CollectionOfOne(separator($0, $1)) })
}
/// Returns the concatenation of the elements in this collection of
/// collections, inserting the separator produced by the closure between each
/// sequence.
@inlinable
public func joined<Separator>(
by separator: @escaping (Element, Element) -> Separator
) -> JoinedByClosureCollection<Elements, Separator> {
JoinedByClosureCollection(base: elements, separator: separator)
}
}
+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
}
}
+482
View File
@@ -0,0 +1,482 @@
//===----------------------------------------------------------------------===//
//
// 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 {
/// Implementation for min(count:areInIncreasingOrder:)
@inlinable
internal func _minImplementation(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element] {
var iterator = makeIterator()
var result: [Element] = []
result.reserveCapacity(count)
while result.count < count, let e = iterator.next() {
result.append(e)
}
try result.sort(by: areInIncreasingOrder)
while let e = iterator.next() {
// To be part of `result`, `e` must be strictly less than `result.last`.
guard try areInIncreasingOrder(e, result.last!) else { continue }
result.removeLast()
let insertionIndex =
try result.partitioningIndex { try areInIncreasingOrder(e, $0) }
result.insert(e, at: insertionIndex)
}
return result
}
/// Implementation for max(count:areInIncreasingOrder:)
@inlinable
internal func _maxImplementation(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element] {
var iterator = makeIterator()
var result: [Element] = []
result.reserveCapacity(count)
while result.count < count, let e = iterator.next() {
result.append(e)
}
try result.sort(by: areInIncreasingOrder)
while let e = iterator.next() {
// To be part of `result`, `e` must be greater/equal to `result.first`.
guard try !areInIncreasingOrder(e, result.first!) else { continue }
let insertionIndex =
try result.partitioningIndex { try areInIncreasingOrder(e, $0) }
assert(insertionIndex > 0)
// Inserting `e` and then removing the first element (or vice versa)
// would perform a double shift, so we manually shift down the elements
// before dropping `e` in.
var i = 1
while i < insertionIndex {
result[i - 1] = result[i]
i += 1
}
result[insertionIndex - 1] = e
}
return result
}
/// Returns the smallest elements of this sequence, as sorted by the given
/// predicate.
///
/// This example partially sorts an array of integers to retrieve its three
/// smallest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let smallestThree = numbers.min(count: 3, sortedBy: <)
/// // [1, 2, 3]
///
/// If you need to sort a sequence but only need to access its smallest
/// elements, using this method can give you a performance boost over sorting
/// the entire sequence. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameters:
/// - count: The number of elements to return. If `count` is greater than
/// the number of elements in this sequence, all of the sequence's
/// elements are returned.
/// - areInIncreasingOrder: A predicate that returns `true` if its
/// first argument should be ordered before its second argument;
/// otherwise, `false`.
/// - Returns: An array of the smallest `count` elements of this sequence,
/// sorted according to `areInIncreasingOrder`.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// sequence and *k* is `count`.
@inlinable
public func min(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element] {
precondition(count >= 0, """
Cannot find a minimum with a negative count of elements!
"""
)
// Do nothing if we're prefixing nothing.
guard count > 0 else {
return []
}
return try _minImplementation(count: count, sortedBy: areInIncreasingOrder)
}
/// Returns the largest elements of this sequence, as sorted by the given
/// predicate.
///
/// This example partially sorts an array of integers to retrieve its three
/// largest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let largestThree = numbers.max(count: 3, sortedBy: <)
/// // [7, 8, 9]
///
/// If you need to sort a sequence but only need to access its largest
/// elements, using this method can give you a performance boost over sorting
/// the entire sequence. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameters:
/// - count: The number of elements to return. If `count` is greater than
/// the number of elements in this sequence, all of the sequence's
/// elements are returned.
/// - areInIncreasingOrder: A predicate that returns `true` if its
/// first argument should be ordered before its second argument;
/// otherwise, `false`.
/// - Returns: An array of the largest `count` elements of this sequence,
/// sorted according to `areInIncreasingOrder`.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// sequence and *k* is `count`.
@inlinable
public func max(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element] {
precondition(count >= 0, """
Cannot find a maximum with a negative count of elements!
"""
)
// Do nothing if we're suffixing nothing.
guard count > 0 else {
return []
}
return try _maxImplementation(count: count, sortedBy: areInIncreasingOrder)
}
}
extension Sequence where Element: Comparable {
/// Returns the smallest elements of this sequence.
///
/// This example partially sorts an array of integers to retrieve its three
/// smallest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let smallestThree = numbers.min(count: 3)
/// // [1, 2, 3]
///
/// If you need to sort a sequence but only need to access its smallest
/// elements, using this method can give you a performance boost over sorting
/// the entire sequence. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameter count: The number of elements to return. If `count` is greater
/// than the number of elements in this sequence, all of the sequence's
/// elements are returned.
/// - Returns: An array of the smallest `count` elements of this sequence.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// sequence and *k* is `count`.
@inlinable
public func min(count: Int) -> [Element] {
min(count: count, sortedBy: <)
}
/// Returns the largest elements of this sequence.
///
/// This example partially sorts an array of integers to retrieve its three
/// largest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let largestThree = numbers.max(count: 3)
/// // [7, 8, 9]
///
/// If you need to sort a sequence but only need to access its largest
/// elements, using this method can give you a performance boost over sorting
/// the entire sequence. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameter count: The number of elements to return. If `count` is greater
/// than the number of elements in this sequence, all of the sequence's
/// elements are returned.
/// - Returns: An array of the largest `count` elements of this sequence.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// sequence and *k* is `count`.
@inlinable
public func max(count: Int) -> [Element] {
max(count: count, sortedBy: <)
}
}
extension Collection {
/// Returns the smallest elements of this collection, as sorted by the given
/// predicate.
///
/// This example partially sorts an array of integers to retrieve its three
/// smallest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let smallestThree = numbers.min(count: 3, sortedBy: <)
/// // [1, 2, 3]
///
/// If you need to sort a collection but only need to access its smallest
/// elements, using this method can give you a performance boost over sorting
/// the entire collection. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameters:
/// - count: The number of elements to return. If `count` is greater than
/// the number of elements in this collection, all of the collection's
/// elements are returned.
/// - areInIncreasingOrder: A predicate that returns `true` if its
/// first argument should be ordered before its second argument;
/// otherwise, `false`.
/// - Returns: An array of the smallest `count` elements of this collection,
/// sorted according to `areInIncreasingOrder`.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// collection and *k* is `count`.
@inlinable
public func min(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element] {
precondition(count >= 0, """
Cannot find a minimum with a negative count of elements!
"""
)
// 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.
guard prefixCount < (self.count / 10) else {
return Array(try sorted(by: areInIncreasingOrder).prefix(prefixCount))
}
return try _minImplementation(count: count, sortedBy: areInIncreasingOrder)
}
/// Returns the largest elements of this collection, as sorted by the given
/// predicate.
///
/// This example partially sorts an array of integers to retrieve its three
/// largest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let largestThree = numbers.max(count: 3, sortedBy: <)
/// // [7, 8, 9]
///
/// If you need to sort a collection but only need to access its largest
/// elements, using this method can give you a performance boost over sorting
/// the entire collection. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameters:
/// - count: The number of elements to return. If `count` is greater than
/// the number of elements in this collection, all of the collection's
/// elements are returned.
/// - areInIncreasingOrder: A predicate that returns `true` if its
/// first argument should be ordered before its second argument;
/// otherwise, `false`.
/// - Returns: An array of the largest `count` elements of this collection,
/// sorted according to `areInIncreasingOrder`.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// collection and *k* is `count`.
@inlinable
public func max(
count: Int,
sortedBy areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> [Element] {
precondition(count >= 0, """
Cannot find a maximum with a negative count of elements!
"""
)
// 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.
guard suffixCount < (self.count / 10) else {
return Array(try sorted(by: areInIncreasingOrder).suffix(suffixCount))
}
return try _maxImplementation(count: count, sortedBy: areInIncreasingOrder)
}
}
extension Collection where Element: Comparable {
/// Returns the smallest elements of this collection.
///
/// This example partially sorts an array of integers to retrieve its three
/// smallest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let smallestThree = numbers.min(count: 3)
/// // [1, 2, 3]
///
/// If you need to sort a collection but only need to access its smallest
/// elements, using this method can give you a performance boost over sorting
/// the entire collection. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameter count: The number of elements to return. If `count` is greater
/// than the number of elements in this collection, all of the collection's
/// elements are returned.
/// - Returns: An array of the smallest `count` elements of this collection.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// collection and *k* is `count`.
@inlinable
public func min(count: Int) -> [Element] {
min(count: count, sortedBy: <)
}
/// Returns the largest elements of this collection.
///
/// This example partially sorts an array of integers to retrieve its three
/// largest values:
///
/// let numbers = [7, 1, 6, 2, 8, 3, 9]
/// let smallestThree = numbers.max(count: 3)
/// // [7, 8, 9]
///
/// If you need to sort a collection but only need to access its largest
/// elements, using this method can give you a performance boost over sorting
/// the entire collection. The order of equal elements is guaranteed to be
/// preserved.
///
/// - Parameter count: The number of elements to return. If `count` is greater
/// than the number of elements in this collection, all of the collection's
/// elements are returned.
/// - Returns: An array of the largest `count` elements of this collection.
///
/// - Complexity: O(*k* log *k* + *nk*), where *n* is the length of the
/// collection and *k* is `count`.
@inlinable
public func max(count: Int) -> [Element] {
max(count: count, sortedBy: <)
}
}
//===----------------------------------------------------------------------===//
// Simultaneous minimum and maximum evaluation
//===----------------------------------------------------------------------===//
extension Sequence {
/// Returns both the minimum and maximum elements in the sequence, using the
/// given predicate as the comparison between elements.
///
/// The predicate must be a *strict weak ordering* over the elements. That is,
/// for any elements `a`, `b`, and `c`, the following conditions must hold:
///
/// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity)
/// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are
/// both `true`, then `areInIncreasingOrder(a, c)` is also
/// `true`. (Transitive comparability)
/// - Two elements are *incomparable* if neither is ordered before the other
/// according to the predicate. If `a` and `b` are incomparable, and `b`
/// and `c` are incomparable, then `a` and `c` are also incomparable.
/// (Transitive incomparability)
///
/// This example shows how to use the `minAndMax(by:)` method on a dictionary
/// to find the key-value pair with the lowest value and the pair with the
/// highest value.
///
/// let hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]
/// if let extremeHues = hues.minAndMax(by: {$0.value < $1.value}) {
/// print(extremeHues.min, extremeHues.max)
/// } else {
/// print("There are no hues")
/// }
/// // Prints: "(key: "Coral", value: 16) (key: "Heliotrope", value: 296)"
///
/// - Precondition: The sequence is finite.
///
/// - Parameter areInIncreasingOrder: A predicate that returns `true` if its
/// first argument should be ordered before its second argument; otherwise,
/// `false`.
/// - Returns: A tuple with the sequence's minimum element, followed by its
/// maximum element. If the sequence provides multiple qualifying minimum
/// elements, the first equivalent element is returned; of multiple maximum
/// elements, the last is returned. If the sequence has no elements, the
/// method returns `nil`.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
@inlinable
public func minAndMax(
by areInIncreasingOrder: (Element, Element) throws -> Bool
) rethrows -> (min: Element, max: Element)? {
// Check short sequences.
var iterator = makeIterator()
guard var lowest = iterator.next() else { return nil }
guard var highest = iterator.next() else { return (lowest, lowest) }
// Confirm the initial bounds.
if try areInIncreasingOrder(highest, lowest) { swap(&lowest, &highest) }
// Read the elements in pairwise. Structuring the comparisons around this
// is actually faster than loops based on extracting and testing elements
// one-at-a-time.
while var low = iterator.next() {
var high = iterator.next() ?? low
if try areInIncreasingOrder(high, low) { swap(&low, &high) }
if try areInIncreasingOrder(low, lowest) { lowest = low }
if try !areInIncreasingOrder(high, highest) { highest = high }
}
return (lowest, highest)
}
}
extension Sequence where Element: Comparable {
/// Returns both the minimum and maximum elements in the sequence.
///
/// This example finds the smallest and largest values in an array of height
/// measurements.
///
/// let heights = [67.5, 65.7, 64.3, 61.1, 58.5, 60.3, 64.9]
/// if let (lowestHeight, greatestHeight) = heights.minAndMax() {
/// print(lowestHeight, greatestHeight)
/// } else {
/// print("The list of heights is empty")
/// }
/// // Prints: "58.5 67.5"
///
/// - Precondition: The sequence is finite.
///
/// - Returns: A tuple with the sequence's minimum element, followed by its
/// maximum element. If the sequence provides multiple qualifying minimum
/// elements, the first equivalent element is returned; of multiple maximum
/// elements, the last is returned. If the sequence has no elements, the
/// method returns `nil`.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
@inlinable
public func minAndMax() -> (min: Element, max: Element)? {
minAndMax(by: <)
}
}
+150 -15
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 Apple Inc. and the Swift project authors
// Copyright (c) 2020-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
@@ -14,18 +14,18 @@
//===----------------------------------------------------------------------===//
extension MutableCollection {
/// Moves all elements satisfying `belongsInSecondPartition` into a suffix
/// of the collection, preserving their relative order, and returns the
/// start of the resulting suffix.
/// Moves all elements satisfying `belongsInSecondPartition` into a suffix of
/// the collection, preserving their relative order, and returns the start of
/// the resulting suffix.
///
/// - Complexity: O(*n* log *n*), where *n* is the number of elements.
/// - Precondition:
/// `n == distance(from: range.lowerBound, to: range.upperBound)`
@usableFromInline
@inlinable
internal mutating func stablePartition(
count n: Int,
subrange: Range<Index>,
by belongsInSecondPartition: (Element) throws-> Bool
by belongsInSecondPartition: (Element) throws -> Bool
) rethrows -> Index {
if n == 0 { return subrange.lowerBound }
if n == 1 {
@@ -138,22 +138,22 @@ extension MutableCollection where Self: BidirectionalCollection {
// * predicate(self[i]) == true, for i in hi ..< endIndex
Loop: while true {
FindLo: repeat {
FindLo: do {
while lo < hi {
if try belongsInSecondPartition(self[lo]) { break FindLo }
formIndex(after: &lo)
}
break Loop
} while false
}
FindHi: repeat {
FindHi: do {
formIndex(before: &hi)
while lo < hi {
if try !belongsInSecondPartition(self[hi]) { break FindHi }
formIndex(before: &hi)
}
break Loop
} while false
}
swapAt(lo, hi)
formIndex(after: &lo)
@@ -168,18 +168,19 @@ extension MutableCollection where Self: BidirectionalCollection {
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns the index of the first element in the collection that matches
/// the predicate.
/// Returns the start index of the partition of a collection that matches
/// the given predicate.
///
/// The collection must already be partitioned according to the predicate.
/// That is, there should be an index `i` where for every element in
/// `collection[..<i]` the predicate is `false`, and for every element
/// in `collection[i...]` the predicate is `true`.
/// `collection[..<i]` the predicate is `false`, and for every element in
/// `collection[i...]` the predicate is `true`.
///
/// - Parameter belongsInSecondPartition: A predicate that partitions the
/// collection.
/// - Returns: The index of the first element in the collection for which
/// `predicate` returns `true`.
/// `predicate` returns `true`, or `endIndex` if there are no elements
/// for which `predicate` returns `true`.
///
/// - Complexity: O(log *n*), where *n* is the length of this collection if
/// the collection conforms to `RandomAccessCollection`, otherwise O(*n*).
@@ -204,3 +205,137 @@ extension Collection {
}
}
//===----------------------------------------------------------------------===//
// partitioned(by:)
//===----------------------------------------------------------------------===//
extension Sequence {
/// Returns two arrays containing, in order, the elements of the sequence that
/// do and don’t satisfy the given predicate.
///
/// In this example, `partitioned(by:)` is used to separate the input based on
/// whether a name is shorter than five characters:
///
/// let cast = ["Vivien", "Marlon", "Kim", "Karl"]
/// let (longNames, shortNames) = cast.partitioned(by: { $0.count < 5 })
/// print(longNames)
/// // Prints "["Vivien", "Marlon"]"
/// print(shortNames)
/// // Prints "["Kim", "Karl"]"
///
/// - Parameter predicate: A closure that takes an element of the sequence as
/// its argument and returns a Boolean value indicating whether the element
/// should be included in the second returned array. Otherwise, the element
/// will appear in the first returned array.
///
/// - 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.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
@inlinable
public func partitioned(
by predicate: (Element) throws -> Bool
) rethrows -> (falseElements: [Element], trueElements: [Element]) {
var lhs = [Element]()
var rhs = [Element]()
for element in self {
if try predicate(element) {
rhs.append(element)
} else {
lhs.append(element)
}
}
return (lhs, rhs)
}
}
extension Collection {
/// Returns two arrays containing, in order, the elements of the collection
/// that do and don’t satisfy the given predicate.
///
/// In this example, `partitioned(by:)` is used to separate the input based on
/// whether a name is shorter than five characters.
///
/// let cast = ["Vivien", "Marlon", "Kim", "Karl"]
/// let (longNames, shortNames) = cast.partitioned(by: { $0.count < 5 })
/// print(longNames)
/// // Prints "["Vivien", "Marlon"]"
/// print(shortNames)
/// // Prints "["Kim", "Karl"]"
///
/// - Parameter predicate: A closure that takes an element of the collection
/// as its argument and returns a Boolean value indicating whether the element
/// should be included in the second returned array. Otherwise, the element
/// will appear in the first returned array.
///
/// - 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.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
public func partitioned(
by predicate: (Element) throws -> Bool
) rethrows -> (falseElements: [Element], trueElements: [Element]) {
guard !self.isEmpty else {
return ([], [])
}
// Since collections have known sizes, we can allocate one array of size
// `self.count`, then insert items at the beginning or end of that contiguous
// block. This way, we don’t have to do any dynamic array resizing. Since we
// insert the right elements on the right side in reverse order, we need to
// reverse them back to the original order at the end.
let count = self.count
// Inside of the `initializer` closure, we set what the actual mid-point is.
// We will use this to partition the single array into two.
var midPoint: Int = 0
let elements = try [Element](
unsafeUninitializedCapacity: count,
initializingWith: { buffer, initializedCount in
var lhs = buffer.baseAddress!
var rhs = lhs + buffer.count
do {
for element in self {
if try predicate(element) {
rhs -= 1
rhs.initialize(to: element)
} else {
lhs.initialize(to: element)
lhs += 1
}
}
precondition(lhs == rhs, """
Collection's `count` differed from the number of elements iterated.
"""
)
let rhsIndex = rhs - buffer.baseAddress!
buffer[rhsIndex...].reverse()
initializedCount = buffer.count
midPoint = rhsIndex
} catch {
let lhsCount = lhs - buffer.baseAddress!
let rhsCount = (buffer.baseAddress! + buffer.count) - rhs
buffer.baseAddress!.deinitialize(count: lhsCount)
rhs.deinitialize(count: rhsCount)
throw error
}
})
let lhs = elements[..<midPoint]
let rhs = elements[midPoint...]
return (
Array(lhs),
Array(rhs)
)
}
}
+455 -112
View File
@@ -9,63 +9,166 @@
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// nextPermutation()
//===----------------------------------------------------------------------===//
extension MutableCollection
where Self: BidirectionalCollection, Element: Comparable
{
/// Permutes this collection's elements through all the lexical orderings.
///
/// Call `nextPermutation()` repeatedly starting with the collection in sorted
/// order. When the full cycle of all permutations has been completed, the
/// collection will be back in sorted order and this method will return
/// `false`.
///
/// - Returns: A Boolean value indicating whether the collection still has
/// remaining permutations. When this method returns `false`, the collection
/// is in ascending order according to `areInIncreasingOrder`.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
internal mutating func nextPermutation(upperBound: Index? = nil) -> Bool {
// Ensure we have > 1 element in the collection.
guard !isEmpty else { return false }
var i = index(before: endIndex)
if i == startIndex { return false }
let upperBound = upperBound ?? endIndex
while true {
let ip1 = i
formIndex(before: &i)
// Find the last ascending pair (ie. ..., a, b, ... where a < b)
if self[i] < self[ip1] {
// Find the last element greater than self[i]
// This is _always_ at most `ip1` due to if statement above
let j = lastIndex(where: { self[i] < $0 })!
// At this point we have something like this:
// 0, 1, 4, 3, 2
// ^ ^
// i j
swapAt(i, j)
self.reverse(subrange: ip1 ..< endIndex)
// Only return if we've made a change within ..<upperBound region
if i < upperBound {
return true
} else {
i = index(before: endIndex)
continue
}
}
if i == startIndex {
self.reverse()
return false
}
}
}
}
//===----------------------------------------------------------------------===//
// struct Permutations<Base>
//===----------------------------------------------------------------------===//
/// A sequence of all the permutations of a collection's elements.
public struct Permutations<Base: Collection> {
/// The base collection.
public let base: Base
public struct PermutationsSequence<Base: Collection> {
/// The base collection to iterate over for permutations.
@usableFromInline
internal let base: Base
@usableFromInline
internal let baseCount: Int
internal let countToChoose: Int
/// The range of accepted sizes of permutations.
///
/// - Note: This may be empty if the attempted range entirely exceeds the
/// bounds of the size of the `base` collection.
@usableFromInline
internal let kRange: Range<Int>
/// Initializes a `PermutationsSequence` for all permutations of `base` of
/// size `k`.
///
/// - Parameters:
/// - base: The collection to iterate over for permutations
/// - k: The expected size of each permutation, or `nil` (default) to
/// iterate over all permutations of the same size as the base collection.
@inlinable
internal init(_ base: Base, k: Int? = nil) {
let kRange: ClosedRange<Int>?
if let countToChoose = k {
kRange = countToChoose ... countToChoose
} else {
kRange = nil
}
self.init(base, kRange: kRange)
}
/// Initializes a `PermutationsSequence` for all combinations of `base` of
/// sizes within a given range.
///
/// - Parameters:
/// - base: The collection to iterate over for permutations.
/// - kRange: The range of accepted sizes of permutations, or `nil` to
/// iterate over all permutations of the same size as the base collection.
@inlinable
internal init<R: RangeExpression>(
_ base: Base, kRange: R?
) where R.Bound == Int {
self.base = base
let baseCount = base.count
self.baseCount = baseCount
self.countToChoose = k ?? baseCount
let upperBound = baseCount + 1
self.kRange = kRange?.relative(to: 0 ..< .max)
.clamped(to: 0 ..< upperBound) ??
baseCount ..< upperBound
}
/// The total number of permutations.
@inlinable
public var count: Int {
return baseCount >= countToChoose
? stride(from: baseCount, to: baseCount - countToChoose, by: -1).reduce(1, *)
: 0
kRange.map {
stride(from: baseCount, to: baseCount - $0, by: -1).reduce(1, *)
}.reduce(0, +)
}
}
extension Permutations: Sequence {
extension PermutationsSequence: Sequence {
/// The iterator for a `PermutationsSequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var base: Base
internal let base: Base
@usableFromInline
internal let baseCount: Int
/// The current range of accepted sizes of permutations.
/// - Note: The range is contracted until empty while iterating over
/// permutations of different sizes. When the range is empty, iteration is
/// finished.
@usableFromInline
internal var kRange: Range<Int>
/// Whether or not iteration is finished (`kRange` is empty)
@inlinable
internal var isFinished: Bool {
return kRange.isEmpty
}
@usableFromInline
internal var indexes: [Base.Index]
@usableFromInline
internal var hasMorePermutations: Bool
@usableFromInline
internal var countToChoose: Int = 0
/// `true` if we're generating permutations of the full collection.
@usableFromInline
internal var permutesFullCollection: Bool {
countToChoose == indexes.count
}
@usableFromInline
internal init(_ base: Base) {
self.base = base
self.indexes = Array(base.indices)
self.countToChoose = self.indexes.count
self.hasMorePermutations = true
}
@usableFromInline
internal init(_ base: Base, count: Int) {
self.base = base
self.countToChoose = count
// Produce exactly one empty permutation when `count == 0`.
self.indexes = count == 0 ? [] : Array(base.indices)
// Can't produce any permutations when `count > base.count`.
self.hasMorePermutations = count <= indexes.count
@inlinable
internal init(_ permutations: PermutationsSequence) {
self.base = permutations.base
self.baseCount = permutations.baseCount
self.kRange = permutations.kRange
self.indexes = Array(permutations.base.indices)
}
/// Advances the `indexes` array such that the first `countToChoose`
@@ -79,31 +182,32 @@ extension Permutations: Sequence {
/// is in ascending order.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@usableFromInline
@inlinable
internal mutating func nextState() -> Bool {
let countToChoose = self.kRange.lowerBound
let edge = countToChoose - 1
// Find first index greater than the one at `edge`.
if let i = indexes[countToChoose...].firstIndex(where: { indexes[edge] < $0 }) {
indexes.swapAt(edge, i)
} else {
indexes.reverse(subrange: countToChoose..<indexes.endIndex)
indexes.reverse(subrange: countToChoose ..< indexes.endIndex)
// Find last increasing pair below `edge`.
// TODO: This could be indexes[..<edge].adjacentPairs().lastIndex(where: ...)
var lastAscent = edge - 1
while (lastAscent >= 0 && indexes[lastAscent] >= indexes[lastAscent + 1]) {
lastAscent -= 1
}
if (lastAscent < 0) {
if lastAscent < 0 {
return false
}
// Find rightmost index less than that at `lastAscent`.
if let i = indexes[lastAscent...].lastIndex(where: { indexes[lastAscent] < $0 }) {
indexes.swapAt(lastAscent, i)
}
indexes.reverse(subrange: (lastAscent + 1)..<indexes.endIndex)
indexes.reverse(subrange: (lastAscent + 1) ..< indexes.endIndex)
}
return true
@@ -111,89 +215,125 @@ extension Permutations: Sequence {
@inlinable
public mutating func next() -> [Base.Element]? {
if !hasMorePermutations { return nil }
guard !isFinished else { return nil }
/// Advances `kRange` by incrementing its `lowerBound` until the range is
/// empty, when iteration is finished.
func advanceKRange() {
kRange.removeFirst()
indexes = Array(base.indices)
}
let countToChoose = self.kRange.lowerBound
if countToChoose == 0 {
defer {
advanceKRange()
}
return []
}
let permutesFullCollection = (countToChoose == baseCount)
if permutesFullCollection {
// If we're permuting the full collection, each iteration is just a
// call to `nextPermutation` on `indexes`.
defer { hasMorePermutations = indexes.nextPermutation() }
defer {
let hasMorePermutations = indexes.nextPermutation()
if !hasMorePermutations {
advanceKRange()
}
}
return indexes.map { base[$0] }
} else {
// Otherwise, return the items at the first `countToChoose` indices and
// advance the state.
defer { hasMorePermutations = nextState() }
defer {
let hasMorePermutations = nextState()
if !hasMorePermutations {
advanceKRange()
}
}
return indexes.prefix(countToChoose).map { base[$0] }
}
}
}
@usableFromInline
internal var permutesFullCollection: Bool {
baseCount == countToChoose
}
@inlinable
public func makeIterator() -> Iterator {
permutesFullCollection
? Iterator(base)
: Iterator(base, count: countToChoose)
Iterator(self)
}
}
extension Permutations: LazySequenceProtocol where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// nextPermutation(by:)
//===----------------------------------------------------------------------===//
extension MutableCollection
where Self: BidirectionalCollection, Element: Comparable
{
/// Permutes this collection's elements through all the lexical orderings.
///
/// Call `nextPermutation()` repeatedly starting with the collection in
/// sorted order. When the full cycle of all permutations has been completed,
/// the collection will be back in sorted order and this method will return
/// `false`.
///
/// - Returns: A Boolean value indicating whether the collection still has
/// remaining permutations. When this method returns `false`, the collection
/// is in ascending order according to `areInIncreasingOrder`.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@usableFromInline
internal mutating func nextPermutation() -> Bool {
// ensure we have > 1 element in the collection
if isEmpty { return false }
var i = index(before: endIndex)
if i == startIndex { return false }
while true {
let ip1 = i
formIndex(before: &i)
if self[i] < self[ip1] {
var j = index(before: endIndex)
while self[i] >= self[j] {
formIndex(before: &j)
}
swapAt(i, j)
self.reverse(subrange: ip1..<endIndex)
return true
}
if i == startIndex {
self.reverse()
return false
}
}
}
}
extension PermutationsSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// permutations(ofCount:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns a collection of the permutations of this collection with lengths
/// in the specified range.
///
/// This example prints the different permutations of one to two elements from
/// an array of three names:
///
/// let names = ["Alex", "Celeste", "Davide"]
/// for perm in names.permutations(ofCount: 1...2) {
/// print(perm.joined(separator: ", "))
/// }
/// // Alex
/// // Celeste
/// // Davide
/// // Alex, Celeste
/// // Alex, Davide
/// // Celeste, Alex
/// // Celeste, Davide
/// // Davide, Alex
/// // Davide, Celeste
///
/// This example prints _all_ the permutations (including an empty array) from
/// an array of numbers:
///
/// let numbers = [10, 20, 30]
/// for perm in numbers.permutations(ofCount: 0...) {
/// print(perm)
/// }
/// // []
/// // [10]
/// // [20]
/// // [30]
/// // [10, 20]
/// // [10, 30]
/// // [20, 10]
/// // [20, 30]
/// // [30, 10]
/// // [30, 20]
/// // [10, 20, 30]
/// // [10, 30, 20]
/// // [20, 10, 30]
/// // [20, 30, 10]
/// // [30, 10, 20]
/// // [30, 20, 10]
///
/// The returned permutations are in ascending order by length, and then
/// lexicographically within each group of the same length.
///
/// - Parameter kRange: A range of the number of elements to include in each
/// permutation. `kRange` can be any integer range expression, and is
/// clamped to the number of elements in this collection. Passing a range
/// covering sizes greater than the number of elements in this collection
/// results in an empty sequence.
///
/// - Complexity: O(1) for random-access base collections. O(*n*) where *n*
/// is the number of elements in the base collection, since
/// `PermutationsSequence` accesses the `count` of the base collection.
@inlinable
public func permutations<R: RangeExpression>(
ofCount kRange: R
) -> PermutationsSequence<Self> where R.Bound == Int {
PermutationsSequence(self, kRange: kRange)
}
/// Returns a collection of the permutations of this collection of the
/// specified length.
///
@@ -236,14 +376,217 @@ extension Collection {
/// sequence, the resulting sequence has no elements.
///
/// - Parameter k: The number of elements to include in each permutation.
/// If `count` is `nil`, the resulting sequence represents permutations
/// of this entire collection.
/// If `k` is `nil`, the resulting sequence represents permutations of this
/// entire collection. If `k` is greater than the number of elements in
/// this collection, the resulting sequence is empty.
///
/// - Complexity: O(1)
public func permutations(ofCount k: Int? = nil) -> Permutations<Self> {
assert(
/// - Complexity: O(1) for random-access base collections. O(*n*) where *n*
/// is the number of elements in the base collection, since
/// `PermutationsSequence` accesses the `count` of the base collection.
@inlinable
public func permutations(ofCount k: Int? = nil) -> PermutationsSequence<Self> {
precondition(
k ?? 0 >= 0,
"Can't have permutations with a negative number of elements.")
return Permutations(self, k: k)
return PermutationsSequence(self, k: k)
}
}
//===----------------------------------------------------------------------===//
// uniquePermutations()
//===----------------------------------------------------------------------===//
/// A sequence of the unique permutations of the elements of a sequence or
/// collection.
///
/// To create a `UniquePermutationsSequence` instance, call one of the
/// `uniquePermutations` methods on your collection.
public struct UniquePermutationsSequence<Base: Collection> {
/// The base collection to iterate over for permutations.
@usableFromInline
internal let base: Base
@usableFromInline
internal var indexes: [Base.Index]
@usableFromInline
internal let kRange: Range<Int>
}
extension UniquePermutationsSequence where Base.Element: Hashable {
@inlinable
internal static func _indexes(_ base: Base) -> [Base.Index] {
let firstIndexesAndCountsByElement = Dictionary(
base.indices.lazy.map { (base[$0], ($0, 1)) },
uniquingKeysWith: { indexAndCount, _ in (indexAndCount.0, indexAndCount.1 + 1) })
return firstIndexesAndCountsByElement
.values.sorted(by: { $0.0 < $1.0 })
.flatMap { index, count in repeatElement(index, count: count) }
}
@inlinable
internal init(_ elements: Base) {
self.indexes = Self._indexes(elements)
self.base = elements
self.kRange = self.indexes.count ..< (self.indexes.count + 1)
}
@inlinable
internal init<R: RangeExpression>(_ base: Base, _ range: R)
where R.Bound == Int
{
self.indexes = Self._indexes(base)
self.base = base
let upperBound = self.indexes.count + 1
self.kRange = range.relative(to: 0 ..< .max)
.clamped(to: 0 ..< upperBound)
}
}
extension UniquePermutationsSequence: Sequence {
/// The iterator for a `UniquePermutationsSequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal let base: Base
@usableFromInline
internal var indexes: [Base.Index]
@usableFromInline
internal var lengths: Range<Int>
@usableFromInline
internal var initial = true
@inlinable
internal init(_ elements: Base, indexes: [Base.Index], lengths: Range<Int>) {
self.base = elements
self.indexes = indexes
self.lengths = lengths
}
@inlinable
public mutating func next() -> [Base.Element]? {
// In the end case, `lengths` is an empty range.
if lengths.isEmpty {
return nil
}
// The first iteration must produce the original sorted array, before any
// permutations. We skip the permutation the first time so that we can
// always mutate the array _before_ returning a slice, which avoids
// copying when possible.
if initial {
initial = false
return indexes[..<lengths.lowerBound].map { base[$0] }
}
if !indexes.nextPermutation(upperBound: lengths.lowerBound) {
lengths.removeFirst()
if lengths.isEmpty {
return nil
}
}
return indexes[..<lengths.lowerBound].map { base[$0] }
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(base, indexes: indexes, lengths: kRange)
}
}
extension UniquePermutationsSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
extension Collection where Element: Hashable {
/// Returns a sequence of the unique permutations of this sequence of the
/// specified length.
///
/// Use this method to iterate over the unique permutations of a sequence
/// with repeating elements. This example prints every unique two-element
/// permutation of an array of numbers:
///
/// let numbers = [1, 1, 2]
/// for perm in numbers.uniquePermutations(ofCount: 2) {
/// print(perm)
/// }
/// // [1, 1]
/// // [1, 2]
/// // [2, 1]
///
/// By contrast, the `permutations(ofCount:)` method permutes a collection's
/// elements by position, and can include permutations with equal elements
/// in each permutation:
///
/// for perm in numbers.permutations(ofCount: 2)
/// print(perm)
/// }
/// // [1, 1]
/// // [1, 1]
/// // [1, 2]
/// // [1, 2]
/// // [2, 1]
/// // [2, 1]
///
/// The returned permutations are in lexicographically sorted order.
///
/// - Parameter k: The number of elements to include in each permutation.
/// If `k` is `nil`, the resulting sequence represents permutations of this
/// entire collection. If `k` is greater than the number of elements in
/// this collection, the resulting sequence is empty.
///
/// - Complexity: O(*n*), where *n* is the number of elements in this
/// collection.
@inlinable
public func uniquePermutations(ofCount k: Int? = nil)
-> UniquePermutationsSequence<Self>
{
if let k = k {
return UniquePermutationsSequence(self, k ..< (k + 1))
} else {
return UniquePermutationsSequence(self)
}
}
/// Returns a collection of the unique permutations of this sequence with
/// lengths in the specified range.
///
/// Use this method to iterate over the unique permutations of a sequence
/// with repeating elements. This example prints every unique permutation
/// of an array of numbers with lengths through 2 elements:
///
/// let numbers = [1, 1, 2]
/// for perm in numbers.uniquePermutations(ofCount: ...2) {
/// print(perm)
/// }
/// // []
/// // [1]
/// // [2]
/// // [1, 1]
/// // [1, 2]
/// // [2, 1]
///
/// The returned permutations are in ascending order by length, and then
/// lexicographically within each group of the same length.
///
/// - Parameter kRange: A range of the number of elements to include in each
/// permutation. `kRange` can be any integer range expression, and is
/// clamped to the number of elements in this collection. Passing a range
/// covering sizes greater than the number of elements in this collection
/// results in an empty sequence.
///
/// - Complexity: O(*n*), where *n* is the number of elements in this
/// collection.
@inlinable
public func uniquePermutations<R: RangeExpression>(
ofCount kRange: R
) -> UniquePermutationsSequence<Self> where R.Bound == Int {
UniquePermutationsSequence(self, kRange)
}
}
+309 -38
View File
@@ -9,21 +9,27 @@
//
//===----------------------------------------------------------------------===//
/// A sequence that represents the product of two sequence's elements.
public struct Product2<Base1: Sequence, Base2: Collection> {
/// A sequence that represents the product of two sequences' elements.
public struct Product2Sequence<Base1: Sequence, Base2: Collection> {
/// The outer sequence in the product.
public let base1: Base1
/// The inner sequence in the product.
public let base2: Base2
@usableFromInline
internal let base1: Base1
/// The inner sequence in the product.
@usableFromInline
internal let base2: Base2
@inlinable
internal init(_ base1: Base1, _ base2: Base2) {
self.base1 = base1
self.base2 = base2
}
}
extension Product2: Sequence {
/// The iterator for a `Product2` sequence.
extension Product2Sequence: Sequence {
public typealias Element = (Base1.Element, Base2.Element)
/// The iterator for a `Product2Sequence` sequence.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var i1: Base1.Iterator
@@ -34,8 +40,8 @@ extension Product2: Sequence {
@usableFromInline
internal let base2: Base2
@usableFromInline
internal init(_ c: Product2) {
@inlinable
internal init(_ c: Product2Sequence) {
self.base2 = c.base2
self.i1 = c.base1.makeIterator()
self.i2 = c.base2.makeIterator()
@@ -43,7 +49,8 @@ extension Product2: Sequence {
}
@inlinable
public mutating func next() -> (Base1.Element, Base2.Element)? {
public mutating func next() -> (Base1.Element,
Base2.Element)? {
// This is the initial state, where i1.next() has never
// been called, or the final state, where i1.next() has
// already returned nil.
@@ -76,20 +83,21 @@ extension Product2: Sequence {
}
}
@inlinable
public func makeIterator() -> Iterator {
return Iterator(self)
Iterator(self)
}
}
extension Product2: Collection where Base1: Collection {
/// The index type for a `Product2` collection.
extension Product2Sequence: Collection where Base1: Collection {
/// The index type for a `Product2Sequence` collection.
public struct Index: Comparable {
@usableFromInline
internal var i1: Base1.Index
@usableFromInline
internal var i2: Base2.Index
@usableFromInline
@inlinable
internal init(i1: Base1.Index, i2: Base2.Index) {
self.i1 = i1
self.i2 = i2
@@ -120,36 +128,299 @@ extension Product2: Collection where Base1: Collection {
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i.i1 != base1.endIndex, "Can't advance past endIndex")
let newIndex2 = base2.index(after: i.i2)
return newIndex2 == base2.endIndex
? Index(i1: base1.index(after: i.i1), i2: base2.startIndex)
: Index(i1: i.i1, i2: newIndex2)
public subscript(position: Index) -> (Base1.Element,
Base2.Element) {
(base1[position.i1], base2[position.i2])
}
// TODO: Implement index(_:offsetBy:) and index(_:offsetBy:limitedBy:)
/// Forms an index from a pair of base indices, normalizing
/// `(i, base2.endIndex)` to `(base1.index(after: i), base2.startIndex)` if
/// necessary.
@inlinable
internal func normalizeIndex(_ i1: Base1.Index, _ i2: Base2.Index) -> Index {
i2 == base2.endIndex
? Index(i1: base1.index(after: i1), i2: base2.startIndex)
: Index(i1: i1, i2: i2)
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i.i1 != base1.endIndex, "Can't advance past endIndex")
return normalizeIndex(i.i1, base2.index(after: i.i2))
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
if start > end {
return -distance(from: end, to: start)
}
if start.i1 == end.i1 {
return base2[start.i2..<end.i2].count
}
guard start.i1 <= end.i1
else { return -distance(from: end, to: start) }
guard start.i1 != end.i1
else { return base2.distance(from: start.i2, to: end.i2) }
return base2[start.i2...].count + base2[..<end.i2].count
+ base2.count * (base1.distance(from: start.i1, to: end.i1) - 1)
// The number of full cycles through `base2` between `start` and `end`,
// excluding the cycles that `start` and `end` are on.
let fullBase2Cycles = base1[start.i1..<end.i1].count - 1
if start.i2 <= end.i2 {
// start.i2
// v
// start.i1 > [l l l|c c c c c c r r r]
// [l l l c c c c c c r r r] >
// ... > `fullBase2Cycles` times
// [l l l c c c c c c r r r] >
// end.i1 > [l l l c c c c c c|r r r]
// ^
// end.i2
let left = base2[..<start.i2].count
let center = base2[start.i2..<end.i2].count
let right = base2[end.i2...].count
return center + right
+ fullBase2Cycles * (left + center + right)
+ left + center
} else {
// start.i2
// v
// start.i1 > [l l l c c c c c c|r r r]
// [l l l c c c c c c r r r] >
// ... > `fullBase2Cycles` times
// [l l l c c c c c c r r r] >
// end.i1 > [l l l|c c c c c c r r r]
// ^
// end.i2
let left = base2[..<end.i2].count
let right = base2[start.i2...].count
// We can avoid traversing `base2[end.i2..<start.i2]` if `start` and `end`
// are on consecutive cycles.
guard fullBase2Cycles > 0 else { return right + left }
let center = base2[end.i2..<start.i2].count
return right
+ fullBase2Cycles * (left + center + right)
+ left
}
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return i }
return distance > 0
? offsetForward(i, by: distance)
: offsetBackward(i, by: -distance)
}
@inlinable
public func index(
_ i: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
if distance >= 0 {
return limit >= i
? offsetForward(i, by: distance, limitedBy: limit)
: offsetForward(i, by: distance)
} else {
return limit <= i
? offsetBackward(i, by: -distance, limitedBy: limit)
: offsetBackward(i, by: -distance)
}
}
@inlinable
public subscript(position: Index) -> (Base1.Element, Base2.Element) {
return (base1[position.i1], base2[position.i2])
internal func offsetForward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetForward(i, by: distance, limitedBy: endIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetBackward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetBackward(i, by: distance, limitedBy: startIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetForward(
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance >= 0)
assert(limit >= i)
if limit.i1 == i.i1 {
// Delegate to `base2` if the offset is limited to `i.i1`.
//
// i.i2 limit.i2
// v v
// i.i1 > [x x x|x x x x x x|x x x]
return base2.index(i.i2, offsetBy: distance, limitedBy: limit.i2)
.map { i2 in Index(i1: i.i1, i2: i2) }
}
if let i2 = base2.index(i.i2, offsetBy: distance, limitedBy: base2.endIndex) {
// `distance` does not overflow `base2[i.i2...]`.
//
// i.i2 i2
// v v
// i.i1 > [x x x|x x x x x x|x x x]
// [ |> > > > > >| ] (`distance`)
return normalizeIndex(i.i1, i2)
}
let suffixCount = base2[i.i2...].count
let remaining = distance - suffixCount
let nextI1 = base1.index(after: i.i1)
if limit.i1 == nextI1 {
// Delegate to `base2` if the offset is limited to `nextI1`.
//
// i.i2
// v
// i.i1 > [x x x|x x x x x x x x x]
// nextI1 > [x x x x x x x x x|x x x]
// ^
// limit.i2
return base2.index(base2.startIndex, offsetBy: remaining, limitedBy: limit.i2)
.map { i2 in Index(i1: nextI1, i2: i2) }
}
if let i2 = base2.index(base2.startIndex, offsetBy: remaining, limitedBy: i.i2) {
// `remaining` does not overflow `base2[..<i.i2]`.
//
// i.i2
// v
// i.i1 > [x x x x x x x x x|x x x]
// [ |> > >] (`suffixCount`)
// [> > >| ] (`remaining`)
// nextI1 > [x x x|x x x x x x x x x]
// ^
// i2
return Index(i1: nextI1, i2: i2)
}
let prefixCount = base2[..<i.i2].count
let base2Count = prefixCount + suffixCount
let base1Distance = remaining / base2Count
guard let i1 = base1.index(nextI1, offsetBy: base1Distance, limitedBy: limit.i1)
else { return nil }
// The distance from `base2.startIndex` to the target.
let base2Distance = remaining % base2Count
let base2Limit = limit.i1 == i1 ? limit.i2 : base2.endIndex
return base2.index(base2.startIndex, offsetBy: base2Distance, limitedBy: base2Limit)
.map { i2 in Index(i1: i1, i2: i2) }
}
@inlinable
internal func offsetBackward(
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance >= 0)
assert(limit <= i)
if limit.i1 == i.i1 {
// Delegate to `base2` if the offset is limited to `i.i1`.
//
// limit.i2 i.i2
// v v
// i.i1 > [x x x|x x x x x x|x x x]
return base2.index(i.i2, offsetBy: -distance, limitedBy: limit.i2)
.map { i2 in Index(i1: i.i1, i2: i2) }
}
if let i2 = base2.index(i.i2, offsetBy: -distance, limitedBy: base2.startIndex) {
// `distance` does not underflow `base2[..<i.i2]`.
//
// i2 i.i2
// v v
// i.i1 > [x x x|x x x x x x|x x x]
// [ |< < < < < <| ] (`distance`)
return Index(i1: i.i1, i2: i2)
}
let prefixCount = base2[..<i.i2].count
let remaining = distance - prefixCount
let previousI1 = base1.index(i.i1, offsetBy: -1)
if limit.i1 == previousI1 {
// Delegate to `base2` if the offset is limited to `previousI1`.
//
// limit.i2
// v
// previousI1 > [x x x|x x x x x x x x x]
// i.i1 > [x x x x x x x x x|x x x]
// ^
// i.i2
return base2.index(base2.endIndex, offsetBy: -remaining, limitedBy: limit.i2)
.map { i2 in Index(i1: previousI1, i2: i2) }
}
if let i2 = base2.index(base2.endIndex, offsetBy: -remaining, limitedBy: i.i2) {
// `remaining` does not underflow `base2[i.i2...]`.
//
// i2
// v
// previousI1 > [x x x x x x x x x|x x x]
// [ |< < <] (`remaining`)
// [< < <| ] (`prefixCount`)
// i.i1 > [x x x|x x x x x x x x x]
// ^
// i.i2
return Index(i1: previousI1, i2: i2)
}
let suffixCount = base2[i.i2...].count
let base2Count = prefixCount + suffixCount
let base1Distance = remaining / base2Count
// The distance from `base2.endIndex` to the target.
let base2Distance = remaining % base2Count
if base2Distance == 0 {
// We end up exactly between two cycles, so `base1Distance` would
// overshoot the target by 1.
//
// base2.startIndex
// v
// i1 > |x x x x x x x x x x x x] >
// ... > `base1Distance` times
// previousI1 > [x x x x x x x x x x x x] >
// i.i1 > [x x x|x x x x x x x x x]
// ^
// i.i2
if let i1 = base1.index(previousI1, offsetBy: -(base1Distance - 1), limitedBy: limit.i1) {
let index = Index(i1: i1, i2: base2.startIndex)
return index < limit ? nil : index
} else {
return nil
}
}
guard let i1 = base1.index(previousI1, offsetBy: -base1Distance, limitedBy: limit.i1)
else { return nil }
let base2Limit = limit.i1 == i1 ? limit.i2 : base2.startIndex
return base2.index(base2.endIndex, offsetBy: -base2Distance, limitedBy: base2Limit)
.map { i2 in Index(i1: i1, i2: i2) }
}
}
extension Product2: BidirectionalCollection
extension Product2Sequence: BidirectionalCollection
where Base1: BidirectionalCollection, Base2: BidirectionalCollection
{
@inlinable
@@ -166,12 +437,11 @@ extension Product2: BidirectionalCollection
}
}
extension Product2: RandomAccessCollection
extension Product2Sequence: RandomAccessCollection
where Base1: RandomAccessCollection, Base2: RandomAccessCollection {}
extension Product2.Index: Hashable where Base1.Index: Hashable, Base2.Index: Hashable {}
extension Product2: Equatable where Base1: Equatable, Base2: Equatable {}
extension Product2: Hashable where Base1: Hashable, Base2: Hashable {}
extension Product2Sequence.Index: Hashable
where Base1.Index: Hashable, Base2.Index: Hashable {}
//===----------------------------------------------------------------------===//
// product(_:_:)
@@ -210,8 +480,9 @@ extension Product2: Hashable where Base1: Hashable, Base2: Hashable {}
/// - s2: The second sequence to iterate over.
///
/// - Complexity: O(1)
@inlinable
public func product<Base1: Sequence, Base2: Collection>(
_ s1: Base1, _ s2: Base2
) -> Product2<Base1, Base2> {
return Product2(s1, s2)
) -> Product2Sequence<Base1, Base2> {
Product2Sequence(s1, s2)
}
+11 -13
View File
@@ -62,8 +62,7 @@ extension Collection {
/// This method is equivalent to calling `randomStableSample(k:using:)`,
/// passing in the system's default random generator.
///
/// - Parameters:
/// - k: The number of elements to randomly select.
/// - Parameter k: The number of elements to randomly select.
/// - Returns: An array of `k` random elements. If `k` is greater than this
/// collection's count, then this method returns the full collection.
///
@@ -94,7 +93,8 @@ internal func nextW<G: RandomNumberGenerator>(
internal func nextOffset<G: RandomNumberGenerator>(
w: Double, using rng: inout G
) -> Int {
Int(Double.log(.random(in: 0..<1, using: &rng)) / .log(1 - w))
let offset = Double.log(.random(in: 0..<1, using: &rng)) / .log(onePlus: -w)
return offset < Double(Int.max) ? Int(offset) : Int.max
}
extension Collection {
@@ -122,12 +122,12 @@ extension Collection {
// Fill the reservoir with the first `k` elements.
var i = startIndex
while i < endIndex, result.count < k {
while i != endIndex, result.count < k {
result.append(self[i])
formIndex(after: &i)
}
while i < endIndex {
while i != endIndex {
// Calculate the next value of w.
w *= nextW(k: k, using: &rng)
@@ -135,7 +135,7 @@ extension Collection {
let offset = nextOffset(w: w, using: &rng)
i = index(i, offsetBy: offset, limitedBy: endIndex) ?? endIndex
if i < endIndex {
if i != endIndex {
// Swap selected element with a randomly chosen one in the reservoir.
let j = Int.random(in: 0..<result.count, using: &rng)
result[j] = self[i]
@@ -153,8 +153,7 @@ extension Collection {
/// This method is equivalent to calling `randomSample(k:using:)`, passing in
/// the system's default random generator.
///
/// - Parameters:
/// - k: The number of elements to randomly select.
/// - Parameter k: The number of elements to randomly select.
/// - Returns: An array of `k` random elements. The returned elements may be
/// in any order. If `k` is greater than this collection's count, then this
/// method returns the full collection.
@@ -201,10 +200,10 @@ extension Sequence {
w *= nextW(k: k, using: &rng)
// Find the offset of the next element to swap into the reservoir.
var offset = nextOffset(w: w, using: &rng) + 1
var offset = nextOffset(w: w, using: &rng)
// Skip over `offset - 1` elements to find the selected element.
while offset > 1, let _ = iterator.next() {
// Skip over `offset` elements to find the selected element.
while offset > 0, let _ = iterator.next() {
offset -= 1
}
guard let nextElement = iterator.next() else { break }
@@ -224,8 +223,7 @@ extension Sequence {
/// This method is equivalent to calling `randomSample(k:using:)`, passing in
/// the system's default random generator.
///
/// - Parameters:
/// - k: The number of elements to randomly select.
/// - Parameter k: The number of elements to randomly select.
/// - Returns: An array of `k` random elements. The returned elements may be
/// in any order. If `k` is greater than this sequence's count, then this
/// method returns the full sequence.
+620
View File
@@ -0,0 +1,620 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
// MARK: - Exclusive Reductions
extension LazySequenceProtocol {
/// Returns a sequence containing the accumulated results of combining the
/// elements of the sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as a sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].lazy.reductions(0, +)
/// print(Array(runningTotal))
///
/// // prints [0, 1, 3, 6, 10]
/// ```
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving sequence.
/// - Returns: A sequence of the initial value followed by the reduced
/// elements.
///
/// - Complexity: O(1)
@inlinable
public func reductions<Result>(
_ initial: Result,
_ transform: @escaping (Result, Element) -> Result
) -> ExclusiveReductionsSequence<Elements, Result> {
reductions(into: initial) { result, element in
result = transform(result, element)
}
}
/// Returns a sequence containing the accumulated results of combining the
/// elements of the sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as a sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].lazy.reductions(into: 0, +)
/// print(Array(runningTotal))
///
/// // prints [0, 1, 3, 6, 10]
/// ```
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving sequence.
/// - Returns: A sequence of the initial value followed by the reduced
/// elements.
///
/// - Complexity: O(1)
@inlinable
public func reductions<Result>(
into initial: Result,
_ transform: @escaping (inout Result, Element) -> Void
) -> ExclusiveReductionsSequence<Elements, Result> {
ExclusiveReductionsSequence(
base: elements,
initial: initial,
transform: transform)
}
}
extension Sequence {
/// Returns an array containing the accumulated results of combining the
/// elements of the sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as a sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].reductions(0, +)
/// print(runningTotal)
///
/// // prints [0, 1, 3, 6, 10]
/// ```
///
/// When `reductions(_:_:)` is called, the following steps occur:
///
/// 1. The `initial` result is added to an array of results.
/// 2. The `transform` closure is called with the `initial` result and the
/// first element of the sequence, appending the result to the array.
/// 3. The closure is called again repeatedly with the updated accumulating
/// result and each element of the sequence, adding each result to the
/// array.
/// 4. When the sequence is exhausted, the results array is returned to the
/// caller.
///
/// If the sequence has no elements, `transform` is never executed and
/// an array containing only the `initial` result is returned.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving sequence.
/// - Returns: An array of the initial value followed by the reduced elements.
///
/// - Complexity: O(_n_), where _n_ is the length of the sequence.
@inlinable
public func reductions<Result>(
_ initial: Result,
_ transform: (Result, Element) throws -> Result
) rethrows -> [Result] {
try reductions(into: initial) { result, element in
result = try transform(result, element)
}
}
/// Returns an array containing the accumulated results of combining the
/// elements of the sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as a sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].reductions(into: 0, +)
/// print(runningTotal)
///
/// // prints [0, 1, 3, 6, 10]
/// ```
///
/// When `reductions(into:_:_)` is called, the following steps occur:
///
/// 1. The `initial` result is added to an array of results.
/// 2. The `transform` closure is called with the `initial` result and the
/// first element of the sequence, appending the result to the array.
/// 3. The closure is called again repeatedly with the updated accumulating
/// result and each element of the sequence, adding each result to the
/// array.
/// 4. When the sequence is exhausted, the results array is returned to the
/// caller.
///
/// If the sequence has no elements, `transform` is never executed and
/// an array containing only the `initial` result is returned.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving sequence.
/// - Returns: An array of the initial value followed by the reduced elements.
///
/// - Complexity: O(_n_), where _n_ is the length of the sequence.
@inlinable
public func reductions<Result>(
into initial: Result,
_ transform: (inout Result, Element) throws -> Void
) rethrows -> [Result] {
var output = [Result]()
output.reserveCapacity(underestimatedCount + 1)
output.append(initial)
var initial = initial
for element in self {
try transform(&initial, element)
output.append(initial)
}
return output
}
}
/// A sequence of applying a transform to the element of a sequence and the
/// previously transformed result.
public struct ExclusiveReductionsSequence<Base: Sequence, Result> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let initial: Result
@usableFromInline
internal let transform: (inout Result, Base.Element) -> Void
@inlinable
internal init(
base: Base,
initial: Result,
transform: @escaping (inout Result, Base.Element) -> Void
) {
self.base = base
self.initial = initial
self.transform = transform
}
}
extension ExclusiveReductionsSequence: Sequence {
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var iterator: Base.Iterator
@usableFromInline
internal var current: Result?
@usableFromInline
internal let transform: (inout Result, Base.Element) -> Void
@inlinable
internal init(
iterator: Base.Iterator,
current: Result? = nil,
transform: @escaping (inout Result, Base.Element) -> Void
) {
self.iterator = iterator
self.current = current
self.transform = transform
}
@inlinable
public mutating func next() -> Result? {
guard let result = current else { return nil }
current = iterator.next().map { element in
var result = result
transform(&result, element)
return result
}
return result
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(
iterator: base.makeIterator(),
current: initial,
transform: transform)
}
}
extension ExclusiveReductionsSequence: Collection where Base: Collection {
public struct Index: Comparable {
@usableFromInline
internal enum Representation {
case base(Base.Index, Result)
case end
}
@usableFromInline
internal let representation: Representation
@inlinable
internal init(_ representation: Representation) {
self.representation = representation
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
switch (lhs.representation, rhs.representation) {
case (.base(let lhs, _), .base(let rhs, _)):
return lhs == rhs
case (.end, .end):
return true
case (.base, .end), (.end, .base):
return false
}
}
@inlinable
public static func < (lhs: Self, rhs: Self) -> Bool {
switch (lhs.representation, rhs.representation) {
case (.end, _):
return false
case (_, .end):
return true
case (.base(let lhs, _), .base(let rhs, _)):
return lhs < rhs
}
}
}
@inlinable
public var startIndex: Index {
Index(.base(base.startIndex, initial))
}
@inlinable
public var endIndex: Index {
Index(.end)
}
@inlinable
public subscript(position: Index) -> Result {
switch position.representation {
case .base(_, let result):
return result
case .end:
fatalError("Cannot get element of end index.")
}
}
@inlinable
public func index(after index: Index) -> Index {
switch index.representation {
case .base(base.endIndex, _):
return Index(.end)
case .base(let index, var result):
transform(&result, base[index])
return Index(.base(base.index(after: index), result))
case .end:
fatalError("Cannot get index after end index.")
}
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
switch (start.representation, end.representation) {
case let (.base(start, _), .base(end, _)):
return base.distance(from: start, to: end)
case let (.base(index, _), .end):
return base.distance(from: index, to: base.endIndex) + 1
case let (.end, .base(index, _)):
return base.distance(from: base.endIndex, to: index) - 1
case (.end, .end):
return 0
}
}
}
extension ExclusiveReductionsSequence: LazySequenceProtocol {}
extension ExclusiveReductionsSequence: LazyCollectionProtocol
where Base: Collection {}
extension ExclusiveReductionsSequence.Index: Hashable
where Base.Index: Hashable
{
@inlinable
public func hash(into hasher: inout Hasher) {
switch representation {
case .base(let base, _):
hasher.combine(base)
case .end:
break
}
}
}
// MARK: - Inclusive Reductions
extension LazySequenceProtocol {
/// Returns a sequence containing the accumulated results of combining the
/// elements of the sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as a sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].lazy.reductions(+)
/// print(Array(runningTotal))
///
/// // prints [1, 3, 6, 10]
/// ```
///
/// - Parameter transform: A closure that combines the previously reduced
/// result and the next element in the receiving sequence.
/// - Returns: A sequence of the reduced elements.
///
/// - Complexity: O(1)
@inlinable
public func reductions(
_ transform: @escaping (Element, Element) -> Element
) -> InclusiveReductionsSequence<Elements> {
InclusiveReductionsSequence(base: elements, transform: transform)
}
}
extension Sequence {
/// Returns an array containing the accumulated results of combining the
/// elements of the sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as a sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].reductions(+)
/// print(runningTotal)
///
/// // prints [1, 3, 6, 10]
/// ```
///
/// When `reductions(_:)` is called, the following steps occur:
///
/// 1. The `transform` closure is called with the first and second elements
/// of the sequence, appending the result to an array of results.
/// 2. The closure is called again repeatedly with the updated accumulating
/// result and the next element of the sequence, adding each result to the
/// array.
/// 3. When the sequence is exhausted, the results array is returned to the
/// caller.
///
/// If the sequence has no elements, `transform` is never executed and
/// an empty array is returned.
///
/// If the sequence has one element, `transform` is never executed and
/// an array containing only that first element is returned.
///
/// - Parameter transform: A closure that combines the previously reduced
/// result and the next element in the receiving sequence.
/// - Returns: An array of the reduced elements.
///
/// - Complexity: O(_n_), where _n_ is the length of the sequence.
@inlinable
public func reductions(
_ transform: (Element, Element) throws -> Element
) rethrows -> [Element] {
var iterator = makeIterator()
guard let initial = iterator.next() else { return [] }
return try IteratorSequence(iterator).reductions(initial, transform)
}
}
public struct InclusiveReductionsSequence<Base: Sequence> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let transform: (Base.Element, Base.Element) -> Base.Element
@inlinable
internal init(
base: Base,
transform: @escaping (Base.Element, Base.Element) -> Base.Element
) {
self.base = base
self.transform = transform
}
}
extension InclusiveReductionsSequence: Sequence {
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var iterator: Base.Iterator
@usableFromInline
internal var element: Base.Element?
@usableFromInline
internal let transform: (Base.Element, Base.Element) -> Base.Element
@inlinable
internal init(
iterator: Base.Iterator,
transform: @escaping (Base.Element, Base.Element) -> Base.Element
) {
self.iterator = iterator
self.transform = transform
}
@inlinable
public mutating func next() -> Base.Element? {
guard let previous = element else {
element = iterator.next()
return element
}
guard let next = iterator.next() else { return nil }
element = transform(previous, next)
return element
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(iterator: base.makeIterator(), transform: transform)
}
}
extension InclusiveReductionsSequence: Collection where Base: Collection {
public struct Index: Comparable {
@usableFromInline
internal let base: Base.Index
@usableFromInline
internal let result: Element?
@inlinable
internal init(base: Base.Index, result: Element?) {
self.base = base
self.result = result
}
@inlinable
public static func < (lhs: Self, rhs: Self) -> Bool {
lhs.base < rhs.base
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs.base == rhs.base
}
}
@inlinable
public var startIndex: Index {
Index(base: base.startIndex, result: base.first)
}
@inlinable
public var endIndex: Index {
Index(base: base.endIndex, result: nil)
}
@inlinable
public subscript(index: Index) -> Base.Element {
guard let result = index.result else {
fatalError("Can't subscript using endIndex")
}
return result
}
@inlinable
public func index(after index: Index) -> Index {
guard let result = index.result else {
fatalError("Can't advance past endIndex")
}
let index = base.index(after: index.base)
let nextResult = index == base.endIndex
? nil
: transform(result, base[index])
return Index(base: index, result: nextResult)
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
base.distance(from: start.base, to: end.base)
}
}
extension InclusiveReductionsSequence: LazySequenceProtocol {}
extension InclusiveReductionsSequence: LazyCollectionProtocol
where Base: Collection {}
extension InclusiveReductionsSequence.Index: Hashable
where Base.Index: Hashable
{
@inlinable
public func hash(into hasher: inout Hasher) {
hasher.combine(base)
}
}
// MARK: - Scan
extension LazySequenceProtocol {
@available(*, deprecated, message: "Use reductions(_:_:) instead.")
@inlinable
public func scan<Result>(
_ initial: Result,
_ transform: @escaping (Result, Element) -> Result
) -> ExclusiveReductionsSequence<Elements, Result> {
reductions(initial, transform)
}
@available(*, deprecated, message: "Use reductions(into:_:) instead.")
@inlinable
public func scan<Result>(
into initial: Result,
_ transform: @escaping (inout Result, Element) -> Void
) -> ExclusiveReductionsSequence<Elements, Result> {
reductions(into: initial, transform)
}
}
extension Sequence {
@available(*, deprecated, message: "Use reductions(_:_:) instead.")
@inlinable
public func scan<Result>(
_ initial: Result,
_ transform: (Result, Element) throws -> Result
) rethrows -> [Result] {
try reductions(initial, transform)
}
@available(*, deprecated, message: "Use reductions(into:_:) instead.")
@inlinable
public func scan<Result>(
into initial: Result,
_ transform: (inout Result, Element) throws -> Void
) rethrows -> [Result] {
try reductions(into: initial, transform)
}
}
extension LazySequenceProtocol {
@available(*, deprecated, message: "Use reductions(_:) instead.")
@inlinable
public func scan(
_ transform: @escaping (Element, Element) -> Element
) -> InclusiveReductionsSequence<Elements> {
reductions(transform)
}
}
extension Sequence {
@available(*, deprecated, message: "Use reductions(_:) instead.")
@inlinable
public func scan(
_ transform: (Element, Element) throws -> Element
) rethrows -> [Element] {
try reductions(transform)
}
}
+45 -67
View File
@@ -25,23 +25,23 @@ extension MutableCollection where Self: BidirectionalCollection {
/// Output:
/// [p o n m e f g h i j k l d c b a]
/// ^ ^
/// f l
/// lower upper
///
/// - Postcondition: For returned indices `(f, l)`:
/// `f == limit || l == limit`
@usableFromInline
/// - Postcondition: For returned indices `(lower, upper)`:
/// `lower == limit || upper == limit`
@inlinable
@discardableResult
internal mutating func _reverse(
subrange: Range<Index>, until limit: Index
) -> (Index, Index) {
var f = subrange.lowerBound
var l = subrange.upperBound
while f != limit && l != limit {
formIndex(before: &l)
swapAt(f, l)
formIndex(after: &f)
var lower = subrange.lowerBound
var upper = subrange.upperBound
while lower != limit && upper != limit {
formIndex(before: &upper)
swapAt(lower, upper)
formIndex(after: &lower)
}
return (f, l)
return (lower, upper)
}
/// Reverses the elements within the given subrange.
@@ -59,13 +59,12 @@ extension MutableCollection where Self: BidirectionalCollection {
@inlinable
public mutating func reverse(subrange: Range<Index>) {
if subrange.isEmpty { return }
var lo = subrange.lowerBound
var hi = subrange.upperBound
while lo < hi {
formIndex(before: &hi)
swapAt(lo, hi)
formIndex(after: &lo)
var lower = subrange.lowerBound
var upper = subrange.upperBound
while lower < upper {
formIndex(before: &upper)
swapAt(lower, upper)
formIndex(after: &lower)
}
}
}
@@ -76,8 +75,8 @@ extension MutableCollection where Self: BidirectionalCollection {
extension MutableCollection {
/// Swaps the elements of the two given subranges, up to the upper bound of
/// the smaller subrange. The returned indices are the ends of the two
/// ranges that were actually swapped.
/// the smaller subrange. The returned indices are the ends of the two ranges
/// that were actually swapped.
///
/// Input:
/// [a b c d e f g h i j k l m n o p]
@@ -95,7 +94,7 @@ extension MutableCollection {
/// - distance(from: lhs.lowerBound, to: p) == distance(from:
/// rhs.lowerBound, to: q)
/// - p == lhs.upperBound || q == rhs.upperBound
@usableFromInline
@inlinable
internal mutating func _swapNonemptySubrangePrefixes(
_ lhs: Range<Index>, _ rhs: Range<Index>
) -> (Index, Index) {
@@ -113,8 +112,8 @@ extension MutableCollection {
return (p, q)
}
/// Rotates the elements within the given subrange so that the element
/// at the specified index becomes the start of the subrange.
/// Rotates the elements within the given subrange so that the element at the
/// specified index becomes the start of the subrange.
///
/// Rotating a collection is equivalent to breaking the collection into two
/// sections at the index `newStart`, and then swapping those two sections.
@@ -147,10 +146,9 @@ extension MutableCollection {
if s == m { return e }
if m == e { return s }
// We have two regions of possibly-unequal length that need to be
// exchanged. The return value of this method is going to be the
// position following that of the element that is currently last
// (element j).
// We have two regions of possibly-unequal length that need to be exchanged.
// The return value of this method is going to be the position following
// that of the element that is currently last (element j).
//
// [a b c d e f g|h i j] or [a b c|d e f g h i j]
// ^ ^ ^ ^ ^ ^
@@ -158,8 +156,8 @@ extension MutableCollection {
//
var ret = e // start with a known incorrect result.
while true {
// Exchange the leading elements of each region (up to the
// length of the shorter region).
// Exchange the leading elements of each region (up to the length of the
// shorter region).
//
// [a b c d e f g|h i j] or [a b c|d e f g h i j]
// ^^^^^ ^^^^^ ^^^^^ ^^^^^
@@ -170,21 +168,20 @@ extension MutableCollection {
let (s1, m1) = _swapNonemptySubrangePrefixes(s..<m, m..<e)
if m1 == e {
// Left-hand case: we have moved element j into position. if
// we haven't already, we can capture the return value which
// is in s1.
// Left-hand case: we have moved element j into position. If we haven't
// already, we can capture the return value which is in s1.
//
// Note: the STL breaks the loop into two just to avoid this
// comparison once the return value is known. I'm not sure
// it's a worthwhile optimization, though.
// Note: the STL breaks the loop into two just to avoid this comparison
// once the return value is known. I'm not sure it's a worthwhile
// optimization, though.
if ret == e { ret = s1 }
// If both regions were the same size, we're done.
if s1 == m { break }
}
// Now we have a smaller problem that is also a rotation, so we
// can adjust our bounds and repeat.
// Now we have a smaller problem that is also a rotation, so we can adjust
// our bounds and repeat.
//
// h i j[d e f g|a b c] or d e f[a b c|g h i j]
// ^ ^ ^ ^ ^ ^
@@ -196,8 +193,8 @@ extension MutableCollection {
return ret
}
/// Rotates the elements of this collection so that the element
/// at the specified index becomes the start of the collection.
/// Rotates the elements of this collection so that the element at the
/// specified index becomes the start of the collection.
///
/// Rotating a collection is equivalent to breaking the collection into two
/// sections at the index `newStart`, and then swapping those two sections.
@@ -213,7 +210,7 @@ extension MutableCollection {
/// rotating.
/// - Returns: The new index of the element that was first pre-rotation.
///
/// - Complexity: O(*n*)
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
@discardableResult
public mutating func rotate(toStartAt newStart: Index) -> Index {
@@ -222,8 +219,8 @@ extension MutableCollection {
}
extension MutableCollection where Self: BidirectionalCollection {
/// Rotates the elements within the given subrange so that the element
/// at the specified index becomes the start of the subrange.
/// Rotates the elements within the given subrange so that the element at the
/// specified index becomes the start of the subrange.
///
/// Rotating a collection is equivalent to breaking the collection into two
/// sections at the index `newStart`, and then swapping those two sections.
@@ -256,13 +253,13 @@ extension MutableCollection where Self: BidirectionalCollection {
return newStart == p ? q : p
}
/// Rotates the elements of this collection so that the element
/// at the specified index becomes the start of the collection.
/// Rotates the elements of this collection so that the element at the
/// specified index becomes the start of the collection.
///
/// Rotating a collection is equivalent to breaking the collection into two
/// sections at the index `newStart`, and then swapping those two sections.
/// In this example, the `numbers` array is rotated so that the element at
/// index `3` (`40`) is first:
/// sections at the index `newStart`, and then swapping those two sections. In
/// this example, the `numbers` array is rotated so that the element at index
/// `3` (`40`) is first:
///
/// var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
/// let oldStart = numbers.rotate(toStartAt: 3)
@@ -273,29 +270,10 @@ extension MutableCollection where Self: BidirectionalCollection {
/// rotating.
/// - Returns: The new index of the element that was first pre-rotation.
///
/// - Complexity: O(*n*)
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
@discardableResult
public mutating func rotate(toStartAt newStart: Index) -> Index {
rotate(subrange: startIndex..<endIndex, toStartAt: newStart)
}
}
// Deprecations
extension MutableCollection {
@available(*, deprecated, renamed: "rotate(subrange:toStartAt:)")
@discardableResult
public mutating func rotate(
subrange: Range<Index>,
at newStart: Index) -> Index
{
rotate(subrange: subrange, toStartAt: newStart)
}
@available(*, deprecated, renamed: "rotate(toStartAt:)")
@discardableResult
public mutating func rotate(at newStart: Index) -> Index {
rotate(toStartAt: newStart)
}
}
-112
View File
@@ -1,112 +0,0 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// slidingWindows(ofCount:)
//===----------------------------------------------------------------------===//
extension Collection {
/// A collection for all contiguous windows of length size, the
/// windows overlap.
///
/// - Complexity: O(*1*) if the collection conforms to
/// `RandomAccessCollection`, otherwise O(*k*) where `k` is `count`.
/// Access to the next window is O(*1*).
///
/// - Parameter count: The number of elements in each window subsequence.
///
/// - Returns: If the collection is shorter than `size` the resulting
/// SlidingWindows collection will be empty.
public func slidingWindows(ofCount count: Int) -> SlidingWindows<Self> {
SlidingWindows(base: self, size: count)
}
}
public struct SlidingWindows<Base: Collection> {
public let base: Base
public let size: Int
private var firstUpperBound: Base.Index?
init(base: Base, size: Int) {
precondition(size > 0, "SlidingWindows size must be greater than zero")
self.base = base
self.size = size
self.firstUpperBound = base.index(base.startIndex, offsetBy: size, limitedBy: base.endIndex)
}
}
extension SlidingWindows: Collection {
public struct Index: Comparable {
internal var lowerBound: Base.Index
internal var upperBound: Base.Index
public static func == (lhs: Index, rhs: Index) -> Bool {
lhs.lowerBound == rhs.lowerBound
}
public static func < (lhs: Index, rhs: Index) -> Bool {
lhs.lowerBound < rhs.lowerBound
}
}
public var startIndex: Index {
if let upperBound = firstUpperBound {
return Index(lowerBound: base.startIndex, upperBound: upperBound)
} else {
return endIndex
}
}
public var endIndex: Index {
Index(lowerBound: base.endIndex, upperBound: base.endIndex)
}
public subscript(index: Index) -> Base.SubSequence {
precondition(index.lowerBound != index.upperBound, "SlidingWindows index is out of range")
return base[index.lowerBound..<index.upperBound]
}
public func index(after index: Index) -> Index {
precondition(index < endIndex, "Advancing past end index")
guard index.upperBound < base.endIndex else { return endIndex }
return Index(
lowerBound: base.index(after: index.lowerBound),
upperBound: base.index(after: index.upperBound)
)
}
// TODO: Implement distance(from:to:), index(_:offsetBy:) and
// index(_:offsetBy:limitedBy:)
}
extension SlidingWindows: BidirectionalCollection where Base: BidirectionalCollection {
public func index(before index: Index) -> Index {
precondition(index > startIndex, "Incrementing past start index")
if index == endIndex {
return Index(
lowerBound: base.index(index.lowerBound, offsetBy: -size),
upperBound: index.upperBound
)
} else {
return Index(
lowerBound: base.index(before: index.lowerBound),
upperBound: base.index(before: index.upperBound)
)
}
}
}
extension SlidingWindows: RandomAccessCollection where Base: RandomAccessCollection {}
extension SlidingWindows: Equatable where Base: Equatable {}
extension SlidingWindows: Hashable where Base: Hashable, Base.Index: Hashable {}
extension SlidingWindows.Index: Hashable where Base.Index: Hashable {}
+756
View File
@@ -0,0 +1,756 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// SplitSequence
//===----------------------------------------------------------------------===//
/// A sequence that lazily splits a base sequence into subsequences separated by
/// elements that satisfy the given `whereSeparator` predicate.
///
/// - Note: This type is the result of
///
/// x.split(maxSplits:omittingEmptySubsequences:whereSeparator)
/// x.split(separator:maxSplits:omittingEmptySubsequences)
///
/// where `x` conforms to `LazySequenceProtocol`.
public struct SplitSequence<Base: Sequence> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let isSeparator: (Base.Element) -> Bool
@usableFromInline
internal let maxSplits: Int
@usableFromInline
internal let omittingEmptySubsequences: Bool
@inlinable
internal init(
base: Base,
isSeparator: @escaping (Base.Element) -> Bool,
maxSplits: Int,
omittingEmptySubsequences: Bool
) {
self.base = base
self.isSeparator = isSeparator
self.maxSplits = maxSplits
self.omittingEmptySubsequences = omittingEmptySubsequences
}
}
extension SplitSequence: Sequence {
public struct Iterator {
public typealias Element = [Base.Element]
@usableFromInline
internal var base: Base.Iterator
@usableFromInline
internal let isSeparator: (Base.Element) -> Bool
@usableFromInline
internal let maxSplits: Int
@usableFromInline
internal let omittingEmptySubsequences: Bool
/// The number of splits performed.
@usableFromInline
internal var splitCount = 0
/// The number of subsequences returned.
@usableFromInline
internal var sequenceLength = 0
@inlinable
internal init(
base: Base.Iterator,
whereSeparator: @escaping (Base.Element) -> Bool,
maxSplits: Int,
omittingEmptySubsequences: Bool
) {
self.base = base
self.isSeparator = whereSeparator
self.maxSplits = maxSplits
self.omittingEmptySubsequences = omittingEmptySubsequences
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(
base: base.makeIterator(),
whereSeparator: self.isSeparator,
maxSplits: self.maxSplits,
omittingEmptySubsequences: self.omittingEmptySubsequences
)
}
}
extension SplitSequence.Iterator: IteratorProtocol {
@inlinable
public mutating func next() -> Element? {
var currentElement = base.next()
var subsequence: Element = []
// Add the next elements of the base sequence to this subsequence, until we
// reach a separator, unless we've already split the maximum number of
// times. In all cases, stop at the end of the base sequence.
while currentElement != nil {
if splitCount < maxSplits && isSeparator(currentElement!) {
if omittingEmptySubsequences && subsequence.isEmpty {
// Keep going if we don't want to return an empty subsequence.
currentElement = base.next()
continue
} else {
splitCount += 1
break
}
} else {
subsequence.append(currentElement!)
currentElement = base.next()
}
}
// We're done iterating when we've reached the end of the base sequence,
// and we've either returned the maximum number of subsequences (one more
// than the number of separators), or the only subsequence left to return is
// empty and we're omitting those.
if currentElement == nil
&& (sequenceLength == splitCount + 1
|| omittingEmptySubsequences && subsequence.isEmpty)
{
return nil
} else {
sequenceLength += 1
return subsequence
}
}
}
extension SplitSequence: LazySequenceProtocol {}
extension LazySequenceProtocol {
/// Lazily returns the longest possible subsequences of the sequence, in
/// order, that don't contain elements satisfying the given predicate.
///
/// The resulting lazy sequence consists of at most `maxSplits + 1`
/// subsequences. Elements that are used to split the sequence are not
/// returned as part of any subsequence (except possibly the last one, in the
/// case where `maxSplits` is less than the number of separators in the
/// sequence).
///
/// The following examples show the effects of the `maxSplits` and
/// `omittingEmptySubsequences` parameters when lazily splitting a sequence of
/// integers using a closure that matches numbers evenly divisible by 3 or 5.
/// The first use of `split` returns each subsequence that was originally
/// separated by one or more such numbers.
///
/// let numbers = stride(from: 1, through: 16, by: 1)
/// for subsequence in numbers.lazy.split(
/// whereSeparator: { $0 % 3 == 0 || $0 % 5 == 0 }
/// ) {
/// print(subsequence)
/// }
/// /* Prints:
/// [1, 2]
/// [4]
/// [7, 8]
/// [11]
/// [13, 14]
/// [16]
/// */
///
/// The second example passes `1` for the `maxSplits` parameter, so the
/// original sequence is split just once, into two subsequences.
///
/// for subsequence in numbers.lazy.split(
/// maxSplits: 1,
/// whereSeparator: { $0 % 3 == 0 || $0 % 5 == 0 }
/// ) {
/// print(subsequence)
/// }
/// /* Prints:
/// [1, 2]
/// [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
/// */
///
/// The final example passes `false` for the `omittingEmptySubsequences`
/// parameter, so the sequence of returned subsequences contains empty
/// subsequences where numbers evenly divisible by 3 or 5 were repeated.
///
/// for subsequence in numbers.lazy.split(
/// omittingEmptySubsequences: false,
/// whereSeparator: { $0 % 3 == 0 || $0 % 5 == 0 }
/// ) {
/// print(subsequence)
/// }
/// /* Prints:
/// [1, 2]
/// [4]
/// []
/// [7, 8]
/// []
/// [11]
/// [13, 14]
/// [16]
/// */
///
/// - Parameters:
/// - maxSplits: The maximum number of times to split the sequence, or
/// one less than the number of subsequences to return. If
/// `maxSplits + 1` subsequences are returned, the last one is a suffix
/// of the original sequence containing the remaining elements.
/// `maxSplits` must be greater than or equal to zero. The default value
/// is `Int.max`.
/// - omittingEmptySubsequences: If `false`, an empty subsequence is
/// returned in the result for each pair of consecutive elements
/// satisfying the `isSeparator` predicate and for each element at the
/// start or end of the sequence satisfying the `isSeparator`
/// predicate. The default value is `true`.
/// - whereSeparator: A closure that takes an element as an argument and
/// returns a Boolean value indicating whether the sequence should be
/// split at that element.
/// - Returns: A lazy sequence of subsequences, split from this sequence's
/// elements.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
@inlinable
public func split(
maxSplits: Int = Int.max,
omittingEmptySubsequences: Bool = true,
whereSeparator isSeparator: @escaping (Element) -> Bool
) -> SplitSequence<Elements> {
precondition(maxSplits >= 0, "Must take zero or more splits")
return SplitSequence(
base: elements,
isSeparator: isSeparator,
maxSplits: maxSplits,
omittingEmptySubsequences: omittingEmptySubsequences
)
}
}
extension LazySequenceProtocol where Element: Equatable {
/// Lazily returns the longest possible subsequences of the sequence, in
/// order, around elements equal to the given element.
///
/// The resulting lazy sequence consists of at most `maxSplits + 1`
/// subsequences. Elements that are used to split the sequence are not
/// returned as part of any subsequence (except possibly the last one, in the
/// case where `maxSplits` is less than the number of separators in the
/// sequence).
///
/// The following examples show the effects of the `maxSplits` and
/// `omittingEmptySubsequences` parameters when splitting a sequence of
/// integers at each zero (`0`). The first use of `split` returns each
/// subsequence that was originally separated by one or more zeros.
///
/// let numbers = AnySequence([1, 2, 0, 3, 4, 0, 0, 5])
/// for subsequence in numbers.lazy.split(separator: 0) {
/// print(subsequence)
/// }
/// /* Prints:
/// [1, 2]
/// [3, 4]
/// [5]
/// */
///
/// The second example passes `1` for the `maxSplits` parameter, so the
/// original sequence is split just once, into two subsequences.
///
/// for subsequence in numbers.lazy.split(
/// separator: 0,
/// maxSplits: 1
/// ) {
/// print(subsequence)
/// }
/// /* Prints:
/// [1, 2]
/// [3, 4, 0, 0, 5]
/// */
///
/// The final example passes `false` for the `omittingEmptySubsequences`
/// parameter, so the sequence of returned subsequences contains empty
/// subsequences where zeros were repeated.
///
/// for subsequence in numbers.lazy.split(
/// separator: 0,
/// omittingEmptySubsequences: false
/// ) {
/// print(subsequence)
/// }
/// /* Prints:
/// [1, 2]
/// [3, 4]
/// []
/// [5]
/// */
///
/// - Parameters:
/// - separator: The element that should be split upon.
/// - maxSplits: The maximum number of times to split the sequence, or
/// one less than the number of subsequences to return. If
/// `maxSplits + 1` subsequences are returned, the last one is a suffix
/// of the original sequence containing the remaining elements.
/// `maxSplits` must be greater than or equal to zero. The default value
/// is `Int.max`.
/// - omittingEmptySubsequences: If `false`, an empty subsequence is
/// returned in the result for each consecutive pair of `separator`
/// elements in the sequence and for each instance of `separator` at
/// the start or end of the sequence. If `true`, only nonempty
/// subsequences are returned. The default value is `true`.
/// - Returns: A lazy sequence of subsequences, split from this sequence's
/// elements.
///
/// - Complexity: O(*n*), where *n* is the length of the sequence.
@inlinable
public func split(
separator: Element,
maxSplits: Int = Int.max,
omittingEmptySubsequences: Bool = true
) -> SplitSequence<Elements> {
precondition(maxSplits >= 0, "Must take zero or more splits")
return SplitSequence(
base: elements,
isSeparator: { $0 == separator },
maxSplits: maxSplits,
omittingEmptySubsequences: omittingEmptySubsequences
)
}
}
//===----------------------------------------------------------------------===//
// SplitCollection
//===----------------------------------------------------------------------===//
/// A collection that lazily splits a base collection into subsequences
/// separated by elements that satisfy the given `whereSeparator` predicate.
///
/// - Note: This type is the result of
///
/// x.split(maxSplits:omittingEmptySubsequences:whereSeparator)
/// x.split(separator:maxSplits:omittingEmptySubsequences)
///
/// where `x` conforms to `LazySequenceProtocol` and `Collection`.
public struct SplitCollection<Base: Collection> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let isSeparator: (Base.Element) -> Bool
@usableFromInline
internal let maxSplits: Int
@usableFromInline
internal let omittingEmptySubsequences: Bool
@usableFromInline
internal var _startIndex: Index
@inlinable
internal init(
base: Base,
isSeparator: @escaping (Base.Element) -> Bool,
maxSplits: Int,
omittingEmptySubsequences: Bool
) {
self.base = base
self.isSeparator = isSeparator
self.maxSplits = maxSplits
self.omittingEmptySubsequences = omittingEmptySubsequences
// We precalculate `startIndex`. There are three possibilities:
// 1. `base` is empty and we're _not_ omitting empty subsequences, in which
// case the following index describes the sole element of this collection;
self._startIndex = Index(
baseRange: base.startIndex..<base.startIndex,
sequenceLength: 1,
splitCount: 0
)
if base.isEmpty {
if omittingEmptySubsequences {
// 2. `base` is empty and we _are_ omitting empty subsequences, so this
// collection has no elements;
_startIndex = endIndex
}
} else {
// 3. `base` isn't empty, so we must iterate it to determine the start
// index.
_startIndex = indexForSubsequence(
atOrAfter: base.startIndex,
sequenceLength: 0,
splitCount: 0
)
}
}
}
extension SplitCollection: Collection {
/// Position of a subsequence in a split collection.
public struct Index: Comparable {
/// The range corresponding to the subsequence at this position.
@usableFromInline
internal let baseRange: Range<Base.Index>
/// The number of subsequences up to and including this position in the
/// collection.
@usableFromInline
internal let sequenceLength: Int
/// The number splits performed up to and including this position in the
/// collection.
@usableFromInline
internal let splitCount: Int
@inlinable
internal init(
baseRange: Range<Base.Index>,
sequenceLength: Int,
splitCount: Int
) {
self.baseRange = baseRange
self.sequenceLength = sequenceLength
self.splitCount = splitCount
}
@inlinable
public static func == (lhs: Index, rhs: Index) -> Bool {
// `sequenceLength` is equivalent to the index's 1-based position in the
// collection of indices.
lhs.sequenceLength == rhs.sequenceLength
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
lhs.sequenceLength < rhs.sequenceLength
}
}
/// Returns the index of the subsequence starting at or after the given base
/// collection index.
@inlinable
internal func indexForSubsequence(
atOrAfter lowerBound: Base.Index,
sequenceLength: Int,
splitCount: Int
) -> Index {
var start = lowerBound
// If we don't have any more splits to do (which we'll determine shortly),
// the end of this subsequence will be the end of the base collection.
var end = base.endIndex
if splitCount < maxSplits {
// The non-inclusive end of this subsequence is marked by the next
// separator, or the end of the base collection.
end =
base[start...].firstIndex(where: isSeparator)
?? base.endIndex
if base[start..<end].isEmpty {
if omittingEmptySubsequences {
// Find the next subsequence of non-separators.
start =
base[end...].firstIndex(where: { !isSeparator($0) })
?? base.endIndex
if start == base.endIndex {
// No non-separators left in the base collection. We're done.
return endIndex
}
end = base[start...].firstIndex(where: isSeparator) ?? base.endIndex
}
}
}
var updatedSplitCount = splitCount
if end != base.endIndex {
// This subsequence ends on a separator (and perhaps includes other
// separators, if we're omitting empty subsequences), so we've performed
// another split.
updatedSplitCount += 1
}
return Index(
baseRange: start..<end,
sequenceLength: sequenceLength + 1,
splitCount: updatedSplitCount
)
}
@inlinable
public var startIndex: Index {
_startIndex
}
@inlinable
public var endIndex: Index {
Index(
baseRange: base.endIndex..<base.endIndex,
sequenceLength: Int.max,
splitCount: Int.max
)
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i != endIndex, "Can't advance past endIndex")
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 at the following element.
subsequenceStart = base.index(after: i.baseRange.upperBound)
}
guard subsequenceStart != base.endIndex else {
if !omittingEmptySubsequences
&& i.sequenceLength < i.splitCount + 1
{
// The base collection ended with a separator, so we need to emit one
// more empty subsequence. This one differs from `endIndex` in its
// `sequenceLength` (except in an extreme edge case!), which is the
// sole property tested for equality and comparison.
return Index(
baseRange: base.endIndex..<base.endIndex,
sequenceLength: i.sequenceLength + 1,
splitCount: i.splitCount
)
} else {
return endIndex
}
}
return indexForSubsequence(
atOrAfter: subsequenceStart,
sequenceLength: i.sequenceLength,
splitCount: i.splitCount
)
}
@inlinable
public subscript(position: Index) -> Base.SubSequence {
precondition(position != endIndex, "Can't subscript using endIndex")
return base[position.baseRange]
}
}
extension SplitCollection.Index: Hashable {
@inlinable
public func hash(into hasher: inout Hasher) {
hasher.combine(sequenceLength)
}
}
extension SplitCollection: LazyCollectionProtocol {}
extension LazySequenceProtocol where Self: Collection, Elements: Collection {
/// Lazily returns the longest possible subsequences of the collection, in
/// order, that don't contain elements satisfying the given predicate.
///
/// The resulting lazy collection consists of at most `maxSplits + 1`
/// subsequences. Elements that are used to split the collection are not
/// returned as part of any subsequence (except possibly the last one, in the
/// case where `maxSplits` is less than the number of separators in the
/// collection).
///
/// The following examples show the effects of the `maxSplits` and
/// `omittingEmptySubsequences` parameters when lazily splitting a string
/// using a closure that matches spaces. The first use of `split` returns each
/// word that was originally separated by one or more spaces.
///
/// let line = "BLANCHE: I don't want realism. I want magic!"
/// for spaceless in line.lazy.split(whereSeparator: { $0 == " " }) {
/// print(spaceless)
/// }
/// // Prints
/// // BLANCHE:
/// // I
/// // don't
/// // want
/// // realism.
/// // I
/// // want
/// // magic!
///
/// The second example passes `1` for the `maxSplits` parameter, so the
/// original string is split just once, into two new strings.
///
/// for spaceless in line.lazy.split(
/// maxSplits: 1,
/// whereSeparator: { $0 == " " }
/// ) {
/// print(spaceless)
/// }
/// // Prints
/// // BLANCHE:
/// // I don't want realism. I want magic!
///
/// The final example passes `false` for the `omittingEmptySubsequences`
/// parameter, so the returned array contains empty strings where spaces
/// were repeated.
///
/// for spaceless in line.lazy.split(
/// omittingEmptySubsequences: false,
/// whereSeparator: { $0 == " " }
/// ) {
/// print(spaceless)
/// }
/// // Prints
/// // BLANCHE:
/// //
/// //
/// // I
/// // don't
/// // want
/// // realism.
/// // I
/// // want
/// // magic!
///
/// - Parameters:
/// - maxSplits: The maximum number of times to split the collection, or
/// one less than the number of subsequences to return. If
/// `maxSplits + 1` subsequences are returned, the last one is a suffix
/// of the original collection containing the remaining elements.
/// `maxSplits` must be greater than or equal to zero. The default value
/// is `Int.max`.
/// - omittingEmptySubsequences: If `false`, an empty subsequence is
/// returned in the result for each pair of consecutive elements
/// satisfying the `isSeparator` predicate and for each element at the
/// start or end of the collection satisfying the `isSeparator`
/// predicate. The default value is `true`.
/// - whereSeparator: A closure that takes an element as an argument and
/// returns a Boolean value indicating whether the collection should be
/// split at that element.
/// - Returns: A lazy collection of subsequences, split from this collection's
/// elements.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
public func split(
maxSplits: Int = Int.max,
omittingEmptySubsequences: Bool = true,
whereSeparator isSeparator: @escaping (Element) -> Bool
) -> SplitCollection<Elements> {
precondition(maxSplits >= 0, "Must take zero or more splits")
return SplitCollection(
base: elements,
isSeparator: isSeparator,
maxSplits: maxSplits,
omittingEmptySubsequences: omittingEmptySubsequences
)
}
}
extension LazySequenceProtocol
where Self: Collection, Elements: Collection, Element: Equatable
{
/// Lazily returns the longest possible subsequences of the collection, in
/// order, around elements equal to the given element.
///
/// The resulting lazy collection consists of at most `maxSplits + 1`
/// subsequences. Elements that are used to split the collection are not
/// returned as part of any subsequence (except possibly the last one, in the
/// case where `maxSplits` is less than the number of separators in the
/// collection).
///
/// The following examples show the effects of the `maxSplits` and
/// `omittingEmptySubsequences` parameters when splitting a string at each
/// space character (" "). The first use of `split` returns each word that
/// was originally separated by one or more spaces.
///
/// let line = "BLANCHE: I don't want realism. I want magic!"
/// for spaceless in line.lazy.split(separator: " ") {
/// print(spaceless)
/// }
/// // Prints
/// // BLANCHE:
/// // I
/// // don't
/// // want
/// // realism.
/// // I
/// // want
/// // magic!
///
/// The second example passes `1` for the `maxSplits` parameter, so the
/// original string is split just once, into two new strings.
///
/// for spaceless in line.lazy.split(separator: " ", maxSplits: 1) {
/// print(spaceless)
/// }
/// // Prints
/// // BLANCHE:
/// // I don't want realism. I want magic!
///
/// The final example passes `false` for the `omittingEmptySubsequences`
/// parameter, so the returned array contains empty strings where spaces
/// were repeated.
///
/// for spaceless in line.lazy.split(
/// separator: " ",
/// omittingEmptySubsequences: false
/// ) {
/// print(spaceless)
/// }
/// // Prints
/// // BLANCHE:
/// //
/// //
/// // I
/// // don't
/// // want
/// // realism.
/// // I
/// // want
/// // magic!
///
/// - Parameters:
/// - separator: The element that should be split upon.
/// - maxSplits: The maximum number of times to split the collection, or
/// one less than the number of subsequences to return. If
/// `maxSplits + 1` subsequences are returned, the last one is a suffix
/// of the original collection containing the remaining elements.
/// `maxSplits` must be greater than or equal to zero. The default value
/// is `Int.max`.
/// - omittingEmptySubsequences: If `false`, an empty subsequence is
/// returned in the result for each consecutive pair of `separator`
/// elements in the collection and for each instance of `separator` at
/// the start or end of the collection. If `true`, only nonempty
/// subsequences are returned. The default value is `true`.
/// - Returns: A lazy collection of subsequences split from this collection's
/// elements.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
public func split(
separator: Element,
maxSplits: Int = Int.max,
omittingEmptySubsequences: Bool = true
) -> SplitCollection<Elements> {
precondition(maxSplits >= 0, "Must take zero or more splits")
return SplitCollection(
base: elements,
isSeparator: { $0 == separator },
maxSplits: maxSplits,
omittingEmptySubsequences: omittingEmptySubsequences
)
}
}
+283
View File
@@ -0,0 +1,283 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// striding(by:)
//===----------------------------------------------------------------------===//
extension Sequence {
/// Returns a sequence stepping through the elements every `step` starting at
/// the first value. Any remainders of the stride will be trimmed.
///
/// (0...10).striding(by: 2) // == [0, 2, 4, 6, 8, 10]
/// (0...10).striding(by: 3) // == [0, 3, 6, 9]
///
/// - Complexity: O(1). Access to successive values is O(k) where _k_ is the
/// striding `step`.
///
/// - Parameter step: The amount to step with each iteration.
/// - Returns: Returns a sequence for stepping through the elements by the
/// specified amount.
@inlinable
public func striding(by step: Int) -> StridingSequence<Self> {
StridingSequence(base: self, stride: step)
}
}
extension Collection {
/// Returns a sequence stepping through the elements every `step` starting at
/// the first value. Any remainders of the stride will be trimmed.
///
/// (0...10).striding(by: 2) // == [0, 2, 4, 6, 8, 10]
/// (0...10).striding(by: 3) // == [0, 3, 6, 9]
///
/// - Complexity: O(1). Access to successive values is O(1) if the collection
/// conforms to `RandomAccessCollection`; otherwise, O(_k_), where _k_ is
/// the striding `step`.
///
/// - Parameter step: The amount to step with each iteration.
/// - Returns: Returns a collection for stepping through the elements by the
/// specified amount.
@inlinable
public func striding(by step: Int) -> StridingCollection<Self> {
StridingCollection(base: self, stride: step)
}
}
/// A wrapper that strides over a base sequence.
public struct StridingSequence<Base: Sequence> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let stride: Int
@inlinable
internal init(base: Base, stride: Int) {
precondition(stride > 0, "Stride must be greater than zero")
self.base = base
self.stride = stride
}
}
extension StridingSequence {
@inlinable
public func striding(by step: Int) -> Self {
Self(base: base, stride: stride * step)
}
}
extension StridingSequence: Sequence {
/// An iterator over a `StridingSequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var iterator: Base.Iterator
@usableFromInline
internal let stride: Int
@usableFromInline
internal var striding: Bool = false
@inlinable
internal init(iterator: Base.Iterator, stride: Int) {
self.iterator = iterator
self.stride = stride
}
@inlinable
public mutating func next() -> Base.Element? {
guard striding else {
striding = true
return iterator.next()
}
for _ in 0..<stride - 1 {
guard iterator.next() != nil else { break }
}
return iterator.next()
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(iterator: base.makeIterator(), stride: stride)
}
}
extension StridingSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
/// A wrapper that strides over a base collection.
public struct StridingCollection<Base: Collection> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let stride: Int
@inlinable
internal init(base: Base, stride: Int) {
precondition(stride > 0, "striding must be greater than zero")
self.base = base
self.stride = stride
}
}
extension StridingCollection {
@inlinable
public func striding(by step: Int) -> Self {
Self(base: base, stride: stride * step)
}
}
extension StridingCollection: Collection {
/// A position in a `StridingCollection` instance.
public struct Index: Comparable {
@usableFromInline
internal let base: Base.Index
@usableFromInline
internal init(_ base: Base.Index) {
self.base = base
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
lhs.base < rhs.base
}
}
@inlinable
public var startIndex: Index {
Index(base.startIndex)
}
@inlinable
public var endIndex: Index {
Index(base.endIndex)
}
@inlinable
public subscript(i: Index) -> Base.Element {
base[i.base]
}
@inlinable
public func index(after i: Index) -> Index {
precondition(i.base != base.endIndex, "Advancing past end index")
return index(i, offsetBy: 1)
}
@inlinable
public func index(
_ i: Index,
offsetBy n: Int,
limitedBy limit: Index
) -> Index? {
guard n != 0 else { return i }
guard limit != i else { return nil }
return n > 0
? offsetForward(i, offsetBy: n, limitedBy: limit)
: offsetBackward(i, offsetBy: -n, limitedBy: limit)
}
@inlinable
internal func offsetForward(
_ i: Index,
offsetBy n: Int,
limitedBy limit: Index
) -> Index? {
if limit < i {
if let idx = base.index(
i.base,
offsetBy: n * stride,
limitedBy: base.endIndex
) {
return Index(idx)
} else {
assert(distance(from: i, to: endIndex) == n, "Advancing past end index")
return endIndex
}
} else if let idx = base.index(
i.base,
offsetBy: n * stride,
limitedBy: limit.base
) {
return Index(idx)
} else {
return distance(from: i, to: limit) == n
? endIndex
: nil
}
}
@inlinable
internal func offsetBackward(
_ i: Index,
offsetBy n: Int,
limitedBy limit: Index
) -> Index? {
// We typically use the ternary operator but this significantly increases
// compile times when using Swift 5.3.2
// https://github.com/apple/swift-algorithms/issues/146
let distance: Int
if i == endIndex {
distance = -((base.count - 1) % stride + 1) + (n - 1) * -stride
} else {
distance = n * -stride
}
return base.index(
i.base,
offsetBy: distance,
limitedBy: limit.base
).map(Index.init)
}
@inlinable
public var count: Int {
base.isEmpty ? 0 : (base.count - 1) / stride + 1
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
let distance = base.distance(from: start.base, to: end.base)
return distance / stride + (distance % stride).signum()
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
precondition(distance <= 0 || i.base != base.endIndex, "Advancing past end index")
precondition(distance >= 0 || i.base != base.startIndex, "Incrementing past start index")
let limit = distance > 0 ? endIndex : startIndex
let idx = index(i, offsetBy: distance, limitedBy: limit)
precondition(idx != nil, "The distance \(distance) is not valid for this collection")
return idx!
}
}
extension StridingCollection: BidirectionalCollection
where Base: RandomAccessCollection {
@inlinable
public func index(before i: Index) -> Index {
precondition(i.base != base.startIndex, "Incrementing past start index")
return index(i, offsetBy: -1)
}
}
extension StridingCollection: RandomAccessCollection
where Base: RandomAccessCollection {}
extension StridingCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
extension StridingCollection.Index: Hashable where Base.Index: Hashable {}
+88
View File
@@ -0,0 +1,88 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// suffix(while:)
//===----------------------------------------------------------------------===//
extension BidirectionalCollection {
/// Returns a subsequence containing the elements from the end until
/// `predicate` returns `false` and skipping the remaining elements.
///
/// - Parameter predicate: A closure that takes an element of the sequence as
/// its argument and returns `true` if the element should be included or
/// `false` if it should be excluded. Once the predicate returns `false` it
/// will not be called again.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
public func suffix(
while predicate: (Element) throws -> Bool
) rethrows -> SubSequence {
try self[startOfSuffix(while: predicate)...]
}
}
//===----------------------------------------------------------------------===//
// endOfPrefix(while:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns the exclusive upper bound of the prefix of elements that satisfy
/// the predicate.
///
/// - Parameter predicate: A closure that takes an element of the collection
/// as its argument and returns `true` if the element is part of the prefix
/// or `false` if it is not. Once the predicate returns `false` it will not
/// be called again.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
public func endOfPrefix(
while predicate: (Element) throws -> Bool
) rethrows -> Index {
var index = startIndex
while try index != endIndex && predicate(self[index]) {
formIndex(after: &index)
}
return index
}
}
//===----------------------------------------------------------------------===//
// startOfSuffix(while:)
//===----------------------------------------------------------------------===//
extension BidirectionalCollection {
/// Returns the inclusive lower bound of the suffix of elements that satisfy
/// the predicate.
///
/// - Parameter predicate: A closure that takes an element of the collection
/// as its argument and returns `true` if the element is part of the suffix
/// or `false` if it is not. Once the predicate returns `false` it will not
/// be called again.
///
/// - Complexity: O(*n*), where *n* is the length of the collection.
@inlinable
public func startOfSuffix(
while predicate: (Element) throws -> Bool
) rethrows -> Index {
var index = endIndex
while index != startIndex {
let after = index
formIndex(before: &index)
if try !predicate(self[index]) {
return after
}
}
return index
}
}
+218 -28
View File
@@ -7,44 +7,234 @@
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
// trimmingPrefix(while:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns a `SubSequence` formed by discarding all elements at the start of
/// the collection which satisfy the given predicate.
///
/// This example uses `trimmingPrefix(while:)` to get a substring without the
/// white space at the beginning of the string:
///
/// let myString = " hello, world "
/// print(myString.trimmingPrefix(while: \.isWhitespace)) // "hello, world "
///
/// - Parameter predicate: A closure which determines if the element should be
/// omitted from the resulting slice.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
public func trimmingPrefix(
while predicate: (Element) throws -> Bool
) rethrows -> SubSequence {
let start = try endOfPrefix(while: predicate)
return self[start..<endIndex]
}
}
//===----------------------------------------------------------------------===//
// trimPrefix(while:)
//===----------------------------------------------------------------------===//
extension Collection where Self: RangeReplaceableCollection {
/// Mutates a `Collection` by discarding all elements at the start of it which
/// satisfy the given predicate.
///
/// This example uses `trimPrefix(while:)` to remove the white space at the
/// beginning of the string:
///
/// let myString = " hello, world "
/// myString.trimPrefix(while: \.isWhitespace)
/// print(myString) // "hello, world "
///
/// - Parameter predicate: A closure which determines if the element should be
/// removed from the string.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
@_disfavoredOverload
public mutating func trimPrefix(
while predicate: (Element) throws -> Bool
) rethrows {
let startOfResult = try endOfPrefix(while: predicate)
removeSubrange(startIndex..<startOfResult)
}
}
extension Collection where Self == Self.SubSequence {
/// Mutates a `Collection` by discarding all elements at the start of it which
/// satisfy the given predicate.
///
/// This example uses `trimPrefix(while:)` to remove the white space at the
/// beginning of the string:
///
/// let myString = " hello, world "
/// myString.trimPrefix(while: \.isWhitespace)
/// print(myString) // "hello, world "
///
/// - Parameters predicate: A closure which determines if the element should
/// be removed from the string.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
public mutating func trimPrefix(
while predicate: (Element) throws -> Bool
) rethrows {
self = try trimmingPrefix(while: predicate)
}
}
//===----------------------------------------------------------------------===//
// trimming(while:) / trimmingSuffix(while:)
//===----------------------------------------------------------------------===//
extension BidirectionalCollection {
/// Returns a `SubSequence` formed by discarding all elements at the start and end of the collection
/// which satisfy the given predicate.
/// Returns a `SubSequence` formed by discarding all elements at the start and
/// end of the collection which satisfy the given predicate.
///
/// This example uses `trimming(where:)` to get a substring without the white space at the
/// beginning and end of the string:
/// This example uses `trimming(while:)` to get a substring without the white
/// space at the beginning and end of the string:
///
/// ```
/// let myString = " hello, world "
/// print(myString.trimming(where: \.isWhitespace)) // "hello, world"
/// ```
/// let myString = " hello, world "
/// print(myString.trimming(while: \.isWhitespace)) // "hello, world"
///
/// - parameters:
/// - predicate: A closure which determines if the element should be omitted from the
/// resulting slice.
/// - Parameter predicate: A closure which determines if the element should be
/// omitted from the resulting slice.
///
/// - complexity: `O(n)`, where `n` is the length of this collection.
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
public func trimming(
where predicate: (Element) throws -> Bool
while predicate: (Element) throws -> Bool
) rethrows -> SubSequence {
// Consume elements from the front.
let sliceStart = try firstIndex { try predicate($0) == false } ?? endIndex
// sliceEnd is the index _after_ the last index to match the predicate.
var sliceEnd = endIndex
while sliceStart != sliceEnd {
let idxBeforeSliceEnd = index(before: sliceEnd)
guard try predicate(self[idxBeforeSliceEnd]) else {
return self[sliceStart..<sliceEnd]
}
sliceEnd = idxBeforeSliceEnd
}
// Trimmed everything.
return self[Range(uncheckedBounds: (sliceStart, sliceStart))]
try trimmingPrefix(while: predicate).trimmingSuffix(while: predicate)
}
/// Returns a `SubSequence` formed by discarding all elements at the end of
/// the collection which satisfy the given predicate.
///
/// This example uses `trimmingSuffix(while:)` to get a substring without the
/// white space at the end of the string:
///
/// let myString = " hello, world "
/// print(myString.trimmingSuffix(while: \.isWhitespace)) // " hello, world"
///
/// - Parameter predicate: A closure which determines if the element should be
/// omitted from the resulting slice.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
public func trimmingSuffix(
while predicate: (Element) throws -> Bool
) rethrows -> SubSequence {
let end = try startOfSuffix(while: predicate)
return self[startIndex..<end]
}
}
//===----------------------------------------------------------------------===//
// trim(while:) / trimSuffix(while:)
//===----------------------------------------------------------------------===//
extension BidirectionalCollection where Self: RangeReplaceableCollection {
/// Mutates a `BidirectionalCollection` by discarding all elements at the
/// start and at the end of it which satisfy the given predicate.
///
/// This example uses `trim(while:)` to remove the white space at the
/// beginning of the string:
///
/// let myString = " hello, world "
/// myString.trim(while: \.isWhitespace)
/// print(myString) // "hello, world"
///
/// - Parameter predicate: A closure which determines if the element should be
/// removed from the string.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
@_disfavoredOverload
public mutating func trim(
while predicate: (Element) throws -> Bool
) rethrows {
try trimSuffix(while: predicate)
try trimPrefix(while: predicate)
}
/// Mutates a `BidirectionalCollection` by discarding all elements at the end
/// of it which satisfy the given predicate.
///
/// This example uses `trimSuffix(while:)` to remove the white space at the
/// beginning of the string:
///
/// let myString = " hello, world "
/// myString.trimSuffix(while: \.isWhitespace)
/// print(myString) // " hello, world"
///
/// - Parameter predicate: A closure which determines if the element should be
/// removed from the string.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
@_disfavoredOverload
public mutating func trimSuffix(
while predicate: (Element) throws -> Bool
) rethrows {
let endOfResult = try startOfSuffix(while: predicate)
removeSubrange(endOfResult..<endIndex)
}
}
extension BidirectionalCollection where Self == Self.SubSequence {
/// Mutates a `BidirectionalCollection` by discarding all elements at the
/// start and at the end of it which satisfy the given predicate.
///
/// This example uses `trim(while:)` to remove the white space at the
/// beginning of the string:
///
/// let myString = " hello, world "
/// myString.trim(while: \.isWhitespace)
/// print(myString) // "hello, world"
///
/// - Parameter predicate: A closure which determines if the element should be
/// removed from the string.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
public mutating func trim(
while predicate: (Element) throws -> Bool
) rethrows {
self = try trimming(while: predicate)
}
/// Mutates a `BidirectionalCollection` by discarding all elements at the end
/// of it which satisfy the given predicate.
///
/// This example uses `trimSuffix(while:)` to remove the white space at the
/// beginning of the string:
///
/// let myString = " hello, world "
/// myString.trimSuffix(while: \.isWhitespace)
/// print(myString) // " hello, world"
///
/// - Parameter predicate: A closure which determines if the element should be
/// removed from the string.
///
/// - Complexity: O(*n*), where *n* is the length of this collection.
///
@inlinable
public mutating func trimSuffix(
while predicate: (Element) throws -> Bool
) rethrows {
self = try trimmingSuffix(while: predicate)
}
}
+86 -10
View File
@@ -9,25 +9,83 @@
//
//===----------------------------------------------------------------------===//
/// A sequence wrapper that leaves out duplicate elements of a base sequence.
public struct UniquedSequence<Base: Sequence, Subject: Hashable> {
/// The base collection.
@usableFromInline
internal let base: Base
/// The projection function.
@usableFromInline
internal let projection: (Base.Element) -> Subject
@usableFromInline
internal init(base: Base, projection: @escaping (Base.Element) -> Subject) {
self.base = base
self.projection = projection
}
}
extension UniquedSequence: Sequence {
/// The iterator for a `UniquedSequence` instance.
public struct Iterator: IteratorProtocol {
@usableFromInline
internal var base: Base.Iterator
@usableFromInline
internal let projection: (Base.Element) -> Subject
@usableFromInline
internal var seen: Set<Subject> = []
@usableFromInline
internal init(
base: Base.Iterator,
projection: @escaping (Base.Element) -> Subject
) {
self.base = base
self.projection = projection
}
@inlinable
public mutating func next() -> Base.Element? {
while let element = base.next() {
if seen.insert(projection(element)).inserted {
return element
}
}
return nil
}
}
@inlinable
public func makeIterator() -> Iterator {
Iterator(base: base.makeIterator(), projection: projection)
}
}
extension UniquedSequence: LazySequenceProtocol
where Base: LazySequenceProtocol {}
//===----------------------------------------------------------------------===//
// uniqued()
//===----------------------------------------------------------------------===//
extension Sequence where Element: Hashable {
/// Returns an array with only the unique elements of this sequence, in the
/// Returns a sequence with only the unique elements of this sequence, in the
/// order of the first occurrence of each unique element.
///
/// let animals = ["dog", "pig", "cat", "ox", "dog", "cat"]
/// let uniqued = animals.uniqued()
/// print(uniqued)
/// print(Array(uniqued))
/// // Prints '["dog", "pig", "cat", "ox"]'
///
/// - Returns: An array with only the unique elements of this sequence.
/// - Returns: A sequence with only the unique elements of this sequence.
/// .
/// - Complexity: O(*n*), where *n* is the length of the sequence.
/// - Complexity: O(1).
@inlinable
public func uniqued() -> [Element] {
uniqued(on: { $0 })
public func uniqued() -> UniquedSequence<Self, Element> {
UniquedSequence(base: self, projection: { $0 })
}
}
@@ -40,14 +98,14 @@ extension Sequence {
/// first characters:
///
/// let animals = ["dog", "pig", "cat", "ox", "cow", "owl"]
/// let uniqued = animals.uniqued(on: {$0.first})
/// let uniqued = animals.uniqued(on: { $0.first })
/// print(uniqued)
/// // Prints '["dog", "pig", "cat", "ox"]'
///
/// - Parameter projection: A closure that transforms an element into the
/// value to use for uniqueness. If `projection` returns the same value
/// for two different elements, the second element will be excluded
/// from the resulting array.
/// value to use for uniqueness. If `projection` returns the same value for
/// two different elements, the second element will be excluded from the
/// resulting array.
///
/// - Returns: An array with only the unique elements of this sequence, as
/// determined by the result of `projection` for each element.
@@ -67,3 +125,21 @@ extension Sequence {
return result
}
}
//===----------------------------------------------------------------------===//
// lazy.uniqued()
//===----------------------------------------------------------------------===//
extension LazySequenceProtocol {
/// Returns a lazy sequence with the unique elements of this sequence (as
/// determined by the given projection), in the order of the first occurrence
/// of each unique element.
///
/// - Complexity: O(1).
@inlinable
public func uniqued<Subject: Hashable>(
on projection: @escaping (Element) -> Subject
) -> UniquedSequence<Self, Subject> {
UniquedSequence(base: self, projection: projection)
}
}
+360
View File
@@ -0,0 +1,360 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
// windows(ofCount:)
//===----------------------------------------------------------------------===//
extension Collection {
/// Returns a collection of all the overlapping slices of a given size.
///
/// Use this method to iterate over overlapping subsequences of this
/// collection. This example prints every five character substring of `str`:
///
/// let str = "Hello, world!"
/// for substring in str.windows(ofCount: 5) {
/// print(substring)
/// }
/// // "Hello"
/// // "ello,"
/// // "llo, "
/// // "lo, W"
/// // ...
/// // "orld!"
///
/// - Parameter count: The number of elements in each window subsequence.
/// - Returns: A collection of subsequences of this collection, each with
/// length `count`. If this collection is shorter than `count`, the
/// resulting collection is empty.
///
/// - Complexity: O(1) if the collection conforms to
/// `RandomAccessCollection`, otherwise O(*k*) where `k` is `count`.
/// Access to successive windows is O(1).
@inlinable
public func windows(ofCount count: Int) -> WindowsOfCountCollection<Self> {
WindowsOfCountCollection(base: self, windowSize: count)
}
}
/// A collection wrapper that presents a sliding window over the elements of
/// a collection.
public struct WindowsOfCountCollection<Base: Collection> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let windowSize: Int
@usableFromInline
internal var endOfFirstWindow: Base.Index?
@inlinable
internal init(base: Base, windowSize: Int) {
precondition(windowSize > 0, "Windows size must be greater than zero")
self.base = base
self.windowSize = windowSize
self.endOfFirstWindow =
base.index(base.startIndex, offsetBy: windowSize, limitedBy: base.endIndex)
}
}
extension WindowsOfCountCollection: Collection {
/// A position in a `WindowsOfCountCollection` instance.
public struct Index: Comparable {
@usableFromInline
internal var lowerBound: Base.Index
@usableFromInline
internal var upperBound: Base.Index
@inlinable
internal init(lowerBound: Base.Index, upperBound: Base.Index) {
self.lowerBound = lowerBound
self.upperBound = upperBound
}
@inlinable
public static func == (lhs: Index, rhs: Index) -> Bool {
lhs.lowerBound == rhs.lowerBound
}
@inlinable
public static func < (lhs: Index, rhs: Index) -> Bool {
lhs.lowerBound < rhs.lowerBound
}
}
@inlinable
public var startIndex: Index {
if let upperBound = endOfFirstWindow {
return Index(lowerBound: base.startIndex, upperBound: upperBound)
} else {
return endIndex
}
}
@inlinable
public var endIndex: Index {
Index(lowerBound: base.endIndex, upperBound: base.endIndex)
}
@inlinable
public subscript(index: Index) -> Base.SubSequence {
precondition(
index.lowerBound != index.upperBound,
"Windows index is out of range")
return base[index.lowerBound..<index.upperBound]
}
@inlinable
public func index(after index: Index) -> Index {
precondition(index != endIndex, "Advancing past end index")
guard index.upperBound < base.endIndex else { return endIndex }
let lowerBound = windowSize == 1
? index.upperBound
: base.index(after: index.lowerBound)
let upperBound = base.index(after: index.upperBound)
return Index(lowerBound: lowerBound, upperBound: upperBound)
}
@inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index {
guard distance != 0 else { return i }
return distance > 0
? offsetForward(i, by: distance)
: offsetBackward(i, by: -distance)
}
@inlinable
public func index(
_ i: Index,
offsetBy distance: Int,
limitedBy limit: Index
) -> Index? {
guard distance != 0 else { return i }
guard limit != i else { return nil }
if distance > 0 {
return limit > i
? offsetForward(i, by: distance, limitedBy: limit)
: offsetForward(i, by: distance)
} else {
return limit < i
? offsetBackward(i, by: -distance, limitedBy: limit)
: offsetBackward(i, by: -distance)
}
}
@inlinable
internal func offsetForward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetForward(i, by: distance, limitedBy: endIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetBackward(_ i: Index, by distance: Int) -> Index {
guard let index = offsetBackward(i, by: distance, limitedBy: startIndex)
else { fatalError("Index is out of bounds") }
return index
}
@inlinable
internal func offsetForward(
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit > i)
// `endIndex` and the index before it both have `base.endIndex` as their
// upper bound, so we first advance to the base index _before_ the upper
// bound of the output, in order to avoid advancing past the end of `base`
// when advancing to `endIndex`.
//
// Advancing by 4:
//
// input: [x|x x x x x|x x x x] [x x|x x x x x|x x x]
// |> > >|>| or |> > >|
// output: [x x x x x|x x x x x] [x x x x x x x x x x] (`endIndex`)
if distance >= windowSize {
// Avoid traversing `self[i.lowerBound..<i.upperBound]` when the lower
// bound of the output is greater than or equal to the upper bound of the
// input.
// input: [x|x x x x|x x x x x x x]
// |> >|> > >|>|
// output: [x x x x x x x|x x x x|x]
guard limit.lowerBound >= i.upperBound,
let lowerBound = base.index(
i.upperBound,
offsetBy: distance - windowSize,
limitedBy: limit.lowerBound),
let indexBeforeUpperBound = base.index(
lowerBound,
offsetBy: windowSize - 1,
limitedBy: limit.upperBound)
else { return nil }
// If `indexBeforeUpperBound` equals `base.endIndex`, we're advancing to
// `endIndex`.
guard indexBeforeUpperBound != base.endIndex else { return endIndex }
return Index(
lowerBound: lowerBound,
upperBound: base.index(after: indexBeforeUpperBound))
} else {
// input: [x|x x x x x x|x x x x x]
// |> > > >| |> > >|>|
// output: [x x x x x|x x x x x x|x]
guard let indexBeforeUpperBound = base.index(
i.upperBound,
offsetBy: distance - 1,
limitedBy: limit.upperBound)
else { return nil }
// If `indexBeforeUpperBound` equals the limit, the upper bound itself
// exceeds it.
guard indexBeforeUpperBound != limit.upperBound || limit == endIndex
else { return nil }
// If `indexBeforeUpperBound` equals `base.endIndex`, we're advancing to
// `endIndex`.
guard indexBeforeUpperBound != base.endIndex else { return endIndex }
return Index(
lowerBound: base.index(i.lowerBound, offsetBy: distance),
upperBound: base.index(after: indexBeforeUpperBound))
}
}
@inlinable
internal func offsetBackward(
_ i: Index, by distance: Int, limitedBy limit: Index
) -> Index? {
assert(distance > 0)
assert(limit < i)
if i == endIndex {
// Advance `base.endIndex` by `distance - 1`, because the index before
// `endIndex` also has `base.endIndex` as its upper bound.
//
// Advancing by 4:
//
// input: [x x x x x x x x x x] (`endIndex`)
// |< < < < <|< < <|
// output: [x x|x x x x x|x x x]
guard let upperBound = base.index(
base.endIndex,
offsetBy: -(distance - 1),
limitedBy: limit.upperBound)
else { return nil }
return Index(
lowerBound: base.index(upperBound, offsetBy: -windowSize),
upperBound: upperBound)
} else if distance >= windowSize {
// Avoid traversing `self[i.lowerBound..<i.upperBound]` when the upper
// bound of the output is less than or equal to the lower bound of the
// input.
//
// input: [x x x x x x x|x x x x|x]
// |< < < <|< <|
// output: [x|x x x x|x x x x x x x]
guard limit.upperBound <= i.lowerBound,
let upperBound = base.index(
i.lowerBound,
offsetBy: -(distance - windowSize),
limitedBy: limit.upperBound)
else { return nil }
return Index(
lowerBound: base.index(upperBound, offsetBy: -windowSize),
upperBound: upperBound)
} else {
// input: [x x x x x|x x x x x x|x]
// |< < < <| |< < < <|
// output: [x|x x x x x x|x x x x x]
guard let lowerBound = base.index(
i.lowerBound,
offsetBy: -distance,
limitedBy: limit.lowerBound)
else { return nil }
return Index(
lowerBound: lowerBound,
upperBound: base.index(i.lowerBound, offsetBy: -distance))
}
}
@inlinable
public func distance(from start: Index, to end: Index) -> Int {
guard start <= end else { return -distance(from: end, to: start) }
guard start != end else { return 0 }
guard end != endIndex else {
// We add 1 here because the index before `endIndex` also has
// `base.endIndex` as its upper bound.
return base[start.upperBound...].count + 1
}
if start.upperBound <= end.lowerBound {
// The distance between `start.lowerBound` and `start.upperBound` is
// already known.
//
// start: [x|x x x x|x x x x x x x]
// |- - - -|> >|
// end: [x x x x x x x|x x x x|x]
return windowSize + base[start.upperBound..<end.lowerBound].count
} else {
// start: [x|x x x x x x|x x x x x]
// |> > > >|
// end: [x x x x x|x x x x x x|x]
return base[start.lowerBound..<end.lowerBound].count
}
}
}
extension WindowsOfCountCollection: BidirectionalCollection
where Base: BidirectionalCollection
{
@inlinable
public func index(before index: Index) -> Index {
precondition(index != startIndex, "Incrementing past start index")
if index == endIndex {
return Index(
lowerBound: base.index(index.lowerBound, offsetBy: -windowSize),
upperBound: index.upperBound
)
} else {
return Index(
lowerBound: base.index(before: index.lowerBound),
upperBound: base.index(before: index.upperBound)
)
}
}
}
extension WindowsOfCountCollection: RandomAccessCollection
where Base: RandomAccessCollection {}
extension WindowsOfCountCollection: LazySequenceProtocol, LazyCollectionProtocol
where Base: LazySequenceProtocol {}
extension WindowsOfCountCollection.Index: Hashable where Base.Index: Hashable {}
-19
View File
@@ -1,19 +0,0 @@
//===----------------------------------------------------------*- swift -*-===//
//
// This source file is part of the Swift Argument Parser 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
//
//===----------------------------------------------------------------------===//
#error("""
-----------------------------------------------------
Please test with `swift test --enable-test-discovery`
-----------------------------------------------------
""")
@@ -0,0 +1,84 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
import XCTest
import Algorithms
final class AdjacentPairsTests: XCTestCase {
func testEmptySequence() {
let pairs = (0...).prefix(0).adjacentPairs()
XCTAssertEqualSequences(pairs, [], by: ==)
}
func testOneElementSequence() {
let pairs = (0...).prefix(1).adjacentPairs()
XCTAssertEqualSequences(pairs, [], by: ==)
}
func testTwoElementSequence() {
let pairs = (0...).prefix(2).adjacentPairs()
XCTAssertEqualSequences(pairs, [(0, 1)], by: ==)
}
func testThreeElementSequence() {
let pairs = (0...).prefix(3).adjacentPairs()
XCTAssertEqualSequences(pairs, [(0, 1), (1, 2)], by: ==)
}
func testManySequences() {
for n in 4...100 {
let pairs = (0...).prefix(n).adjacentPairs()
XCTAssertEqualSequences(pairs, zip(0..., 1...).prefix(n - 1), by: ==)
}
}
func testZeroElements() {
let pairs = (0..<0).adjacentPairs()
XCTAssertEqual(pairs.startIndex, pairs.endIndex)
XCTAssertEqualSequences(pairs, [], by: ==)
}
func testOneElement() {
let pairs = (0..<1).adjacentPairs()
XCTAssertEqual(pairs.startIndex, pairs.endIndex)
XCTAssertEqualSequences(pairs, [], by: ==)
}
func testTwoElements() {
let pairs = (0..<2).adjacentPairs()
XCTAssertEqualSequences(pairs, [(0, 1)], by: ==)
}
func testThreeElements() {
let pairs = (0..<3).adjacentPairs()
XCTAssertEqualSequences(pairs, [(0, 1), (1, 2)], by: ==)
}
func testManyElements() {
for n in 4...100 {
let pairs = (0..<n).adjacentPairs()
XCTAssertEqualSequences(pairs, zip(0..., 1...).prefix(n - 1), by: ==)
}
}
func testIndexTraversals() {
let validator = IndexValidator<AdjacentPairsCollection<Range<Int>>>()
validator.validate((0..<0).adjacentPairs(), expectedCount: 0)
validator.validate((0..<1).adjacentPairs(), expectedCount: 0)
validator.validate((0..<2).adjacentPairs(), expectedCount: 1)
validator.validate((0..<5).adjacentPairs(), expectedCount: 4)
}
func testLaziness() {
XCTAssertLazySequence((0...).lazy.adjacentPairs())
XCTAssertLazyCollection((0..<100).lazy.adjacentPairs())
}
}
+7 -6
View File
@@ -36,16 +36,17 @@ final class ChainTests: XCTestCase {
}
func testChainIndexTraversals() {
validateIndexTraversals(
chain("abcd", "XYZ"),
chain("abcd", ""),
chain("", "XYZ"),
chain("", ""),
indices: { chain in
let validator = IndexValidator<Chain2Sequence<String, String>>(
indicesIncludingEnd: { chain in
chain.base1.indices.map { .init(first: $0) }
+ chain.base2.indices.map { .init(second: $0) }
+ [.init(second: chain.base2.endIndex)]
})
validator.validate(chain("abcd", "XYZ"), expectedCount: 4 + 3)
validator.validate(chain("abcd", ""), expectedCount: 4 + 0)
validator.validate(chain("", "XYZ"), expectedCount: 0 + 3)
validator.validate(chain("", ""), expectedCount: 0 + 0)
}
func testChainIndexOffsetAcrossBoundary() {
+133 -6
View File
@@ -47,8 +47,12 @@ final class ChunkedTests: XCTestCase {
func testSimple() {
// Example
let names = ["David", "Kyle", "Karoy", "Nate"]
let chunks = names.chunked(on: { $0.first })
XCTAssertEqualSequences([["David"], ["Kyle", "Karoy"], ["Nate"]], chunks)
let chunks = names.chunked(on: { $0.first! })
let expected: [(Character, ArraySlice<String>)] = [
("D", ["David"]),
("K", ["Kyle", "Karoy"]),
("N", ["Nate"])]
XCTAssertEqualSequences(expected, chunks, by: ==)
// Empty sequence
XCTAssertEqual(0, names.prefix(0).chunked(on: { $0.first }).count)
@@ -59,10 +63,11 @@ final class ChunkedTests: XCTestCase {
}
func testChunkedOn() {
validateFruitChunks(fruits.chunked(on: { $0.first }))
validateFruitChunks(fruits.chunked(on: { $0.first }).map { $1 })
let lazyChunks = fruits.lazy.chunked(on: { $0.first })
validateFruitChunks(lazyChunks)
validateFruitChunks(lazyChunks.map { $1 })
IndexValidator().validate(lazyChunks)
}
func testChunkedBy() {
@@ -70,10 +75,132 @@ final class ChunkedTests: XCTestCase {
let lazyChunks = fruits.lazy.chunked(by: { $0.first == $1.first })
validateFruitChunks(lazyChunks)
IndexValidator().validate(lazyChunks)
}
func testChunkedByComparesConsecutiveElements() {
XCTAssertEqualSequences(
[1, 2, 3, 4, 6, 7, 8, 9].chunked(by: { $1 - $0 == 1 }),
[[1, 2, 3, 4], [6, 7, 8, 9]])
XCTAssertEqualSequences(
[1, 2, 3, 4, 6, 7, 8, 9].lazy.chunked(by: { $1 - $0 == 1 }),
[[1, 2, 3, 4], [6, 7, 8, 9]])
XCTAssertEqualSequences(
[1, 2, 3, 4, 6, 7, 8, 9].lazy.chunked(by: { $1 - $0 == 1 }).reversed(),
[[6, 7, 8, 9], [1, 2, 3, 4]])
IndexValidator().validate([1, 2, 3].lazy.chunked(by: { $1 - $0 == 1 }))
}
func testChunkedLazy() {
XCTAssertLazy(fruits.lazy.chunked(by: { $0.first == $1.first }))
XCTAssertLazy(fruits.lazy.chunked(on: { $0.first }))
XCTAssertLazySequence(fruits.lazy.chunked(by: { $0.first == $1.first }))
XCTAssertLazySequence(fruits.lazy.chunked(on: { $0.first }))
}
//===----------------------------------------------------------------------===//
// Tests for `chunks(ofCount:)`
//===----------------------------------------------------------------------===//
func testChunksOfCount() {
XCTAssertEqualSequences([Int]().chunks(ofCount: 1), [])
XCTAssertEqualSequences([Int]().chunks(ofCount: 5), [])
let collection1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
XCTAssertEqualSequences(collection1.chunks(ofCount: 1),
[[1], [2], [3], [4], [5], [6], [7], [8], [9], [10]])
XCTAssertEqualSequences(collection1.chunks(ofCount: 3),
[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]])
XCTAssertEqualSequences(collection1.chunks(ofCount: 5),
[[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]])
XCTAssertEqualSequences(collection1.chunks(ofCount: 11),
[[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]])
let collection2 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
XCTAssertEqualSequences(collection2.chunks(ofCount: 3),
[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11]])
}
func testChunksOfCountBidirectional() {
let collection1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
XCTAssertEqualSequences(collection1.chunks(ofCount: 1).reversed(),
[[10], [9], [8], [7], [6], [5], [4], [3], [2], [1]])
XCTAssertEqualSequences(collection1.chunks(ofCount: 3).reversed(),
[[10], [7, 8, 9], [4, 5, 6], [1, 2, 3]])
XCTAssertEqualSequences(collection1.chunks(ofCount: 5).reversed(),
[[6, 7, 8, 9, 10], [1, 2, 3, 4, 5]])
XCTAssertEqualSequences(collection1.chunks(ofCount: 11).reversed(),
[[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]])
let collection2 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
XCTAssertEqualSequences(collection2.chunks(ofCount: 3).reversed(),
[[10, 11], [7, 8, 9], [4, 5, 6], [1, 2, 3]])
}
func testChunksOfCountCount() {
XCTAssertEqual([Int]().chunks(ofCount: 1).count, 0)
XCTAssertEqual([Int]().chunks(ofCount: 5).count, 0)
let collection1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
XCTAssertEqual(collection1.chunks(ofCount: 1).count, 10)
XCTAssertEqual(collection1.chunks(ofCount: 3).count, 4)
XCTAssertEqual(collection1.chunks(ofCount: 5).count, 2)
XCTAssertEqual(collection1.chunks(ofCount: 11).count, 1)
let collection2 = (1...50).map { $0 }
XCTAssertEqual(collection2.chunks(ofCount: 9).count, 6)
}
func testEmptyChunksOfCountTraversal() {
let emptyChunks = [Int]().chunks(ofCount: 1)
IndexValidator().validate(emptyChunks, expectedCount: 0)
}
func testChunksOfCountTraversal() {
let validator = IndexValidator<ChunksOfCountCollection<ClosedRange<Int>>>()
for i in 1...10 {
let range = 1...50
let chunks = range.chunks(ofCount: i)
validator.validate(
chunks,
expectedCount: range.count / i + (range.count % i).signum())
}
}
func testEvenChunks() {
XCTAssertEqualSequences(
(0..<10).evenlyChunked(in: 4),
[0..<3, 3..<6, 6..<8, 8..<10])
XCTAssertEqualSequences(
(0..<3).evenlyChunked(in: 5),
[0..<1, 1..<2, 2..<3, 3..<3, 3..<3])
XCTAssertEqualSequences(
"".evenlyChunked(in: 0),
[])
XCTAssertEqualSequences(
"".evenlyChunked(in: 1),
[""])
}
func testEvenChunksIndexTraversals() {
let validator = IndexValidator<EvenlyChunkedCollection<Range<Int>>>()
[
(0..<10).evenlyChunked(in: 1),
(0..<10).evenlyChunked(in: 2),
(0..<10).evenlyChunked(in: 3),
(0..<10).evenlyChunked(in: 10),
(0..<10).evenlyChunked(in: 20),
(0..<0).evenlyChunked(in: 0),
(0..<0).evenlyChunked(in: 1),
(0..<0).evenlyChunked(in: 10),
].forEach { validator.validate($0) }
}
}
@@ -2,7 +2,7 @@
//
// This source file is part of the Swift Algorithms open source project
//
// Copyright (c) 2020 Apple Inc. and the Swift project authors
// Copyright (c) 2020-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
@@ -13,33 +13,114 @@ import XCTest
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)
// `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)
// `k` entirely greater than element count results in no combinations
let c12 = c.combinations(ofCount: 5...10).count
XCTAssertEqual(c12, 0)
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)
}
func testCombinations() {
let c = "ABCD"
let c1 = c.combinations(ofCount: 1)
XCTAssertEqual(["A", "B", "C", "D"], c1.map { String($0) })
let c2 = c.combinations(ofCount: 2)
XCTAssertEqual(["AB", "AC", "AD", "BC", "BD", "CD"], c2.map { String($0) })
let c3 = c.combinations(ofCount: 3)
XCTAssertEqual(["ABC", "ABD", "ACD", "BCD"], c3.map { String($0) })
let c4 = c.combinations(ofCount: 4)
XCTAssertEqual(["ABCD"], c4.map { String($0) })
let c5 = c.combinations(ofCount: 2...4)
XCTAssertEqual(["AB", "AC", "AD", "BC", "BD", "CD", "ABC", "ABD", "ACD", "BCD", "ABCD"], c5.map { String($0) })
let c6 = c.combinations(ofCount: 0...4)
XCTAssertEqual(["", "A", "B", "C", "D", "AB", "AC", "AD", "BC", "BD", "CD", "ABC", "ABD", "ACD", "BCD", "ABCD"], c6.map { String($0) })
let c7 = c.combinations(ofCount: 0...)
XCTAssertEqual(["", "A", "B", "C", "D", "AB", "AC", "AD", "BC", "BD", "CD", "ABC", "ABD", "ACD", "BCD", "ABCD"], c7.map { String($0) })
let c8 = c.combinations(ofCount: ...4)
XCTAssertEqual(["", "A", "B", "C", "D", "AB", "AC", "AD", "BC", "BD", "CD", "ABC", "ABD", "ACD", "BCD", "ABCD"], c8.map { String($0) })
let c9 = c.combinations(ofCount: ...3)
XCTAssertEqual(["", "A", "B", "C", "D", "AB", "AC", "AD", "BC", "BD", "CD", "ABC", "ABD", "ACD", "BCD"], c9.map { String($0) })
let c10 = c.combinations(ofCount: 1...)
XCTAssertEqual(["A", "B", "C", "D", "AB", "AC", "AD", "BC", "BD", "CD", "ABC", "ABD", "ACD", "BCD", "ABCD"], c10.map { String($0) })
}
func testEmpty() {
// `k == 0` results in one zero-length combination
XCTAssertEqualSequences([[]], "".combinations(ofCount: 0))
XCTAssertEqualSequences([[]], "".combinations(ofCount: 0...0))
XCTAssertEqualSequences([[]], "ABCD".combinations(ofCount: 0))
XCTAssertEqualSequences([[]], "ABCD".combinations(ofCount: 0...0))
// `k` greater than element count results in zero combinations
XCTAssertEqualSequences([], "".combinations(ofCount: 5))
XCTAssertEqualSequences([], "".combinations(ofCount: 5...10))
XCTAssertEqualSequences([], "ABCD".combinations(ofCount: 5))
XCTAssertEqualSequences([], "ABCD".combinations(ofCount: 5...10))
}
func testCombinationsLazy() {
XCTAssertLazy("ABC".lazy.combinations(ofCount: 1))
XCTAssertLazySequence("ABC".lazy.combinations(ofCount: 1))
XCTAssertLazySequence("ABC".lazy.combinations(ofCount: 1...3))
XCTAssertLazySequence("ABC".lazy.combinations(ofCount: 1...))
XCTAssertLazySequence("ABC".lazy.combinations(ofCount: ...3))
XCTAssertLazySequence("ABC".lazy.combinations(ofCount: 0...))
}
}
@@ -0,0 +1,45 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
import XCTest
import Algorithms
final class CompactedTests: XCTestCase {
let tests: [[Int?]] =
[nil, nil, nil, 0, 1, 2]
.uniquePermutations(ofCount: 0...)
.map(Array.init)
func testCompactedCompacted() {
for collection in self.tests {
let seq = AnySequence(collection)
XCTAssertEqualSequences(
seq.compactMap({ $0 }), seq.compacted())
XCTAssertEqualSequences(
collection.compactMap({ $0 }), collection.compacted())
}
}
func testCompactedBidirectionalCollection() {
for array in self.tests {
XCTAssertEqualSequences(array.compactMap({ $0 }).reversed(),
array.compacted().reversed())
}
}
func testCollectionTraversals() {
let validator = IndexValidator<CompactedCollection<[Int?], Int>>()
for array in self.tests {
validator.validate(array.compacted())
}
}
}
+49 -7
View File
@@ -19,28 +19,70 @@ final class CycleTests: XCTestCase {
[1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4],
cycle.prefix(20)
)
}
func testCycleClosedRangePrefix() {
let a = Array((0..<17).cycled().prefix(10_000))
XCTAssertEqual(10_000, a.count)
}
func testEmptyCycle() {
let empty = Array("".cycled())
XCTAssert(empty.isEmpty)
}
func testCycleLazy() {
XCTAssertLazySequence((1...4).lazy.cycled())
}
func testRepeated() {
let repeats = (1...4).cycled(times: 3)
XCTAssertEqualSequences(
[1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4],
repeats)
}
func testRepeatedClosedRange() {
let repeats = Array((1..<5).cycled(times: 2500))
XCTAssertEqual(10_000, repeats.count)
}
func testRepeatedEmptyCollection() {
let empty1 = Array("".cycled(times: 100))
XCTAssert(empty1.isEmpty)
}
func testRepeatedZeroTimesCycle() {
let empty2 = Array("Hello".cycled(times: 0))
XCTAssert(empty2.isEmpty)
}
func testCycleLazy() {
XCTAssertLazy((1...4).lazy.cycled())
func testRepeatedLazy() {
XCTAssertLazySequence((1...4).lazy.cycled(times: 3))
}
func testRepeatedIndexMethods() {
let cycle = (1..<5).cycled(times: 2)
let startIndex = cycle.startIndex
var nextIndex = cycle.index(after: startIndex)
XCTAssertEqual(cycle.distance(from: startIndex, to: nextIndex), 1)
nextIndex = cycle.index(nextIndex, offsetBy: 5)
XCTAssertEqual(cycle.distance(from: startIndex, to: nextIndex), 6)
nextIndex = cycle.index(nextIndex, offsetBy: 2, limitedBy: cycle.endIndex)!
XCTAssertEqual(cycle.distance(from: startIndex, to: nextIndex), 8)
let outOfBounds = cycle.index(nextIndex, offsetBy: 1,
limitedBy: cycle.endIndex)
XCTAssertNil(outOfBounds)
let previousIndex = cycle.index(before: nextIndex)
XCTAssertEqual(cycle.distance(from: startIndex, to: previousIndex), 7)
}
func testRepeatedCount() {
let cycle = (1..<5).cycled(times: 2)
XCTAssertEqual(cycle.count, 8)
}
}
@@ -0,0 +1,23 @@
//===----------------------------------------------------------------------===//
//
// 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 FirstNonNilTests: XCTestCase {
func testFirstNonNil() {
XCTAssertNil([].firstNonNil { $0 })
XCTAssertNil(["A", "B", "C"].firstNonNil { Int($0) })
XCTAssertNil(["A", "B", "C"].firstNonNil { _ in nil })
XCTAssertEqual(["A", "B", "10"].firstNonNil { Int($0) }, 10)
XCTAssertEqual(["20", "B", "10"].firstNonNil { Int($0) }, 20)
}
}
@@ -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)
}
}
}
@@ -29,6 +29,6 @@ final class IndexedTests: XCTestCase {
}
func testIndexedLazy() {
XCTAssertLazy("ABCD".lazy.indexed())
XCTAssertLazyCollection("ABCD".lazy.indexed())
}
}
@@ -0,0 +1,103 @@
//===----------------------------------------------------------------------===//
//
// 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
@testable import Algorithms
final class IntersperseTests: XCTestCase {
func testSequence() {
let interspersed = (1...).prefix(5).interspersed(with: 0)
XCTAssertEqualSequences(interspersed, [1,0,2,0,3,0,4,0,5])
}
func testSequenceEmpty() {
let interspersed = (1...).prefix(0).interspersed(with: 0)
XCTAssertEqualSequences(interspersed, [])
}
func testString() {
let interspersed = "ABCDE".interspersed(with: "-")
XCTAssertEqualSequences(interspersed, "A-B-C-D-E")
}
func testStringEmpty() {
let interspersed = "".interspersed(with: "-")
XCTAssertEqualSequences(interspersed, "")
}
func testArray() {
let interspersed = [1,2,3,4].interspersed(with: 0)
XCTAssertEqualSequences(interspersed, [1,0,2,0,3,0,4])
}
func testArrayEmpty() {
let interspersed = [].interspersed(with: 0)
XCTAssertEqualSequences(interspersed, [])
}
func testCollection() {
let interspersed = ["A","B","C","D"].interspersed(with: "-")
XCTAssertEqual(interspersed.count, 7)
}
func testBidirectionalCollection() {
let reversed = "ABCDE".interspersed(with: "-").reversed()
XCTAssertEqualSequences(reversed, "E-D-C-B-A")
}
func testIndexTraversals() {
let validator = IndexValidator<InterspersedSequence<String>>()
validator.validate("".interspersed(with: "-"), expectedCount: 0)
validator.validate("A".interspersed(with: "-"), expectedCount: 1)
validator.validate("AB".interspersed(with: "-"), expectedCount: 3)
validator.validate("ABCDE".interspersed(with: "-"), expectedCount: 9)
}
func testIntersperseLazy() {
XCTAssertLazySequence((1...).prefix(0).lazy.interspersed(with: 0))
XCTAssertLazyCollection("ABCDE".lazy.interspersed(with: "-"))
}
func testInterspersedMap() {
XCTAssertEqualSequences(
(0..<0).lazy.interspersedMap({ $0 }, with: { _, _ in 100 }),
[])
XCTAssertEqualSequences(
(0..<1).lazy.interspersedMap({ $0 }, with: { _, _ in 100 }),
[0])
XCTAssertEqualSequences(
(0..<5).lazy.interspersedMap({ $0 }, with: { $0 + $1 + 100 }),
[0, 101, 1, 103, 2, 105, 3, 107, 4])
}
func testInterspersedMapLazy() {
XCTAssertLazySequence(AnySequence([]).lazy.interspersedMap({ $0 }, with: { _, _ in 100 }))
XCTAssertLazyCollection((0..<0).lazy.interspersedMap({ $0 }, with: { _, _ in 100 }))
}
func testInterspersedMapIndexTraversals() {
let validator = IndexValidator<InterspersedMapSequence<Range<Int>, Int>>()
validator.validate(
(0..<0).lazy.interspersedMap({ $0 }, with: {_, _ in 100 }),
expectedCount: 0)
validator.validate(
(0..<1).lazy.interspersedMap({ $0 }, with: {_, _ in 100 }),
expectedCount: 1)
validator.validate(
(0..<2).lazy.interspersedMap({ $0 }, with: {_, _ in 100 }),
expectedCount: 3)
validator.validate(
(0..<5).lazy.interspersedMap({ $0 }, with: {_, _ in 100 }),
expectedCount: 9)
}
}
@@ -0,0 +1,132 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
import XCTest
@testable import Algorithms
final class JoinedTests: XCTestCase {
let stringArrays = [
[],
[""],
["", ""],
["foo"],
["foo", "bar"],
["", "", "foo", "", "bar", "baz", ""],
]
func testJoined() {
let expected = ["", "", "", "foo", "foobar", "foobarbaz"]
for (strings, expected) in zip(stringArrays, expected) {
// regular sequence
XCTAssertEqualSequences(AnySequence(strings).joined(), expected)
// lazy sequence
XCTAssertEqualSequences(AnySequence(strings).lazy.joined(), expected)
// regular collection
XCTAssertEqualSequences(strings.joined(), expected)
// lazy collection
XCTAssertEqualSequences(strings.lazy.joined() as FlattenCollection, expected)
}
}
func testJoinedByElement() {
let separator: Character = " "
let expected = ["", "", " ", "foo", "foo bar", " foo bar baz "]
for (strings, expected) in zip(stringArrays, expected) {
XCTAssertEqualSequences(AnySequence(strings).joined(by: separator), expected)
XCTAssertEqualSequences(AnySequence(strings).lazy.joined(by: separator), expected)
XCTAssertEqualSequences(strings.joined(by: separator), expected)
XCTAssertEqualSequences(strings.lazy.joined(by: separator), expected)
}
}
func testJoinedBySequence() {
let separator = ", "
let expected = ["", "", ", ", "foo", "foo, bar", ", , foo, , bar, baz, "]
for (strings, expected) in zip(stringArrays, expected) {
XCTAssertEqualSequences(AnySequence(strings).joined(by: separator), expected)
XCTAssertEqualSequences(AnySequence(strings).lazy.joined(by: separator), expected)
XCTAssertEqualSequences(strings.joined(by: separator), expected)
XCTAssertEqualSequences(strings.lazy.joined(by: separator), expected)
}
}
func testJoinedByElementClosure() {
let separator = { (left: String, right: String) -> Character in
left.isEmpty || right.isEmpty ? " " : "-"
}
let expected = ["", "", " ", "foo", "foo-bar", " foo bar-baz "]
for (strings, expected) in zip(stringArrays, expected) {
XCTAssertEqualSequences(AnySequence(strings).joined(by: separator), expected)
XCTAssertEqualSequences(AnySequence(strings).lazy.joined(by: separator), expected)
XCTAssertEqualSequences(strings.joined(by: separator), expected)
XCTAssertEqualSequences(strings.lazy.joined(by: separator), expected)
}
}
func testJoinedBySequenceClosure() {
let separator = { (left: String, right: String) in
"(\(left.count), \(right.count))"
}
let expected = [
"",
"",
"(0, 0)",
"foo",
"foo(3, 3)bar",
"(0, 0)(0, 3)foo(3, 0)(0, 3)bar(3, 3)baz(3, 0)"
]
for (strings, expected) in zip(stringArrays, expected) {
XCTAssertEqualSequences(AnySequence(strings).joined(by: separator), expected)
XCTAssertEqualSequences(AnySequence(strings).lazy.joined(by: separator), expected)
XCTAssertEqualSequences(strings.joined(by: separator), expected)
XCTAssertEqualSequences(strings.lazy.joined(by: separator), expected)
}
}
func testJoinedLazy() {
XCTAssertLazySequence(AnySequence([[1], [2]]).lazy.joined())
XCTAssertLazySequence(AnySequence([[1], [2]]).lazy.joined(by: 1))
XCTAssertLazySequence(AnySequence([[1], [2]]).lazy.joined(by: { _, _ in 1 }))
XCTAssertLazyCollection([[1], [2]].lazy.joined())
XCTAssertLazyCollection([[1], [2]].lazy.joined(by: 1))
XCTAssertLazyCollection([[1], [2]].lazy.joined(by: { _, _ in 1 }))
}
func testJoinedIndexTraversals() {
let validator = IndexValidator<FlattenCollection<[String]>>()
// the last test case takes too long to run
for strings in stringArrays.dropLast() {
validator.validate(strings.joined() as FlattenCollection)
}
}
func testJoinedByIndexTraversals() {
let validator1 = IndexValidator<JoinedByCollection<[String], String>>()
let validator2 = IndexValidator<JoinedByClosureCollection<[String], String>>()
// the last test case takes too long to run
for (strings, separator) in product(stringArrays.dropLast(), ["", " ", ", "]) {
validator1.validate(strings.joined(by: separator))
validator2.validate(strings.lazy.joined(by: { _, _ in separator }))
}
}
}
@@ -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,274 @@
//===----------------------------------------------------------------------===//
//
// 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 SortedPrefixTests: XCTestCase {
func testMinCount() {
// Replacement at start and end
let input = [10, 11, 12, 1, 13, 2, 14, 3, 4, 5, 6, 0, 7, 8, 9]
let min = input.min(count: 5)
XCTAssertEqualSequences(min, 0..<5)
// Stability with all equal values
let maxZeroes = Array(repeating: 0, count: 100)
.enumerated()
.max(count: 5, sortedBy: { $0.element < $1.element })
XCTAssertEqualSequences(maxZeroes.map { $0.offset }, 95..<100)
}
func testMaxCount() {
// Replacement at start and end
let input = [0, 11, 12, 1, 13, 2, 14, 3, 4, 5, 6, 7, 8, 9, 10]
let max = input.max(count: 5)
XCTAssertEqualSequences(max, 10..<15)
// Stability with all equal values
let maxZeroes = Array(repeating: 0, count: 100)
.enumerated()
.max(count: 5, sortedBy: { $0.element < $1.element })
XCTAssertEqualSequences(maxZeroes.map { $0.offset }, 95..<100)
}
func testEmpty() {
let array = [Int]()
XCTAssertEqual(array.min(count: 0), [])
XCTAssertEqual(array.min(count: 100), [])
XCTAssertEqual(array.max(count: 0), [])
XCTAssertEqual(array.max(count: 100), [])
}
func testMinMaxSequences() {
let input = (1...100).shuffled().interspersed(with: 50)
let seq = AnySequence(input)
XCTAssertEqualSequences(seq.min(count: 0), [])
XCTAssertEqualSequences(seq.min(count: 5), 1...5)
XCTAssertEqualSequences(seq.max(count: 0), [])
XCTAssertEqualSequences(seq.max(count: 5), 96...100)
}
func testSortedPrefixComparable() {
let array: [Int] = [20, 1, 4, 70, 100, 2, 3, 7, 90]
XCTAssertEqual(array.min(count: 0), [])
XCTAssertEqual(array.min(count: 1), [1])
XCTAssertEqualSequences(array.min(count: 5), array.sorted().prefix(5))
XCTAssertEqual(array.min(count: 10), array.sorted())
}
func testMinMaxWithHugeCount() {
XCTAssertEqual([4, 2, 1, 3].min(count: .max), [1, 2, 3, 4])
XCTAssertEqual([4, 2, 1, 3].max(count: .max), [1, 2, 3, 4])
}
func testMinCountWithHugeInput() {
let range = 1...1000
let input = range.shuffled()
XCTAssertEqual(input.min(count: 0, sortedBy: <), [])
XCTAssertEqual(input.min(count: 0, sortedBy: >), [])
XCTAssertEqual(input.min(count: 1, sortedBy: <), [range.lowerBound])
XCTAssertEqual(input.min(count: 1, sortedBy: >), [range.upperBound])
XCTAssertEqualSequences(input.min(count: 5, sortedBy: <), range.prefix(5))
XCTAssertEqualSequences(
input.min(count: 5, sortedBy: >),
range.suffix(5).reversed())
XCTAssertEqualSequences(
input.min(count: 500, sortedBy: <),
range.prefix(500))
XCTAssertEqualSequences(
input.min(count: 500, sortedBy: >),
range.suffix(500).reversed())
XCTAssertEqualSequences(input.min(count: 1000, sortedBy: <), range)
XCTAssertEqualSequences(
input.min(count: 1000, sortedBy: >),
range.reversed())
}
func testMaxCountWithHugeInput() {
let range = 1...1000
let input = range.shuffled()
XCTAssertEqual(input.max(count: 0, sortedBy: <), [])
XCTAssertEqual(input.max(count: 0, sortedBy: >), [])
XCTAssertEqual(input.max(count: 1, sortedBy: <), [range.upperBound])
XCTAssertEqual(input.max(count: 1, sortedBy: >), [range.lowerBound])
XCTAssertEqualSequences(input.max(count: 5, sortedBy: <), range.suffix(5))
XCTAssertEqualSequences(
input.max(count: 5, sortedBy: >),
range.prefix(5).reversed())
XCTAssertEqualSequences(
input.max(count: 500, sortedBy: <),
range.suffix(500))
XCTAssertEqualSequences(
input.max(count: 500, sortedBy: >),
range.prefix(500).reversed())
XCTAssertEqualSequences(input.max(count: 1000, sortedBy: <), range)
XCTAssertEqualSequences(
input.max(count: 1000, sortedBy: >),
range.reversed())
}
func testStability() {
assertStability([1,1,1,2,5,7,3,6,2,5,7,3,6], withCount: 3)
assertStability([1,1,1,2,5,7,3,6,2,5,7,3,6], withCount: 6)
assertStability([1,1,1,2,5,7,3,6,2,5,7,3,6], withCount: 20)
assertStability([1,1,1,2,5,7,3,6,2,5,7,3,6], withCount: 1000)
assertStability(Array(repeating: 0, count: 100), withCount: 0)
assertStability(Array(repeating: 0, count: 100), withCount: 1)
assertStability(Array(repeating: 0, count: 100), withCount: 2)
assertStability(Array(repeating: 0, count: 100), withCount: 5)
assertStability(Array(repeating: 0, count: 100), withCount: 20)
assertStability(Array(repeating: 0, count: 100), withCount: 100)
assertStability(Array(repeating: 1, count: 50) + Array(repeating: 0, count: 50), withCount: 2)
assertStability(Array(repeating: 1, count: 50) + Array(repeating: 0, count: 50), withCount: 5)
assertStability(Array(repeating: 1, count: 50) + Array(repeating: 0, count: 50), withCount: 20)
assertStability(Array(repeating: 1, count: 50) + Array(repeating: 0, count: 50), withCount: 50)
assertStability([0,0], withCount: 1)
assertStability([0,0], withCount: 2)
assertStability([0,1,0,1,0,1], withCount: 2)
assertStability([0,1,0,1,0,1], withCount: 6)
assertStability([0,0,0,1,1,1], withCount: 1)
assertStability([0,0,0,1,1,1], withCount: 3)
assertStability([0,0,0,1,1,1], withCount: 4)
assertStability([0,0,0,1,1,1], withCount: 6)
assertStability([1,1,1,0,0,0], withCount: 1)
assertStability([1,1,1,0,0,0], withCount: 3)
assertStability([1,1,1,0,0,0], withCount: 4)
assertStability([1,1,1,0,0,0], withCount: 6)
assertStability([1,1,1,0,0,0], withCount: 5)
}
func assertStability(
_ actual: [Int],
withCount count: Int
) {
func stableOrder(
a: (offset: Int, element: Int),
b: (offset: Int, element: Int)) -> Bool
{
a.element == b.element
? a.offset < b.offset
: a.element < b.element
}
do {
let sorted = actual.enumerated()
.min(count: count) { $0.element < $1.element }
XCTAssert(sorted.isSorted(by: stableOrder))
}
do {
let sorted = actual.enumerated()
.max(count: count) { $0.element < $1.element }
XCTAssert(sorted.isSorted(by: stableOrder))
}
}
}
final class MinAndMaxTests: XCTestCase {
/// Confirms that empty sequences yield no results.
func testEmpty() {
XCTAssertNil(EmptyCollection<Int>().minAndMax())
}
/// Confirms the same element is used when there is only one.
func testSingleElement() {
let result = CollectionOfOne(2).minAndMax()
XCTAssertEqual(result?.min, 2)
XCTAssertEqual(result?.max, 2)
}
/// Confirms the same value is used when all the elements have it.
func testSingleValueMultipleElements() {
let result = repeatElement(3.3, count: 5).minAndMax()
XCTAssertEqual(result?.min, 3.3)
XCTAssertEqual(result?.max, 3.3)
// Even count
let result2 = repeatElement("c" as Character, count: 6).minAndMax()
XCTAssertEqual(result2?.min, "c")
XCTAssertEqual(result2?.max, "c")
}
/// Confirms when the minimum value is constantly updated, but the maximum
/// never is.
func testRampDown() {
let result = (1...5).reversed().minAndMax()
XCTAssertEqual(result?.min, 1)
XCTAssertEqual(result?.max, 5)
// Even count
let result2 = "fedcba".minAndMax()
XCTAssertEqual(result2?.min, "a")
XCTAssertEqual(result2?.max, "f")
}
/// Confirms when the maximum value is constantly updated, but the minimum
/// never is.
func testRampUp() {
let result = (1...5).minAndMax()
XCTAssertEqual(result?.min, 1)
XCTAssertEqual(result?.max, 5)
// Even count
let result2 = "abcdef".minAndMax()
XCTAssertEqual(result2?.min, "a")
XCTAssertEqual(result2?.max, "f")
}
/// Confirms when the maximum and minimum change during a run.
func testUpsAndDowns() {
let result = [4, 3, 3, 5, 2, 0, 7, 6].minAndMax()
XCTAssertEqual(result?.min, 0)
XCTAssertEqual(result?.max, 7)
// Odd count
let result2 = "gfabdec".minAndMax()
XCTAssertEqual(result2?.min, "a")
XCTAssertEqual(result2?.max, "g")
}
/// Confirms that the given predicate is used to find the min/max.
func testPredicate() {
let result = (1...5).minAndMax(by: >)
XCTAssertEqual(result?.min, 5)
XCTAssertEqual(result?.max, 1)
// Odd count
let result2 = "gfabdec".minAndMax(by: >)
XCTAssertEqual(result2?.min, "g")
XCTAssertEqual(result2?.max, "a")
}
/// Confirms that the min and max are "stable" as defined for minAndMax.
func testStability() {
for n in 1...10 {
let result = repeatElement(0, count: n)
.enumerated()
.minAndMax(by: { $0.element < $1.element })
XCTAssertEqual(result?.min.offset, 0)
XCTAssertEqual(result?.max.offset, n - 1)
}
}
}
+109 -8
View File
@@ -64,14 +64,17 @@ final class PartitionTests: XCTestCase {
func testStablePartitionWithSubrange() {
for length in 10...20 {
let a = Array(0..<length)
for j in 0..<length {
var b = a
let partitionRange = 0..<j
let condition = { $0 < j - 1 }
let p = b.stablePartition(subrange: partitionRange, by: condition)
XCTAssertEqual(p, partitionRange.count > 0 ? 1 : 0)
XCTAssertEqualSequences(b[partitionRange.lowerBound..<p], a[partitionRange].filter { !condition($0) })
XCTAssertEqualSequences(b[p..<partitionRange.upperBound], a[partitionRange].filter(condition))
for i in 0..<length {
for j in 0...i {
var b = a
let partitionRange = j..<i
let condition = { $0 < i - 1 }
let p = b.stablePartition(subrange: partitionRange, by: condition)
XCTAssertEqual(p, partitionRange.count == 0 ? j : j + 1)
XCTAssertEqualSequences(b[partitionRange.lowerBound..<p], a[partitionRange].filter { !condition($0) })
XCTAssertEqualSequences(b[p..<partitionRange.upperBound], a[partitionRange].filter(condition))
}
}
}
}
@@ -88,4 +91,102 @@ final class PartitionTests: XCTestCase {
}
}
}
func testPartitioningIndexWithEmptyInput() {
let input: [Int] = []
let a = input.partitioningIndex(where: { _ in return true })
XCTAssertEqual(a, input.startIndex)
let b = input.partitioningIndex(where: { _ in return false })
XCTAssertEqual(b, input.endIndex)
}
func testPartitioningIndexWithOneEmptyPartition() {
let input: Range<Int> = (0 ..< 10)
let a = input.partitioningIndex(where: { $0 > 10 })
XCTAssertEqual(a, input.endIndex)
let b = input.partitioningIndex(where: { $0 >= 0 })
XCTAssertEqual(b, input.startIndex)
}
func testPartitionWithSubrangeBidirectionalCollection() {
for length in 10...20 {
let a = Array(0..<length)
for i in 0..<length {
for j in 0...i {
var b = a
let partitionRange = j..<i
let condition = { $0 < i - 1 }
let p = b.partition(subrange: partitionRange, by: condition)
XCTAssertEqual(p, partitionRange.count == 0 ? j : j + 1)
XCTAssertEqualSequences(b[partitionRange.lowerBound..<p], a[partitionRange].filter { !condition($0) })
XCTAssertUnorderedEqualSequences(b[p..<partitionRange.upperBound], a[partitionRange].filter(condition))
}
}
}
}
func testPartitionWithSubrangeMutableCollection() {
for length in 10...20 {
let a = Array(0..<length)
for i in 0..<length {
for j in 0...i {
var b = a.eraseToAnyMutableCollection()
var bdc = a
let partitionRange = j..<i
let condition = { $0 < i - 1 }
let p = b.partition(subrange: partitionRange, by: condition)
let bdcp = bdc.partition(subrange: partitionRange, by: condition)
XCTAssertEqual(p, partitionRange.count == 0 ? j : j + 1)
XCTAssertEqualSequences(b[partitionRange.lowerBound..<p], a[partitionRange].filter { !condition($0) })
XCTAssertUnorderedEqualSequences(b[p..<partitionRange.upperBound], a[partitionRange].filter(condition))
// Must produce the same result as the `BidirectionalCollection` specialized overload.
XCTAssertEqualSequences(b[partitionRange.lowerBound..<p], bdc[partitionRange.lowerBound..<bdcp])
XCTAssertUnorderedEqualSequences(b[p..<partitionRange.upperBound], bdc[bdcp..<partitionRange.upperBound])
}
}
}
}
func testPartitionedWithEmptyInput() {
let input: [Int] = []
let s0 = input.partitioned(by: { _ in return true })
XCTAssertTrue(s0.0.isEmpty)
XCTAssertTrue(s0.1.isEmpty)
}
/// Test the example given in the `partitioned(by:)` documentation
func testPartitionedExample() throws {
let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let (longNames, shortNames) = cast.partitioned(by: { $0.count < 5 })
XCTAssertEqual(longNames, ["Vivien", "Marlon"])
XCTAssertEqual(shortNames, ["Kim", "Karl"])
}
func testPartitionedWithPredicate() throws {
let s0 = ["A", "B", "C", "D"].partitioned(by: { $0 == $0.lowercased() })
let s1 = ["a", "B", "C", "D"].partitioned(by: { $0 == $0.lowercased() })
let s2 = ["a", "B", "c", "D"].partitioned(by: { $0 == $0.lowercased() })
let s3 = ["a", "B", "c", "d"].partitioned(by: { $0 == $0.lowercased() })
XCTAssertEqual(s0.0, ["A", "B", "C", "D"])
XCTAssertEqual(s0.1, [])
XCTAssertEqual(s1.0, ["B", "C", "D"])
XCTAssertEqual(s1.1, ["a"])
XCTAssertEqual(s2.0, ["B", "D"])
XCTAssertEqual(s2.1, ["a", "c"])
XCTAssertEqual(s3.0, ["B"])
XCTAssertEqual(s3.1, ["a", "c", "d"])
}
}
@@ -26,27 +26,58 @@ final class PermutationsTests: XCTestCase {
XCTAssertTrue(p.allSatisfy { $0.count == count })
XCTAssertTrue(p.isSorted(by: { $0.lexicographicallyPrecedes($1) }))
}
func ts<R: RangeExpression>(count: R) where R.Bound == Int {
let p = count.relative(to: 0 ..< .max)
.clamped(to: 0 ..< c.count + 1)
.flatMap {
c.permutations(ofCount: $0)
}
let p2 = c.permutations(ofCount: count)
XCTAssertEqual(p.count, p2.count)
XCTAssertEqualSequences(p, Array(p2))
}
t(count: 0)
t(count: 1)
t(count: 2)
t(count: 3)
t(count: 4)
t(count: 5)
t(count: nil)
ts(count: 0...0)
ts(count: 1...1)
ts(count: 0...1)
ts(count: 0...2)
ts(count: 0...3)
ts(count: 1...3)
ts(count: 2...3)
ts(count: 0...)
ts(count: ...5)
ts(count: ...4)
ts(count: ...6)
}
func testEmpty() {
// `k == 0` results in one zero-length permutation
XCTAssertEqual(1, "".permutations().count)
XCTAssertEqual(1, "ABCD".permutations(ofCount: 0).count)
XCTAssertEqual(1, "ABCD".permutations(ofCount: 0...0).count)
XCTAssertEqual(Array("".permutations()), [[]])
XCTAssertEqual(Array("".permutations(ofCount: 0)), [[]])
XCTAssertEqual(Array("ABCD".permutations(ofCount: 0)), [[]])
XCTAssertEqual(Array("ABCD".permutations(ofCount: 0...0)), [[]])
// `k` greater than element count results in zero permutations
XCTAssertEqual(0, "".permutations(ofCount: 5).count)
XCTAssertEqual(Array("".permutations(ofCount: 5)), [])
XCTAssertEqual(Array("ABCD".permutations(ofCount: 5)), [])
XCTAssertEqual(Array("ABCD".permutations(ofCount: 5..<6)), [])
XCTAssertEqual(Array("ABCD".permutations(ofCount: 5..<7)), [])
XCTAssertEqual(Array("ABCD".permutations(ofCount: 5...)), [])
}
func testNextPermutation() {
@@ -64,13 +95,110 @@ final class PermutationsTests: XCTestCase {
XCTAssertEqual([1, 2, 3, 4, 7, 6, 5], numbers)
_ = numbers.nextPermutation()
XCTAssertEqual([1, 2, 3, 5, 4, 6, 7], numbers)
// Fast-forward to end of permutations.
while numbers.nextPermutation() {}
XCTAssertEqual([1, 2, 3, 4, 5, 6, 7], numbers)
}
func testPermutationsLazy() {
XCTAssertLazy("ABCD".lazy.permutations(ofCount: 2))
XCTAssertLazySequence("ABCD".lazy.permutations(ofCount: 2))
}
func testDocumentationExample1() {
// From Guides/Permutations.md
let numbers = [10, 20, 30]
let permutations = numbers.permutations()
XCTAssertEqualSequences(permutations, [
[10, 20, 30],
[10, 30, 20],
[20, 10, 30],
[20, 30, 10],
[30, 10, 20],
[30, 20, 10],
])
}
func testDocumentationExample2() {
// From Guides/Permutations.md
let numbers = [10, 20, 30]
let permutations = numbers.permutations(ofCount: 2)
XCTAssertEqualSequences(permutations, [
[10, 20],
[10, 30],
[20, 10],
[20, 30],
[30, 10],
[30, 20],
])
}
func testDocumentationExample3() {
// From Guides/Permutations.md
let numbers2 = [20, 10, 10]
let permutations = numbers2.permutations()
XCTAssertEqualSequences(permutations, [
[20, 10, 10],
[20, 10, 10],
[10, 20, 10],
[10, 10, 20],
[10, 20, 10],
[10, 10, 20],
])
}
func testDocumentationExample4() {
// From Guides/Permutations.md
let numbers = [10, 20, 30]
let permutations = numbers.permutations(ofCount: 0...)
XCTAssertEqualSequences(permutations, [
[],
[10],
[20],
[30],
[10, 20],
[10, 30],
[20, 10],
[20, 30],
[30, 10],
[30, 20],
[10, 20, 30],
[10, 30, 20],
[20, 10, 30],
[20, 30, 10],
[30, 10, 20],
[30, 20, 10],
])
}
func testDocumentationExample5() {
// From Permutations.swift
let names = ["Alex", "Celeste", "Davide"]
let permutations = names.permutations(ofCount: 2)
XCTAssertEqualSequences(permutations, [
["Alex", "Celeste"],
["Alex", "Davide"],
["Celeste", "Alex"],
["Celeste", "Davide"],
["Davide", "Alex"],
["Davide", "Celeste"],
])
}
func testDocumentationExample6() {
// From Permutations.swift
let names = ["Alex", "Celeste", "Davide"]
let permutations = names.permutations(ofCount: 1...2)
XCTAssertEqualSequences(permutations, [
["Alex"],
["Celeste"],
["Davide"],
["Alex", "Celeste"],
["Alex", "Davide"],
["Celeste", "Alex"],
["Celeste", "Davide"],
["Davide", "Alex"],
["Davide", "Celeste"],
])
}
}
@@ -39,17 +39,18 @@ final class ProductTests: XCTestCase {
}
func testProductIndexTraversals() {
validateIndexTraversals(
product([1, 2, 3, 4], "abc"),
product([1, 2, 3, 4], ""),
product([], "abc"),
product([], ""),
indices: { product in
let validator = IndexValidator<Product2Sequence<[Int], String>>(
indicesIncludingEnd: { product in
product.base1.indices.flatMap { i1 in
product.base2.indices.map { i2 in
.init(i1: i1, i2: i2)
}
} + [.init(i1: product.base1.endIndex, i2: product.base2.startIndex)]
})
validator.validate(product([1, 2, 3, 4], "abc"), expectedCount: 4 * 3)
validator.validate(product([1, 2, 3, 4], ""), expectedCount: 4 * 0)
validator.validate(product([], "abc"), expectedCount: 0 * 3)
validator.validate(product([], ""), expectedCount: 0 * 0)
}
}
@@ -10,7 +10,7 @@
//===----------------------------------------------------------------------===//
import XCTest
import Algorithms
@testable import Algorithms
func validateRandomSamples<S: Sequence>(
_ samples: [Int: Int],
@@ -95,4 +95,32 @@ final class RandomSampleTests: XCTestCase {
let sample2c = c.randomStableSample(count: k, using: &generator)
XCTAssertEqual(sample1c, sample2c)
}
func testRandomSampleRandomEdgeCasesInternal() {
struct ZeroGenerator: RandomNumberGenerator {
mutating func next() -> UInt64 { 0 }
}
var zero = ZeroGenerator()
_ = nextOffset(w: 1, using: &zero) // must not crash
struct AlmostAllZeroGenerator: RandomNumberGenerator {
private var forward: SplitMix64
private var count: Int = 0
init(seed: UInt64) {
forward = SplitMix64(seed: seed)
}
mutating func next() -> UInt64 {
defer { count &+= 1 }
if count % 1000 == 0 { return forward.next() }
return 0
}
}
var almostAllZero = AlmostAllZeroGenerator(seed: 0)
_ = s.randomSample(count: k, using: &almostAllZero) // must not crash
almostAllZero = AlmostAllZeroGenerator(seed: 0)
_ = c.randomSample(count: k, using: &almostAllZero) // must not crash
}
}
@@ -0,0 +1,94 @@
//===----------------------------------------------------------------------===//
//
// 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 ReductionsTests: XCTestCase {
struct TestError: Error {}
// MARK: - Exclusive Reductions
func testExclusiveLazy() {
XCTAssertEqualSequences((1...).prefix(4).lazy.reductions(0, +), [0, 1, 3, 6, 10])
XCTAssertEqualSequences((1...).prefix(1).lazy.reductions(0, +), [0, 1])
XCTAssertEqualSequences((1...).prefix(0).lazy.reductions(0, +), [0])
XCTAssertEqualCollections([1, 2, 3, 4].lazy.reductions(0, +), [0, 1, 3, 6, 10])
XCTAssertEqualCollections([1].lazy.reductions(0, +), [0, 1])
XCTAssertEqualCollections(EmptyCollection<Int>().lazy.reductions(0, +), [0])
XCTAssertEqual([1, 2, 3, 4].lazy.reductions(into: 0, +=), [0, 1, 3, 6, 10])
XCTAssertEqual([1].lazy.reductions(into: 0, +=), [0, 1])
XCTAssertEqual(EmptyCollection<Int>().lazy.reductions(into: 0, +=), [0])
XCTAssertLazySequence((1...).prefix(1).lazy.reductions(0, +))
XCTAssertLazySequence([1].lazy.reductions(0, +))
XCTAssertLazyCollection([1].lazy.reductions(0, +))
}
func testExclusiveEager() {
XCTAssertEqual([1, 2, 3, 4].reductions(0, +), [0, 1, 3, 6, 10])
XCTAssertEqual([1].reductions(0, +), [0, 1])
XCTAssertEqual(EmptyCollection<Int>().reductions(0, +), [0])
XCTAssertEqual([1, 2, 3, 4].reductions(into: 0, +=), [0, 1, 3, 6, 10])
XCTAssertEqual([1].reductions(into: 0, +=), [0, 1])
XCTAssertEqual(EmptyCollection<Int>().reductions(into: 0, +=), [0])
XCTAssertNoThrow(try [].reductions(0) { _, _ in throw TestError() })
XCTAssertThrowsError(try [1].reductions(0) { _, _ in throw TestError() })
}
func testExclusiveIndexTraversals() {
let validator = IndexValidator<ExclusiveReductionsSequence<Range<Int>, Int>>()
validator.validate((0..<0).lazy.reductions(0, +), expectedCount: 1)
validator.validate((0..<1).lazy.reductions(0, +), expectedCount: 2)
validator.validate((0..<4).lazy.reductions(0, +), expectedCount: 5)
}
// MARK: - Inclusive Reductions
func testInclusiveLazy() {
XCTAssertEqualSequences((1...).prefix(4).lazy.reductions(+), [1, 3, 6, 10])
XCTAssertEqualSequences((1...).prefix(1).lazy.reductions(+), [1])
XCTAssertEqualSequences((1...).prefix(0).lazy.reductions(+), [])
XCTAssertEqualCollections([1, 2, 3, 4].lazy.reductions(+), [1, 3, 6, 10])
XCTAssertEqualCollections([1].lazy.reductions(+), [1])
XCTAssertEqualCollections(EmptyCollection<Int>().lazy.reductions(+), [])
XCTAssertLazySequence((1...).prefix(1).lazy.reductions(+))
XCTAssertLazySequence([1].lazy.reductions(+))
XCTAssertLazyCollection([1].lazy.reductions(+))
}
func testInclusiveEager() {
XCTAssertEqual([1, 2, 3, 4].reductions(+), [1, 3, 6, 10])
XCTAssertEqual([1].reductions(+), [1])
XCTAssertEqual(EmptyCollection<Int>().reductions(+), [])
XCTAssertNoThrow(try [].reductions { _, _ in throw TestError() })
XCTAssertNoThrow(try [1].reductions { _, _ in throw TestError() })
XCTAssertThrowsError(try [1, 1].reductions { _, _ in throw TestError() })
}
func testInclusiveIndexTraversals() {
let validator = IndexValidator<InclusiveReductionsSequence<Range<Int>>>()
validator.validate((0..<0).lazy.reductions(+), expectedCount: 0)
validator.validate((0..<1).lazy.reductions(+), expectedCount: 1)
validator.validate((0..<4).lazy.reductions(+), expectedCount: 4)
}
}
+62 -1
View File
@@ -10,9 +10,70 @@
//===----------------------------------------------------------------------===//
import XCTest
import Algorithms
@testable import Algorithms
final class RotateTests: XCTestCase {
/// Tests the example given in `_reverse(subrange:until:)`’s documentation
func testUnderscoreReverse() {
var input = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p"]
let limit: Int = 4
let (lower, upper) = input._reverse(subrange: input.startIndex..<input.endIndex, until: input.startIndex.advanced(by: limit))
let expected = ["p", "o", "n", "m", "e", "f", "g", "h", "i", "j", "k", "l", "d", "c", "b", "a"]
XCTAssertEqual(input, expected)
XCTAssertEqual(lower, input.startIndex.advanced(by: limit))
XCTAssertEqual(upper, input.endIndex.advanced(by: -limit))
}
/// Tests the example given in `reverse(subrange:)`’s documentation
func testReverse() {
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
numbers.reverse(subrange: 0..<4)
XCTAssertEqual(numbers, [40, 30, 20, 10, 50, 60, 70, 80])
}
/// Tests `rotate(subrange:toStartAt:)` with an empty subrange
/// The order of elements are unchanged
func testRotateEmptySubrange() {
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let oldStart = numbers.rotate(subrange: 3..<3, toStartAt: 3)
XCTAssertEqual(numbers, [10, 20, 30, 40, 50, 60, 70, 80])
XCTAssertEqual(numbers[oldStart], 40)
}
/// Tests `rotate(subrange:toStartAt:)` with an empty collection
func testRotateSubrangeOnEmptyCollection() {
var numbers = [Int]()
let oldStart = numbers.rotate(subrange: 0..<0, toStartAt: 0)
XCTAssertEqual(numbers, [])
XCTAssertEqual(oldStart, numbers.startIndex)
}
/// Tests `rotate(subrange:toStartAt:)` with the full range of the collection
func testRotateFullRange() {
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let oldStart = numbers.rotate(subrange: 0..<8, toStartAt: 1)
XCTAssertEqual(numbers, [20, 30, 40, 50, 60, 70, 80, 10])
XCTAssertEqual(numbers[oldStart], 10)
}
/// Tests the example given in `rotate(subrange:toStartAt:)`’s documentation
func testRotateSubrange() {
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let oldStart = numbers.rotate(subrange: 0..<4, toStartAt: 2)
XCTAssertEqual(numbers, [30, 40, 10, 20, 50, 60, 70, 80])
XCTAssertEqual(numbers[oldStart], 10)
}
/// Tests the example given in `rotate(toStartAt:)`’s documentation
func testRotateExample() {
var numbers = [10, 20, 30, 40, 50, 60, 70, 80]
let oldStart = numbers.rotate(toStartAt: 3)
XCTAssertEqual(numbers, [40, 50, 60, 70, 80, 10, 20, 30])
XCTAssertEqual(numbers[oldStart], 10)
}
/// Tests `rotate(toStartAt:)` on collections of varying lengths, at different
/// starting points
func testRotate() {
for length in 0...15 {
let a = Array(0..<length)
@@ -1,91 +0,0 @@
//===----------------------------------------------------------------------===//
//
// 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 SlidingWindowsTests: XCTestCase {
func testWindowsOfString() {
let s = "swift"
let w = s.slidingWindows(ofCount: 2)
var i = w.startIndex
XCTAssertEqualSequences(w[i], "sw")
w.formIndex(after: &i)
XCTAssertEqualSequences(w[i], "wi")
w.formIndex(after: &i)
XCTAssertEqualSequences(w[i], "if")
w.formIndex(after: &i)
XCTAssertEqualSequences(w[i], "ft")
// w.index(after: w.endIndex) // ← Precondition failed: SlidingWindows index is out of range
// w.index(before: w.startIndex) // ← Precondition failed: SlidingWindows index is out of range
// w.formIndex(after: &i); w[i] // ← Precondition failed: SlidingWindows index is out of range
}
func testWindowsOfRange() {
let a = 0...100
XCTAssertTrue(a.slidingWindows(ofCount: 200).isEmpty)
let w = a.slidingWindows(ofCount: 10)
XCTAssertEqualSequences(w.first!, 0..<10)
XCTAssertEqualSequences(w.last!, 91..<101)
}
func testWindowsOfInt() {
let a = [ 0, 1, 0, 1 ].slidingWindows(ofCount: 2)
XCTAssertEqual(a.count, 3)
XCTAssertEqual(a.map { $0.reduce(0, +) }, [1, 1, 1])
let a2 = [0, 1, 2, 3, 4, 5, 6].slidingWindows(ofCount: 3).map {
$0.reduce(0, +)
}.reduce(0, +)
XCTAssertEqual(a2, 3 + 6 + 9 + 12 + 15)
}
func testWindowsCount() {
let a = [0, 1, 2, 3, 4, 5]
XCTAssertEqual(a.slidingWindows(ofCount: 3).count, 4)
let a2 = [0, 1, 2, 3, 4]
XCTAssertEqual(a2.slidingWindows(ofCount: 6).count, 0)
let a3 = [Int]()
XCTAssertEqual(a3.slidingWindows(ofCount: 2).count, 0)
}
func testWindowsSecondAndLast() {
let a = [0, 1, 2, 3, 4, 5]
let w = a.slidingWindows(ofCount: 4)
let snd = w[w.index(after: w.startIndex)]
XCTAssertEqualSequences(snd, [1, 2, 3, 4])
let w2 = a.slidingWindows(ofCount: 3)
XCTAssertEqualSequences(w2.last!, [3, 4, 5])
}
func testWindowsIndexAfterAndBefore() {
let a = [0, 1, 2, 3, 4, 5].slidingWindows(ofCount: 2)
var i = a.startIndex
a.formIndex(after: &i)
a.formIndex(after: &i)
a.formIndex(before: &i)
XCTAssertEqualSequences(a[i], [1, 2])
}
}
Loaded 100 of 108 files, more files were not shown because too many files have changed in this diff. Show more