languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-10-14 17:56:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Expand docs for Stream.lastWhere and singleWhere

Browse source 
Closes #30071

Add a template in the `firstWhere` doc for the paragraph about `orElse`
handling. Expand the discussion around error handling in the `lastWhere`
and `singleWhere` docs without relying on reading the `firstWhere` doc
first.

R=lrn@google.com

Change-Id: I302381bb5f4f7daa392ee22bbf667db7d7259ef5
CoreLibraryReviewExempt: Doc changes only.
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/310761
Commit-Queue: Nate Bosch <nbosch@google.com>
Reviewed-by: Lasse Nielsen <lrn@google.com>
This commit is contained in:
Nate Bosch 2023-06-22 19:07:40 +00:00 committed by Commit Queue
parent 5940badbd3
commit a282120406
1 changed files with 26 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
sdk/lib/async/stream.dart
View file

@ -1661,10 +1661,12 @@ abstract mixin class Stream<T> {
/// Returns a future that is completed with the first element of this stream
/// for which [test] returns `true`.
///
/// {@template stream_where_or_else}
/// If no such element is found before this stream is done, and an
/// [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.
/// {@endtemplate}
///
/// If this stream emits an error before the first matching element,
/// the returned future is completed with that error, and processing stops.
@ -1718,13 +1720,18 @@ abstract mixin class Stream<T> {
/// Finds the last element in this stream matching [test].
///
/// If this stream emits an error, the returned future is completed with that
/// error, and processing stops.
/// Returns a future that is completed with the last element of this stream
/// for which [test] returns `true`.
///
/// Otherwise as [firstWhere], except that the last matching element is found
/// {@macro stream_where_or_else}
///
/// If this stream emits an error at any point, the returned future is
/// completed with that error, and the subscription is canceled.
///
/// A non-error result cannot be provided before this stream is done.
///
/// Similar too [firstWhere], except that the last matching element is found
/// instead of the first.
/// That means that a non-error result cannot be provided before this stream
/// is done.
///
/// Example:
/// ```dart
@ -1770,7 +1777,20 @@ abstract mixin class Stream<T> {
/// Finds the single element in this stream matching [test].
///
/// Like [lastWhere], except that it is an error if more than one
/// Returns a future that is completed with the single element of this stream
/// for which [test] returns `true`.
///
/// {@macro stream_where_or_else}
///
/// Only one element may match. If more than one matching element is found an
/// error is thrown, regardless of whether [orElse] was passed.
///
/// If this stream emits an error at any point, the returned future is
/// completed with that error, and the subscription is canceled.
///
/// A non-error result cannot be provided before this stream is done.
///
/// Similar to [lastWhere], except that it is an error if more than one
/// matching element occurs in this stream.
///
/// Example: