@@ -427,6 +427,62 @@ pub trait DoubleEndedIterator: Iterator {
427427#[ stable( feature = "rust1" , since = "1.0.0" ) ]
428428 fn next_back ( & mut self ) -> Option < Self :: Item > ;
429429
430+ /// Returns the `n`th element from the end of the iterator.
431+ ///
432+ /// This is essentially the reversed version of [`nth`]. Although like most indexing
433+ /// operations, the count starts from zero, so `nth_back(0)` returns the first value fro
434+ /// the end, `nth_back(1)` the second, and so on.
435+ ///
436+ /// Note that all elements between the end and the returned element will be
437+ /// consumed, including the returned element. This also means that calling
438+ /// `nth_back(0)` multiple times on the same iterator will return different
439+ /// elements.
440+ ///
441+ /// `nth_back()` will return [`None`] if `n` is greater than or equal to the length of the
442+ /// iterator.
443+ ///
444+ /// [`None`]: ../../std/option/enum.Option.html#variant.None
445+ /// [`nth`]: ../../std/iter/trait.Iterator.html#method.nth
446+ ///
447+ /// # Examples
448+ ///
449+ /// Basic usage:
450+ ///
451+ /// ```
452+ /// #![feature(iter_nth_back)]
453+ /// let a = [1, 2, 3];
454+ /// assert_eq!(a.iter().nth_back(2), Some(&1));
455+ /// ```
456+ ///
457+ /// Calling `nth_back()` multiple times doesn't rewind the iterator:
458+ ///
459+ /// ```
460+ /// #![feature(iter_nth_back)]
461+ /// let a = [1, 2, 3];
462+ ///
463+ /// let mut iter = a.iter();
464+ ///
465+ /// assert_eq!(iter.nth_back(1), Some(&2));
466+ /// assert_eq!(iter.nth_back(1), None);
467+ /// ```
468+ ///
469+ /// Returning `None` if there are less than `n + 1` elements:
470+ ///
471+ /// ```
472+ /// #![feature(iter_nth_back)]
473+ /// let a = [1, 2, 3];
474+ /// assert_eq!(a.iter().nth_back(10), None);
475+ /// ```
476+ #[ inline]
477+ #[ unstable( feature = "iter_nth_back" , issue = "56995" ) ]
478+ fn nth_back ( & mut self , mut n : usize ) -> Option < Self :: Item > {
479+ for x in self . rev ( ) {
480+ if n == 0 { return Some ( x) }
481+ n -= 1 ;
482+ }
483+ None
484+ }
485+
430486 /// This is the reverse version of [`try_fold()`]: it takes elements
431487/// starting from the back of the iterator.
432488///
@@ -461,8 +517,11 @@ pub trait DoubleEndedIterator: Iterator {
461517/// ```
462518#[ inline]
463519 #[ stable( feature = "iterator_try_fold" , since = "1.27.0" ) ]
464- fn try_rfold < B , F , R > ( & mut self , init : B , mut f : F ) -> R where
465- Self : Sized , F : FnMut ( B , Self :: Item ) -> R , R : Try < Ok =B >
520+ fn try_rfold < B , F , R > ( & mut self , init : B , mut f : F ) -> R
521+ where
522+ Self : Sized ,
523+ F : FnMut ( B , Self :: Item ) -> R ,
524+ R : Try < Ok =B >
466525 {
467526 let mut accum = init;
468527 while let Some ( x) = self . next_back ( ) {
@@ -524,8 +583,10 @@ pub trait DoubleEndedIterator: Iterator {
524583/// ```
525584#[ inline]
526585 #[ stable( feature = "iter_rfold" , since = "1.27.0" ) ]
527- fn rfold < B , F > ( mut self , accum : B , mut f : F ) -> B where
528- Self : Sized , F : FnMut ( B , Self :: Item ) -> B ,
586+ fn rfold < B , F > ( mut self , accum : B , mut f : F ) -> B
587+ where
588+ Self : Sized ,
589+ F : FnMut ( B , Self :: Item ) -> B ,
529590 {
530591 self . try_rfold ( accum, move |acc, x| Ok :: < B , !> ( f ( acc, x) ) ) . unwrap ( )
531592 }
@@ -574,7 +635,8 @@ pub trait DoubleEndedIterator: Iterator {
574635/// ```
575636#[ inline]
576637 #[ stable( feature = "iter_rfind" , since = "1.27.0" ) ]
577- fn rfind < P > ( & mut self , mut predicate : P ) -> Option < Self :: Item > where
638+ fn rfind < P > ( & mut self , mut predicate : P ) -> Option < Self :: Item >
639+ where
578640 Self : Sized ,
579641 P : FnMut ( & Self :: Item ) -> bool
580642 {
@@ -587,7 +649,12 @@ pub trait DoubleEndedIterator: Iterator {
587649
588650#[ stable( feature = "rust1" , since = "1.0.0" ) ]
589651impl < ' a , I : DoubleEndedIterator + ?Sized > DoubleEndedIterator for & ' a mut I {
590- fn next_back ( & mut self ) -> Option < I :: Item > { ( * * self ) . next_back ( ) }
652+ fn next_back ( & mut self ) -> Option < I :: Item > {
653+ ( * * self ) . next_back ( )
654+ }
655+ fn nth_back ( & mut self , n : usize ) -> Option < I :: Item > {
656+ ( * * self ) . nth_back ( n)
657+ }
591658}
592659
593660/// An iterator that knows its exact length.
0 commit comments