NAME

Elastic::Model::Role::Iterator - A generic iterator role

VERSION

version 0.52

SYNOPSIS

    print "Total: ".$iter->size;

    while (my $el = $iter->next) {
        print "Row: ".$iter->index + 1;
        print "Data: $el";
        print "More to come..."
            unless $iter->is_last;
    }

DESCRIPTION

Elastic::Model::Role::Iterator is a generic iterator role which is applied to Elastic::Model::Results and Elastic::Model::Results::Scrolled via Elastic::Model::Role::Results.

ATTRIBUTES

elements

    \@elements = $iter->elements

An array ref containing all of the data structures that we can iterate over.

size

    $size = $iter->size

The number of elements in "elements".

wrapper

    $iter     = $iter->wrapper($code_ref);
    $code_ref = $iter->wrapper();

A coderef that wraps all single-element wrapped accessors. Defaults to "as_elements()".

multi_wrapper

    $iter     = $iter->multi_wrapper($code_ref);
    $code_ref = $iter->multi_wrapper();

A coderef that wraps all multi-element wrapped accessors. Defaults to "as_elements()".

ITERATOR CONTROL

index

    $index = $iter->index;      # index of the current element, or undef
    $iter->index(0);            # set the current element to the first element
    $iter->index(-1);           # set the current element to the last element
    $iter->index(undef);        # resets the iterator, no current element

"index" contains the current index of the iterator. Before you start iterating, it will return undef.

reset

    $iter->reset;

Resets the iterator so that the next call to "next" will return the first element. Note: any calls to "shift" means that those elements have been discarded. "reset" will not reload these.

INFORMATIONAL ACCESSORS

size

    $size = $iter->size;

Returns the number of "elements".

even

    $bool = $iter->even

Is the current "index" even?

odd

    $bool = $iter->odd

Is the current "index" odd?

parity

    $parity = $iter->parity

Returns 'odd' or 'even'. Useful for alternating the colour of rows:

    while ( my $el = $iter->next ) {
        my $css_class = $el->parity;
        # display row
    }

is_first

    $bool = $iter->is_first

Is the "current" element the first element?

is_last

    $bool = $iter->is_last

Is the "current" element the last element?

has_next

    $bool = $iter->has_next

Is there a "next" element?

has_prev

    $bool = $iter->has_prev

Is there a "prev" element?

WRAPPERS

All of the accessors ending in _element or _elements returns the raw data structure stored in "elements".

The "short" accessors (eg "first", "next") pass the result of the "long" accessors (eg first_element, next_element) through the "wrapper" (or "multi_wrapper" for accessors with multiple return values), allowing the wrapper to transform the raw data in some way.

The default for the "short" accessors is just to return the value unchanged.

as_elements()

    $iter->as_elements()

Sets the "wrapper" and "multi_wrapper" to return the raw data structures stored in "elements".

ELEMENT ACCESSORS

All of the accessors below have 2 forms:

• Element, eg next_element which returns the raw element.

• Short, which passes the raw element through the "wrapper" or "multi_wrapper" currently in effect.

first

    $el = $iter->first

Returns the first element, and resets the iterator so that a call to "next" will return the second element. If there is no first element, it returns undef.

Also first_element

next

    $el = $iter->next;

Returns the next element, and advances the iterator by one. If there is no next element, it returns undef. If the next element is the last element, then it will work like this:

    $iter->next;        # returns last element
    $iter->next;        # returns undef, and resets iterator
    $iter->next;        # returns first element

Also next_element

prev

    $el = $iter->prev

Returns the previous element, and moves the iterator one step in reverse. If there is no previous element, it returns undef. If the previous element is the first element, then it will work like this:

    $iter->prev;        # returns prev element
    $iter->prev;        # returns undef, and resets iterator to end
    $iter->prev;        # returns last element

Also prev_element

current

    $el = $iter->current

Returns the current element, or undef

Also current_element

last

    $el = $iter->last

Returns the last element, and resets the iterator so that a call to "next" will return undef, and a second call to "next" will return the first element If there is no last element, it returns undef.

Also last_element

peek_next

    $el = $iter->peek_next

Returns the next element (or undef), but doesn't move the iterator.

Also peek_next_element

peek_prev

    $el = $iter->peek_prev

Returns the previous element (or undef), but doesn't move the iterator.

Also peek_prev_element

shift

    $el = $iter->shift

Returns the "first" element and removes it from from the list. "size" will decrease by 1. Returns undef if there are no more elements.

Also shift_element

slice

    @els = $iter->slice($offset,$length);

Returns a list of (max) $length elements, starting at $offset (which is zero-based):

    $iter->slice();             # all elements;
    $iter->slice(5);            # elements 5..size
    $iter->slice(-5);           # elements size-5..size
    $iter->slice(0,10);         # elements 0..9
    $iter->slice(5,10);         # elements 5..14

If your iterator only contains 5 elements:

    $iter->slice(3,10);         # elements 3..4
    $iter->slice(10,10);        # an empty list

Also slice_elements

all

    @els = $iter->all

Returns all "elements" as a list.

Also all_elements

AUTHOR

Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Clinton Gormley.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Elastic::Model

perl -MCPAN -e shell
install Elastic::Model