forward-iteration-protocol

Returns eight values used to implement iteration over the collection argument.

Only the collection argument this function was called with may be used as the collection argument to functions returned by this function. Only the initial-state object and state objects returned by the next-state and copy-state functions may be used as the state argument to functions returned by this function. Only the limit object may be used as the limit argument to the finished-state? function.

An example of the use of the iteration protocol is the following definition of a single-argument version of the do function:

define method do1 (f :: <function>, c :: <collection>)
  let (init, limit, next, end?, key, elt) =
                     forward-iteration-protocol(c);
  for (state = init then next(c, state),
     until: end?(c, state, limit))
    f(elt(c, state));
  end for;
end method do1;

Exported from

Modifiers

open

Arguments

collection

An instance of <collection>.

Values

initial-state	An instance of <object>. The initial iteration state object.
limit	An instance of <object> that is used by the finished-state? function to determine whether the iteration has been completed.
next-state	An instance of <function>. Its signature is next-state(collection, state) ⇒ new-state.
	This function steps the iteration by producing a new state from the associated collection and state. The next-state function may or may not modify the state argument; it is an error to use a state value after it has been passed to the associated next-state function. The copy-state function provides a mechanism for saving a particular state in an iteration for later resumption.
finished-state?	An instance of <function>. Its signature is finished-state?(collection, state, limit) ⇒ boolean.
	This function returns #t if the iteration of the collection has been completed, i.e., there are no other elements of the collection to consider. It returns #f otherwise. It is an error to use a finished state in a call to the associated next-state, current-element, current-key or current-element-setter functions.
current-key	An instance of <function>. Its signature is current-key(collection, state) ⇒ key.
	This function returns the unique key associated with state in the collection. If the current-key function were called once with each state value produced during an iteration over a collection, the resulting sequence of values would contain every key from the collection exactly once; it would be the key-sequence of the collection.
current-element	An instance of <function>. Its signature is current-element(collection, state) ⇒ element.
	This function returns the element of collection currently indicated by state.
current-element-setter	An instance of <function>. Its signature is current-element-setter(value, collection, state) ⇒ value.
	This function sets the element of collection indicated by state to value and returns value. If collection is not an instance of <mutable-collection>, or if the value is not of a type acceptable to the collection, an error is signaled.
copy-state	An instance of <function>. Its signature is copy-state(collection, state) ⇒ new-state.
	This function returns a state that represents the same point in the iteration over collection as is represented by state.