mirror of
https://github.com/apple/swift-algorithms
synced 2026-11-22 04:10:39 +00:00
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
This commit is contained in:
1 parent
0d6f943832
commit
4f53c9cf40
10 files changed
+129
-16
No files matched your search
@@ -0,0 +1,5 @@
|
||||
version: 1
|
||||
builder:
|
||||
configs:
|
||||
- documentation_targets: [Algorithms]
|
||||
|
||||
@@ -777,8 +777,8 @@ extension ChunksOfCountCollection {
|
||||
}
|
||||
|
||||
extension Collection {
|
||||
/// Returns a collection of subsequences of this collection, each with the
|
||||
/// specified length.
|
||||
/// 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
|
||||
@@ -792,8 +792,7 @@ extension Collection {
|
||||
/// // [1, 2, 3, 4, 5]
|
||||
/// // [6, 7, 8, 9, 10]
|
||||
///
|
||||
/// print(c.chunks(ofCount: 3).map(Array.init))
|
||||
/// for chunk in numbers.chunks(ofCount: 5) {
|
||||
/// for chunk in numbers.chunks(ofCount: 3) {
|
||||
/// print(chunk)
|
||||
/// }
|
||||
/// // [1, 2, 3]
|
||||
@@ -808,6 +807,7 @@ extension Collection {
|
||||
///
|
||||
/// - 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!")
|
||||
@@ -828,7 +828,8 @@ extension ChunksOfCountCollection: LazyCollectionProtocol
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension Collection {
|
||||
/// Returns a collection of evenly divided subsequences of this 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
|
||||
|
||||
@@ -5,8 +5,25 @@ along with their related types.
|
||||
|
||||
## Overview
|
||||
|
||||
This library adds a variety of extended operations to the Swift standard library's
|
||||
`Sequence` and `Collection` protocols, via extension methods and global functions.
|
||||
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
|
||||
|
||||
|
||||
@@ -4,6 +4,17 @@ Break collections into consecutive chunks by length, count, or based on closure-
|
||||
|
||||
## 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
|
||||
@@ -13,10 +24,12 @@ Break collections into consecutive chunks by length, count, or based on closure-
|
||||
|
||||
### Chunking a Collection by Predicate
|
||||
|
||||
- ``Swift/Collection/chunked(on:)``
|
||||
- ``Swift/Collection/chunked(by:)``
|
||||
- ``Swift/LazySequenceProtocol/chunked(by:)``
|
||||
- ``Swift/LazySequenceProtocol/chunked(by:)``
|
||||
|
||||
### Chunking a Collection by Subject
|
||||
|
||||
- ``Swift/Collection/chunked(on:)``
|
||||
- ``Swift/LazySequenceProtocol/chunked(on:)``
|
||||
|
||||
### Supporting Types
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# DeprecatedScan
|
||||
|
||||
These methods are deprecated, use the `reductions` family of methods instead.
|
||||
These methods are deprecated; use the `reductions` family of methods instead.
|
||||
|
||||
## Overview
|
||||
See: <doc:Reductions>
|
||||
|
||||
## Topics
|
||||
|
||||
|
||||
@@ -3,6 +3,27 @@
|
||||
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
|
||||
|
||||
@@ -4,17 +4,32 @@ Remove duplicated elements or strip the `nil` values from a sequence or collecti
|
||||
|
||||
## Overview
|
||||
|
||||
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
|
||||
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
|
||||
|
||||
### Uniqueing Elements
|
||||
### Uniquing Elements
|
||||
|
||||
- ``Swift/Sequence/uniqued()``
|
||||
- ``Swift/Sequence/uniqued(on:)``
|
||||
- ``Swift/LazySequenceProtocol/uniqued(on:)``
|
||||
|
||||
### Filtering out nil Elements
|
||||
### Filtering out `nil` Elements
|
||||
|
||||
- ``Swift/Collection/compacted()``
|
||||
- ``Swift/Sequence/compacted()``
|
||||
|
||||
@@ -4,6 +4,35 @@ 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
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
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(_:)``
|
||||
|
||||
@@ -15,8 +15,6 @@ Iterate over tuple pairs of adjacent elements, overlapping windows of a specifie
|
||||
|
||||
### Lazily Splitting a Collection
|
||||
|
||||
These methods…
|
||||
|
||||
- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-4q4x8``
|
||||
- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-68oqf``
|
||||
- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-a46s``
|
||||
|
||||
Reference in new issue
Block a user