.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "Stone::Cursor 3pm"
.TH Stone::Cursor 3pm "2021-01-05" "perl v5.32.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"
Stone::Cursor \- Traverse tags and values of a Stone
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Boulder::Store;
\&$store = Boulder::Store\->new(\*(Aq./soccer_teams\*(Aq);
\&
\& my $stone = $store\->get(28);
\& $cursor = $stone\->cursor;
\& while (my ($key,$value) = $cursor\->each) {
\&   print "$value: Go Bluejays!\en" if $key eq \*(AqState\*(Aq and $value eq \*(AqKatonah\*(Aq;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Boulder::Cursor is a utility class that allows you to create one or
more iterators across a Stone object.  This is used for traversing
large Stone objects in order to identify or modify portions of the
record.
.SS "\s-1CLASS METHODS\s0"
.IX Subsection "CLASS METHODS"
.IP "Boulder::Cursor\->new($stone)" 4
.IX Item "Boulder::Cursor->new($stone)"
Return a new Boulder::Cursor over the specified Stone object.  This
will return an error if the object is not a Stone or a
descendent. This method is usually not called directly, but rather
indirectly via the Stone \fBcursor()\fR method:
.Sp
.Vb 1
\&  my $cursor = $stone\->cursor;
.Ve
.SS "\s-1OBJECT METHODS\s0"
.IX Subsection "OBJECT METHODS"
.ie n .IP "$cursor\->\fBeach()\fR" 4
.el .IP "\f(CW$cursor\fR\->\fBeach()\fR" 4
.IX Item "$cursor->each()"
Iterate over the attached \fBStone\fR.  Each iteration will return a
two-valued list consisting of a tag path and a value.  The tag path is
of a form that can be used with \fB\fBStone::index()\fB\fR (in fact, a cursor
is used internally to implement the \fB\fBStone::dump()\fB\fR method.  When the
end of the \fBStone\fR is reached, \f(CW\*(C`each()\*(C'\fR will return an empty list,
after which it will start over again from the beginning.  If you
attempt to insert or delete from the stone while iterating over it,
all attached cursors will reset to the beginnning.
.Sp
For example:
.Sp
.Vb 4
\&        $cursor = $s\->cursor;
\&        while (($key,$value) = $cursor\->each) {
\&           print "$value: BOW WOW!\en" if $key=~/pet/;           
\&        }
.Ve
.ie n .IP "$cursor\->\fBreset()\fR" 4
.el .IP "\f(CW$cursor\fR\->\fBreset()\fR" 4
.IX Item "$cursor->reset()"
This resets the cursor back to the beginning of the associated
\&\fBStone\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln D. Stein <lstein@cshl.org>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1997\-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor
\&\s-1NY.\s0  This module can be used and distributed on the same terms as Perl
itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Boulder, Stone