.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DR::Tarantool::Iterator 3pm"
.TH DR::Tarantool::Iterator 3pm "2019-10-07" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DR::Tarantool::Iterator \- an iterator and a container class for
DR::Tarantool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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 );
\&    }
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
A constructor.
.PP
\fIArguments\fR
.IX Subsection "Arguments"
.IP "\(bu" 4
An array of tuples to iterate over.
.IP "\(bu" 4
A list of named arguments:
.RS 4
.IP "item_class" 4
.IX Item "item_class"
Name of the class to bless each tuple in the iterator with.
If the field is '\fB\s-1ARRAYREF\s0\fR' then the first element of the array is
\&\fBitem_class\fR, and the second element is \fBitem_constructor\fR.
.IP "item_constructor" 4
.IX Item "item_constructor"
Name of a constructor to invoke for each tuple. If this value is
undefined and \fBitem_class\fR is defined, the iterator blesses each
tuple but does not invoke a constructor on it.
.Sp
The constructor is invoked on with three arguments: \fBitem\fR,
\&\fBitem_index\fR and \fBiterator\fR, for example:
.Sp
.Vb 5
\&    my $iter = DR::Tarantool::Iterator\->new(
\&        [ [1], [2], [3] ],
\&        item_class => \*(AqMyClass\*(Aq,
\&        item_constructor => \*(Aqnew\*(Aq
\&    );
\&
\&    my $iter = DR::Tarantool::Iterator\->new(    # the same
\&        [ [1], [2], [3] ],
\&        item_class => [ \*(AqMyClass\*(Aq, \*(Aqnew\*(Aq ]
\&    );
\&
\&
\&    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
.Ve
.IP "data" 4
.IX Item "data"
Application state to store in the iterator. Is useful
if additional state needs to be passed into tuple constructor.
.RE
.RS 4
.RE
.SS "clone(%opt)"
.IX Subsection "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 \fBitem_class\fR and (or) \fBitem_constructor\fR.
.PP
If \fBclone_items\fR argument is true, the function clones the  tuple
list as well.
.PP
.Vb 3
\&    my $iter1 = $old_iter\->clone(item_class => [ \*(AqMyClass\*(Aq, \*(Aqnew\*(Aq ]);
\&    my $iter2 = $old_iter\->clone(item_class => [ \*(AqMyClass\*(Aq, \*(Aqnew\*(Aq ],
\&        clone_items => 1);
\&
\&    $old_iter\->sort(sub { $_[0]\->name cmp $_[1]\->name });
\&    # $iter1 is sorted, too, but $iter2 is not
.Ve
.SS "count"
.IX Subsection "count"
Return the number of tuples available through the iterator.
.SS "item"
.IX Subsection "item"
Return one tuple from the iterator by its index 
(or croak an error if the index is out of range).
.SS "raw_item"
.IX Subsection "raw_item"
Return one raw tuple from the iterator by its index 
(or croak error if the index is out of range).
.PP
In other words, this method ignores \fBitem_class\fR and \fBitem_constructor\fR.
.SS "raw_sort(&)"
.IX Subsection "raw_sort(&)"
Sort the contents referred to by the iterator (changes the current 
iterator object).
The compare function receives two \fBraw\fR objects:
.PP
.Vb 1
\&    $iter\->raw_sort(sub { $_[0]\->field cmp $_[1]\->field });
.Ve
.SS "sort(&)"
.IX Subsection "sort(&)"
Sort the contents referred to by the iterator (changes the current object).
The compare function receives two constructed objects:
.PP
.Vb 1
\&    $iter\->sort(sub { $_[0]\->field <=> $_[1]\->field });
.Ve
.SS "grep(&)"
.IX Subsection "grep(&)"
Find all objects in the set referred to by the iterator that
match a given search criteria (linear search).
.PP
.Vb 1
\&    my $admins = $users\->grep(sub { $_[0]\->is_admin });
.Ve
.SS "raw_grep(&)"
.IX Subsection "raw_grep(&)"
Same as grep, but works on raw objects.
.PP
.Vb 1
\&    my $admins = $users\->raw_grep(sub { $_[0]\->is_admin });
.Ve
.SS "get"
.IX Subsection "get"
An alias for item method.
.SS "exists"
.IX Subsection "exists"
Return \fBtrue\fR if the iterator contains a tuple with the given
index.
.PP
.Vb 1
\&    my $item = $iter\->exists(10) ? $iter\->get(10) : somethig_else();
.Ve
.SS "next"
.IX Subsection "next"
Return the next tuple, or \fBundef\fR in case of eof.
.PP
.Vb 3
\&    while(my $item = $iter\->next) {
\&        do_something_with( $item );
\&    }
.Ve
.PP
Index of the current tuple can be queried with function 'iter'.
.SS "iter"
.IX Subsection "iter"
Return index of the tuple at the current iterator position.
.SS "reset"
.IX Subsection "reset"
Reset iteration index, return the previous value of the index.
.SS "all"
.IX Subsection "all"
Return all tuples available through the iterator.
.PP
.Vb 2
\&    my @list = $iter\->all;
\&    my $list_aref = $iter\->all;
\&
\&    my @abc_list = map { $_\->abc } $iter\->all;
\&    my @abc_list = $iter\->all(\*(Aqabc\*(Aq);               # the same
\&
\&
\&    my @list = map { [ $_\->abc, $_\->cde ] } $iter\->all;
\&    my @list = $iter\->all(\*(Aqabc\*(Aq, \*(Aqcde\*(Aq);                # the same
\&
\&
\&    my @list = map { $_\->abc + $_\->cde } $iter\->all;
\&    my @list = $iter\->all(sub { $_[0]\->abc + $_\->cde }); # the same
.Ve
.SS "item_class"
.IX Subsection "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).
.SS "item_constructor"
.IX Subsection "item_constructor"
Set/return the tuple constructor.
The value is used only if item_class is defined.
.SS "push"
.IX Subsection "push"
Push a tuple into the iterator.
.SS "data"
.IX Subsection "data"
Return/set an application-specific context maintained in the iterator
object. This can be useful to pass additional state to \fBitem_constructor\fR.