# firstWhere method

Future<T> firstWhere (bool test(T element), { T orElse() })

Finds the first element of this stream matching `test`.

Returns a future that is completed with the first element of this stream that `test` returns `true` for.

If no such element is found before this stream is done, and a `orElse` function is provided, the result of calling `orElse` becomes the value of the future. If `orElse` throws, the returned future is completed with that error.

If this stream emits an error before the first matching element, the returned future is completed with that error, and processing stops.

Stops listening to this stream after the first matching element or error has been received.

Internally the method cancels its subscription after the first element that matches the predicate. This means that single-subscription (non-broadcast) streams are closed and cannot be reused after a call to this method.

If an error occurs, or if this stream ends without finding a match and with no `orElse` function provided, the returned future is completed with an error.

## Implementation

    Future<T> firstWhere(bool test(T element), {T orElse()}) {
      _Future<T> future = new _Future();
      StreamSubscription subscription;
      subscription = this.listen(
          (T value) {
            _runUserCode(() => test(value), (bool isMatch) {
              if (isMatch) {
                _cancelAndValue(subscription, future, value);
              }
            }, _cancelAndErrorClosure(subscription, future));
          },
          onError: future._completeError,
          onDone: () {
            if (orElse != null) {
              _runUserCode(orElse, future._complete, future._completeError);
              return;
            }
            try {
              throw IterableElementError.noElement();
            } catch (e, s) {
              _completeWithErrorCallback(future, e, s);
            }
          },
          cancelOnError: true);
      return future;
    }