Merge pull request #1 from RougeWare/feature/MVP

MVP

Author: KyNorthstar

.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+/.build
+/Packages
+/*.xcodeproj
+xcuserdata/

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

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>IDEDidComputeMac32BitWarning</key>
+	<true/>
+</dict>
+</plist>

.swiftpm/xcode/package.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist

@@ -0,0 +1,28 @@
+// swift-tools-version:5.2
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "FunctionTools",
+    products: [
+        // Products define the executables and libraries produced by a package, and make them visible to other packages.
+        .library(
+            name: "FunctionTools",
+            targets: ["FunctionTools"]),
+    ],
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        // .package(url: /* package url */, from: "1.0.0"),
+    ],
+    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: "FunctionTools",
+            dependencies: []),
+        .testTarget(
+            name: "FunctionToolsTests",
+            dependencies: ["FunctionTools"]),
+    ]
+)

Package.swift

@@ -1,2 +1,92 @@
-# Swift-Function-Tools
-Some tools to make functions easier to use in Swift
+# Function Tools #
+
+Some basic tools for functional programming
+
+
+## `blackhole` ##
+
+Simply functions which take a value and do nothing with it. Useful for testing and mocks.
+For example:
+```swift
+stuff.forEach(blackhole)
+```
+
+
+## `null` ##
+
+Like `blackhole`, this simply functions which take a value and do nothing with it. Unlike `blackhole`, this will always be optimized away in production code. Useful for giving to functions which demand a callback, when you don't have anything to do after it calls back.
+For example:
+```swift
+myObject.someAsyncFunction(onComplete: null)
+```
+
+
+## `call` ##
+
+A utility function which simply calls the given function. This is useful for compressing higher-order functions.
+For example:
+```swift
+let someFunctions: [BlindCallback] = [
+    { print("Hello") },
+    { print("World!") },
+]
+
+someFunctions.forEach(call)
+```
+
+
+## `curry` ##
+
+Converts a non-currying function into a currying function.
+For example:
+```swift
+let add = curry(+)
+[1, 2, 3, 4].map(add(4)) // [5, 6, 7, 8]
+```
+
+
+## Function Types ##
+
+Some typealiases for common functions:
+
+
+
+### Callbacks ###
+
+* `BlindCallback` and `ThrowingBlindCallback`
+    * A function that you'd pass to another one as a callback, which doesn't need to know anything nor report anything 
+* `Callback` and `ThrowingCallback`
+    * A function that you'd pass to another one as a callback, which needs to know the result of the other one 
+
+
+### Transformer family of functions ###
+
+* `Transformer` and `ThrowingTransformer`
+    * A function which can transform one thing into another, like the kind you pass to a `map` function
+
+* `Filter` and `ThrowingFilter`
+    * A function which can filter a sequence of elements, like the kind you pass to a `filter` function
+
+
+### Generator family of functions ###
+
+* `Generator` and `ThrowingGenerator`
+    * A function which can generate one thing without any input, like in an `@autoclosure`
+
+
+### Reducer family of functions ###
+
+* `Reducer` and `ThrowingReducer`
+    * A function which can reduce a sequence of elements into one value, like the kind you pass to a `reduce` function
+
+* `AllocationReducer` and `ThrowingAllocationReducer`
+    * A function which can reduce a sequence of elements into one value by allocating new reductions, like the kind you  pass to a `reduce` function. Often slower than `Reducer`.
+
+
+### Combinator family ###
+
+* `Combinator` and `ThrowingCombinator`
+    * A function which can combine two values into one
+
+* `CurriedCombinator`
+    * A function which can combine two values into one, over the course of multiple separate function calls.

README.md

