1Data::ObjectDriver::ResUusletrSeCto(n3tprmi)buted Perl DDoactuam:e:nOtbajteicotnDriver::ResultSet(3pm)
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 (my $widget = $result->next) {
19 # Do stuff with $widget
20 }
21
23 This object is returned by the 'result' method found in the
24 Data::ObjectDriver::BaseObject class. This object manages a query and
25 the resulting data. It allows additional search terms and arguments to
26 be added and will not submit the query until a method that returns data
27 is called. By passing this object around code in multiple places can
28 alter the query easily until the data is needed.
29 Once a method returning data is called (next, count, etc) the query is
31 submitted to the database and the returned data is managed by the
32 ResultSet object like an iterator.
33
35 $result_set = $class->result($terms, $args)
36 This method is actually defined in Data::ObjectDriver::BaseObject but
37 it is the way a new ResultSet object is created.
38 Arguments:
40 $terms - A hashref. Same format as the first argument to
42 Data::ObjectDriver::DBI::search
43 $args - A hashref. Same format as the second argument to
44 Data::ObjectDriver::DBI::search
45 Return value:
47 This method returns a Data::ObjectDriver::ResultSet object
49 $new_result = Data::ObjectDriver::ResultSet->iterator(\@data)
51 Create a new result set object that takes existing data and operates
52 only as an iterator, without any of the query management.
53 Arguments:
55 $data - An array ref of data elements
57 Return value:
59 A Data::ObjectDriver::ResultSet object
61 add_constraint
63 Apply a constraint to the result. The format of the two arguments is
64 the same as for Data::ObjectDriver::DBI::search
65 Arguments:
67 $terms - A hashref of object fields and values constraining them. Same
69 as first parameter to result method.
70 $args - A hashref of values that affect the returned data, such as
71 limit and sort by. Same as first parameter to result method.
72 ; Return value : Returns 1 if successful and 0 otherwise
74 ; Notes : Do we fail if called after we've retrieved the result set?
76 Ignore it? Requery?
77 ; Example
79 $res->add_constraint({object_id => $id}, {limit => 100})
81 add_term
83 Apply a single search term to the result. Equivalent to:
84 $res->add_constraint($terms)
86 Arguments:
88 $terms - A hashref of object fields and values constraining them
90 ; Return value : Returns 1 if successful and 0 otherwise
92 ; Notes : Same question as for add_constraint
94 ; Example
96 $res->add_term({object_id => $id})
98 clear_term
100 Clear a single search term from the result.
101 Arguments:
103 @terms - An array of term names to clear
105 ; Return value : Returns 1 if successful and 0 otherwise
107 ; Notes : none
109 ; Example
111 $res->clear_term(qw(limit offset))
113 add_limit
115 Apply a limit to the result. Equivalent to:
116 $res->add_constraint({}, {limit => $limit})
118 Arguments:
120 $limit - A scalar numeric value giving the limit of the number of
122 objects returned
123 ; Return value : Returns 1 if successful and 0 otherwise
125 ; Notes :
127 ; Example
129 $res->add_limit(100)
131 clear_limit
133 Clear any limit value in the result.
134 Arguments:
136 none
138 ; Return value : Returns 1 if successful and 0 otherwise
140 ; Notes : None
142 ; Example
144 $res->clear_limit
146 add_offset
148 Add an offset for the results returned. Result set must also have a
149 limit set at some point.
150 Arguments:
152 $offset - A scalar numeric value giving the offset for the first object
154 returned
155 ; Return value : Returns 1 if successful and 0 otherwise
157 ; Notes : none
159 ; Example
161 $res->add_offset(5_000)
163 clear_offset
165 Clear any offset value in the result.
166 Arguments:
168 none
170 ; Return value : Returns 1 if successful and 0 otherwise
172 ; Notes :
174 ; Example
176 $res->clear_offset
178 add_order
180 Add a sort order for the results returned.
181 Arguments:
183 [0] = $order = - A scalar string value giving the sort order for the
185 results, one of ascend or descend
186 ; Return value : Returns 1 if successful and 0 otherwise
188 ; Notes : >none''
190 ; Example
192 $res->add_order('ascend')
194 clear_order
196 Clear any offset value in the result.
197 Arguments:
199 none
201 ; Return value : Returns 1 if successful and 0 otherwise
203 ; Notes : none
205 ; Example
207 $res->clear_order
209 index
211 Return the current index into the result set.
212 Arguments:
214 none
216 ; Return value : An integer giving the zero based index of the current
218 element in the result set.
219 ; Notes : none
221 ; Example
223 $idx = $res->index;
225 next
227 Retrieve the next item in the resultset
228 Arguments:
230 none
232 ; Return value : The next object or undef if past the end of the result
234 set
235 ; Notes : Calling this method will force a DB query. All subsequent
237 calls to curr will return this object
238 ; Example
240 $obj = $res->next;
242 peek_next
244 Retrieve the next item in the resultset WITHOUT advancing the cursor.
245 Arguments:
247 none
249 ; Return value : The next object or undef if past the end of the result
251 set
252 ; Notes : Calling this method will force a DB query. All subsequent
254 calls to curr will return this object
255 ; Example
257 while ($bottle = $res->next){
259 if ($bottle->type eq 'Bud Light'
261 && $res->peek_next->type eq 'Chimay'){
262 $bottle->pass; #don't spoil my palate
264 }else{
266 $bottle->drink;
267 }
268 }
269 prev
271 Retrieve the previous item in the result set
272 Arguments:
274 none
276 ; Return value : The previous object or undef if before the beginning
278 of the result set
279 ; Notes : All subsequent calls to curr will return this object
281 ; Example
283 $obj = $res->prev;
285 curr
287 Retrieve the current item in the result set. This item is set by calls
288 to next and prev
289 Arguments:
291 none
293 ; Return value : The current object or undef if past the boundaries of
295 the result set
296 ; Notes : none
298 ; Example
300 $obj = $res->curr
302 slice
304 Return a slice of the result set. This is logically equivalent to
305 setting a limit and offset and then retrieving all the objects via
306 -next>. If you call slice and then call next, you will get undef and
307 additionally is_finished will be true.
308 Arguments:
310 $from - Scalar integer giving the start of the slice range
312 $to - Scalar integer giving the end of the slice range
313 ; Return value : An array of objects
315 ; Notes : Objects are index from 0 just like perl arrays.
317 ; Example
319 my @objs = $res->slice(0, 20)
321 count
323 Get the count of the items in the result set.
324 Arguments:
326 none
328 ; Return value : A scalar count of the number of items in the result
330 set
331 ; Notes : This will cause a count() query on the database if the result
333 set hasn't been retrieved yet. If the result set has been retrieved it
334 will just return the number of objects stored in the result set object.
335 ; Example
337 $num = $res->count
339 is_finished
341 Returns whether we've arrived at the end of the result set
342 Arguments:
344 none
346 ; Return value : Returns 1 if we are finished iterating though the
348 result set and 0 otherwise
349 ; Notes : none
351 ; Example
353 while (not $res->is_finished) {
355 my $obj = $res->next;
356 # Stuff ...
357 }
358 dod_debug
360 Set this and you'll see $Data::ObjectDriver::DEBUG output when I go to
361 get the results.
362 rewind
364 Move back to the start of the iterator for this instance of results of
365 a query.
366 first
368 Returns the first object in the result set.
369 Arguments:
371 none
373 ; Return value : The first object in the result set
375 ; Notes : Resets the current cursor so that calls to curr return this
377 value.
378 ; Example
380 $obj = $res->first
382 last
384 Returns the last object in the result set.
385 Arguments:
387 none
389 ; Return value : The last object in the result set
391 ; Notes : Resets the current cursor so that calls to curr return this
393 value.
394 ; Example
396 $obj = $res->last
398 is_last
400 Returns 1 if the cursor is on the last row of the result set, 0 if it
401 is not.
402 Arguments:
404 none
406 ; Return value : Returns 1 if the cursor is on the last row of the
408 result set, 0 if it is not.
409 ; Example
411 if ( $res->is_last ) {
413 ## do some stuff
414 }
415perl v5.34.0 2022-01-21Data::ObjectDriver::ResultSet(3pm)