Provided by: libdata-objectdriver-perl_0.22-1_all bug

NAME

       Data::ObjectDriver::ResultSet - Manage a DB query

SYNOPSIS

           # Get a resultset object for Object::Widget, which inherits from
           # Data::ObjectDriver::BaseObject
           my $result = Object::Widget->result($terms, $args);

           $result->add_term({color => 'blue'});

           $result->add_limit(10);
           $result->add_offset(100);

           while (my $widget = $result->next) {
               # Do stuff with $widget
           }

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.

       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.

METHODS

   $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.

       Arguments:

       $terms - A hashref.  Same format as the first argument to Data::ObjectDriver::DBI::search
       $args - A hashref.  Same format as the second argument to Data::ObjectDriver::DBI::search

       Return value:

       This method returns a Data::ObjectDriver::ResultSet object

   $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.

       Arguments:

       $data - An array ref of data elements

       Return value:

       A Data::ObjectDriver::ResultSet object

   add_constraint
       Apply a constraint to the result.  The format of the two arguments is the same as for
       Data::ObjectDriver::DBI::search

       Arguments:

       $terms - A hashref of object fields and values constraining them.  Same as first parameter
       to result method.
       $args - A hashref of values that affect the returned data, such as limit and sort by.
       Same as first parameter to result method.

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : Do we fail if called after we've retrieved the result set?  Ignore it?  Requery?

       ; Example

         $res->add_constraint({object_id => $id}, {limit => 100})

   add_term
       Apply a single search term to the result.  Equivalent to:

         $res->add_constraint($terms)

       Arguments:

       $terms - A hashref of object fields and values constraining them

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : Same question as for add_constraint

       ; Example

         $res->add_term({object_id => $id})

   clear_term
       Clear a single search term from the result.

       Arguments:

       @terms - An array of term names to clear

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : none

       ; Example

         $res->clear_term(qw(limit offset))

   add_limit
       Apply a limit to the result.  Equivalent to:

         $res->add_constraint({}, {limit => $limit})

       Arguments:

       $limit - A scalar numeric value giving the limit of the number of objects returned

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes :

       ; Example

         $res->add_limit(100)

   clear_limit
       Clear any limit value in the result.

       Arguments:

       none

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : None

       ; Example

         $res->clear_limit

   add_offset
       Add an offset for the results returned.  Result set must also have a limit set at some
       point.

       Arguments:

       $offset - A scalar numeric value giving the offset for the first object returned

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : none

       ; Example

         $res->add_offset(5_000)

   clear_offset
       Clear any offset value in the result.

       Arguments:

       none

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes :

       ; Example

         $res->clear_offset

   add_order
       Add a sort order for the results returned.

       Arguments:

       [0] = $order =  - A scalar string value giving the sort order for the results, one of
       ascend or descend

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : >none''

       ; Example

         $res->add_order('ascend')

   clear_order
       Clear any offset value in the result.

       Arguments:

       none

       ; Return value : Returns 1 if successful and 0 otherwise

       ; Notes : none

       ; Example

         $res->clear_order

   index
       Return the current index into the result set.

       Arguments:

       none

       ; Return value : An integer giving the zero based index of the current element in the
       result set.

       ; Notes : none

       ; Example

         $idx = $res->index;

   next
       Retrieve the next item in the resultset

       Arguments:

       none

       ; Return value : The next object or undef if past the end of the result set

       ; Notes : Calling this method will force a DB query.  All subsequent calls to curr will
       return this object

       ; Example

         $obj = $res->next;

   peek_next
       Retrieve the next item in the resultset WITHOUT advancing the cursor.

       Arguments:

       none

       ; Return value : The next object or undef if past the end of the result set

       ; Notes : Calling this method will force a DB query.  All subsequent calls to curr will
       return this object

       ; Example

         while ($bottle = $res->next){

             if ($bottle->type eq 'Bud Light'
                 && $res->peek_next->type eq 'Chimay'){

                 $bottle->pass; #don't spoil my palate

             }else{
                 $bottle->drink;
             }
         }

   prev
       Retrieve the previous item in the result set

       Arguments:

       none

       ; Return value : The previous object or undef if before the beginning of the result set

       ; Notes : All subsequent calls to curr will return this object

       ; Example

         $obj = $res->prev;

   curr
       Retrieve the current item in the result set.  This item is set by calls to next and prev

       Arguments:

       none

       ; Return value : The current object or undef if past the boundaries of the result set

       ; Notes : none

       ; Example

         $obj = $res->curr

   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 -next>.  If you call slice and then call
       next, you will get undef and additionally is_finished will be true.

       Arguments:

       $from - Scalar integer giving the start of the slice range
       $to - Scalar integer giving the end of the slice range

       ; Return value : An array of objects

       ; Notes : Objects are index from 0 just like perl arrays.

       ; Example

         my @objs = $res->slice(0, 20)

   count
       Get the count of the items in the result set.

       Arguments:

       none

       ; Return value : A scalar count of the number of items in the result set

       ; Notes : This will cause a count() 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.

       ; Example

         $num = $res->count

   is_finished
       Returns whether we've arrived at the end of the result set

       Arguments:

       none

       ; Return value : Returns 1 if we are finished iterating though the result set and 0
       otherwise

       ; Notes : none

       ; Example

         while (not $res->is_finished) {
             my $obj = $res->next;
             # Stuff ...
         }

   dod_debug
       Set this and you'll see $Data::ObjectDriver::DEBUG output when I go to get the results.

   rewind
       Move back to the start of the iterator for this instance of results of a query.

   first
       Returns the first object in the result set.

       Arguments:

       none

       ; Return value : The first object in the result set

       ; Notes : Resets the current cursor so that calls to curr return this value.

       ; Example

         $obj = $res->first

   last
       Returns the last object in the result set.

       Arguments:

       none

       ; Return value : The last object in the result set

       ; Notes : Resets the current cursor so that calls to curr return this value.

       ; Example

         $obj = $res->last

   is_last
       Returns 1 if the cursor is on the last row of the result set, 0 if it is not.

       Arguments:

       none

       ; Return value : Returns 1 if the cursor is on the last row of the result set, 0 if it is
       not.

       ; Example

         if ( $res->is_last ) {
            ## do some stuff
         }