@@ -0,0 +1,97 @@
+//
+//  Blackholes.swift
+//  FunctionTools
+//
+//  Created by Ben Leggiero on 2020-04-02.
+//  Copyright © 2020 Ben Leggiero BS-1-PS.
+//
+
+
+
+/// This guarantees that even the most scrutinous of optimizers will never optimize-away these blackholes
+private var blackholeAcceptor: Any? {
+    didSet {
+        blackholeAcceptor = nil
+    }
+}
+
+
+/// A function which does nothing, but will never be optimized away. Useful for testing.
+///
+/// - SeeAlso: `null`
+@inline(never)
+public func blackhole() -> Void { }
+
+
+/// A function which takes one value and does nothing with it, but will never be optimized away. Useful for testing.
+///
+/// For example:
+/// ```swift
+/// stuff.forEach(blackhole)
+/// ```
+///
+/// ```
+/// struct MySwiftUIView_Previews: PreviewProvider {
+///     static var previews: some View {
+///         Group {
+///             MySwiftUIView(callback: blackhole)
+///         }
+///     }
+/// }
+/// ```
+///
+/// - Parameter a: Anything at all
+///
+/// - SeeAlso: `null`
+@inline(never)
+public func blackhole<A>(_ a: A) -> Void { blackholeAcceptor = a }
+
+
+/// A function which takes two values and does nothing with them, but will never be optimized away. Useful for testing.
+///
+/// - Parameters:
+///     - a: Anything at all
+///     - b: Anything at all
+///
+/// - SeeAlso: `null`
+@inline(never)
+public func blackhole<A, B>(_ a: A, _ b: B) -> Void { blackholeAcceptor = (a, b) }
+
+
+/// A function which takes three values and does nothing with them, but will never be optimized away. Useful for testing.
+///
+/// - Parameters:
+///     - a: Anything at all
+///     - b: Anything at all
+///     - c: Anything at all
+///
+/// - SeeAlso: `null`
+@inline(never)
+public func blackhole<A, B, C>(_ a: A, _ b: B, _ c: C) -> Void { blackholeAcceptor = (a, b, c) }
+
+
+/// A function which takes four values and does nothing with them, but will never be optimized away. Useful for testing.
+///
+/// - Parameters:
+///     - a: Anything at all
+///     - b: Anything at all
+///     - c: Anything at all
+///     - d: Anything at all
+///
+/// - SeeAlso: `null`
+@inline(never)
+public func blackhole<A, B, C, D>(_ a: A, _ b: B, _ c: C, _ d: D) -> Void { blackholeAcceptor = (a, b, c, d) }
+
+
+/// A function which takes five values and does nothing with them, but will never be optimized away. Useful for testing.
+///
+/// - Parameters:
+///     - a: Anything at all
+///     - b: Anything at all
+///     - c: Anything at all
+///     - d: Anything at all
+///     - e: Anything at all
+///
+/// - SeeAlso: `null`
+@inline(never)
+public func blackhole<A, B, C, D, E>(_ a: A, _ b: B, _ c: C, _ d: D, _ e: E) -> Void { blackholeAcceptor = (a, b, c, d, e) }

Sources/FunctionTools/Blackholes.swift

@@ -0,0 +1,50 @@
+//
+//  Call.swift
+//  FunctionTools
+//
+//  Created by Ben Leggiero on 2020-04-02.
+//  Copyright © 2020 Ben Leggiero BS-1-PS.
+//
+
+import Foundation
+
+
+
+/// A utility function which simply calls the given function. This is useful for compressing higher-order functions
+///
+/// For example:
+/// ```swift
+/// let someFunctions: [BlindCallback] = [
+///     { print("Hello") },
+///     { print("World!") },
+/// ]
+///
+/// someFunctions.forEach(call)
+/// ```
+///
+/// - Parameter callee: The function to call
+/// - Throws: Anything `callee` throws
+@inlinable
+public func call(_ callee: ThrowingBlindCallback) rethrows {
+    try callee()
+}
+
+
+
+/// A utility function which simply calls the given function. This is useful for compressing higher-order functions
+///
+/// For example:
+/// ```swift
+/// let someFunctions: [BlindCallback] = [
+///     { print("Hello") },
+///     { print("World!") },
+/// ]
+///
+/// someFunctions.forEach(call)
+/// ```
+///
+/// - Parameter callee: The function to call
+@inlinable
+public func call(_ callee: BlindCallback) {
+    callee()
+}

Sources/FunctionTools/Call.swift

@@ -0,0 +1,24 @@
+//
+//  Curry.swift
+//  FunctionTools
+//
+//  Created by Ben Leggiero on 2020-04-02.
+//  Copyright © 2020 Ben Leggiero BS-1-PS.
+//
+
+import Foundation
+
+
+
+/// Converts a non-currying function into a currying function
+///
+/// ```swift
+/// let add = curry(+)
+/// [1, 2, 3, 4].map(add(4)) // [5, 6, 7, 8]
+/// ```
+///
+/// - Parameter f: The function to convert
+/// - Returns: A currying form of the given function
+func curry<A, B, C>(_ f: @escaping Combinator<A, B, C>) -> Transformer<A, Transformer<B, C>> {
+    return { a in { b in f(a, b) } }
+}