@@ -377,6 +377,119 @@ pub fn once<T>(value: T) -> Once<T> {
377377 Once { inner : Some ( value) . into_iter ( ) }
378378}
379379
380+ /// An iterator that repeats elements of type `A` endlessly by
381+ /// applying the provided closure `F: FnMut() -> A`.
382+ ///
383+ /// This `struct` is created by the [`once_with`] function.
384+ /// See its documentation for more.
385+ ///
386+ /// [`once_with`]: fn.once_with.html
387+ #[ derive( Copy , Clone , Debug ) ]
388+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
389+ pub struct OnceWith < F > {
390+ gen : Option < F > ,
391+ }
392+
393+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
394+ impl < A , F : FnOnce ( ) -> A > Iterator for OnceWith < F > {
395+ type Item = A ;
396+
397+ #[ inline]
398+ fn next ( & mut self ) -> Option < A > {
399+ self . gen . take ( ) . map ( |f| f ( ) )
400+ }
401+
402+ #[ inline]
403+ fn size_hint ( & self ) -> ( usize , Option < usize > ) {
404+ self . gen . iter ( ) . size_hint ( )
405+ }
406+ }
407+
408+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
409+ impl < A , F : FnOnce ( ) -> A > DoubleEndedIterator for OnceWith < F > {
410+ fn next_back ( & mut self ) -> Option < A > {
411+ self . next ( )
412+ }
413+ }
414+
415+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
416+ impl < A , F : FnOnce ( ) -> A > ExactSizeIterator for OnceWith < F > {
417+ fn len ( & self ) -> usize {
418+ self . gen . iter ( ) . len ( )
419+ }
420+ }
421+
422+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
423+ impl < A , F : FnOnce ( ) -> A > FusedIterator for OnceWith < F > { }
424+
425+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
426+ unsafe impl < A , F : FnOnce ( ) -> A > TrustedLen for OnceWith < F > { }
427+
428+ /// Creates an iterator that lazily generates a value exactly once by invoking
429+ /// the provided closure.
430+ ///
431+ /// This is commonly used to adapt a single value generator into a [`chain`] of
432+ /// other kinds of iteration. Maybe you have an iterator that covers almost
433+ /// everything, but you need an extra special case. Maybe you have a function
434+ /// which works on iterators, but you only need to process one value.
435+ ///
436+ /// Unlike [`once`], this function will lazily generate the value on request.
437+ ///
438+ /// [`once`]: fn.once.html
439+ /// [`chain`]: trait.Iterator.html#method.chain
440+ ///
441+ /// # Examples
442+ ///
443+ /// Basic usage:
444+ ///
445+ /// ```
446+ /// #![feature(iter_once_with)]
447+ ///
448+ /// use std::iter;
449+ ///
450+ /// // one is the loneliest number
451+ /// let mut one = iter::once_with(|| 1);
452+ ///
453+ /// assert_eq!(Some(1), one.next());
454+ ///
455+ /// // just one, that's all we get
456+ /// assert_eq!(None, one.next());
457+ /// ```
458+ ///
459+ /// Chaining together with another iterator. Let's say that we want to iterate
460+ /// over each file of the `.foo` directory, but also a configuration file,
461+ /// `.foorc`:
462+ ///
463+ /// ```no_run
464+ /// #![feature(iter_once_with)]
465+ ///
466+ /// use std::iter;
467+ /// use std::fs;
468+ /// use std::path::PathBuf;
469+ ///
470+ /// let dirs = fs::read_dir(".foo").unwrap();
471+ ///
472+ /// // we need to convert from an iterator of DirEntry-s to an iterator of
473+ /// // PathBufs, so we use map
474+ /// let dirs = dirs.map(|file| file.unwrap().path());
475+ ///
476+ /// // now, our iterator just for our config file
477+ /// let config = iter::once_with(|| PathBuf::from(".foorc"));
478+ ///
479+ /// // chain the two iterators together into one big iterator
480+ /// let files = dirs.chain(config);
481+ ///
482+ /// // this will give us all of the files in .foo as well as .foorc
483+ /// for f in files {
484+ /// println!("{:?}", f);
485+ /// }
486+ /// ```
487+ #[ inline]
488+ #[ unstable( feature = "iter_once_with" , issue = "57581" ) ]
489+ pub fn once_with < A , F : FnOnce ( ) -> A > ( gen : F ) -> OnceWith < F > {
490+ OnceWith { gen : Some ( gen) }
491+ }
492+
380493/// Creates a new iterator where each iteration calls the provided closure
381494/// `F: FnMut(&mut St) -> Option<T>`.
382495///
0 commit comments