::next_gen

在稳定 Rust 上的安全生成器。

示例

重实现 range 迭代器

use ::next_gen::prelude::*;

#[generator(yield(u8))]
fn range (start: u8, end: u8)
{
    let mut current = start;
    while current < end {
        yield_!(current);
        current += 1;
    }
}

mk_gen!(let generator = range(3, 10));
assert_eq!(
    generator.collect::<Vec<_>>(),
    (3.. 10).collect::<Vec<_>>(),
);

使用埃拉托斯特尼筛法实现质数迭代器

use ::next_gen::prelude::*;

enum NeverSome {}

/// Generator over all the primes less or equal to `up_to`.
#[generator(yield(usize))]
fn primes_up_to (up_to: usize)
  -> Option<NeverSome>
{
    if up_to < 2 { return None; }
    let mut sieve = vec![true; up_to.checked_add(1).expect("Overflow")];
    let mut p: usize = 1;
    loop {
        p += 1 + sieve
                    .get(p + 1..)?
                    .iter()
                    .position(|&is_prime| is_prime)?
        ;
        yield_!(p);
        let p2 = if let Some(p2) = p.checked_mul(p) { p2 } else {
            continue
        };
        if p2 >= up_to { continue; }
        sieve[p2..]
            .iter_mut()
            .step_by(p)
            .for_each(|is_prime| *is_prime = false)
        ;
    }
}

mk_gen!(let primes = primes_up_to(10_000));
for prime in primes {
    assert!(
        (2_usize..)
            .take_while(|&n| n.saturating_mul(n) <= prime)
            .all(|n| prime % n != 0)
    );
}

定义具有自借用状态的迭代器

这无疑是生成器最有用的功能。

例如，考虑以下问题

