Merge pull request #18 from RougeWare/feature/Mutation

Introduced mutation! 🎉

Author: KyNorthstar

.github/workflows/swift.yml

@@ -1,4 +1,4 @@
-name: Swift
+name: Tests
 
 on: [push]
 

.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata

@@ -1,4 +1,4 @@
-// swift-tools-version:5.1
+// swift-tools-version:5.2
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription
@@ -13,14 +13,14 @@ let package = Package(
     ],
     dependencies: [
         // Dependencies declare other packages that this package depends on.
-        // .package(url: /* package url */, from: "1.0.0"),
+        .package(name: "RangeTools", url: "https://github.com/RougeWare/Swift-Range-Tools.git", from: "1.2.1"),
     ],
     targets: [
         // Targets are the basic building blocks of a package. A target can define a module or a test suite.
         // Targets can depend on other targets in this package, and on products in packages which this package depends on.
         .target(
             name: "SafeCollectionAccess",
-            dependencies: []),
+            dependencies: ["RangeTools"]),
         .testTarget(
             name: "SafeCollectionAccessTests",
             dependencies: ["SafeCollectionAccess"]),

Package.resolved

@@ -1,20 +1,67 @@
+[![Tested on GitHub Actions](https://github.com/RougeWare/Swift-Safe-Collection-Access/actions/workflows/swift.yml/badge.svg)](https://github.com/RougeWare/Swift-Safe-Collection-Access/actions/workflows/swift.yml) [![](https://www.codefactor.io/repository/github/rougeware/swift-safe-collection-access/badge)](https://www.codefactor.io/repository/github/rougeware/swift-safe-collection-access)
+
+[![Swift 5](https://img.shields.io/badge/swift-5-brightgreen.svg?logo=swift&logoColor=white)](https://swift.org) [![swift package manager 5.2 is supported](https://img.shields.io/badge/swift%20package%20manager-5.2-brightgreen.svg)](https://swift.org/package-manager) [![Supports macOS, iOS, tvOS, watchOS, Linux, & Windows](https://img.shields.io/badge/macOS%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS%20%7C%20Linux%20%7C%20Windows-grey.svg)](./Package.swift) 
+[![](https://img.shields.io/github/release-date/rougeware/swift-safe-collection-access?label=latest%20release)](https://github.com/RougeWare/Swift-Safe-Collection-Access/releases/latest)
+
+
 # Swift Safe Collection Access #
 
-Ever wonder why Swift crashes if you access a collection the wrong way? Especially an array? Me too here's some extensions.
+Ever wonder why Swift crashes if you access a collection the wrong way? Especially an array? Me too here's some extensions. 🎉
 
 
 
-## Example ##
+## `collection[orNil:]` ##
+
+This subscript fails gracefully on invalid input by returning `nil` or refusing to mutate the collection. With valid input, it behaves precisely like Swift's builtin subscripts!
 
 ```swift
 
 import SafeCollectionAccess
 
 
 
-let first5Fibonacci = [1, 1, 2, 3, 5]
+var first5Fibonacci = [1, 1, 2, 3, 5]
+
+first5Fibonacci[orNil: 0]                       // Optional(1)
+first5Fibonacci[orNil: 3] == first5Fibonacci[3] // true
+first5Fibonacci[orNil: 999]                     // `nil`
+first5Fibonacci[orNil: -1]                      // `nil`
+
+first5Fibonacci[orNil: 2...4]  // Optional([2, 4])
+first5Fibonacci[orNil: -2...2] // `nil`
+first5Fibonacci[orNil: ..<42]  // `nil`
+
+
+first5Fibonacci[orNil: 1]   = 42  // [1, 42, 2, 3, 5]
+first5Fibonacci[orNil: 999] = -1  // [1, 42, 2, 3, 5]
+first5Fibonacci[orNil: -1]  = 777 // [1, 42, 2, 3, 5]
+
+first5Fibonacci[orNil: 0...2]  = [9, 5]    // [9, 5, 3, 5]
+first5Fibonacci[orNil: -2...2] = [42]      // [9, 5, 3, 5]
+first5Fibonacci[orNil: ..<42]  = [7, 7, 7] // [9, 5, 3, 5]
+```
+
+
+
+## `collection[clamping:]` ##
+
+This subscript fails gracefully on invalid input by returning or mutating the closest valid element (or, with empty collections, returning `nil` or refusing to mutate). With valid input, it behaves precisely like Swift's builtin subscripts!
+
+```swift
+
+import SafeCollectionAccess
+
+
+
+var first5Fibonacci = [1, 1, 2, 3, 5]
+
+first5Fibonacci[clamping: 0]                       // 1
+first5Fibonacci[clamping: 3] == first5Fibonacci[3] // true
+first5Fibonacci[clamping: 999]                     // 5
+first5Fibonacci[clamping: -1]                      // 1
+
 
-print(first5Fibonacci[orNil: 0]) // Optional(1)
-print(first5Fibonacci[orNil: 0] == first5Fibonacci[safe: 1]) // true
-print(first5Fibonacci[safe: 5]) // nil
+first5Fibonacci[clamping: 1]   = 42  // [1, 42, 2, 3, 5]
+first5Fibonacci[clamping: 999] = -1  // [1, 42, 2, 3, -1]
+first5Fibonacci[clamping: -1]  = 777 // [777, 42, 2, 3, -1]
 ```

Package.swift

@@ -12,61 +12,81 @@ import Foundation
 
 public extension RandomAccessCollection {
 
-    /// Safely access ranges in this collection.
-    /// If the range you pass extends outside this collection, `nil` is returned.
-    ///
-    /// - Complexity: O(1)
+    /// Determines whether this collection contains elements throughout the given range
     ///
-    /// - Parameter range: A range of valid lower and upper indices of characters in the string.
-    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range is not contained
-    ///            within `0` (inclusive) and `count` (exclusive).
-    @inlinable
-    subscript(orNil range: ClosedRange<Index>) -> SubSequence? {
-        return contains(index: range.lowerBound) && contains(index: range.upperBound)
-            ? self[range]
-            : nil
+    /// - Parameter range: The range of elements to test
+    /// - Returns: `true` iff this collection contains elements at all the indices covered by the `range`
+    func completelyContains<RangeType>(range: RangeType) -> Bool
+    where RangeType: SafeRangeExpression,
+          RangeType.Bound == Index
+    {
+        guard let range = range.relative(clampingIfContainedWithin: self) else {
+            return false
+        }
+        
+        return completelyContains(range: range)
     }
 
 
-    /// Safely access ranges in this collection.
-    /// If the range you pass extends outside this collection, `nil` is returned.
+    /// Determines whether this collection contains elements throughout the given range
     ///
-    /// - Complexity: O(1)
+    /// - Parameter range: The range of elements to test
+    /// - Returns: `true` iff this collection contains elements at all the indices covered by the `range`
+    func completelyContains(range: Range<Index>) -> Bool {
+        contains(index: range.lowerBound)
+            && contains(index: index(before: range.upperBound))
+    }
+    
+    
+    /// Determines whether this collection contains any elements at the given range, even if the range extends beyond this collection
     ///
-    /// - Parameter range: A range of valid lower and upper indices of characters in the string.
-    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range is not contained
-    ///            within `0` (inclusive) and `count` (inclusive).
-    @inlinable
-    subscript(orNil range: Range<Index>) -> SubSequence? {
-        guard !range.isEmpty else {
-            return self[range]
+    /// - Parameter range: The range of elements to test
+    /// - Returns: `true` iff this collection contains elements at any of the indices covered by the `range`
+    func rangeOverlapsThisCollection<RangeType>(_ range: RangeType) -> Bool
+    where RangeType: SafeRangeExpression,
+          RangeType.Bound == Index
+    {
+        guard let range = range.relative(clampingIfContainedWithin: self) else {
+            return false
         }
 
-        return contains(index: range.lowerBound) && contains(index: index(before: range.upperBound))
-            ? self[range]
-            : nil
+        return rangeOverlapsThisCollection(range)
     }
 
 
-    /// Safely access ranges in this collection.
-    /// If the range you pass extends outside this collection, `nil` is returned.
+    /// Determines whether this collection contains any elements at the given range, even if the range extends beyond this collection
     ///
-    /// - Complexity: O(1)
+    /// - Parameter range: The range of elements to test
+    /// - Returns: `true` iff this collection contains elements at any of the indices covered by the `range`
+    func rangeOverlapsThisCollection(_ range: Range<Index>) -> Bool {
+        contains(index: range.lowerBound)
+            || contains(index: index(before: range.upperBound))
+    }
+    
+    
+    /// Some sugar for clamping the given range within this collection. If the given range doesn't overlap this collection at all, `nil` is returned.
     ///
-    /// - Parameter range: A range of a valid lower index of characters in the string.
-    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range is not contained
-    ///            within `0` (inclusive) and `count` (exclusive).
-    @inlinable
-    subscript(orNil range: PartialRangeFrom<Index>) -> SubSequence? {
-        
-        guard range.lowerBound != endIndex else {
-            // `self[self.endIndex...]` is always valid, resulting in an empty subsequence
-            return self[range]
-        }
-        
-        return contains(index: range.lowerBound)
-            ? self[range.lowerBound...]
-            : nil
+    /// This sugar sweetens `SafeRangeExpression`'s `relative(clampingTo:)` method.
+    ///
+    /// - Parameter range: The range to clamp to this collection
+    /// - Returns: A range which is definitely within this collecion, or `nil` if it doesn't overlap this collection
+    @inline(__always)
+    func clamp<RangeType>(range: RangeType) -> Range<Index>?
+    where RangeType: SafeRangeExpression,
+          RangeType.Bound == Index
+    {
+        range.relative(clampingIfContainedWithin: self)
+    }
+    
+    
+    /// A generic implementation of the below `[orNil:]` subscripts
+    @inline(__always)
+    @usableFromInline
+    internal subscript<RangeType>(_orNil_getOnly range: RangeType) -> SubSequence?
+    where RangeType: SafeRangeExpression,
+          RangeType.Bound == Index
+    {
+       clamp(range: range).map { self[$0] }
     }
 
 
@@ -75,35 +95,44 @@ public extension RandomAccessCollection {
     ///
     /// - Complexity: O(1)
     ///
-    /// - Parameter range: A range of a valid upper index of characters in the string.
-    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range's bound is not
-    ///            within `0` (inclusive) and `count` (inclusive).
+    /// - Parameter range: A range of valid indices of characters in the collection.
+    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range is not contained
+    ///            within `0` (inclusive) and `count` (exclusive).
     @inlinable
-    subscript(orNil range: PartialRangeUpTo<Index>) -> SubSequence? {
-        
-        guard range.upperBound != startIndex else {
-            // `self[..<self.startIndex]` is always valid, resulting in an empty subsequence
-            return self[range]
-        }
-        
-        return contains(index: index(before: range.upperBound))
-            ? self[orNil: startIndex ..< range.upperBound]
-            : nil
+    subscript<RangeType>(orNil range: RangeType) -> SubSequence?
+    where RangeType: SafeRangeExpression,
+          RangeType.Bound == Index {
+        self[_orNil_getOnly: range]
     }
 
 
-    /// Safely access ranges in this collection.
-    /// If the range you pass extends outside this collection, `nil` is returned.
+    /// Safely access or mutate ranges in this collection.
+    /// If the range you pass extends outside this collection, `nil` is returned, or if you're trying to mutate this collection, nothing is done.
+    /// Setting the value to `nil` is interpreted as removing the range from this collection
     ///
     /// - Complexity: O(1)
     ///
-    /// - Parameter range: A range of a valid upper index of characters in the string.
-    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range's bound is not
+    /// - Parameter range: A range of valid indices of characters in the collection.
+    /// - Returns: The characters at the given index-range in this string, or `nil` if the given range is not contained
     ///            within `0` (inclusive) and `count` (exclusive).
     @inlinable
-    subscript(orNil range: PartialRangeThrough<Index>) -> SubSequence? {
-        return contains(index: range.upperBound)
-            ? self[orNil: startIndex ... range.upperBound]
-            : nil
+    subscript<RangeType>(orNil range: RangeType) -> SubSequence?
+    where RangeType: SafeRangeExpression,
+          RangeType.Bound == Index,
+          Self: MutableCollection,
+          Self: RangeReplaceableCollection
+    {
+        get { self[_orNil_getOnly: range] }
+        
+        set {
+            guard rangeOverlapsThisCollection(range) else { return }
+            
+            if let newValue = newValue {
+                self[range] = newValue
+            }
+            else {
+                self.removeSubrange(range)
+            }
+        }
     }
 }