@@ -361,11 +361,12 @@ pub trait From<T>: Sized {
361
361
/// An attempted conversion that consumes `self`, which may or may not be
362
362
/// expensive.
363
363
///
364
- /// Library authors should not directly implement this trait, but should prefer
365
- /// implementing the [`TryFrom`] trait, which offers greater flexibility and
366
- /// provides an equivalent `TryInto` implementation for free, thanks to a
367
- /// blanket implementation in the standard library. For more information on this,
368
- /// see the documentation for [`Into`].
364
+ /// Library authors should usually not directly implement this trait,
365
+ /// but should prefer implementing the [`TryFrom`] trait, which offers
366
+ /// greater flexibility and provides an equivalent `TryInto`
367
+ /// implementation for free, thanks to a blanket implementation in the
368
+ /// standard library. For more information on this, see the
369
+ /// documentation for [`Into`].
369
370
///
370
371
/// # Implementing `TryInto`
371
372
///
@@ -396,15 +397,16 @@ pub trait TryInto<T>: Sized {
396
397
/// This might be handled by truncating the `i64` to an `i32` (essentially
397
398
/// giving the `i64`'s value modulo `i32::MAX`) or by simply returning
398
399
/// `i32::MAX`, or by some other method. The `From` trait is intended
399
- /// for lossless conversions, so the `TryFrom` trait informs the
400
+ /// for perfect conversions, so the `TryFrom` trait informs the
400
401
/// programmer when a type conversion could go bad and lets them
401
402
/// decide how to handle it.
402
403
///
403
404
/// # Generic Implementations
404
405
///
405
406
/// - `TryFrom<T> for U` implies [`TryInto<U>`]` for T`
406
407
/// - [`try_from`] is reflexive, which means that `TryFrom<T> for T`
407
- /// is implemented
408
+ /// is implemented and cannot fail -- the associated `Error` type for
409
+ /// calling `T::try_from()` on a value of type `T` is `!`.
408
410
///
409
411
/// # Examples
410
412
///
@@ -417,12 +419,18 @@ pub trait TryInto<T>: Sized {
417
419
/// let smaller_number = big_number as i32;
418
420
/// assert_eq!(smaller_number, -727379968);
419
421
///
422
+ /// // Returns an error because `big_number` is too big to
423
+ /// // fit in an `i32`.
420
424
/// let try_smaller_number = i32::try_from(big_number);
421
425
/// assert!(try_smaller_number.is_err());
422
426
///
427
+ /// // Returns `Ok(3)`.
423
428
/// let try_successful_smaller_number = i32::try_from(3);
424
429
/// assert!(try_successful_smaller_number.is_ok());
425
430
/// ```
431
+ ///
432
+ /// [`try_from`]: trait.TryFrom.html#tymethod.try_from
433
+ /// [`TryInto`]: trait.TryInto.html
426
434
#[ stable( feature = "try_from" , since = "1.34.0" ) ]
427
435
pub trait TryFrom < T > : Sized {
428
436
/// The type returned in the event of a conversion error.
0 commit comments