SE-0235: Add Result<Success, Failure: Error> to Standard Library

stdlib/public/core/CMakeLists.txt

@@ -116,6 +116,7 @@ set(SWIFTLIB_ESSENTIAL
   ReflectionMirror.swift
   Repeat.swift
   REPL.swift
+  Result.swift
   Reverse.swift
   Runtime.swift.gyb
   RuntimeFunctionCounters.swift

stdlib/public/core/GroupInfo.json

@@ -220,5 +220,8 @@
     "Comparable.swift",
     "Codable.swift",
     "MigrationSupport.swift"
+  ],
+  "Result": [
+    "Result.swift"
   ]
 }

stdlib/public/core/Result.swift

@@ -0,0 +1,142 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// A value that represents either a success or failure, capturing associated
+/// values in both cases.
+@_frozen
+public enum Result<Value, Error: Swift.Error> {
+  /// A success, storing a `Value`.
+  case value(Value)
+
+  /// A failure, storing an `Error`.
+  case error(Error)
+
+  /// Evaluates the given transform closure when this `Result` instance is
+  /// `.value`, passing the value as a parameter.
+  ///
+  /// Use the `map` method with a closure that returns a non-`Result` value.
+  ///
+  /// - Parameter transform: A closure that takes the successful value of the
+  ///   instance.
+  /// - Returns: A new `Result` instance with the result of the transform, if
+  ///   it was applied.
+  public func map<NewValue>(
+    _ transform: (Value) -> NewValue
+  ) -> Result<NewValue, Error> {
+    switch self {
+    case let .value(value):
+      return .value(transform(value))
+    case let .error(error):
+      return .error(error)
+    }
+  }
+
+  /// Evaluates the given transform closure when this `Result` instance is
+  /// `.error`, passing the error as a parameter.
+  ///
+  /// Use the `mapError` method with a closure that returns a non-`Result`
+  /// value.
+  ///
+  /// - Parameter transform: A closure that takes the failure value of the
+  ///   instance.
+  /// - Returns: A new `Result` instance with the result of the transform, if
+  ///   it was applied.
+  public func mapError<NewError>(
+    _ transform: (Error) -> NewError
+  ) -> Result<Value, NewError> {
+    switch self {
+    case let .value(value):
+      return .value(value)
+    case let .error(error):
+      return .error(transform(error))
+    }
+  }
+
+  /// Evaluates the given transform closure when this `Result` instance is
+  /// `.value`, passing the value as a parameter and flattening the result.
+  ///
+  /// - Parameter transform: A closure that takes the successful value of the
+  ///   instance.
+  /// - Returns: A new `Result` instance, either from the transform or from
+  ///   the previous error value.
+  public func flatMap<NewValue>(
+    _ transform: (Value) -> Result<NewValue, Error>
+  ) -> Result<NewValue, Error> {
+    switch self {
+    case let .value(value):
+      return transform(value)
+    case let .error(error):
+      return .error(error)
+    }
+  }
+
+  /// Evaluates the given transform closure when this `Result` instance is
+  /// `.error`, passing the error as a parameter and flattening the result.
+  ///
+  /// - Parameter transform: A closure that takes the error value of the
+  ///   instance.
+  /// - Returns: A new `Result` instance, either from the transform or from
+  ///   the previous success value.
+  public func flatMapError<NewError>(
+    _ transform: (Error) -> Result<Value, NewError>
+  ) -> Result<Value, NewError> {
+    switch self {
+    case let .value(value):
+      return .value(value)
+    case let .error(error):
+      return transform(error)
+    }
+  }
+
+  /// Unwraps the `Result` into a throwing expression.
+  ///
+  /// - Returns: The success value, if the instance is a success.
+  /// - Throws:  The error value, if the instance is a failure.
+  public func unwrapped() throws -> Value {
+    switch self {
+    case let .value(value):
+      return value
+    case let .error(error):
+      throw error
+    }
+  }
+}
+
+extension Result where Error == Swift.Error {
+  /// Create an instance by capturing the output of a throwing closure.
+  ///
+  /// - Parameter catching: A throwing closure to evaluate.
+  @_transparent
+  public init(catching body: () throws -> Value) {
+    do {
+      let value = try body()
+      self = .value(value)
+    } catch {
+      self = .error(error)
+    }
+  }
+}
+
+extension Result : Equatable where Value : Equatable, Error : Equatable { }
+
+extension Result : Hashable where Value : Hashable, Error : Hashable {
+  public func hash(into hasher: inout Hasher) {
+    switch self {
+    case let .value(value):
+      hasher.combine(value)
+      hasher.combine(Optional<Error>.none)
+    case let .error(error):
+      hasher.combine(Optional<Value>.none)
+      hasher.combine(error)
+    }
+  }
+}

