TITLE

Iter -- A PIR-based Iterator Object

DESCRIPTION

An iterator with an object-oriented interface, written in PIR. Currently implemented only for Array type PMCs. Expect Hash support shortly.

SYNOPSIS

    load_bytecode 'Iter.pir'
    .local pmc iter
               iter = new 'Iter'

    ## initialize the iterator
    iter.'start'(your_aggregate)

    ## advance to the next item in the iterator
    iter.'next'()

    ## check for exhaustion
    $I0 = iter.'exhausted'()
    if $I0 goto done

    ## get the value from the iterator
    $P0 = iter.'value'()

    ## alternate interface to advance and get the value
    $P0 = iter.'nextval'()

Iter Methods

.'start'(PMC aggregate)

Initialize the iterator. Must pass a PMC aggregate, or an exception is thrown.

.'next'()

Sets the internal value attribute to the value of the next item from the iterator. Sets the internal exhausted attribute if the iterator is exhausted.

.'exhausted'()

Returns true (1) if the iterator is exhausted. Returns false (0) otherwise.

.'value'()

Returns the current value from the iterator. Returns PMCNULL if exhausted.

.'nextval'()

Executes .'next'(), and returns .'value'().

AUTHOR

Jerry Gay a.k.a. particle