Enum Enumerator

#[non_exhaustive]
pub enum Enumerator {
    NonEnumerable,
    Empty,
    Str(&'static [&'static str]),
    Iter(Box<dyn Iterator<Item = Value> + Send + Sync>),
    RevIter(Box<dyn DoubleEndedIterator<Item = Value> + Send + Sync>),
    Seq(usize),
    Values(Vec<Value>),
}

Enumerators help define iteration behavior for Objects.

When Jinja wants to know the length of an object, if it’s empty or not or if it wants to iterate over it, it will ask the Object to enumerate itself with the enumerate method. The returned enumerator has enough information so that the object can be iterated over, but it does not necessarily mean that iteration actually starts or that it has the data to yield the right values.

In fact, you should never inspect an enumerator. You can create it or forward it. For actual iteration use ObjectExt::try_iter etc.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NonEnumerable

Marks non enumerable objects.

Such objects cannot be iterated over, the length is unknown which means they are not considered empty by the engine. This is a good choice for plain objects.

Iterable	Length
no	unknown

Empty

The empty enumerator. It yields no elements.

Iterable	Length
yes	known (0)

Str(&'static [&'static str])

A slice of static strings.

This is a useful enumerator to enumerate the attributes of an object or the keys in a string hash map.

Iterable	Length
yes	known

Iter(Box<dyn Iterator<Item = Value> + Send + Sync>)

A dynamic iterator over values.

The length is known if the Iterator::size_hint has matching lower and upper bounds. The logic used by the engine is the following:

let len = match iter.size_hint() {
    (lower, Some(upper)) if lower == upper => Some(lower),
    _ => None
};

Because the engine prefers repeatable iteration, it will keep creating new enumerators every time the iteration should restart. Sometimes that might not always be possible (eg: you stream data in) in which case

Iterable	Length
yes	sometimes known

RevIter(Box<dyn DoubleEndedIterator<Item = Value> + Send + Sync>)

Like Iter but supports efficient reversing.

This means that the iterator has to be of type DoubleEndedIterator.

Iterable	Length
yes	sometimes known

Seq(usize)

Indicates sequential iteration.

This instructs the engine to iterate over an object by enumerating it from 0 to n by calling Object::get_value. This is essentially the way sequences are supposed to be enumerated.

Iterable	Length
yes	known

Values(Vec<Value>)

A vector of known values to iterate over.

The iterator will yield each value in the vector one after another.

Iterable	Length
yes	known