1Data::ObjectDriver::ResUusletrSeCto(n3t)ributed Perl DocDuamtean:t:aOtbijoenctDriver::ResultSet(3)
2
6 Data::ObjectDriver::ResultSet - Manage a DB query
7
9 # Get a resultset object for Object::Widget, which inherits from
10 # Data::ObjectDriver::BaseObject
11 my $result = Object::Widget->result($terms, $args);
12 $result->add_term({color => 'blue'});
14 $result->add_limit(10);
16 $result->add_offset(100);
17 while (not $result->is_empty) {
19 my $widget = $result->next;
20 # Do stuff with $widget
22 }
23
25 This object is returned by the 'result' method found in the
26 Data::ObjectDriver::BaseObject class. This object manages a query and
27 the resulting data. It allows additional search terms and arguments to
28 be added and will not submit the query until a method that returns data
29 is called. By passing this object around code in multiple places can
30 alter the query easily until the data is needed.
31 Once a method returning data is called (next, count, etc) the query is
33 submitted to the database and the returned data is managed by the
34 ResultSet object like an iterator.
35
37 $result_set = $class->result($terms, $args)
38 This method is actually defined in Data::ObjectDriver::BaseObject but
39 it is the way a new ResultSet object is created.
40 Arguments:
42 $terms - A hashref. Same format as the first argument to
44 Data::ObjectDriver::DBI::search
45 $args - A hashref. Same format as the second argument to
46 Data::ObjectDriver::DBI::search
47 Return value:
49 This method returns a Data::ObjectDriver::ResultSet object
51 $new_result = Data::ObjectDriver::ResultSet->iterator(\@data)
53 Create a new result set object that takes existing data and operates
54 only as an iterator, without any of the query managment.
55 Arguments:
57 $data - An array ref of data elements
59 Return value:
61 A Data::ObjectDriver::ResultSet object
63 add_constraint
65 Apply a constraint to the result. The format of the two arguments is
66 the same as for Data::ObjectDriver::DBI::search
67 Arguments:
69 $terms - A hashref of object fields and values constraining them. Same
71 as first parameter to result method.
72 $args - A hashref of values that affect the returned data, such as
73 limit and sort by. Same as first parameter to result method.
74 ; Return value : Returns 1 if successful and 0 otherwise
76 ; Notes : Do we fail if called after we've retrieved the result set?
78 Ignore it? Requery?
79 ; Example
81 $res->add_constraint({object_id => $id}, {limit => 100})
83 add_term
85 Apply a single search term to the result. Equivalent to:
86 $res->add_constraint($terms)
88 Arguments:
90 $terms - A hashref of object fields and values constraining them
92 ; Return value : Returns 1 if successful and 0 otherwise
94 ; Notes : Same question as for add_constraint
96 ; Example
98 $res->add_term({object_id => $id})
100 clear_term
102 Clear a single search term from the result.
103 Arguments:
105 @terms - An array of term names to clear
107 ; Return value : Returns 1 if successful and 0 otherwise
109 ; Notes : none
111 ; Example
113 $res->clear_term(qw(limit offset))
115 add_limit
117 Apply a limit to the result. Equivalent to:
118 $res->add_constraint({}, {limit => $limit})
120 Arguments:
122 $limit - A scalar numeric value giving the limit of the number of
124 objects returned
125 ; Return value : Returns 1 if successful and 0 otherwise
127 ; Notes :
129 ; Example
131 $res->add_limit(100)
133 clear_limit
135 Clear any limit value in the result.
136 Arguments:
138 none
140 ; Return value : Returns 1 if successful and 0 otherwise
142 ; Notes : None
144 ; Example
146 $res->clear_limit
148 add_offset
150 Add an offset for the results returned. Result set must also have a
151 limit set at some point.
152 Arguments:
154 $offset - A scalar numeric value giving the offset for the first object
156 returned
157 ; Return value : Returns 1 if successful and 0 otherwise
159 ; Notes : none
161 ; Example
163 $res->add_offset(5_000)
165 clear_offset
167 Clear any offset value in the result.
168 Arguments:
170 none
172 ; Return value : Returns 1 if successful and 0 otherwise
174 ; Notes :
176 ; Example
178 $res->clear_offset
180 add_order
182 Add a sort order for the results returned.
183 Arguments:
185 [0] = $order = - A scalar string value giving the sort order for the
187 results, one of ascend or descend
188 ; Return value : Returns 1 if successful and 0 otherwise
190 ; Notes : >none''
192 ; Example
194 $res->add_order('ascend')
196 clear_order
198 Clear any offset value in the result.
199 Arguments:
201 none
203 ; Return value : Returns 1 if successful and 0 otherwise
205 ; Notes : none
207 ; Example
209 $res->clear_order
211 index
213 Return the current index into the result set.
214 Arguments:
216 none
218 ; Return value : An integer giving the zero based index of the current
220 element in the result set.
221 ; Notes : none
223 ; Example
225 $idx = $res->index;
227 next
229 Retrieve the next item in the resultset
230 Arguments:
232 none
234 ; Return value : The next object or undef if past the end of the result
236 set
237 ; Notes : Calling this method will force a DB query. All subsequent
239 calls to curr will return this object
240 ; Example
242 $obj = $res->next;
244 peek_next
246 Retrieve the next item in the resultset WITHOUT advancing the cursor.
247 Arguments:
249 none
251 ; Return value : The next object or undef if past the end of the result
253 set
254 ; Notes : Calling this method will force a DB query. All subsequent
256 calls to curr will return this object
257 ; Example
259 while ($bottle = $res->next){
261 if ($bottle->type eq 'Bud Light'
263 && $res->peek_next->type eq 'Chimay'){
264 $bottle->pass; #don't spoil my palate
266 }else{
268 $bottle->drink;
269 }
270 }
271 prev
273 Retrieve the previous item in the result set
274 Arguments:
276 none
278 ; Return value : The previous object or undef if before the beginning
280 of the result set
281 ; Notes : All subsequent calls to curr will return this object
283 ; Example
285 $obj = $res->prev;
287 curr
289 Retrieve the current item in the result set. This item is set by calls
290 to next and prev
291 Arguments:
293 none
295 ; Return value : The current object or undef if past the boundaries of
297 the result set
298 ; Notes : none
300 ; Example
302 $obj = $res->curr
304 slice
306 Return a slice of the result set. This is logically equivalent to
307 setting a limit and offset and then retrieving all the objects via
308 -next>. If you call slice and then call next, you will get undef and
309 additionally is_empty will be true.
310 Arguments:
312 $from - Scalar integer giving the start of the slice range
314 $to - Scalar integer giving the end of the slice range
315 ; Return value : An array of objects
317 ; Notes : Objects are index from 0 just like perl arrays.
319 ; Example
321 my @objs = $res->slice(0, 20)
323 count
325 Get the count of the items in the result set.
326 Arguments:
328 none
330 ; Return value : A scalar count of the number of items in the result
332 set
333 ; Notes : This will cause a count() query on the database if the result
335 set hasn't been retrieved yet. If the result set has been retrieved it
336 will just return the number of objects stored in the result set object.
337 ; Example
339 $num = $res->count
341 is_finished
343 Returns whether we've arrived at the end of the result set
344 Arguments:
346 none
348 ; Return value : Returns 1 if we are finished iterating though the
350 result set and 0 otherwise
351 ; Notes : none
353 ; Example
355 while (not $res->is_finished) {
357 my $obj = $res->next;
358 # Stuff ...
359 }
360 dod_debug
362 Set this and you'll see $Data::ObjectDriver::DEBUG output when I go to
363 get the results.
364 rewind
366 Move back to the start of the iterator for this instance of results of
367 a query.
368 first
370 Returns the first object in the result set.
371 Arguments:
373 none
375 ; Return value : The first object in the result set
377 ; Notes : Resets the current cursor so that calls to curr return this
379 value.
380 ; Example
382 $obj = $res->first
384 last
386 Returns the last object in the result set.
387 Arguments:
389 none
391 ; Return value : The last object in the result set
393 ; Notes : Resets the current cursor so that calls to curr return this
395 value.
396 ; Example
398 $obj = $res->last
400 is_last
402 Returns 1 if the cursor is on the last row of the result set, 0 if it
403 is not.
404 Arguments:
406 none
408 ; Return value : Returns 1 if the cursor is on the last row of the
410 result set, 0 if it is not.
411 ; Example
413 if ( $res->is_last ) {
415 ## do some stuff
416 }
417perl v5.12.0 2010-03-22 Data::ObjectDriver::ResultSet(3)