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