OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.async; | 5 part of dart.async; |
6 | 6 |
7 /// A type representing values that are either `Future<T>` or `T`. | 7 /// A type representing values that are either `Future<T>` or `T`. |
8 /// | 8 /// |
9 /// This class declaration is a public stand-in for an internal | 9 /// This class declaration is a public stand-in for an internal |
10 /// future-or-value generic type. References to this class are resolved to the | 10 /// future-or-value generic type. References to this class are resolved to the |
(...skipping 482 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
493 * If the callback returns a [Future], | 493 * If the callback returns a [Future], |
494 * the future returned by `then` will be completed with | 494 * the future returned by `then` will be completed with |
495 * the same result as the future returned by the callback. | 495 * the same result as the future returned by the callback. |
496 * | 496 * |
497 * If [onError] is not given, and this future completes with an error, | 497 * If [onError] is not given, and this future completes with an error, |
498 * the error is forwarded directly to the returned future. | 498 * the error is forwarded directly to the returned future. |
499 * | 499 * |
500 * In most cases, it is more readable to use [catchError] separately, possibly | 500 * In most cases, it is more readable to use [catchError] separately, possibly |
501 * with a `test` parameter, instead of handling both value and error in a | 501 * with a `test` parameter, instead of handling both value and error in a |
502 * single [then] call. | 502 * single [then] call. |
| 503 * |
| 504 * Note that futures don't delay reporting of errors until listeners are |
| 505 * added. If the first `then` or `catchError` call happens after this future |
| 506 * has completed with an error then the error is reported as unhandled error. |
| 507 * See the description on [Future]. |
503 */ | 508 */ |
504 Future<S> then<S>(FutureOr<S> onValue(T value), {Function onError}); | 509 Future<S> then<S>(FutureOr<S> onValue(T value), {Function onError}); |
505 | 510 |
506 /** | 511 /** |
507 * Handles errors emitted by this [Future]. | 512 * Handles errors emitted by this [Future]. |
508 * | 513 * |
509 * This is the asynchronous equivalent of a "catch" block. | 514 * This is the asynchronous equivalent of a "catch" block. |
510 * | 515 * |
511 * Returns a new [Future] that will be completed with either the result of | 516 * Returns a new [Future] that will be completed with either the result of |
512 * this future or the result of calling the `onError` callback. | 517 * this future or the result of calling the `onError` callback. |
(...skipping 10 matching lines...) Expand all Loading... |
523 * | 528 * |
524 * If `test` returns `true`, | 529 * If `test` returns `true`, |
525 * [onError] is called with the error and possibly stack trace, | 530 * [onError] is called with the error and possibly stack trace, |
526 * and the returned future is completed with the result of this call | 531 * and the returned future is completed with the result of this call |
527 * in exactly the same way as for [then]'s `onError`. | 532 * in exactly the same way as for [then]'s `onError`. |
528 * | 533 * |
529 * If `test` is omitted, it defaults to a function that always returns true. | 534 * If `test` is omitted, it defaults to a function that always returns true. |
530 * The `test` function should not throw, but if it does, it is handled as | 535 * The `test` function should not throw, but if it does, it is handled as |
531 * if the `onError` function had thrown. | 536 * if the `onError` function had thrown. |
532 * | 537 * |
| 538 * Note that futures don't delay reporting of errors until listeners are |
| 539 * added. If the first `catchError` (or `then`) call happens after this future |
| 540 * has completed with an error then the error is reported as unhandled error. |
| 541 * See the description on [Future]. |
| 542 * |
533 * Example: | 543 * Example: |
534 * | 544 * |
535 * foo | 545 * foo |
536 * .catchError(..., test: (e) => e is ArgumentError) | 546 * .catchError(..., test: (e) => e is ArgumentError) |
537 * .catchError(..., test: (e) => e is NoSuchMethodError) | 547 * .catchError(..., test: (e) => e is NoSuchMethodError) |
538 * .then((v) { ... }); | 548 * .then((v) { ... }); |
539 * | 549 * |
540 * This method is equivalent to: | 550 * This method is equivalent to: |
541 * | 551 * |
542 * Future catchError(onError(error), | 552 * Future catchError(onError(error), |
(...skipping 276 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
819 AsyncError replacement = Zone.current.errorCallback(error, stackTrace); | 829 AsyncError replacement = Zone.current.errorCallback(error, stackTrace); |
820 if (replacement != null) { | 830 if (replacement != null) { |
821 error = _nonNullError(replacement.error); | 831 error = _nonNullError(replacement.error); |
822 stackTrace = replacement.stackTrace; | 832 stackTrace = replacement.stackTrace; |
823 } | 833 } |
824 result._completeError(error, stackTrace); | 834 result._completeError(error, stackTrace); |
825 } | 835 } |
826 | 836 |
827 /** Helper function that converts `null` to a [NullThrownError]. */ | 837 /** Helper function that converts `null` to a [NullThrownError]. */ |
828 Object _nonNullError(Object error) => error ?? new NullThrownError(); | 838 Object _nonNullError(Object error) => error ?? new NullThrownError(); |
OLD | NEW |