Struct generations::Generations

pub struct Generations<Model> { /* fields omitted */ }

This struct manages transitions between generations. It stores two models, one of which is considered "current" and the other "scratch". The step method advances the simulation by calling a function with a reference to the current generation and a mutable reference to the scratch generation; the function uses the current generation to write the next generation out to the scratch generation, after which it becomes the new current generation (and the previous generation becomes the new scratch generation).

Methods

impl<Model> Generations<Model>

#[must_use] pub fn new(seed: Model, scratch: Model) -> Self

Create a new Generations instance with a seed model, which will become the initial current generation, and a scratch generation.

Example

Create a simulation using a vector for the seed generation and a pre-allocated vector for the scratch generation

use generations::Generations;

let mut gen = Generations::new(
    vec![1, 2, 3, 4, 5],
    Vec::with_capacity(5)
);

gen.step(|current_gen, next_gen| {
    assert_eq!(current_gen, &[1, 2, 3, 4, 5]);
    assert_eq!(next_gen, &[]);
    assert_eq!(next_gen.capacity(), 5);
});

#[must_use] pub fn current(&self) -> &Model

Get a reference to the current generation. This is the result of the most recent step or reset, or the seed generation if no steps have been run.

Example

use generations::Generations;

let gen = Generations::new_defaulted(vec![1, 2, 3, 4]);
assert_eq!(gen.current(), &[1, 2, 3, 4]);

pub fn step(&mut self, stepper: impl FnOnce(&Model, &mut Model)) -> &Model

Advance the simulation 1 step using a stepping function. The stepping function takes a reference to the current generation and a mutable reference to the new generation. The stepping function should advance the simulation by reading the current genration and writing the next generation. After the stepping function writes the new generation, it is marked as current.

This function returns a reference to the previously current generation, so that it can be compared if desired with the current generation.

Example

// Simple example that rotates a vector 1 step
use generations::Generations;

let mut gen = Generations::new_cloned(vec![1, 2, 3, 4]);

let prev = gen.step(|current_gen, next_gen| {
    next_gen.clear();
    next_gen.extend(current_gen.iter().skip(1));
    next_gen.extend(current_gen.first());
});

assert_eq!(prev, &[1, 2, 3, 4]);
assert_eq!(gen.current(), &[2, 3, 4, 1]);

pub fn reset_with(&mut self, seeder: impl FnOnce(&mut Model))

Replace the current generation with a new seed generation using a function. Has no effect on the existing scratch generation.

use generations::Generations;

let mut gen = Generations::new_defaulted(vec![1, 2, 3, 4]);
gen.reset_with(|seed_gen| {
    seed_gen.clear();
    seed_gen.extend(&[5, 5, 5, 5]);
});
assert_eq!(gen.current(), &[5, 5, 5, 5]);

pub fn reset(&mut self, seed: Model)

Replace the current generation with a new seed generation. Has no effect on the existing scratch generation.

See also reset_with for a reset method that reuses the existing storage of the current generation.

use generations::Generations;

let mut gen = Generations::new_defaulted(vec![1, 2, 3, 4]);
gen.reset(vec![4, 3, 2, 1]);
assert_eq!(gen.current(), &[4, 3, 2, 1]);

#[must_use] pub fn with_rule<F: FnMut(&Model, &mut Model)>(
    self,
    stepper: F
) -> Simulation<Model, F>

Combine a Generations struct with a repeatable stepping function, to create a simulation that can be stepped with the same logic each generation. See step for an explaination of the stepping function.

impl<Model: Clone> Generations<Model>

#[must_use] pub fn new_cloned(seed_generation: Model) -> Self

Create a new Generations instance with a seed model. Clone the seed model to create an initial scratch model.

pub fn reset_from(&mut self, seed: &Model)

Replace the current generation with a clone of a new seed generation. Has no effect on the current scratch generation.

impl<Model: Default> Generations<Model>

#[must_use] pub fn new_defaulted(seed_generation: Model) -> Self

Create a new Generations instance with a seed model. The Model type's default value is used as the initial scratch model.

Trait Implementations

impl<Model: Debug> Debug for Generations<Model>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Model, Step> AsRef<Generations<Model>> for Simulation<Model, Step>

fn as_ref(&self) -> &Generations<Model>

Performs the conversion.

impl<Model: Clone> Clone for Generations<Model>

fn clone(&self) -> Generations<Model>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.