9.4 Sequences🔗ℹ

A sequence supplies elements to a for iteration. Lists, mutable lists, pair lists, maps, sets, arrays, strings, byte strings, and sequenceable ranges are sequences, and new kinds of sequences can be defined by calling Sequence.make, Sequence.instantiable, or implementing Sequenceable.

A sequence is more general than a list or stream in that it can have internal state, and the state can even be specific to a particular instantiation of the sequence for a new iteration.

Static information associated by Sequence makes an expression acceptable as a sequence to for in static mode, and it is suitable when a more specialized annotation (such as List or Array) is not available.

A Sequence.expect_of(ann, ...) annotation is the same as Sequence, but elements drawn from the sequence via for have the static information of anns (where multiple anns correspond to multiple values for each element, such as the key and value from a map). The extracted elements are not checked or converted, however, and each anns is used only for its static information.

• init_pos: A value that represents the initial sequence position. Any kind of value is allowed, because it is used only by other supplied functions, such as pos_to_element and next_pos.

• continue_at_pos: An optional function that takes the current position and reports whether iteration should continue with that position. A #false for continue_at_pos is equivalent to a function that always returns #true. This function is applied before an attempt to map the position to an element using pos_to_element.

• pos_to_element: A function that takes the current position and returns a value (or multiple values) for the element at that position. This function will be called once per element in an iteration, and only if iteration has not been stopped by a #false return from one of the continue functions.

• continue_at_val: An optional function that takes the current element (which may be multiple values supplied as multiple arguments) and reports whether iteration should continue with that element. A #false for continue_at_value is equivalent to a function that always returns #true. This function is applied before exposing an element to an iteration, and it is also called before early_next_pos.

• early_next_pos: An optional function that takes the current position and returns an updated position. A #false for early_next_pos is equivalent to a function that returns its argument. This function is called before the current element is exposed to an iteration, and it is called before continue_at_value. It is intended for cases where retaining the position after extracting an element would incorrectly retain the element via the position. Typically, if early_next_pos advances a position, then next_pos will return its argument, and continue_at_pos_val needs to be #false (otherwise the value must be retained for that predicate).

• continue_at_pos_val: An optional function that takes both the current position and elements (which may be multiple values supplied as multiple arguments) and reports whether iteration should continue with that element. A #false for continue_at_pos_val is equivalent to a function that always returns #true. This function is applied after the element is exposed to iteration. If early_next_pos is supplied, its return is the first argument to continue_at_pos_val.

• next_pos: A function that takes the current position and returns the next position.

The arguments to Sequence.make are required to be a mixture of #false and function values, beware that the arguments are not checked. Errors due to invalid or inconsistent values may be detected later.

This same initial position and functions are used for every instantiation of the result sequence. To distinguish different instantiations, use Sequence.instantiate.

An interface that a class can implement (publicly or privately) to make instances of the class work with as a sequence for for—in dynamic mode, but see also sequence for statically optimizing for expansions. The interface has a single abstract method:

• to_sequence() — returns a sequence value, possibly constructed with Sequence.make or Sequence.instantiable.