[gardening] Adding Guides to compacted()

Author: LucianoPAlmeida

Guides/Compacted.md

@@ -0,0 +1,39 @@
+# 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)]
+
+Convenience method that flatten the `nil`s out of a sequence or collection. 
+That behaves exactly one of the most common uses of `compactMap` which is `collection.lazy.compactMap { $0 }` 
+which is only remove `nil`s without transforming the elements.
+
+```swift
+let array: [Int?] = [10, nil, 30, nil, 2, 3, nil, 5]
+let withNoNils = array.compacted()
+// Array(withNoNils) == [10, 30, 2, 3, 5]
+
+```
+
+The most convenient part of `compacted()` is that we avoid the usage of a closure.
+
+## Detailed Design
+
+The `compacted()` methods has two overloads:
+
+```swift
+extension Sequence {
+  public func compacted<Unwrapped>() -> CompactedSequence<Self, Unwrapped> { ... }
+}
+
+extension Collection {
+  public func compacted<Unwrapped>() -> CompactedCollection<Self, Unwrapped> { ... }
+}
+```
+
+One is a more general `CompactedSequence` for any `Sequence` base. And the other a more specialized `CompactedCollection` 
+where base is a `Collection` and with conditional conformance to `BidirectionalCollection`, `RandomAccessCollection`, 
+`LazyCollectionProtocol`, `Equatable` and `Hashable` when base collection conforms to them.
+
+### Naming
+
+The naming method name `compacted()` matches the current method `compactMap` that one of the most common usages `compactMap { $0 }` is abstracted by it.  

README.md

@@ -45,6 +45,7 @@ Read more about the package, and the intent behind it, in the [announcement on s
 - [`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/LazySplit.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.
+- [`compacted()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Compacted.md): Flatten the `nil`s out of a sequence of collection.
 
 ## Adding Swift Algorithms as a Dependency
 

Sources/Algorithms/Compacted.swift

@@ -197,6 +197,7 @@ extension CompactedSequence: Equatable
 
 extension CompactedSequence: Hashable
   where Element: Hashable {
+
   @inlinable
   public func hash(into hasher: inout Hasher) {
     for element in self {