iOS/Pods/Alamofire/Source/Result.swift

   1 //
   2 //  Result.swift
   3 //
   4 //  Copyright (c) 2014-2017 Alamofire Software Foundation (http://alamofire.org/)
   5 //
   6 //  Permission is hereby granted, free of charge, to any person obtaining a copy
   7 //  of this software and associated documentation files (the "Software"), to deal
   8 //  in the Software without restriction, including without limitation the rights
   9 //  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10 //  copies of the Software, and to permit persons to whom the Software is
  11 //  furnished to do so, subject to the following conditions:
  12 //
  13 //  The above copyright notice and this permission notice shall be included in
  14 //  all copies or substantial portions of the Software.
  15 //
  16 //  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17 //  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18 //  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19 //  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20 //  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21 //  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  22 //  THE SOFTWARE.
  23 //
  24
  25 import Foundation
  26
  27 /// Used to represent whether a request was successful or encountered an error.
  28 ///
  29 /// - success: The request and all post processing operations were successful resulting in the serialization of the
  30 ///            provided associated value.
  31 ///
  32 /// - failure: The request encountered an error resulting in a failure. The associated values are the original data
  33 ///            provided by the server as well as the error that caused the failure.
  34 public enum Result<Value> {
  35     case success(Value)
  36     case failure(Error)
  37
  38     /// Returns `true` if the result is a success, `false` otherwise.
  39     public var isSuccess: Bool {
  40         switch self {
  41         case .success:
  42             return true
  43         case .failure:
  44             return false
  45         }
  46     }
  47
  48     /// Returns `true` if the result is a failure, `false` otherwise.
  49     public var isFailure: Bool {
  50         return !isSuccess
  51     }
  52
  53     /// Returns the associated value if the result is a success, `nil` otherwise.
  54     public var value: Value? {
  55         switch self {
  56         case .success(let value):
  57             return value
  58         case .failure:
  59             return nil
  60         }
  61     }
  62
  63     /// Returns the associated error value if the result is a failure, `nil` otherwise.
  64     public var error: Error? {
  65         switch self {
  66         case .success:
  67             return nil
  68         case .failure(let error):
  69             return error
  70         }
  71     }
  72 }
  73
  74 // MARK: - CustomStringConvertible
  75
  76 extension Result: CustomStringConvertible {
  77     /// The textual representation used when written to an output stream, which includes whether the result was a
  78     /// success or failure.
  79     public var description: String {
  80         switch self {
  81         case .success:
  82             return "SUCCESS"
  83         case .failure:
  84             return "FAILURE"
  85         }
  86     }
  87 }
  88
  89 // MARK: - CustomDebugStringConvertible
  90
  91 extension Result: CustomDebugStringConvertible {
  92     /// The debug textual representation used when written to an output stream, which includes whether the result was a
  93     /// success or failure in addition to the value or error.
  94     public var debugDescription: String {
  95         switch self {
  96         case .success(let value):
  97             return "SUCCESS: \(value)"
  98         case .failure(let error):
  99             return "FAILURE: \(error)"
 100         }
 101     }
 102 }
 103
 104 // MARK: - Functional APIs
 105
 106 extension Result {
 107     /// Creates a `Result` instance from the result of a closure.
 108     ///
 109     /// A failure result is created when the closure throws, and a success result is created when the closure
 110     /// succeeds without throwing an error.
 111     ///
 112     ///     func someString() throws -> String { ... }
 113     ///
 114     ///     let result = Result(value: {
 115     ///         return try someString()
 116     ///     })
 117     ///
 118     ///     // The type of result is Result<String>
 119     ///
 120     /// The trailing closure syntax is also supported:
 121     ///
 122     ///     let result = Result { try someString() }
 123     ///
 124     /// - parameter value: The closure to execute and create the result for.
 125     public init(value: () throws -> Value) {
 126         do {
 127             self = try .success(value())
 128         } catch {
 129             self = .failure(error)
 130         }
 131     }
 132
 133     /// Returns the success value, or throws the failure error.
 134     ///
 135     ///     let possibleString: Result<String> = .success("success")
 136     ///     try print(possibleString.unwrap())
 137     ///     // Prints "success"
 138     ///
 139     ///     let noString: Result<String> = .failure(error)
 140     ///     try print(noString.unwrap())
 141     ///     // Throws error
 142     public func unwrap() throws -> Value {
 143         switch self {
 144         case .success(let value):
 145             return value
 146         case .failure(let error):
 147             throw error
 148         }
 149     }
 150
 151     /// Evaluates the specified closure when the `Result` is a success, passing the unwrapped value as a parameter.
 152     ///
 153     /// Use the `map` method with a closure that does not throw. For example:
 154     ///
 155     ///     let possibleData: Result<Data> = .success(Data())
 156     ///     let possibleInt = possibleData.map { $0.count }
 157     ///     try print(possibleInt.unwrap())
 158     ///     // Prints "0"
 159     ///
 160     ///     let noData: Result<Data> = .failure(error)
 161     ///     let noInt = noData.map { $0.count }
 162     ///     try print(noInt.unwrap())
 163     ///     // Throws error
 164     ///
 165     /// - parameter transform: A closure that takes the success value of the `Result` instance.
 166     ///
 167     /// - returns: A `Result` containing the result of the given closure. If this instance is a failure, returns the
 168     ///            same failure.
 169     public func map<T>(_ transform: (Value) -> T) -> Result<T> {
 170         switch self {
 171         case .success(let value):
 172             return .success(transform(value))
 173         case .failure(let error):
 174             return .failure(error)
 175         }
 176     }
 177
 178     /// Evaluates the specified closure when the `Result` is a success, passing the unwrapped value as a parameter.
 179     ///
 180     /// Use the `flatMap` method with a closure that may throw an error. For example:
 181     ///
 182     ///     let possibleData: Result<Data> = .success(Data(...))
 183     ///     let possibleObject = possibleData.flatMap {
 184     ///         try JSONSerialization.jsonObject(with: $0)
 185     ///     }
 186     ///
 187     /// - parameter transform: A closure that takes the success value of the instance.
 188     ///
 189     /// - returns: A `Result` containing the result of the given closure. If this instance is a failure, returns the
 190     ///            same failure.
 191     public func flatMap<T>(_ transform: (Value) throws -> T) -> Result<T> {
 192         switch self {
 193         case .success(let value):
 194             do {
 195                 return try .success(transform(value))
 196             } catch {
 197                 return .failure(error)
 198             }
 199         case .failure(let error):
 200             return .failure(error)
 201         }
 202     }
 203
 204     /// Evaluates the specified closure when the `Result` is a failure, passing the unwrapped error as a parameter.
 205     ///
 206     /// Use the `mapError` function with a closure that does not throw. For example:
 207     ///
 208     ///     let possibleData: Result<Data> = .failure(someError)
 209     ///     let withMyError: Result<Data> = possibleData.mapError { MyError.error($0) }
 210     ///
 211     /// - Parameter transform: A closure that takes the error of the instance.
 212     /// - Returns: A `Result` instance containing the result of the transform. If this instance is a success, returns
 213     ///            the same instance.
 214     public func mapError<T: Error>(_ transform: (Error) -> T) -> Result {
 215         switch self {
 216         case .failure(let error):
 217             return .failure(transform(error))
 218         case .success:
 219             return self
 220         }
 221     }
 222
 223     /// Evaluates the specified closure when the `Result` is a failure, passing the unwrapped error as a parameter.
 224     ///
 225     /// Use the `flatMapError` function with a closure that may throw an error. For example:
 226     ///
 227     ///     let possibleData: Result<Data> = .success(Data(...))
 228     ///     let possibleObject = possibleData.flatMapError {
 229     ///         try someFailableFunction(taking: $0)
 230     ///     }
 231     ///
 232     /// - Parameter transform: A throwing closure that takes the error of the instance.
 233     ///
 234     /// - Returns: A `Result` instance containing the result of the transform. If this instance is a success, returns
 235     ///            the same instance.
 236     public func flatMapError<T: Error>(_ transform: (Error) throws -> T) -> Result {
 237         switch self {
 238         case .failure(let error):
 239             do {
 240                 return try .failure(transform(error))
 241             } catch {
 242                 return .failure(error)
 243             }
 244         case .success:
 245             return self
 246         }
 247     }
 248
 249     /// Evaluates the specified closure when the `Result` is a success, passing the unwrapped value as a parameter.
 250     ///
 251     /// Use the `withValue` function to evaluate the passed closure without modifying the `Result` instance.
 252     ///
 253     /// - Parameter closure: A closure that takes the success value of this instance.
 254     /// - Returns: This `Result` instance, unmodified.
 255     @discardableResult
 256     public func withValue(_ closure: (Value) -> Void) -> Result {
 257         if case let .success(value) = self { closure(value) }
 258
 259         return self
 260     }
 261
 262     /// Evaluates the specified closure when the `Result` is a failure, passing the unwrapped error as a parameter.
 263     ///
 264     /// Use the `withError` function to evaluate the passed closure without modifying the `Result` instance.
 265     ///
 266     /// - Parameter closure: A closure that takes the success value of this instance.
 267     /// - Returns: This `Result` instance, unmodified.
 268     @discardableResult
 269     public func withError(_ closure: (Error) -> Void) -> Result {
 270         if case let .failure(error) = self { closure(error) }
 271
 272         return self
 273     }
 274
 275     /// Evaluates the specified closure when the `Result` is a success.
 276     ///
 277     /// Use the `ifSuccess` function to evaluate the passed closure without modifying the `Result` instance.
 278     ///
 279     /// - Parameter closure: A `Void` closure.
 280     /// - Returns: This `Result` instance, unmodified.
 281     @discardableResult
 282     public func ifSuccess(_ closure: () -> Void) -> Result {
 283         if isSuccess { closure() }
 284
 285         return self
 286     }
 287
 288     /// Evaluates the specified closure when the `Result` is a failure.
 289     ///
 290     /// Use the `ifFailure` function to evaluate the passed closure without modifying the `Result` instance.
 291     ///
 292     /// - Parameter closure: A `Void` closure.
 293     /// - Returns: This `Result` instance, unmodified.
 294     @discardableResult
 295     public func ifFailure(_ closure: () -> Void) -> Result {
 296         if isFailure { closure() }
 297
 298         return self
 299     }
 300 }