# [−][src]Function std::iter::once_with

ⓘImportant traits for OnceWith<F>

### Important traits for OnceWith<F>

`impl<A, F> Iterator for OnceWith<F> where
F: FnOnce() -> A, type Item = A;`

    pub fn once_with<A, F>(gen: F) -> OnceWith<F> where
        F: FnOnce() -> A,

🔬 This is a nightly-only experimental API. (`iter_once_with` #57581)

Creates an iterator that lazily generates a value exactly once by invoking the provided closure.

This is commonly used to adapt a single value generator into a `chain` of other kinds of iteration. Maybe you have an iterator that covers almost everything, but you need an extra special case. Maybe you have a function which works on iterators, but you only need to process one value.

Unlike `once`, this function will lazily generate the value on request.

# Examples

Basic usage:

    #![feature(iter_once_with)]

    use std::iter;

    // one is the loneliest number
    let mut one = iter::once_with(|| 1);

    assert_eq!(Some(1), one.next());

    // just one, that's all we get
    assert_eq!(None, one.next());Run

Chaining together with another iterator. Let's say that we want to iterate over each file of the `.foo` directory, but also a configuration file, `.foorc`:

    #![feature(iter_once_with)]

    use std::iter;
    use std::fs;
    use std::path::PathBuf;

    let dirs = fs::read_dir(".foo").unwrap();

    // we need to convert from an iterator of DirEntry-s to an iterator of
    // PathBufs, so we use map
    let dirs = dirs.map(|file| file.unwrap().path());

    // now, our iterator just for our config file
    let config = iter::once_with(|| PathBuf::from(".foorc"));

    // chain the two iterators together into one big iterator
    let files = dirs.chain(config);

    // this will give us all of the files in .foo as well as .foorc
    for f in files {
        println!("{:?}", f);
    }Run

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)