1 | //! Futures |
2 | //! |
3 | //! This module contains a number of functions for working with `Future`s, |
4 | //! including the `FutureExt` trait which adds methods to `Future` types. |
5 | |
6 | #[cfg (feature = "compat" )] |
7 | use crate::compat::Compat; |
8 | use core::pin::Pin; |
9 | use futures_core::{ |
10 | future::TryFuture, |
11 | stream::TryStream, |
12 | task::{Context, Poll}, |
13 | }; |
14 | #[cfg (feature = "sink" )] |
15 | use futures_sink::Sink; |
16 | |
17 | use crate::fns::{ |
18 | inspect_err_fn, inspect_ok_fn, into_fn, map_err_fn, map_ok_fn, map_ok_or_else_fn, |
19 | unwrap_or_else_fn, InspectErrFn, InspectOkFn, IntoFn, MapErrFn, MapOkFn, MapOkOrElseFn, |
20 | UnwrapOrElseFn, |
21 | }; |
22 | use crate::future::{assert_future, Inspect, Map}; |
23 | use crate::stream::assert_stream; |
24 | |
25 | // Combinators |
26 | mod into_future; |
27 | mod try_flatten; |
28 | mod try_flatten_err; |
29 | |
30 | delegate_all!( |
31 | /// Future for the [`try_flatten`](TryFutureExt::try_flatten) method. |
32 | TryFlatten<Fut1, Fut2>( |
33 | try_flatten::TryFlatten<Fut1, Fut2> |
34 | ): Debug + Future + FusedFuture + New[|x: Fut1| try_flatten::TryFlatten::new(x)] |
35 | ); |
36 | |
37 | delegate_all!( |
38 | /// Future for the [`try_flatten_err`](TryFutureExt::try_flatten_err) method. |
39 | TryFlattenErr<Fut1, Fut2>( |
40 | try_flatten_err::TryFlattenErr<Fut1, Fut2> |
41 | ): Debug + Future + FusedFuture + New[|x: Fut1| try_flatten_err::TryFlattenErr::new(x)] |
42 | ); |
43 | |
44 | delegate_all!( |
45 | /// Future for the [`try_flatten_stream`](TryFutureExt::try_flatten_stream) method. |
46 | TryFlattenStream<Fut>( |
47 | try_flatten::TryFlatten<Fut, Fut::Ok> |
48 | ): Debug + Sink + Stream + FusedStream + New[|x: Fut| try_flatten::TryFlatten::new(x)] |
49 | where Fut: TryFuture |
50 | ); |
51 | |
52 | #[cfg (feature = "sink" )] |
53 | delegate_all!( |
54 | /// Sink for the [`flatten_sink`](TryFutureExt::flatten_sink) method. |
55 | #[cfg_attr(docsrs, doc(cfg(feature = "sink" )))] |
56 | FlattenSink<Fut, Si>( |
57 | try_flatten::TryFlatten<Fut, Si> |
58 | ): Debug + Sink + Stream + FusedStream + New[|x: Fut| try_flatten::TryFlatten::new(x)] |
59 | ); |
60 | |
61 | delegate_all!( |
62 | /// Future for the [`and_then`](TryFutureExt::and_then) method. |
63 | AndThen<Fut1, Fut2, F>( |
64 | TryFlatten<MapOk<Fut1, F>, Fut2> |
65 | ): Debug + Future + FusedFuture + New[|x: Fut1, f: F| TryFlatten::new(MapOk::new(x, f))] |
66 | ); |
67 | |
68 | delegate_all!( |
69 | /// Future for the [`or_else`](TryFutureExt::or_else) method. |
70 | OrElse<Fut1, Fut2, F>( |
71 | TryFlattenErr<MapErr<Fut1, F>, Fut2> |
72 | ): Debug + Future + FusedFuture + New[|x: Fut1, f: F| TryFlattenErr::new(MapErr::new(x, f))] |
73 | ); |
74 | |
75 | delegate_all!( |
76 | /// Future for the [`err_into`](TryFutureExt::err_into) method. |
77 | ErrInto<Fut, E>( |
78 | MapErr<Fut, IntoFn<E>> |
79 | ): Debug + Future + FusedFuture + New[|x: Fut| MapErr::new(x, into_fn())] |
80 | ); |
81 | |
82 | delegate_all!( |
83 | /// Future for the [`ok_into`](TryFutureExt::ok_into) method. |
84 | OkInto<Fut, E>( |
85 | MapOk<Fut, IntoFn<E>> |
86 | ): Debug + Future + FusedFuture + New[|x: Fut| MapOk::new(x, into_fn())] |
87 | ); |
88 | |
89 | delegate_all!( |
90 | /// Future for the [`inspect_ok`](super::TryFutureExt::inspect_ok) method. |
91 | InspectOk<Fut, F>( |
92 | Inspect<IntoFuture<Fut>, InspectOkFn<F>> |
93 | ): Debug + Future + FusedFuture + New[|x: Fut, f: F| Inspect::new(IntoFuture::new(x), inspect_ok_fn(f))] |
94 | ); |
95 | |
96 | delegate_all!( |
97 | /// Future for the [`inspect_err`](super::TryFutureExt::inspect_err) method. |
98 | InspectErr<Fut, F>( |
99 | Inspect<IntoFuture<Fut>, InspectErrFn<F>> |
100 | ): Debug + Future + FusedFuture + New[|x: Fut, f: F| Inspect::new(IntoFuture::new(x), inspect_err_fn(f))] |
101 | ); |
102 | |
103 | #[allow (unreachable_pub)] // https://github.com/rust-lang/rust/issues/57411 |
104 | pub use self::into_future::IntoFuture; |
105 | |
106 | delegate_all!( |
107 | /// Future for the [`map_ok`](TryFutureExt::map_ok) method. |
108 | MapOk<Fut, F>( |
109 | Map<IntoFuture<Fut>, MapOkFn<F>> |
110 | ): Debug + Future + FusedFuture + New[|x: Fut, f: F| Map::new(IntoFuture::new(x), map_ok_fn(f))] |
111 | ); |
112 | |
113 | delegate_all!( |
114 | /// Future for the [`map_err`](TryFutureExt::map_err) method. |
115 | MapErr<Fut, F>( |
116 | Map<IntoFuture<Fut>, MapErrFn<F>> |
117 | ): Debug + Future + FusedFuture + New[|x: Fut, f: F| Map::new(IntoFuture::new(x), map_err_fn(f))] |
118 | ); |
119 | |
120 | delegate_all!( |
121 | /// Future for the [`map_ok_or_else`](TryFutureExt::map_ok_or_else) method. |
122 | MapOkOrElse<Fut, F, G>( |
123 | Map<IntoFuture<Fut>, MapOkOrElseFn<F, G>> |
124 | ): Debug + Future + FusedFuture + New[|x: Fut, f: F, g: G| Map::new(IntoFuture::new(x), map_ok_or_else_fn(f, g))] |
125 | ); |
126 | |
127 | delegate_all!( |
128 | /// Future for the [`unwrap_or_else`](TryFutureExt::unwrap_or_else) method. |
129 | UnwrapOrElse<Fut, F>( |
130 | Map<IntoFuture<Fut>, UnwrapOrElseFn<F>> |
131 | ): Debug + Future + FusedFuture + New[|x: Fut, f: F| Map::new(IntoFuture::new(x), unwrap_or_else_fn(f))] |
132 | ); |
133 | |
134 | impl<Fut: ?Sized + TryFuture> TryFutureExt for Fut {} |
135 | |
136 | /// Adapters specific to [`Result`]-returning futures |
137 | pub trait TryFutureExt: TryFuture { |
138 | /// Flattens the execution of this future when the successful result of this |
139 | /// future is a [`Sink`]. |
140 | /// |
141 | /// This can be useful when sink initialization is deferred, and it is |
142 | /// convenient to work with that sink as if the sink was available at the |
143 | /// call site. |
144 | /// |
145 | /// Note that this function consumes this future and returns a wrapped |
146 | /// version of it. |
147 | /// |
148 | /// # Examples |
149 | /// |
150 | /// ``` |
151 | /// use futures::future::{Future, TryFutureExt}; |
152 | /// use futures::sink::Sink; |
153 | /// # use futures::channel::mpsc::{self, SendError}; |
154 | /// # type T = i32; |
155 | /// # type E = SendError; |
156 | /// |
157 | /// fn make_sink_async() -> impl Future<Output = Result< |
158 | /// impl Sink<T, Error = E>, |
159 | /// E, |
160 | /// >> { // ... } |
161 | /// # let (tx, _rx) = mpsc::unbounded::<i32>(); |
162 | /// # futures::future::ready(Ok(tx)) |
163 | /// # } |
164 | /// fn take_sink(sink: impl Sink<T, Error = E>) { /* ... */ } |
165 | /// |
166 | /// let fut = make_sink_async(); |
167 | /// take_sink(fut.flatten_sink()) |
168 | /// ``` |
169 | #[cfg (feature = "sink" )] |
170 | #[cfg_attr (docsrs, doc(cfg(feature = "sink" )))] |
171 | fn flatten_sink<Item>(self) -> FlattenSink<Self, Self::Ok> |
172 | where |
173 | Self::Ok: Sink<Item, Error = Self::Error>, |
174 | Self: Sized, |
175 | { |
176 | crate::sink::assert_sink::<Item, Self::Error, _>(FlattenSink::new(self)) |
177 | } |
178 | |
179 | /// Maps this future's success value to a different value. |
180 | /// |
181 | /// This method can be used to change the [`Ok`](TryFuture::Ok) type of the |
182 | /// future into a different type. It is similar to the [`Result::map`] |
183 | /// method. You can use this method to chain along a computation once the |
184 | /// future has been resolved. |
185 | /// |
186 | /// The provided closure `f` will only be called if this future is resolved |
187 | /// to an [`Ok`]. If it resolves to an [`Err`], panics, or is dropped, then |
188 | /// the provided closure will never be invoked. |
189 | /// |
190 | /// Note that this method consumes the future it is called on and returns a |
191 | /// wrapped version of it. |
192 | /// |
193 | /// # Examples |
194 | /// |
195 | /// ``` |
196 | /// use futures::future::TryFutureExt; |
197 | /// |
198 | /// # futures::executor::block_on(async { |
199 | /// let future = async { Ok::<i32, i32>(1) }; |
200 | /// let future = future.map_ok(|x| x + 3); |
201 | /// assert_eq!(future.await, Ok(4)); |
202 | /// # }); |
203 | /// ``` |
204 | /// |
205 | /// Calling [`map_ok`](TryFutureExt::map_ok) on an errored future has no |
206 | /// effect: |
207 | /// |
208 | /// ``` |
209 | /// use futures::future::TryFutureExt; |
210 | /// |
211 | /// # futures::executor::block_on(async { |
212 | /// let future = async { Err::<i32, i32>(1) }; |
213 | /// let future = future.map_ok(|x| x + 3); |
214 | /// assert_eq!(future.await, Err(1)); |
215 | /// # }); |
216 | /// ``` |
217 | fn map_ok<T, F>(self, f: F) -> MapOk<Self, F> |
218 | where |
219 | F: FnOnce(Self::Ok) -> T, |
220 | Self: Sized, |
221 | { |
222 | assert_future::<Result<T, Self::Error>, _>(MapOk::new(self, f)) |
223 | } |
224 | |
225 | /// Maps this future's success value to a different value, and permits for error handling resulting in the same type. |
226 | /// |
227 | /// This method can be used to coalesce your [`Ok`](TryFuture::Ok) type and [`Error`](TryFuture::Error) into another type, |
228 | /// where that type is the same for both outcomes. |
229 | /// |
230 | /// The provided closure `f` will only be called if this future is resolved |
231 | /// to an [`Ok`]. If it resolves to an [`Err`], panics, or is dropped, then |
232 | /// the provided closure will never be invoked. |
233 | /// |
234 | /// The provided closure `e` will only be called if this future is resolved |
235 | /// to an [`Err`]. If it resolves to an [`Ok`], panics, or is dropped, then |
236 | /// the provided closure will never be invoked. |
237 | /// |
238 | /// Note that this method consumes the future it is called on and returns a |
239 | /// wrapped version of it. |
240 | /// |
241 | /// # Examples |
242 | /// |
243 | /// ``` |
244 | /// use futures::future::TryFutureExt; |
245 | /// |
246 | /// # futures::executor::block_on(async { |
247 | /// let future = async { Ok::<i32, i32>(5) }; |
248 | /// let future = future.map_ok_or_else(|x| x * 2, |x| x + 3); |
249 | /// assert_eq!(future.await, 8); |
250 | /// |
251 | /// let future = async { Err::<i32, i32>(5) }; |
252 | /// let future = future.map_ok_or_else(|x| x * 2, |x| x + 3); |
253 | /// assert_eq!(future.await, 10); |
254 | /// # }); |
255 | /// ``` |
256 | /// |
257 | fn map_ok_or_else<T, E, F>(self, e: E, f: F) -> MapOkOrElse<Self, F, E> |
258 | where |
259 | F: FnOnce(Self::Ok) -> T, |
260 | E: FnOnce(Self::Error) -> T, |
261 | Self: Sized, |
262 | { |
263 | assert_future::<T, _>(MapOkOrElse::new(self, f, e)) |
264 | } |
265 | |
266 | /// Maps this future's error value to a different value. |
267 | /// |
268 | /// This method can be used to change the [`Error`](TryFuture::Error) type |
269 | /// of the future into a different type. It is similar to the |
270 | /// [`Result::map_err`] method. You can use this method for example to |
271 | /// ensure that futures have the same [`Error`](TryFuture::Error) type when |
272 | /// using [`select!`] or [`join!`]. |
273 | /// |
274 | /// The provided closure `f` will only be called if this future is resolved |
275 | /// to an [`Err`]. If it resolves to an [`Ok`], panics, or is dropped, then |
276 | /// the provided closure will never be invoked. |
277 | /// |
278 | /// Note that this method consumes the future it is called on and returns a |
279 | /// wrapped version of it. |
280 | /// |
281 | /// # Examples |
282 | /// |
283 | /// ``` |
284 | /// use futures::future::TryFutureExt; |
285 | /// |
286 | /// # futures::executor::block_on(async { |
287 | /// let future = async { Err::<i32, i32>(1) }; |
288 | /// let future = future.map_err(|x| x + 3); |
289 | /// assert_eq!(future.await, Err(4)); |
290 | /// # }); |
291 | /// ``` |
292 | /// |
293 | /// Calling [`map_err`](TryFutureExt::map_err) on a successful future has |
294 | /// no effect: |
295 | /// |
296 | /// ``` |
297 | /// use futures::future::TryFutureExt; |
298 | /// |
299 | /// # futures::executor::block_on(async { |
300 | /// let future = async { Ok::<i32, i32>(1) }; |
301 | /// let future = future.map_err(|x| x + 3); |
302 | /// assert_eq!(future.await, Ok(1)); |
303 | /// # }); |
304 | /// ``` |
305 | /// |
306 | /// [`join!`]: crate::join |
307 | /// [`select!`]: crate::select |
308 | fn map_err<E, F>(self, f: F) -> MapErr<Self, F> |
309 | where |
310 | F: FnOnce(Self::Error) -> E, |
311 | Self: Sized, |
312 | { |
313 | assert_future::<Result<Self::Ok, E>, _>(MapErr::new(self, f)) |
314 | } |
315 | |
316 | /// Maps this future's [`Error`](TryFuture::Error) to a new error type |
317 | /// using the [`Into`](std::convert::Into) trait. |
318 | /// |
319 | /// This method does for futures what the `?`-operator does for |
320 | /// [`Result`]: It lets the compiler infer the type of the resulting |
321 | /// error. Just as [`map_err`](TryFutureExt::map_err), this is useful for |
322 | /// example to ensure that futures have the same [`Error`](TryFuture::Error) |
323 | /// type when using [`select!`] or [`join!`]. |
324 | /// |
325 | /// Note that this method consumes the future it is called on and returns a |
326 | /// wrapped version of it. |
327 | /// |
328 | /// # Examples |
329 | /// |
330 | /// ``` |
331 | /// use futures::future::TryFutureExt; |
332 | /// |
333 | /// # futures::executor::block_on(async { |
334 | /// let future_err_u8 = async { Err::<(), u8>(1) }; |
335 | /// let future_err_i32 = future_err_u8.err_into::<i32>(); |
336 | /// # }); |
337 | /// ``` |
338 | /// |
339 | /// [`join!`]: crate::join |
340 | /// [`select!`]: crate::select |
341 | fn err_into<E>(self) -> ErrInto<Self, E> |
342 | where |
343 | Self: Sized, |
344 | Self::Error: Into<E>, |
345 | { |
346 | assert_future::<Result<Self::Ok, E>, _>(ErrInto::new(self)) |
347 | } |
348 | |
349 | /// Maps this future's [`Ok`](TryFuture::Ok) to a new type |
350 | /// using the [`Into`](std::convert::Into) trait. |
351 | fn ok_into<U>(self) -> OkInto<Self, U> |
352 | where |
353 | Self: Sized, |
354 | Self::Ok: Into<U>, |
355 | { |
356 | assert_future::<Result<U, Self::Error>, _>(OkInto::new(self)) |
357 | } |
358 | |
359 | /// Executes another future after this one resolves successfully. The |
360 | /// success value is passed to a closure to create this subsequent future. |
361 | /// |
362 | /// The provided closure `f` will only be called if this future is resolved |
363 | /// to an [`Ok`]. If this future resolves to an [`Err`], panics, or is |
364 | /// dropped, then the provided closure will never be invoked. The |
365 | /// [`Error`](TryFuture::Error) type of this future and the future |
366 | /// returned by `f` have to match. |
367 | /// |
368 | /// Note that this method consumes the future it is called on and returns a |
369 | /// wrapped version of it. |
370 | /// |
371 | /// # Examples |
372 | /// |
373 | /// ``` |
374 | /// use futures::future::TryFutureExt; |
375 | /// |
376 | /// # futures::executor::block_on(async { |
377 | /// let future = async { Ok::<i32, i32>(1) }; |
378 | /// let future = future.and_then(|x| async move { Ok::<i32, i32>(x + 3) }); |
379 | /// assert_eq!(future.await, Ok(4)); |
380 | /// # }); |
381 | /// ``` |
382 | /// |
383 | /// Calling [`and_then`](TryFutureExt::and_then) on an errored future has no |
384 | /// effect: |
385 | /// |
386 | /// ``` |
387 | /// use futures::future::TryFutureExt; |
388 | /// |
389 | /// # futures::executor::block_on(async { |
390 | /// let future = async { Err::<i32, i32>(1) }; |
391 | /// let future = future.and_then(|x| async move { Err::<i32, i32>(x + 3) }); |
392 | /// assert_eq!(future.await, Err(1)); |
393 | /// # }); |
394 | /// ``` |
395 | fn and_then<Fut, F>(self, f: F) -> AndThen<Self, Fut, F> |
396 | where |
397 | F: FnOnce(Self::Ok) -> Fut, |
398 | Fut: TryFuture<Error = Self::Error>, |
399 | Self: Sized, |
400 | { |
401 | assert_future::<Result<Fut::Ok, Fut::Error>, _>(AndThen::new(self, f)) |
402 | } |
403 | |
404 | /// Executes another future if this one resolves to an error. The |
405 | /// error value is passed to a closure to create this subsequent future. |
406 | /// |
407 | /// The provided closure `f` will only be called if this future is resolved |
408 | /// to an [`Err`]. If this future resolves to an [`Ok`], panics, or is |
409 | /// dropped, then the provided closure will never be invoked. The |
410 | /// [`Ok`](TryFuture::Ok) type of this future and the future returned by `f` |
411 | /// have to match. |
412 | /// |
413 | /// Note that this method consumes the future it is called on and returns a |
414 | /// wrapped version of it. |
415 | /// |
416 | /// # Examples |
417 | /// |
418 | /// ``` |
419 | /// use futures::future::TryFutureExt; |
420 | /// |
421 | /// # futures::executor::block_on(async { |
422 | /// let future = async { Err::<i32, i32>(1) }; |
423 | /// let future = future.or_else(|x| async move { Err::<i32, i32>(x + 3) }); |
424 | /// assert_eq!(future.await, Err(4)); |
425 | /// # }); |
426 | /// ``` |
427 | /// |
428 | /// Calling [`or_else`](TryFutureExt::or_else) on a successful future has |
429 | /// no effect: |
430 | /// |
431 | /// ``` |
432 | /// use futures::future::TryFutureExt; |
433 | /// |
434 | /// # futures::executor::block_on(async { |
435 | /// let future = async { Ok::<i32, i32>(1) }; |
436 | /// let future = future.or_else(|x| async move { Ok::<i32, i32>(x + 3) }); |
437 | /// assert_eq!(future.await, Ok(1)); |
438 | /// # }); |
439 | /// ``` |
440 | fn or_else<Fut, F>(self, f: F) -> OrElse<Self, Fut, F> |
441 | where |
442 | F: FnOnce(Self::Error) -> Fut, |
443 | Fut: TryFuture<Ok = Self::Ok>, |
444 | Self: Sized, |
445 | { |
446 | assert_future::<Result<Fut::Ok, Fut::Error>, _>(OrElse::new(self, f)) |
447 | } |
448 | |
449 | /// Do something with the success value of a future before passing it on. |
450 | /// |
451 | /// When using futures, you'll often chain several of them together. While |
452 | /// working on such code, you might want to check out what's happening at |
453 | /// various parts in the pipeline, without consuming the intermediate |
454 | /// value. To do that, insert a call to `inspect_ok`. |
455 | /// |
456 | /// # Examples |
457 | /// |
458 | /// ``` |
459 | /// # futures::executor::block_on(async { |
460 | /// use futures::future::TryFutureExt; |
461 | /// |
462 | /// let future = async { Ok::<_, ()>(1) }; |
463 | /// let new_future = future.inspect_ok(|&x| println!("about to resolve: {}" , x)); |
464 | /// assert_eq!(new_future.await, Ok(1)); |
465 | /// # }); |
466 | /// ``` |
467 | fn inspect_ok<F>(self, f: F) -> InspectOk<Self, F> |
468 | where |
469 | F: FnOnce(&Self::Ok), |
470 | Self: Sized, |
471 | { |
472 | assert_future::<Result<Self::Ok, Self::Error>, _>(InspectOk::new(self, f)) |
473 | } |
474 | |
475 | /// Do something with the error value of a future before passing it on. |
476 | /// |
477 | /// When using futures, you'll often chain several of them together. While |
478 | /// working on such code, you might want to check out what's happening at |
479 | /// various parts in the pipeline, without consuming the intermediate |
480 | /// value. To do that, insert a call to `inspect_err`. |
481 | /// |
482 | /// # Examples |
483 | /// |
484 | /// ``` |
485 | /// # futures::executor::block_on(async { |
486 | /// use futures::future::TryFutureExt; |
487 | /// |
488 | /// let future = async { Err::<(), _>(1) }; |
489 | /// let new_future = future.inspect_err(|&x| println!("about to error: {}" , x)); |
490 | /// assert_eq!(new_future.await, Err(1)); |
491 | /// # }); |
492 | /// ``` |
493 | fn inspect_err<F>(self, f: F) -> InspectErr<Self, F> |
494 | where |
495 | F: FnOnce(&Self::Error), |
496 | Self: Sized, |
497 | { |
498 | assert_future::<Result<Self::Ok, Self::Error>, _>(InspectErr::new(self, f)) |
499 | } |
500 | |
501 | /// Flatten the execution of this future when the successful result of this |
502 | /// future is another future. |
503 | /// |
504 | /// This is equivalent to `future.and_then(|x| x)`. |
505 | fn try_flatten(self) -> TryFlatten<Self, Self::Ok> |
506 | where |
507 | Self::Ok: TryFuture<Error = Self::Error>, |
508 | Self: Sized, |
509 | { |
510 | assert_future::<Result<<Self::Ok as TryFuture>::Ok, Self::Error>, _>(TryFlatten::new(self)) |
511 | } |
512 | |
513 | /// Flatten the execution of this future when the successful result of this |
514 | /// future is a stream. |
515 | /// |
516 | /// This can be useful when stream initialization is deferred, and it is |
517 | /// convenient to work with that stream as if stream was available at the |
518 | /// call site. |
519 | /// |
520 | /// Note that this function consumes this future and returns a wrapped |
521 | /// version of it. |
522 | /// |
523 | /// # Examples |
524 | /// |
525 | /// ``` |
526 | /// # futures::executor::block_on(async { |
527 | /// use futures::future::TryFutureExt; |
528 | /// use futures::stream::{self, TryStreamExt}; |
529 | /// |
530 | /// let stream_items = vec![17, 18, 19].into_iter().map(Ok); |
531 | /// let future_of_a_stream = async { Ok::<_, ()>(stream::iter(stream_items)) }; |
532 | /// |
533 | /// let stream = future_of_a_stream.try_flatten_stream(); |
534 | /// let list = stream.try_collect::<Vec<_>>().await; |
535 | /// assert_eq!(list, Ok(vec![17, 18, 19])); |
536 | /// # }); |
537 | /// ``` |
538 | fn try_flatten_stream(self) -> TryFlattenStream<Self> |
539 | where |
540 | Self::Ok: TryStream<Error = Self::Error>, |
541 | Self: Sized, |
542 | { |
543 | assert_stream::<Result<<Self::Ok as TryStream>::Ok, Self::Error>, _>(TryFlattenStream::new( |
544 | self, |
545 | )) |
546 | } |
547 | |
548 | /// Unwraps this future's output, producing a future with this future's |
549 | /// [`Ok`](TryFuture::Ok) type as its |
550 | /// [`Output`](std::future::Future::Output) type. |
551 | /// |
552 | /// If this future is resolved successfully, the returned future will |
553 | /// contain the original future's success value as output. Otherwise, the |
554 | /// closure `f` is called with the error value to produce an alternate |
555 | /// success value. |
556 | /// |
557 | /// This method is similar to the [`Result::unwrap_or_else`] method. |
558 | /// |
559 | /// # Examples |
560 | /// |
561 | /// ``` |
562 | /// use futures::future::TryFutureExt; |
563 | /// |
564 | /// # futures::executor::block_on(async { |
565 | /// let future = async { Err::<(), &str>("Boom!" ) }; |
566 | /// let future = future.unwrap_or_else(|_| ()); |
567 | /// assert_eq!(future.await, ()); |
568 | /// # }); |
569 | /// ``` |
570 | fn unwrap_or_else<F>(self, f: F) -> UnwrapOrElse<Self, F> |
571 | where |
572 | Self: Sized, |
573 | F: FnOnce(Self::Error) -> Self::Ok, |
574 | { |
575 | assert_future::<Self::Ok, _>(UnwrapOrElse::new(self, f)) |
576 | } |
577 | |
578 | /// Wraps a [`TryFuture`] into a future compatible with libraries using |
579 | /// futures 0.1 future definitions. Requires the `compat` feature to enable. |
580 | #[cfg (feature = "compat" )] |
581 | #[cfg_attr (docsrs, doc(cfg(feature = "compat" )))] |
582 | fn compat(self) -> Compat<Self> |
583 | where |
584 | Self: Sized + Unpin, |
585 | { |
586 | Compat::new(self) |
587 | } |
588 | |
589 | /// Wraps a [`TryFuture`] into a type that implements |
590 | /// [`Future`](std::future::Future). |
591 | /// |
592 | /// [`TryFuture`]s currently do not implement the |
593 | /// [`Future`](std::future::Future) trait due to limitations of the |
594 | /// compiler. |
595 | /// |
596 | /// # Examples |
597 | /// |
598 | /// ``` |
599 | /// use futures::future::{Future, TryFuture, TryFutureExt}; |
600 | /// |
601 | /// # type T = i32; |
602 | /// # type E = (); |
603 | /// fn make_try_future() -> impl TryFuture<Ok = T, Error = E> { // ... } |
604 | /// # async { Ok::<i32, ()>(1) } |
605 | /// # } |
606 | /// fn take_future(future: impl Future<Output = Result<T, E>>) { /* ... */ } |
607 | /// |
608 | /// take_future(make_try_future().into_future()); |
609 | /// ``` |
610 | fn into_future(self) -> IntoFuture<Self> |
611 | where |
612 | Self: Sized, |
613 | { |
614 | assert_future::<Result<Self::Ok, Self::Error>, _>(IntoFuture::new(self)) |
615 | } |
616 | |
617 | /// A convenience method for calling [`TryFuture::try_poll`] on [`Unpin`] |
618 | /// future types. |
619 | fn try_poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Result<Self::Ok, Self::Error>> |
620 | where |
621 | Self: Unpin, |
622 | { |
623 | Pin::new(self).try_poll(cx) |
624 | } |
625 | } |
626 | |