test/stdlib/Result.swift

@@ -0,0 +1,178 @@
+// RUN: %target-run-simple-swift
+// REQUIRES: executable_test
+
+import StdlibUnittest
+import Swift
+
+let ResultTests = TestSuite("Result")
+
+fileprivate enum Err: Error, Equatable {
+  case err
+  case derr
+}
+
+fileprivate let string = "string"
+
+fileprivate extension Result {
+  var value: Value? {
+    switch self {
+    case let .value(value):
+      return value
+    case .error:
+      return nil
+    }
+
+    var error: Error? {
+      switch self {
+      case .value:
+        return nil
+      case let .error(error):
+        return error
+      }
+    }
+  }
+}
+
+ResultTests.test("Construction") {
+  let result1: Result<String, Err> = .value(string)
+  let result2: Result<String, Err> = .error(.err)
+  let string1: String? = {
+    switch result1 {
+      case let .value(string): 
+        return string
+      case .error: 
+        expectUnreachable()
+        return nil
+    }
+  }()
+  let error: Err? = {
+    switch result2 {
+      case let .error(error): 
+        return error
+      case .value: 
+        expectUnreachable()
+        return nil
+    }
+  }()
+
+  expectEqual(string1, string)
+  expectEqual(error, .err)
+}
+
+ResultTests.test("Throwing Initialization and Unwrapping") {
+  func notThrowing() throws -> String {
+    return string
+  }
+
+  func throwing() throws -> String {
+    throw Err.err
+  }
+
+  let result1 = Result { try throwing() }
+  let result2 = Result { try notThrowing() }
+
+  // Kept getting enum case 'error' cannot be used as an instance member, so get value manually.
+  switch result1 {
+  case let .error(error):
+    expectEqual(error as? Err, Err.err)
+  case .value:
+    expectUnreachable() 
+  }
+
+  expectEqual(result2.value, string)
+
+  do {
+    _ = try result1.unwrapped()
+  } catch let error as Err {
+    expectEqual(error, Err.err)
+  } catch {
+    expectUnreachable()
+  }
+
+  do {
+    let unwrapped = try result2.unwrapped()
+    expectEqual(unwrapped, string)
+  } catch {
+    expectUnreachable()
+  }
+
+  // Test unwrapping strongly typed error.
+  let result3 = Result<String, Err>.error(Err.err)
+  do {
+    _ = try result3.unwrapped()
+  } catch let error as Err {
+    expectEqual(error, Err.err)
+  } catch {
+    expectUnreachable()
+  }
+}
+
+ResultTests.test("Functional Transforms") {
+  func transformDouble(_ int: Int) -> Int {
+    return 2 * int
+  }
+
+  func transformTriple(_ int: Int) -> Int {
+    return 3 * int
+  }
+
+  func transformError(_ err: Err) -> Err {
+    if err == .err {
+      return .derr
+    } else {
+      return .err
+    }
+  }
+
+  func resultValueTransform(_ int: Int) -> Result<Int, Err> {
+    return .value(transformDouble(int))
+  }
+
+  func resultErrorTransform(_ err: Err) -> Result<Int, Err> {
+    return .error(transformError(err))
+  }
+
+  let result1: Result<Int, Err> = .value(1)
+  let newResult1 = result1.map(transformDouble)
+
+  expectEqual(newResult1, .value(2))
+
+  let result2: Result<Int, Err> = .error(.err)
+  let newResult2 = result2.mapError(transformError)
+
+  expectEqual(newResult2, .error(.derr))
+
+  let result3: Result<Int, Err> = .value(1)
+  let newResult3 = result3.flatMap(resultValueTransform)
+
+  expectEqual(newResult3, .value(2))
+
+  let result4: Result<Int, Err> = .error(.derr)
+  let newResult4 = result4.flatMapError(resultErrorTransform)
+
+  expectEqual(newResult4, .error(.err))
+}
+
+ResultTests.test("Equatable") {
+  let result1: Result<Int, Err> = .value(1)
+  let result2: Result<Int, Err> = .error(.err)
+
+  expectEqual(result1, .value(1))
+  expectNotEqual(result1, .value(2))
+  expectNotEqual(result1, .error(.err))
+  expectNotEqual(result1, .error(.derr))
+
+  expectNotEqual(result2, .value(1))
+  expectNotEqual(result2, .value(2))
+  expectEqual(result2, .error(.err))
+  expectNotEqual(result2, .error(.derr))
+}
+
+ResultTests.test("Hashable") {
+  let result1: Result<Int, Err> = .value(1)
+  let result2: Result<Int, Err> = .value(2)
+  let result3: Result<Int, Err> = .error(.err)
+  checkHashable([result1, result2, result3], equalityOracle: { $0 == $1 })
+}
+
+runAllTests()