New free function mutate (#40)

* add mutate free function.

* Update FPUtils.swift

rename `module` to `root`

* fix `KeyPath`

* Update mutations for multiple values.

* add documentation and tests

* add `nilOutIfEmpty` property for `String` and `Optional<String>`.

---------

Co-authored-by: Oguz Yuksel <oguz.yueksel@teufel.de>

Author: OguzYuuksel

Sources/FoundationExtensions/Collection/String+Extensions.swift

@@ -18,3 +18,10 @@ extension String {
         }
     }
 }
+
+extension String {
+    /// - Returns: `nil` if `isEmpty` is `true`, else returns `String`.
+    public var nilOutIfEmpty: Self? {
+        isEmpty ? nil : self
+    }
+}

Sources/FoundationExtensions/Function/FPUtils.swift

@@ -58,3 +58,54 @@ public func setter<Root, Value>(_ keyPath: WritableKeyPath<Root, Value>) -> (ino
         root[keyPath: keyPath] = value
     }
 }
+
+/// `mutate(root:, with:)` is useful when you want to derive a value from an existing value instead of initializing from scratch.
+/// It is basically a shortened & nicer syntax of a closure.
+///
+///     // Closure version
+///     { root in
+///         var mutableRoot = root
+///         mutableRoot.value1 = ""
+///         mutableRoot.value2 = 0
+///         mutableRoot.value3 = false
+///         return mutableRoot
+///     }(root)
+///
+///     // `mutate(root:, with:)` version
+///     mutate(root: root) {
+///         mutableRoot.value1 = ""
+///         mutableRoot.value2 = 0
+///         mutableRoot.value3 = false
+///     }
+///
+/// - Parameters:
+///   - root: Root value for derivation.
+///   - mutation: Closure where the derivation is applied.
+/// - Returns: Derived version of root.
+public func mutate<Root>(root: Root, with mutation: @escaping (inout Root) -> ()) -> Root {
+    var root = root
+    mutation(&root)
+    return root
+}
+
+/// `mutate(root:, with:, for:)` is useful when you want to derive a value from an existing value instead of initializing from scratch.
+/// It is basically a shortened & nicer syntax of a closure.
+///
+///     // Closure version
+///     { root in
+///         var mutableRoot = root
+///         mutableRoot.value1 = "New!"
+///         return mutableRoot
+///     }(root)
+///
+///     // `mutate(root:, with:)` version
+///     mutate(root: root, with: "New!", for: \.value1)
+///
+/// - Parameters:
+///   - root: Root value for derivation.
+///   - value: Value to be changed in the root.
+///   - for: Keypath for the value in the root.
+/// - Returns: Derived version of root.
+public func mutate<Root, Value>(root: Root, with value: Value, for: WritableKeyPath<Root, Value>) -> Root {
+    mutate(root: root) { $0[keyPath: `for`] = value }
+}

Sources/FoundationExtensions/Optional/Optional+Extensions.swift

@@ -14,6 +14,13 @@ extension Optional where Wrapped: Collection {
     }
 }
 
+extension Optional where Wrapped == String {
+    /// - Returns: `nil` if `isEmpty` is `true` or value is `nil`, else returns `String`.
+    public var nilOutIfEmpty: Self {
+        flatMap { $0.nilOutIfEmpty }
+    }
+}
+
 extension Optional {
     typealias Generic<A> = A?
 

Tests/FoundationExtensionsTests/FunctionalExtensionsTests.swift

@@ -63,5 +63,49 @@ class FunctionalExtensionsTests: XCTestCase {
         // then
         XCTAssertEqual(expectedArrayCompacted, arrayCompacted)
     }
+
+    func testMutateForMultipleProperties() {
+        // given
+        struct MutableValue: Equatable {
+            var value1: String = ""
+            var value2: Int = 0
+            var value3: Date = .init(timeIntervalSince1970: 100)
+        }
+        let immutableValue: MutableValue = .init()
+        let expectedValue: MutableValue = .init(value1: "TestResult",
+                                                value2: 999,
+                                                value3: .init(timeIntervalSince1970: 9999))
+
+        // when
+        let mutatedVersionOfValue = mutate(root: immutableValue) {
+            $0.value1 = "TestResult"
+            $0.value2 = 999
+            $0.value3 = .init(timeIntervalSince1970: 9999)
+        }
+
+        // then
+        XCTAssertEqual(expectedValue, mutatedVersionOfValue)
+    }
+
+    func testMutateForOneProperty() {
+        // given
+        struct MutableValue: Equatable {
+            var value1: String = ""
+            var value2: Int = 0
+            var value3: Date = .init(timeIntervalSince1970: 100)
+        }
+        let immutableValue: MutableValue = .init()
+        let expectedValue: MutableValue = .init(value1: "",
+                                                value2: 15,
+                                                value3: .init(timeIntervalSince1970: 100))
+
+        // when
+        let mutatedVersionOfValue = mutate(root: immutableValue,
+                                           with: 15,
+                                           for: \.value2)
+
+        // then
+        XCTAssertEqual(expectedValue, mutatedVersionOfValue)
+    }
 }
 #endif

Tests/FoundationExtensionsTests/OptionalExtensionTests.swift

@@ -240,5 +240,41 @@ extension OptionalExtensionTests {
         // then
         XCTAssertEqual(expectedResult, sut)
     }
+
+    func testNilOutIfEmptyWhenStringIsEmptyReturnsNil() {
+        // given
+        let optional: String? = ""
+        let expectedResult: String? = nil
+
+        // when
+        let sut = optional?.nilOutIfEmpty
+
+        // then
+        XCTAssertEqual(expectedResult, sut)
+    }
+
+    func testNilOutIfEmptyWhenStringIsNotEmptyReturnsString() {
+        // given
+        let optional: String? = "abc"
+        let expectedResult: String? = "abc"
+
+        // when
+        let sut = optional?.nilOutIfEmpty
+
+        // then
+        XCTAssertEqual(expectedResult, sut)
+    }
+
+    func testNilOutIfEmptyWhenStringIsNilReturnsNil() {
+        // given
+        let optional: String? = nil
+        let expectedResult: String? = nil
+
+        // when
+        let sut = optional?.nilOutIfEmpty
+
+        // then
+        XCTAssertEqual(expectedResult, sut)
+    }
 }
 #endif

Tests/FoundationExtensionsTests/StringExtensionsTest.swift

@@ -16,5 +16,29 @@ class StringExtensionsTest: XCTestCase {
         XCTAssertEqual("a", "a".leftPadding(toLength: 1, withPad: "0")) // no padding
         XCTAssertEqual("acab", "acab".leftPadding(toLength: 3, withPad: "0")) // no truncation
     }
+
+    func testNilOutIfEmptyWhenStringIsEmptyReturnsNil() {
+        // given
+        let value: String = ""
+        let expectedResult: String? = nil
+
+        // when
+        let sut = value.nilOutIfEmpty
+
+        // then
+        XCTAssertEqual(expectedResult, sut)
+    }
+
+    func testNilOutIfEmptyWhenStringIsNotEmptyReturnsString() {
+        // given
+        let value: String = "abc"
+        let expectedResult: String? = "abc"
+
+        // when
+        let sut = value.nilOutIfEmpty
+
+        // then
+        XCTAssertEqual(expectedResult, sut)
+    }
 }
 #endif