NAME

       DR::Tarantool::Iterator - an iterator and a container class for DR::Tarantool

SYNOPSIS

           use DR::Tarantool::Iterator;

           my $iter = DR::Tarantool::Iterator->new([1, 2, 3]);

           my $item0 = $iter->item(0);

           my @all = $iter->all;
           my $all = $iter->all;

           while(my $item = $iter->next) {
               do_something_with_item( $item );
           }

METHODS

   new
       A constructor.

       Arguments

       •   An array of tuples to iterate over.

       •   A list of named arguments:

           item_class
               Name of the class to bless each tuple in the iterator with.  If the field is
               'ARRAYREF' then the first element of the array is item_class, and the second
               element is item_constructor.

           item_constructor
               Name of a constructor to invoke for each tuple. If this value is undefined and
               item_class is defined, the iterator blesses each tuple but does not invoke a
               constructor on it.

               The constructor is invoked on with three arguments: item, item_index and iterator,
               for example:

                   my $iter = DR::Tarantool::Iterator->new(
                       [ [1], [2], [3] ],
                       item_class => 'MyClass',
                       item_constructor => 'new'
                   );

                   my $iter = DR::Tarantool::Iterator->new(    # the same
                       [ [1], [2], [3] ],
                       item_class => [ 'MyClass', 'new' ]
                   );

                   my $item = $iter->item(0);
                   my $item = MyClass->new( [1], 0, $iter );  # the same

                   my $item = $iter->item(2);
                   my $item = MyClass->new( [3], 2, $iter );  # the same

           data
               Application state to store in the iterator. Is useful if additional state needs to
               be passed into tuple constructor.

   clone(%opt)
       Clone the iterator object, but do not clone the tuples.  This method can be used to create
       an iterator that has a different item_class and (or) item_constructor.

       If clone_items argument is true, the function clones the  tuple list as well.

           my $iter1 = $old_iter->clone(item_class => [ 'MyClass', 'new' ]);
           my $iter2 = $old_iter->clone(item_class => [ 'MyClass', 'new' ],
               clone_items => 1);

           $old_iter->sort(sub { $_[0]->name cmp $_[1]->name });
           # $iter1 is sorted, too, but $iter2 is not

   count
       Return the number of tuples available through the iterator.

   item
       Return one tuple from the iterator by its index (or croak an error if the index is out of
       range).

   raw_item
       Return one raw tuple from the iterator by its index (or croak error if the index is out of
       range).

       In other words, this method ignores item_class and item_constructor.

   raw_sort(&)
       Sort the contents referred to by the iterator (changes the current iterator object).  The
       compare function receives two raw objects:

           $iter->raw_sort(sub { $_[0]->field cmp $_[1]->field });

   sort(&)
       Sort the contents referred to by the iterator (changes the current object).  The compare
       function receives two constructed objects:

           $iter->sort(sub { $_[0]->field <=> $_[1]->field });

   grep(&)
       Find all objects in the set referred to by the iterator that match a given search criteria
       (linear search).

           my $admins = $users->grep(sub { $_[0]->is_admin });

   raw_grep(&)
       Same as grep, but works on raw objects.

           my $admins = $users->raw_grep(sub { $_[0]->is_admin });

   get
       An alias for item method.

   exists
       Return true if the iterator contains a tuple with the given index.

           my $item = $iter->exists(10) ? $iter->get(10) : somethig_else();

   next
       Return the next tuple, or undef in case of eof.

           while(my $item = $iter->next) {
               do_something_with( $item );
           }

       Index of the current tuple can be queried with function 'iter'.

   iter
       Return index of the tuple at the current iterator position.

   reset
       Reset iteration index, return the previous value of the index.

   all
       Return all tuples available through the iterator.

           my @list = $iter->all;
           my $list_aref = $iter->all;

           my @abc_list = map { $_->abc } $iter->all;
           my @abc_list = $iter->all('abc');               # the same

           my @list = map { [ $_->abc, $_->cde ] } $iter->all;
           my @list = $iter->all('abc', 'cde');                # the same

           my @list = map { $_->abc + $_->cde } $iter->all;
           my @list = $iter->all(sub { $_[0]->abc + $_->cde }); # the same

   item_class
       Set/return the tuple class. If the value is defined, the iterator blesses tuples with it
       (and also calls item_constructor if it is set).

   item_constructor
       Set/return the tuple constructor.  The value is used only if item_class is defined.

   push
       Push a tuple into the iterator.

   data
       Return/set an application-specific context maintained in the iterator object. This can be
       useful to pass additional state to item_constructor.