method

catchError

Source

/**
 * Handles errors emitted by this [Future].
 *
 * This is the asynchronous equivalent of a "catch" block.
 *
 * Returns a new [Future] that will be completed with either the result of
 * this future or the result of calling the `onError` callback.
 *
 * If this future completes with a value,
 * the returned future completes with the same value.
 *
 * If this future completes with an error,
 * then [test] is first called with the error value.
 *
 * If `test` returns false, the exception is not handled by this `catchError`,
 * and the returned future completes with the same error and stack trace
 * as this future.
 *
 * If `test` returns `true`,
 * [onError] is called with the error and possibly stack trace,
 * and the returned future is completed with the result of this call
 * in exactly the same way as for [then]'s `onError`.
 *
 * If `test` is omitted, it defaults to a function that always returns true.
 * The `test` function should not throw, but if it does, it is handled as
 * if the the `onError` function had thrown.
 *
 * Example:
 *
 *     foo
 *       .catchError(..., test: (e) => e is ArgumentError)
 *       .catchError(..., test: (e) => e is NoSuchMethodError)
 *       .then((v) { ... });
 *
 * This method is equivalent to:
 *
 *     Future catchError(onError(error),
 *                       {bool test(error)}) {
 *       this.then((v) => v,  // Forward the value.
 *                 // But handle errors, if the [test] succeeds.
 *                 onError: (e, stackTrace) {
 *                   if (test == null || test(e)) {
 *                     if (onError is ZoneBinaryCallback) {
 *                       return onError(e, stackTrace);
 *                     }
 *                     return onError(e);
 *                   }
 *                   throw e;
 *                 });
 *     }
 *
 */
Future catchError(Function onError,
                  {bool test(Object error)});