.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::CLI::Interact::Role::Iterator 3pm"
.TH Net::CLI::Interact::Role::Iterator 3pm "2017-11-08" "perl v5.26.1" "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"
Net::CLI::Interact::Role::Iterator \- Array\-based Iterator
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& my $count = $iter\->count;
\&  
\& $iter\->reset;
\& while ( $iter\->has_next ) {
\&    print $iter\->next;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements an array-based iterator which may be mixed-in to add
management of a sequence of elements and processing of that sequence.
.PP
The iterator is inspired by MooseX::Iterator but limited to arrays and adds
many other facilities. The following section describes the methods provided by
this class.
.SH "USAGE"
.IX Header "USAGE"
The slot used for storing iterator elements is named \f(CW\*(C`_sequence\*(C'\fR and you
should write your consuming class to marshall data into this slot, perhaps via
\&\f(CW\*(C`BUILD\*(C'\fR or \f(CW\*(C`init_arg\*(C'\fR. For example:
.PP
.Vb 4
\& has \*(Aq+_sequence\*(Aq => (
\&    isa => \*(AqArrayRef[Thingy]\*(Aq,
\&    init_arg => \*(Aqthings\*(Aq,
\& );
.Ve
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "count"
.IX Subsection "count"
The number of elements currently stored in the iterator. Note that this is of
course not the same as the index of the last item in the iterator (which is
0\-based)
.SS "first"
.IX Subsection "first"
Returns the first item in the iterator.
.SS "last"
.IX Subsection "last"
Returns the last item in the iterator.
.ie n .SS "item_at( $pos )"
.el .SS "item_at( \f(CW$pos\fP )"
.IX Subsection "item_at( $pos )"
Returns the item at the given position in the iterator, or throws an exception
if \f(CW$pos\fR is past the end of the iterator. The position is 0\-based.
.ie n .SS "insert_at( $pos, $iter )"
.el .SS "insert_at( \f(CW$pos\fP, \f(CW$iter\fP )"
.IX Subsection "insert_at( $pos, $iter )"
Inserts the contents of the passed iterator starting \fIat\fR (not \fIafter\fR) the
position given. The passed iterator must also be a consumer of this role. The
position is 0\-based.
.ie n .SS "append( $iter )"
.el .SS "append( \f(CW$iter\fP )"
.IX Subsection "append( $iter )"
Shorthand for \f(CW\*(C`insert_at\*(C'\fR when you want to add the contents of the passed
iterator \fIafter\fR the end of the sequence.
.ie n .SS "idx( $pos? )"
.el .SS "idx( \f(CW$pos\fP? )"
.IX Subsection "idx( $pos? )"
Returns the index (0\-based) of the current iterator cursor, or sets the
cursor if a position (again, 0\-based) is passed.
.PP
An exception is thrown if you attempt to read the cursor position before
having read any elements from the iterator, or if the iterator is empty.
.SS "next"
.IX Subsection "next"
Returns the next item in the iterator sequence, and advances the cursor.
Throws an exception if you have already reached the end of the sequence.
.SS "has_next"
.IX Subsection "has_next"
Returns true if there are further elements to be read from the iterator.
.SS "peek"
.IX Subsection "peek"
Returns the next item in the sequence without advancing the position of the
cursor. It returns \f(CW\*(C`undef\*(C'\fR if you are already at the end of the sequence.
.SS "reset"
.IX Subsection "reset"
Resets the cursor so you can iterate through the sequence of elements again.