Skip to content

Commit 0f81ef4

Browse files
authored
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.
1 parent de3efbc commit 0f81ef4

File tree

3 files changed

+63
-30
lines changed

3 files changed

+63
-30
lines changed

Guides/Chunked.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@ let nearlyEvenChunks = (0..<15).evenlyChunked(in: 4)
6363

6464
When "chunking" a collection, the entire collection is included in the result,
6565
unlike the `split` family of methods, where separators are dropped.
66-
Joining the result of a chunking method call recreates the original collection.
66+
Joining the result of a chunking method call results in a collection equivalent
67+
to the original.
6768

6869
```swift
6970
c.elementsEqual(c.chunked(...).joined())
@@ -90,7 +91,7 @@ extension Collection {
9091

9192
public func chunks(ofCount count: Int) -> ChunkedByCount<Self>
9293

93-
public func evenlyChunked(in count: Int) -> EvenChunks<Self>
94+
public func evenlyChunked(in count: Int) -> EvenlyChunkedCollection<Self>
9495
}
9596

9697
extension LazyCollectionProtocol {
@@ -106,7 +107,7 @@ extension LazyCollectionProtocol {
106107

107108
Each of the "chunked" collection types are bidirectional when the wrapped
108109
collection is bidirectional. `ChunksOfCountCollection` and
109-
`EvenChunksCollection` also conform to `RandomAccessCollection` and
110+
`EvenlyChunkedCollection` also conform to `RandomAccessCollection` and
110111
`LazySequenceProtocol` when their base collections conform.
111112

112113
### Complexity

Sources/Algorithms/Chunked.swift

Lines changed: 58 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@ extension ChunkedOnCollection: LazyCollectionProtocol {}
200200

201201
/// A collection wrapper that evenly breaks a collection into a given number of
202202
/// chunks.
203-
public struct EvenChunksCollection<Base: Collection> {
203+
public struct EvenlyChunkedCollection<Base: Collection> {
204204
/// The base collection.
205205
@usableFromInline
206206
internal let base: Base
@@ -230,7 +230,7 @@ public struct EvenChunksCollection<Base: Collection> {
230230
}
231231
}
232232

233-
extension EvenChunksCollection {
233+
extension EvenlyChunkedCollection {
234234
/// Returns the number of chunks with size `smallChunkSize + 1` at the start
235235
/// of this collection.
236236
@inlinable
@@ -277,7 +277,7 @@ extension EvenChunksCollection {
277277
}
278278
}
279279

280-
extension EvenChunksCollection: Collection {
280+
extension EvenlyChunkedCollection: Collection {
281281
public struct Index: Comparable {
282282
/// The range corresponding to the chunk at this position.
283283
@usableFromInline
@@ -381,9 +381,9 @@ extension EvenChunksCollection: Collection {
381381
}
382382
}
383383

384-
extension EvenChunksCollection.Index: Hashable where Base.Index: Hashable {}
384+
extension EvenlyChunkedCollection.Index: Hashable where Base.Index: Hashable {}
385385

386-
extension EvenChunksCollection: BidirectionalCollection
386+
extension EvenlyChunkedCollection: BidirectionalCollection
387387
where Base: BidirectionalCollection
388388
{
389389
@inlinable
@@ -393,13 +393,13 @@ extension EvenChunksCollection: BidirectionalCollection
393393
}
394394
}
395395

396-
extension EvenChunksCollection: RandomAccessCollection
396+
extension EvenlyChunkedCollection: RandomAccessCollection
397397
where Base: RandomAccessCollection {}
398398

399-
extension EvenChunksCollection: LazySequenceProtocol
399+
extension EvenlyChunkedCollection: LazySequenceProtocol
400400
where Base: LazySequenceProtocol {}
401401

402-
extension EvenChunksCollection: LazyCollectionProtocol
402+
extension EvenlyChunkedCollection: LazyCollectionProtocol
403403
where Base: LazyCollectionProtocol {}
404404

405405
//===----------------------------------------------------------------------===//
@@ -762,22 +762,37 @@ extension ChunksOfCountCollection {
762762
}
763763

764764
extension Collection {
765-
/// Returns a `ChunksOfCountCollection<Self>` view presenting the elements in
766-
/// chunks with count of the given count parameter.
765+
/// Returns a collection of subsequences of this collection, each with the
766+
/// specified length.
767767
///
768-
/// - Parameter count: The size of the chunks. If the `count` parameter is
769-
/// evenly divided by the count of the base `Collection` all the chunks will
770-
/// have the count equals to size. Otherwise, the last chunk will contain
771-
/// the remaining elements.
768+
/// If the number of elements in the collection is evenly divided by `count`,
769+
/// then every chunk will have a length equal to `count`. Otherwise, every
770+
/// chunk but the last will have a length equal to `count`, with the
771+
/// remaining elements in the last chunk.
772772
///
773-
/// let c = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
774-
/// print(c.chunks(ofCount: 5).map(Array.init))
775-
/// // [[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]]
773+
/// let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
774+
/// for chunk in numbers.chunks(ofCount: 5) {
775+
/// print(chunk)
776+
/// }
777+
/// // [1, 2, 3, 4, 5]
778+
/// // [6, 7, 8, 9, 10]
776779
///
777780
/// print(c.chunks(ofCount: 3).map(Array.init))
778-
/// // [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10]]
781+
/// for chunk in numbers.chunks(ofCount: 5) {
782+
/// print(chunk)
783+
/// }
784+
/// // [1, 2, 3]
785+
/// // [4, 5, 5]
786+
/// // [7, 8, 9]
787+
/// // [10]
779788
///
780-
/// - Complexity: O(*n*), because the start index is pre-computed.
789+
/// - Parameter count: The desired size of each chunk.
790+
/// - Returns: A collection of consescutive, non-overlapping subseqeunces of
791+
/// this collection, where each subsequence (except possibly the last) has
792+
/// the length `count`.
793+
///
794+
/// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`;
795+
/// otherwise, O(*k*), where *k* is equal to `count`.
781796
@inlinable
782797
public func chunks(ofCount count: Int) -> ChunksOfCountCollection<Self> {
783798
precondition(count > 0, "Cannot chunk with count <= 0!")
@@ -798,10 +813,9 @@ extension ChunksOfCountCollection: LazyCollectionProtocol
798813
//===----------------------------------------------------------------------===//
799814

800815
extension Collection {
801-
/// Returns a collection of `count` evenly divided subsequences of this
802-
/// collection.
816+
/// Returns a collection of evenly divided subsequences of this collection.
803817
///
804-
/// This method divides the collection into a given number of equally sized
818+
/// This method divides the collection into a given number of evenly sized
805819
/// chunks. If the length of the collection is not divisible by `count`, the
806820
/// chunks at the start will be longer than the chunks at the end, like in
807821
/// this example:
@@ -815,12 +829,30 @@ extension Collection {
815829
/// // "rl"
816830
/// // "d!"
817831
///
818-
/// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`,
819-
/// otherwise O(*n*), where *n* is the length of the collection.
832+
/// If the number passed as `count` is greater than the number of elements in
833+
/// the collection, the result will include one or more empty subsequences.
834+
///
835+
/// for chunk in "Hi!".evenlyChunked(in: 5) {
836+
/// print(chunk)
837+
/// }
838+
/// // "H"
839+
/// // "i"
840+
/// // "!"
841+
/// // ""
842+
/// // ""
843+
///
844+
/// - Parameter count: The number of chunks to evenly divide this collection
845+
/// into. If this collection is non-empty, `count` must be greater than
846+
/// zero; otherwise, `count` may be zero or greater.
847+
/// - Returns: A collection of `count` subsequences of this collection,
848+
/// divided as evenly as possible.
849+
///
850+
/// - Complexity: O(1) if the collection conforms to `RandomAccessCollection`;
851+
/// otherwise, O(*n*), where *n* is the length of the collection.
820852
@inlinable
821-
public func evenlyChunked(in count: Int) -> EvenChunksCollection<Self> {
853+
public func evenlyChunked(in count: Int) -> EvenlyChunkedCollection<Self> {
822854
precondition(count >= 0, "Can't divide into a negative number of chunks")
823855
precondition(count > 0 || isEmpty, "Can't divide a non-empty collection into 0 chunks")
824-
return EvenChunksCollection(base: self, numberOfChunks: count)
856+
return EvenlyChunkedCollection(base: self, numberOfChunks: count)
825857
}
826858
}

Tests/SwiftAlgorithmsTests/ChunkedTests.swift

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ final class ChunkedTests: XCTestCase {
190190
}
191191

192192
func testEvenChunksIndexTraversals() {
193-
let validator = IndexValidator<EvenChunksCollection<Range<Int>>>()
193+
let validator = IndexValidator<EvenlyChunkedCollection<Range<Int>>>()
194194

195195
[
196196
(0..<10).evenlyChunked(in: 1),

0 commit comments

Comments
 (0)