.\" 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
.\"
.\" 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 "Data::ObjectDriver::ResultSet 3pm"
.TH Data::ObjectDriver::ResultSet 3pm "2020-11-01" "perl v5.30.3" "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"
Data::ObjectDriver::ResultSet \- Manage a DB query
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # Get a resultset object for Object::Widget, which inherits from
\&    # Data::ObjectDriver::BaseObject
\&    my $result = Object::Widget\->result($terms, $args);
\&
\&    $result\->add_term({color => \*(Aqblue\*(Aq});
\&
\&    $result\->add_limit(10);
\&    $result\->add_offset(100);
\&
\&    while (my $widget = $result\->next) {
\&        # Do stuff with $widget
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object is returned by the 'result' method found in the Data::ObjectDriver::BaseObject class.  This object manages a query and the resulting data.  It
allows additional search terms and arguments to be added and will not submit the
query until a method that returns data is called.  By passing this object around
code in multiple places can alter the query easily until the data is needed.
.PP
Once a method returning data is called (next, count, etc) the query is
submitted to the database and the returned data is managed by the ResultSet
object like an iterator.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$result_set = $class\->result($terms, $args)"
.el .SS "\f(CW$result_set\fP = \f(CW$class\fP\->result($terms, \f(CW$args\fP)"
.IX Subsection "$result_set = $class->result($terms, $args)"
This method is actually defined in Data::ObjectDriver::BaseObject but it is
the way a new ResultSet object is created.
.PP
Arguments:
.IP "\fI\f(CI$terms\fI\fR \- A hashref.  Same format as the first argument to Data::ObjectDriver::DBI::search" 4
.IX Item "$terms - A hashref. Same format as the first argument to Data::ObjectDriver::DBI::search"
.PD 0
.IP "\fI\f(CI$args\fI\fR \- A hashref.  Same format as the second argument to Data::ObjectDriver::DBI::search" 4
.IX Item "$args - A hashref. Same format as the second argument to Data::ObjectDriver::DBI::search"
.PD
.PP
Return value:
.PP
This method returns a Data::ObjectDriver::ResultSet object
.ie n .SS "$new_result = Data::ObjectDriver::ResultSet\->iterator(\e@data)"
.el .SS "\f(CW$new_result\fP = Data::ObjectDriver::ResultSet\->iterator(\e@data)"
.IX Subsection "$new_result = Data::ObjectDriver::ResultSet->iterator(@data)"
Create a new result set object that takes existing data and operates only as an
iterator, without any of the query management.
.PP
Arguments:
.ie n .IP "$data \- An array ref of data elements" 4
.el .IP "\f(CW$data\fR \- An array ref of data elements" 4
.IX Item "$data - An array ref of data elements"
.PP
Return value:
.PP
A Data::ObjectDriver::ResultSet object
.SS "add_constraint"
.IX Subsection "add_constraint"
Apply a constraint to the result.  The format of the two arguments is the same as for Data::ObjectDriver::DBI::search
.PP
Arguments:
.ie n .IP "$terms \- A hashref of object fields and values constraining them.  Same as first parameter to \fIresult\fR method." 4
.el .IP "\f(CW$terms\fR \- A hashref of object fields and values constraining them.  Same as first parameter to \fIresult\fR method." 4
.IX Item "$terms - A hashref of object fields and values constraining them. Same as first parameter to result method."
.PD 0
.ie n .IP "$args \- A hashref of values that affect the returned data, such as limit and sort by.  Same as first parameter to \fIresult\fR method." 4
.el .IP "\f(CW$args\fR \- A hashref of values that affect the returned data, such as limit and sort by.  Same as first parameter to \fIresult\fR method." 4
.IX Item "$args - A hashref of values that affect the returned data, such as limit and sort by. Same as first parameter to result method."
.PD
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: Do we fail if called after we've retrieved the result set?  Ignore it?  Requery?
.PP
; Example
.PP
.Vb 1
\&  $res\->add_constraint({object_id => $id}, {limit => 100})
.Ve
.SS "add_term"
.IX Subsection "add_term"
Apply a single search term to the result.  Equivalent to:
.PP
.Vb 1
\&  $res\->add_constraint($terms)
.Ve
.PP
Arguments:
.ie n .IP "$terms \- A hashref of object fields and values constraining them" 4
.el .IP "\f(CW$terms\fR \- A hashref of object fields and values constraining them" 4
.IX Item "$terms - A hashref of object fields and values constraining them"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: Same question as for \fIadd_constraint\fR
.PP
; Example
.PP
.Vb 1
\&  $res\->add_term({object_id => $id})
.Ve
.SS "clear_term"
.IX Subsection "clear_term"
Clear a single search term from the result.
.PP
Arguments:
.ie n .IP "@terms \- An array of term names to clear" 4
.el .IP "\f(CW@terms\fR \- An array of term names to clear" 4
.IX Item "@terms - An array of term names to clear"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: \fInone\fR
.PP
; Example
.PP
.Vb 1
\&  $res\->clear_term(qw(limit offset))
.Ve
.SS "add_limit"
.IX Subsection "add_limit"
Apply a limit to the result.  Equivalent to:
.PP
.Vb 1
\&  $res\->add_constraint({}, {limit => $limit})
.Ve
.PP
Arguments:
.ie n .IP "$limit \- A scalar numeric value giving the limit of the number of objects returned" 4
.el .IP "\f(CW$limit\fR \- A scalar numeric value giving the limit of the number of objects returned" 4
.IX Item "$limit - A scalar numeric value giving the limit of the number of objects returned"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
:
.PP
; Example
.PP
.Vb 1
\&  $res\->add_limit(100)
.Ve
.SS "clear_limit"
.IX Subsection "clear_limit"
Clear any limit value in the result.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: \fINone\fR
.PP
; Example
.PP
.Vb 1
\&  $res\->clear_limit
.Ve
.SS "add_offset"
.IX Subsection "add_offset"
Add an offset for the results returned.  Result set must also have a limit set at some point.
.PP
Arguments:
.ie n .IP "$offset \- A scalar numeric value giving the offset for the first object returned" 4
.el .IP "\f(CW$offset\fR \- A scalar numeric value giving the offset for the first object returned" 4
.IX Item "$offset - A scalar numeric value giving the offset for the first object returned"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: \fInone\fR
.PP
; Example
.PP
.Vb 1
\&  $res\->add_offset(5_000)
.Ve
.SS "clear_offset"
.IX Subsection "clear_offset"
Clear any offset value in the result.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
:
.PP
; Example
.PP
.Vb 1
\&  $res\->clear_offset
.Ve
.SS "add_order"
.IX Subsection "add_order"
Add a sort order for the results returned.
.PP
Arguments:
.ie n .IP "[0] = $order = \fI \- A scalar string value giving the sort order for the results, one of \fIascend\fI or \fIdescend\fI\fR" 4
.el .IP "[0] = \f(CW$order\fR = \fI \- A scalar string value giving the sort order for the results, one of \fIascend\fI or \fIdescend\fI\fR" 4
.IX Item "[0] = $order = - A scalar string value giving the sort order for the results, one of ascend or descend"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: >none''
.PP
; Example
.PP
.Vb 1
\&  $res\->add_order(\*(Aqascend\*(Aq)
.Ve
.SS "clear_order"
.IX Subsection "clear_order"
Clear any offset value in the result.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: Returns \fI1\fR if successful and \fI0\fR otherwise
.PP
; Notes
: \fInone\fR
.PP
; Example
.PP
.Vb 1
\&  $res\->clear_order
.Ve
.SS "index"
.IX Subsection "index"
Return the current index into the result set.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: An integer giving the zero based index of the current element in the result set.
.PP
; Notes
: \fInone\fR
.PP
; Example
.PP
.Vb 1
\&  $idx = $res\->index;
.Ve
.SS "next"
.IX Subsection "next"
Retrieve the next item in the resultset
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: The next object or undef if past the end of the result set
.PP
; Notes
: Calling this method will force a \s-1DB\s0 query.  All subsequent calls to \fIcurr\fR will return this object
.PP
; Example
.PP
.Vb 1
\&  $obj = $res\->next;
.Ve
.SS "peek_next"
.IX Subsection "peek_next"
Retrieve the next item in the resultset \s-1WITHOUT\s0 advancing the cursor.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: The next object or undef if past the end of the result set
.PP
; Notes
: Calling this method will force a \s-1DB\s0 query.  All subsequent calls to \fIcurr\fR will return this object
.PP
; Example
.PP
.Vb 1
\&  while ($bottle = $res\->next){
\&
\&      if ($bottle\->type eq \*(AqBud Light\*(Aq
\&          && $res\->peek_next\->type eq \*(AqChimay\*(Aq){
\&
\&          $bottle\->pass; #don\*(Aqt spoil my palate
\&
\&      }else{
\&          $bottle\->drink;
\&      }
\&  }
.Ve
.SS "prev"
.IX Subsection "prev"
Retrieve the previous item in the result set
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: The previous object or undef if before the beginning of the result set
.PP
; Notes
: All subsequent calls to \fIcurr\fR will return this object
.PP
; Example
.PP
.Vb 1
\&  $obj = $res\->prev;
.Ve
.SS "curr"
.IX Subsection "curr"
Retrieve the current item in the result set.  This item is set by calls to \fInext\fR and \fIprev\fR
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: The current object or undef if past the boundaries of the result set
.PP
; Notes
: \fInone\fR
.PP
; Example
.PP
.Vb 1
\&  $obj = $res\->curr
.Ve
.SS "slice"
.IX Subsection "slice"
Return a slice of the result set.  This is logically equivalent to setting a limit and offset and then retrieving all the objects via \fI\-\fRnext>.  If you call \fIslice\fR and then call \fInext\fR, you will get \fIundef\fR and additionally \fIis_finished\fR will be true.
.PP
Arguments:
.ie n .IP "$from \- Scalar integer giving the start of the slice range" 4
.el .IP "\f(CW$from\fR \- Scalar integer giving the start of the slice range" 4
.IX Item "$from - Scalar integer giving the start of the slice range"
.PD 0
.ie n .IP "$to \- Scalar integer giving the end of the slice range" 4
.el .IP "\f(CW$to\fR \- Scalar integer giving the end of the slice range" 4
.IX Item "$to - Scalar integer giving the end of the slice range"
.PD
.PP
; Return value
: An array of objects
.PP
; Notes
: Objects are index from 0 just like perl arrays.
.PP
; Example
.PP
.Vb 1
\&  my @objs = $res\->slice(0, 20)
.Ve
.SS "count"
.IX Subsection "count"
Get the count of the items in the result set.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: A scalar count of the number of items in the result set
.PP
; Notes
: This will cause a \fBcount()\fR query on the database if the result set hasn't been retrieved yet.  If the result set has been retrieved it will just return the number of objects stored in the result set object.
.PP
; Example
.PP
.Vb 1
\&  $num = $res\->count
.Ve
.SS "is_finished"
.IX Subsection "is_finished"
Returns whether we've arrived at the end of the result set
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: Returns \fI1\fR if we are finished iterating though the result set and \fI0\fR otherwise
.PP
; Notes
: \fInone\fR
.PP
; Example
.PP
.Vb 4
\&  while (not $res\->is_finished) {
\&      my $obj = $res\->next;
\&      # Stuff ...
\&  }
.Ve
.SS "dod_debug"
.IX Subsection "dod_debug"
Set this and you'll see \f(CW$Data::ObjectDriver::DEBUG\fR output when
I go to get the results.
.SS "rewind"
.IX Subsection "rewind"
Move back to the start of the iterator for this instance of results of a query.
.SS "first"
.IX Subsection "first"
Returns the first object in the result set.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: The first object in the result set
.PP
; Notes
: Resets the current cursor so that calls to \fIcurr\fR return this value.
.PP
; Example
.PP
.Vb 1
\&  $obj = $res\->first
.Ve
.SS "last"
.IX Subsection "last"
Returns the last object in the result set.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: The last object in the result set
.PP
; Notes
: Resets the current cursor so that calls to \fIcurr\fR return this value.
.PP
; Example
.PP
.Vb 1
\&  $obj = $res\->last
.Ve
.SS "is_last"
.IX Subsection "is_last"
Returns 1 if the cursor is on the last row of the result set, 0 if it is not.
.PP
Arguments:
.IP "\fInone\fR" 4
.IX Item "none"
.PP
; Return value
: Returns \fI1\fR if the cursor is on the last row of the result set, \fI0\fR if it is not.
.PP
; Example
.PP
.Vb 3
\&  if ( $res\->is_last ) {
\&     ## do some stuff
\&  }
.Ve