@@ -377,6 +377,119 @@ pub fn once<T>(value: T) -> Once<T> {
377
377
Once { inner : Some ( value) . into_iter ( ) }
378
378
}
379
379
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
+
380
493
/// Creates a new iterator where each iteration calls the provided closure
381
494
/// `F: FnMut(&mut St) -> Option<T>`.
382
495
///
0 commit comments