fn iter_locked (elems: &'_ Mutex<Set<i32>>)
  -> impl '_ + Iterator<Item = i32>

没有生成器的痛苦尝试

无论你多么努力，如果没有使用 unsafe 或其他使用 unsafe 的自引用库/工具，你将无法使用这样的签名！

• 以下将失败

  fn iter_locked (mutexed_elems: &'_ Mutex<Set<i32>>)
    -> impl '_ + Iterator<Item = i32>
  {
      ::std::iter::from_fn({
          let locked_elems = mutexed_elems.lock().unwrap();
          let mut elems = locked_elems.iter().copied();
          move || {
              // let _ = locked_elems;
              elems.next()
          } // Error, borrowed `locked_elems` is not captured and is thus dropped!
      })
  }
  

  error[E0515]: cannot return value referencing local variable `locked_elems`
    --> src/lib.rs:122:5
     |
  11 | /     ::std::iter::from_fn({
  12 | |         let locked_elems = mutexed_elems.lock().unwrap();
  13 | |         let mut elems = locked_elems.iter().copied();
     | |                         ------------------- `locked_elems` is borrowed here
  14 | |         move || {
  ...  |
  17 | |         } // Error, borrowed `locked_elems` is not captured and is thus dropped!
  18 | |     })
     | |______^ returns a value referencing data owned by the current function
     |
     = help: use `.collect()` to allocate the iterator
  

• 以及这个

  fn iter_locked (mutexed_elems: &'_ Mutex<Set<i32>>)
    -> impl '_ + Iterator<Item = i32>
  {
      ::std::iter::from_fn({
          let locked_elems = mutexed_elems.lock().unwrap();
          let mut elems = locked_elems.iter().copied();
          move || {
              let _ = &locked_elems; // ensure `locked_elems` is captured (and thus moved)
              elems.next() // Error, can't use borrow of moved value!
          }
      })
  }
  

  error[E0515]: cannot return value referencing local variable `locked_elems`
    --> src/lib.rs:144:5
     |
  11 | /     ::std::iter::from_fn({
  12 | |         let locked_elems = mutexed_elems.lock().unwrap();
  13 | |         let mut elems = locked_elems.iter().copied();
     | |                         ------------------- `locked_elems` is borrowed here
  14 | |         move || {
  ...  |
  17 | |         }
  18 | |     })
     | |______^ returns a value referencing data owned by the current function
     |
     = help: use `.collect()` to allocate the iterator
  
  error[E0505]: cannot move out of `locked_elems` because it is borrowed
    --> src/lib.rs:147:9
     |
  8  |   fn iter_locked (mutexed_elems: &'_ Mutex<Set<i32>>)
     |                                  - let's call the lifetime of this reference `'1`
  ...
  11 | /     ::std::iter::from_fn({
  12 | |         let locked_elems = mutexed_elems.lock().unwrap();
  13 | |         let mut elems = locked_elems.iter().copied();
     | |                         ------------------- borrow of `locked_elems` occurs here
  14 | |         move || {
     | |         ^^^^^^^ move out of `locked_elems` occurs here
  15 | |             let _ = &locked_elems; // ensure `locked_elems` is captured (and thus moved)
     | |                      ------------ move occurs due to use in closure
  16 | |             elems.next() // Error, can't use borrow of moved value!
  17 | |         }
  18 | |     })
     | |______- returning this value requires that `locked_elems` is borrowed for `'1`
  
  error: aborting due to 2 previous errors
  

• 在其他情况下，可能存在低效的解决方案

  例如，如果那个 Set 是一个 Vec，在这种情况下，我们可以使用索引作为穷人的自引用，没有“官方”的生命周期，因此 Rust 不会抱怨

  fn iter_locked (mutexed_vec: &'_ Mutex<Vec<i32>>)
    -> impl '_ + Iterator<Item = i32>
  {
      ::std::iter::from_fn({
          let locked_vec = mutexed_vec.lock().unwrap();
          let mut indices = 0.. locked_vec.len();
          move /* locked_vec, indices */ || {
              let i = indices.next()?;
              Some(locked_vec[i]) // copies, so OK.
          }
      })
  }
  let mutexed_elems = Mutex::new(vec![27, 42]);
  let mut iter = iter_locked(&mutexed_elems);
  assert_eq!(iter.next(), Some(27));
  assert_eq!(iter.next(), Some(42));
  assert_eq!(iter.next(), None);
  

但使用生成器就简单多了

use ::next_gen::prelude::*;

#[generator(yield(i32))]
fn gen_iter_locked (mutexed_elems: &'_ Mutex<Set<i32>>)
{
    let locked_elems = mutexed_elems.lock().unwrap();
    for elem in locked_elems.iter().copied() {
        yield_!(elem);
    }
}

use ::next_gen::prelude::*;

/// We already have:
#[generator(yield(i32))]
fn gen_iter_locked (mutexed_elems: &'_ Mutex<Set<i32>>)
...

/// Now let's wrap-it so that it yields a nice iterator:
fn iter_locked (mutexed_elems: &'_ Mutex<Set<i32>>)
  -> impl '_ + Iterator<Item = i32>
{
    if true {
        // One possible syntax to instantiate the generator
        mk_gen!(let generator = box gen_iter_locked(mutexed_elems));
        generator
    } else {
        // or, since we are `box`-ing, we can directly do:
        gen_iter_locked.call_boxed((mutexed_elems, ))
    }
    // : Pin<Box<impl '_ + Generator<Yield = i32>>>
    // : impl '_ + Iterator<Item = i32>
}

let mutexed_elems = Mutex::new([27, 42].iter().copied().collect::<Set<_>>());
let mut iter = iter_locked(&mutexed_elems);
assert_eq!(iter.next(), Some(27));
assert_eq!(iter.next(), Some(42));
assert_eq!(iter.next(), None);

let _: GeneratorState<Yield, Return> = generator.as_mut().resume(resume_arg);

let _: ResumeArg = yield_!(value);

use ::next_gen::prelude::*;

type ShouldContinue = bool;

#[generator(yield(i32), resume(ShouldContinue))]
fn g ()
{
    for i in 0.. {
        let should_continue = yield_!(i);
        if should_continue.not() {
            break;
        }
    }
}

mk_gen!(let mut generator = g());
assert!(matches!(
    generator.as_mut().resume(bool::default()), // <- this resume arg is being ignored
    GeneratorState::Yielded(0),
));
assert!(matches!(
    generator.as_mut().resume(true),
    GeneratorState::Yielded(1),
));
assert!(matches!(
    generator.as_mut().resume(true),
    GeneratorState::Yielded(2),
));
assert!(matches!(
    generator.as_mut().resume(true),
    GeneratorState::Yielded(3),
));

assert!(matches!(
    generator.as_mut().resume(false),
    GeneratorState::Complete,
));

use ::next_gen::prelude::*;

type ShouldContinue = bool;

#[generator(
    yield(i32),
    resume(ShouldContinue) as mut should_continue,
)]
fn g ()
{
    for i in 0.. {
        if should_continue.not() {
            break;
        }
        should_continue = yield_!(i);
    }
}

<!-- AUTOGENERATED FILE -->

```toml
[dependencies]
next-gen.version = "..."
next-gen.default-features = false  # <- ADD THIS to disable `std`&`alloc` for `no_std` compat
next-gen.features = [
    "alloc",  # If your no_std platform has access to allocators.
  # "std",  # `default-features` bundles this.
]