Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::ObjectDriver::ReUserSContributed Perl DoData::ObjectDriver::ResultSet(3)

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
	 }

perl v5.24.1			  2017-04-19  Data::ObjectDriver::ResultSet(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::ObjectDriver::ResultSet&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help