5.3.8.8 ListIterator Objects

###
5.3.8.8 ListIterator Objects

The iterator named in the `iter` (5.3.8.5) attribute of the `<al-for>` tag is an instance of this class. By using an object to iterate over the sequence the toolkit is able to provide additional data that is useful in formatting HTML.

The iterator will retrieve each value from the sequence exactly once. This allows you to use objects that act as sequences by implementing the Python sequence protocol. Only `__getitem__()` is required unless you use pagination, then `__len__()` is also required.

`pagesize`( | )

  Returns the pagesize that was set in the `pagesize` attribute.

`has_prevpage`( | )

  Returns `TRUE` if the page `start` index is greater than zero indicating that there is a previous page.

`has_nextpage`( | )

  Returns `TRUE` if the sequence length is greater than the page `start` index plus the `_pagesize` member indicating that there is a next page.

  If the iterator has not been placed into ``page mode'' by the presence of a `pagesize` attribute a `ListIteratorError` exception will be raised.

`index`( | )

  Returns the index of the current sequence element.

`start`( | )

  Returns the index of the first sequence element on the page.

`count`( | )

  Returns the index of the current sequence element within the current page. This is equivalent to `index() - start()`.

`value`( | )

  Returns the current sequence element.

Most of the methods and all of the members are not meant to be accessed from your code but are documented below to help clarify how the iterator behaves.

`_index`
  Current sequence index -- returned by `index()`.

`_start`
  Sequence index of first element on page -- returned by `start()`.

`_count`
  Sequence index of current element on page -- returned by `count()`.

`_seq`
  Sequence being iterated over -- initialised to `None` and set by `set_sequence()`.

`_have_value`
  Indicates the state of the current element. There are three possible values: `None` indicates that the state is unknown and will be established when the sequence is next accessed, zero indicates that the end of sequence has been reached and there is no valid element, and one indicates the current element is valid.

`_pagesize`
  Current page size -- initialised to `0` and set by the presence of a `pagesize` attribute in the `<al-for>` tag.

`__getstate__`( | )

  When ``page mode'' is enabled the iterator is saved into the session (via the execution context `add_session_vars()` method). This restricts the Python pickler to saving only the `_start` and `_pagesize` members.

`__setstate__`( | tup)

  Restores an iterator from the Python pickler.

`__len__`( | )

  When in ``page mode'' it returns the `_pagesize` member else it returns the length of the sequence.

`set_backdoor`( | op, value)

  The `<al-input>` and `<al-a>` tags provide `nextpage` and `prevpage` attributes that generate names using a special backdoor format. When the browser request is merged the `set_value()` method of the `NamespaceMixin` directs list backdoor input fields to this method. Refer to the documentation in section 7.6.

  The value argument is the browser submitted value for the backdoor field. If a value was submitted for the backdoor field then the op argument is processed. If op equals `"prevpage"` or `"nextpage"` then the iterator selects the previous or next page respectively.

`get_backdoor`( | op)

  When generating backdoor fields for the `<al-input>` and `<al-a>` tags the toolkit calls this method to determine the value that will assigned to that field. The method returns `1`.

`set_pagesize`( | size)

  Sets the `_pagesize` member to size.

`has_sequence`( | )

  Returns whether or not a sequence has been placed into the iterator (`_seq` is not `None`).

`set_sequence`( | seq)

  Sets the `_seq` to seq.

`reset_index`( | )

  If the `<al-for>` tag does not contain a `continue` attribute then this is called just before executing the tag content for the first element in the sequence. It sets the `_index` member to `_start`.

`reset_count`( | )

  This is called just before executing the tag content for the first element in the sequence. It sets the `_count` member to zero.

`clear_value`( | )

  Sets the `_have_value` member to `None` which causes the next call of `has_value()` to retrieve the sequence element indexed by `_index`.

`has_value`( | )

  When the `_have_value` member is `None` this method tries to retrieve the sequence element indexed by `_index`. If an element is returned by the sequence it is saved in the `_value` member and `_have_value` is set to one. If an `IndexError` exception is raised by the sequence then `_have_value` is set to zero.

  The method returns TRUE if a sequence member is contained in `_value`.

  By this mechanism the iterator retrieves each value from the sequence exactly once.

`next`( | )

  Retrieves the next value (if available) from the sequence into the `_value` member.

`set_value`( | value)

  A back door hack for multi-column output that sets respective values of the iterator to sequences created by slicing the sequence in the `expr` attribute of the `<al-for>` tag.