NAME ^

src/pmc/iterator.pmc - Iterator PMC

DESCRIPTION ^

These are the vtable functions for the Iterator base class. Iterators are used in combination with other classes(mainly aggregates) to visit all entries in that aggregate.

SYNOPSIS ^

default usage ^

    .local pmc iterator, array, entry
    iterator = new 'Iterator', array
  iter_loop:
    unless iterator, iter_end  # while (more values)
    entry = shift iterator     # get an entry
    ...
    goto iter_loop
  iter_end:

The new can alteratively be written as:

  iterator = iter array

iterate from the end, for arrays ^

    .local pmc iterator, array, entry
    iterator = new 'Iterator', array
    iterator = .ITERATE_FROM_END
  iter_loop:
    unless iterator, iter_end  # while (more values)
    entry = pop iterator     # get an entry
    ...
    goto iter_loop
  iter_end:

iterate over a hash ^

    .local pmc iterator, hash, key, entry
    iterator = new 'Iterator', hash
  iter_loop:
    unless iterator, iter_end  # while (more values)
    key   = shift iterator     # get the key..
    entry = hash[key]
    ...
    goto iter_loop
  iter_end:

Methods ^

void init()

Raises an exception. Use init_pmc().

void init_pmc(PMC *initializer)

Initializes the iterator with an aggregate PMC. Defaults iteration mode to iterate from start.

void mark()

Marks the current idx/key and the aggregate as live.

PMC *clone()

Make a clone of the iterator.

INTVAL get_integer()

Get number of remaining elements. Does not work for hashes yet. TODO: keep track of current position and direction

STRING *get_string()

Returns a textual representation of the iterator.

INTVAL get_integer_keyed(PMC *key)

INTVAL get_integer_keyed_int(INTVAL idx)

Get integer value of current position plus idx.

FLOATVAL get_number_keyed(PMC *key)

FLOATVAL get_number_keyed_int(INTVAL idx)

Get number value of current position plus idx.

STRING *get_string_keyed(PMC *key)

STRING *get_string_keyed_int(INTVAL idx)

Get string value of current position plus idx.

INTVAL get_bool()

Returns true if the idx/key is not -1.

INTVAL elements()

Returns the number of remaining elements in the aggregate. TODO.

PMC *get_pmc_keyed(PMC *key)

Returns the element for *key.

PMC *get_pmc_keyed_int(INTVAL key)

Returns the element for key.

void set_integer_native(INTVAL value)

Reset the Iterator. value must be one of

 ITERATE_FROM_START        ... Iterate from start
 ITERATE_FROM_START_KEYS   ... OrderedHash by keys
 ITERATE_FROM_END          ... Arrays and PerlString only
INTVAL pop_integer()

FLOATVAL pop_float()

STRING *pop_string()

PMC *pop_pmc()

Returns the element for the current idx/key and sets the idx/key to the previous one.

INTVAL shift_integer()

Returns the element for the current idx/key and sets the idx/key to the next one.

opcode_t *invoke(void *next)

Return the next element of the aggregate. The return type may depend on the aggregate. If there are no more items in the aggregate, I1 .. I4 are zero.

See docs/pdds/pdd03_calling_conventions.pod.

FLOATVAL shift_float()

STRING *shift_string()

PMC *shift_pmc()

Returns the element for the current idx/key and sets the idx/key to the next one.

INTVAL exists_keyed(PMC *key)

Returns whether an element for *key exists in the aggregate.

INTVAL exists_keyed_int(INTVAL idx)

Returns whether an element for idx exists in the aggregate.

INTVAL defined()

Returns whether the iterator contains an aggregate.

INTVAL defined_keyed(PMC *key)

INTVAL defined_keyed_int(INTVAL key)

Returns the result of calling defined_keyed(key) on the aggregate.

INTVAL type_keyed(PMC *key)

Returns the result of calling type_keyed(key) on the aggregate.

INTVAL type_keyed_int(PMC *idx)

Returns the result of calling type_keyed(key) on the aggregate.


parrot