6.39 Sequences

8.12

6.39 Sequences🔗ℹ

A sequence supplies elements to a for iteration. Lists, maps, sets, and arrays 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.

annotation

Sequence

Matches any sequence.

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.

expression

n_expr .. m_expr

expression

n_expr ..

If n_expr produces an integer n and m_expr (when supplied) produces an integer m, returns a listable sequence containing the integers from n (inclusive) to m (exclusive). If m_expr is not specified, the result is an infinite sequence that contains all integers starting from n.

The .. operator’s precedence is lower than the arithmetic operators +, -, *, and /.

A .. expression has static information that makes it acceptable as a sequence to for in static mode.

expression

n_expr ..= m_expr

Like n_expr .. m_expr, but with an inclusive upper bound.

function

fun Sequence.make(

~initial_position:

init_pos :: Any,

~continue_at_position:

continue_at_pos :: maybe(Function.of_arity(1)) = #false,

~position_to_element:

pos_to_element :: Function.of_arity(1),

~continue_at_value:

continue_at_val :: maybe(Function) = #false,

~early_position_to_next:

early_next_pos :: maybe(Function.of_arity(1)) = #false,

~continue_after_position_and_value:

continue_at_pos_val :: maybe(Function) = #false,

~position_to_next:

next_pos :: Function.of_arity(1)

) :: Sequence

Creates a sequence by supplying the index value and stepper, element-to-index function, and continue conditions:

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 wil be called once per element in an iteration, and only if iteration has not been stoppped 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.instiantiate.

fun even_strings_up_to(n :: Int):
  Sequence.make(
    ~initial_position: 0,
    ~continue_at_position: fun (i): i < n,
    ~position_to_element: to_string,
    ~position_to_next: fun (i): i + 2
  )

> for List (i: even_strings_up_to(5)): i
["0", "2", "4"]

function

fun Sequence.instantiable(thunk :: Function.of_arity(0))

:: Sequence

A delaying form of Sequence.make, where thunk is called for every instantiation of the sequence. The given thunk should return the results of Sequence.instantiate.

fun even_strings_up_to(n :: Int):
  Sequence.instantiable(
    fun ():
      let mutable i = 0
      Sequence.instantiate(
        ~initial_position: #void,
        ~continue_at_position: fun (_): i < n,
        ~position_to_element: fun (_): to_string(i),
        ~position_to_next: fun (_): i := i + 2
      ))

> for List (i: even_strings_up_to(5)): i
["0", "2", "4"]

function

fun Sequence.instantiate(

~initial_position:

init_pos :: Any,

~continue_at_position:

continue_at_pos :: maybe(Function.of_arity(1)) = #false,

~position_to_element:

pos_to_element :: Function.of_arity(1),

~continue_at_value:

continue_at_val :: maybe(Function) = #false,

~early_position_to_next:

early_next_pos :: maybe(Function.of_arity(1)) = #false,

~continue_after_position_and_value:

continue_at_pos_val :: maybe(Function) = #false,

~position_to_next:

next_pos :: Function.of_arity(1)

) :: (Any, Any, Any, Any, Any, Any, Any)

Takes arguments of the same form as Sequence.make, but simply returns them as multiple values in an unspecified order. This function is meant to be called from a function passed to Sequence.instantiable.

interface

interface Sequenceable

Provided only in the class space, not the annot or namespace space.

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.

class Posn(x, y):
  private implements Sequenceable
  private override method to_sequence():
    [x, y]

> for List (i: Posn(10, 20)): i
[10, 20]

1	Rhombus Essentials
2	Collections and Iteration
3	Syntax Objects and Macros
4	Classes and Interfaces
5	Static Information and Binding
6	Core Reference
7	Meta and Macros Reference
8	Rhombus Static by Default
9	Libraries
10	Naming Conventions

6.1	General Forms
6.2	Definitions
6.3	Namespaces
6.4	Import
6.5	Export
6.6	Functions
6.7	Operators
6.8	Classes and Interfaces
6.9	Veneers
6.10	Mutable Variables and Assignment
6.11	Repetitions
6.12	Block
6.13	Conditionals
6.14	Matching
6.15	Iteration
6.16	Recursion
6.17	Context Parameters
6.18	Exceptions
6.19	Continuations
6.20	Implicit Forms
6.21	Static and Dynamic Lookup
6.22	Modules and Submodules
6.23	Booleans
6.24	Numbers
6.25	Characters
6.26	Strings
6.27	Keywords
6.28	Symbols
6.29	Byte Strings
6.30	Lists
6.31	Pairs and Pair Lists
6.32	Mutable Lists
6.33	Arrays
6.34	Maps
6.35	Sets
6.36	Boxes
6.37	Indexables
6.38	Listables
6.39	Sequences
6.40	Appendables
6.41	Comparables
6.42	Paths
6.43	Source Locations
6.44	Void
6.45	Equality
6.46	Dot
6.47	Multiple Values
6.48	Annotations
6.49	Enumerations
6.50	Input and Output
6.51	Eval
6.52	Syntax Objects
6.53	Syntax Classes
6.54	Simple Expression Macros
6.55	Unit Testing