Struct semeion::env::Environment

pub struct Environment<'e, K, C> { /* fields omitted */ }

The Environment is a grid, of squared tiles with the same size, where all the entities belong.

The Environment acts both as the data structure as well as the engine that gives life to all the entities in it, and allows their interaction for every generation. Where the behavior of each Entity is defined by the user, via the Entity trait.

Once the Environment is initialized by inserting entities as its initial population, it can be drawn by drawing all its entities, and it is possible to move to the next generation (allowing the interaction between the entities to take place).

An Environment can contains entities of different kinds, and it can be created with specific dimension, that represents the size of the grid that describes its geometry. The geometry of the Environment is defined as a Torus, that is, the grid dimension are adjacent to each other, allowing therefore the entities to move past each dimension into the next tile as if there were no limits.

The lifetime 'e is the lifetime bound that is applied to all the entities owned by the Environment, and it must be the same lifetime for all the entities types that implement the Entity trait. This lifetime defines the bound for the objects (immutable references lifetimes) that implement the Entity trait, and it allows to propagate the same bound to the entities Offspring.

Implementations

impl<'e, K: Ord, C> Environment<'e, K, C>

pub fn new(dimension: impl Into<Dimension>) -> Self

Constructs a new environment with the given dimension.

The dimension represents the size of the grid of squared tiles of same side length, as number of columns and rows.

pub fn dimension(&self) -> Dimension

Gets the Dimension of the Environment.

pub fn insert(&mut self, entity: Box<Trait<'e, K, C>>)

Inserts the given Entity into the Environment.

This method is usually used to pre-populate the environment with a set of entities that will constitute the first generation. After the environment has been pre-populated the set of entities stored in it will depend on the behavior of the entities itself (such ad lifespan increase and decrease, or generated offspring).

pub fn draw(
    &self,
    ctx: &mut C,
    transform: impl Into<Transform>
) -> Result<(), Error>

Draws the environment by iterating over each of its entities, sorted by kind, and calling the draw method for each one of them.

Returns an error if any of the draw methods returns an error. The order of draw calls for each entity of the same type is arbitrary.

pub fn is_empty(&self) -> bool

Returns true only if no Entity is currently in the Environment.

pub fn count(&self) -> usize

Gets the total number of entities in the environment.

pub fn count_kind(&self, kind: &K) -> usize

Gets the total number of entities in the Environment of the given Kind.

pub fn generation(&self) -> u64

Gets the current generation step number.

pub fn entities(&self) -> impl Iterator<Item = &Trait<'e, K, C>>

Gets an iterator over all the entities in the Environment.

The entities will be returned in an arbitrary order.

pub fn entities_at(
    &self,
    location: impl Into<Location>
) -> impl Iterator<Item = &Trait<'e, K, C>>

Gets an iterator over all the entities located at the given location.

The entities will be returned in an arbitrary order. The Environment is seen as a Torus from this method, therefore, out of bounds offsets will be translated considering that the Environment edges are joined.

pub fn nextgen(&mut self) -> Result<u64, Error>

Moves forwards to the next generation. Returns the current generation step number.

Moving to the next generation involves the following actions sorted by order:

• Calling Entity::observe(neighborhood) for each entity with a snapshot of the portion of the environment seen by the entity according to its scope. The order of the entities called is arbitrary.
• Calling Entity::react(neighborhood) for each entity with a snapshot of the portion of the environment seen by the entity according to its scope. The order of the entities called is arbitrary.
• Inserting the entities offspring in the environment.
• Removing the entities that reached the end of their lifespan from the environment.

This method will return an error if any of the calls to Entity::observe() or Entity::act() returns an error, in which case none of the steps that involve the update of the environment will take place.

pub fn nextgen_with(
    &mut self,
    entity_func: Box<dyn Fn(&mut Trait<'e, K, C>) -> Result<(), Error>>
) -> Result<u64, Error>

Moves forwards to the next generation. Returns the current generation step number.

Follows the same semantic of Environment::nextgen(), but allows to call the provided closure for each Entity in the Environment. The closure will be called prior to any other step, allowing to initialize the state of each entity. Returns an error if any of the calls to the provided closure returns an error.

Trait Implementations

impl<'e, K: Debug, C: Debug> Debug for Environment<'e, K, C>

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.