1Data::ObjectDriver::ResUusletrSeCto(n3tprmi)buted Perl DDoactuam:e:nOtbajteicotnDriver::ResultSet(3pm)
2
3
4

NAME

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

SYNOPSIS

9           # Get a resultset object for Object::Widget, which inherits from
10           # Data::ObjectDriver::BaseObject
11           my $result = Object::Widget->result($terms, $args);
12
13           $result->add_term({color => 'blue'});
14
15           $result->add_limit(10);
16           $result->add_offset(100);
17
18           while (my $widget = $result->next) {
19               # Do stuff with $widget
20           }
21

DESCRIPTION

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
30       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

METHODS

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
39       Arguments:
40
41       $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
46       Return value:
47
48       This method returns a Data::ObjectDriver::ResultSet object
49
50   $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
54       Arguments:
55
56       $data - An array ref of data elements
57
58       Return value:
59
60       A Data::ObjectDriver::ResultSet object
61
62   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
66       Arguments:
67
68       $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
73       ; Return value : Returns 1 if successful and 0 otherwise
74
75       ; Notes : Do we fail if called after we've retrieved the result set?
76       Ignore it?  Requery?
77
78       ; Example
79
80         $res->add_constraint({object_id => $id}, {limit => 100})
81
82   add_term
83       Apply a single search term to the result.  Equivalent to:
84
85         $res->add_constraint($terms)
86
87       Arguments:
88
89       $terms - A hashref of object fields and values constraining them
90
91       ; Return value : Returns 1 if successful and 0 otherwise
92
93       ; Notes : Same question as for add_constraint
94
95       ; Example
96
97         $res->add_term({object_id => $id})
98
99   clear_term
100       Clear a single search term from the result.
101
102       Arguments:
103
104       @terms - An array of term names to clear
105
106       ; Return value : Returns 1 if successful and 0 otherwise
107
108       ; Notes : none
109
110       ; Example
111
112         $res->clear_term(qw(limit offset))
113
114   add_limit
115       Apply a limit to the result.  Equivalent to:
116
117         $res->add_constraint({}, {limit => $limit})
118
119       Arguments:
120
121       $limit - A scalar numeric value giving the limit of the number of
122       objects returned
123
124       ; Return value : Returns 1 if successful and 0 otherwise
125
126       ; Notes :
127
128       ; Example
129
130         $res->add_limit(100)
131
132   clear_limit
133       Clear any limit value in the result.
134
135       Arguments:
136
137       none
138
139       ; Return value : Returns 1 if successful and 0 otherwise
140
141       ; Notes : None
142
143       ; Example
144
145         $res->clear_limit
146
147   add_offset
148       Add an offset for the results returned.  Result set must also have a
149       limit set at some point.
150
151       Arguments:
152
153       $offset - A scalar numeric value giving the offset for the first object
154       returned
155
156       ; Return value : Returns 1 if successful and 0 otherwise
157
158       ; Notes : none
159
160       ; Example
161
162         $res->add_offset(5_000)
163
164   clear_offset
165       Clear any offset value in the result.
166
167       Arguments:
168
169       none
170
171       ; Return value : Returns 1 if successful and 0 otherwise
172
173       ; Notes :
174
175       ; Example
176
177         $res->clear_offset
178
179   add_order
180       Add a sort order for the results returned.
181
182       Arguments:
183
184       [0] = $order =  - A scalar string value giving the sort order for the
185       results, one of ascend or descend
186
187       ; Return value : Returns 1 if successful and 0 otherwise
188
189       ; Notes : >none''
190
191       ; Example
192
193         $res->add_order('ascend')
194
195   clear_order
196       Clear any offset value in the result.
197
198       Arguments:
199
200       none
201
202       ; Return value : Returns 1 if successful and 0 otherwise
203
204       ; Notes : none
205
206       ; Example
207
208         $res->clear_order
209
210   index
211       Return the current index into the result set.
212
213       Arguments:
214
215       none
216
217       ; Return value : An integer giving the zero based index of the current
218       element in the result set.
219
220       ; Notes : none
221
222       ; Example
223
224         $idx = $res->index;
225
226   next
227       Retrieve the next item in the resultset
228
229       Arguments:
230
231       none
232
233       ; Return value : The next object or undef if past the end of the result
234       set
235
236       ; Notes : Calling this method will force a DB query.  All subsequent
237       calls to curr will return this object
238
239       ; Example
240
241         $obj = $res->next;
242
243   peek_next
244       Retrieve the next item in the resultset WITHOUT advancing the cursor.
245
246       Arguments:
247
248       none
249
250       ; Return value : The next object or undef if past the end of the result
251       set
252
253       ; Notes : Calling this method will force a DB query.  All subsequent
254       calls to curr will return this object
255
256       ; Example
257
258         while ($bottle = $res->next){
259
260             if ($bottle->type eq 'Bud Light'
261                 && $res->peek_next->type eq 'Chimay'){
262
263                 $bottle->pass; #don't spoil my palate
264
265             }else{
266                 $bottle->drink;
267             }
268         }
269
270   prev
271       Retrieve the previous item in the result set
272
273       Arguments:
274
275       none
276
277       ; Return value : The previous object or undef if before the beginning
278       of the result set
279
280       ; Notes : All subsequent calls to curr will return this object
281
282       ; Example
283
284         $obj = $res->prev;
285
286   curr
287       Retrieve the current item in the result set.  This item is set by calls
288       to next and prev
289
290       Arguments:
291
292       none
293
294       ; Return value : The current object or undef if past the boundaries of
295       the result set
296
297       ; Notes : none
298
299       ; Example
300
301         $obj = $res->curr
302
303   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
309       Arguments:
310
311       $from - Scalar integer giving the start of the slice range
312       $to - Scalar integer giving the end of the slice range
313
314       ; Return value : An array of objects
315
316       ; Notes : Objects are index from 0 just like perl arrays.
317
318       ; Example
319
320         my @objs = $res->slice(0, 20)
321
322   count
323       Get the count of the items in the result set.
324
325       Arguments:
326
327       none
328
329       ; Return value : A scalar count of the number of items in the result
330       set
331
332       ; 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
336       ; Example
337
338         $num = $res->count
339
340   is_finished
341       Returns whether we've arrived at the end of the result set
342
343       Arguments:
344
345       none
346
347       ; Return value : Returns 1 if we are finished iterating though the
348       result set and 0 otherwise
349
350       ; Notes : none
351
352       ; Example
353
354         while (not $res->is_finished) {
355             my $obj = $res->next;
356             # Stuff ...
357         }
358
359   dod_debug
360       Set this and you'll see $Data::ObjectDriver::DEBUG output when I go to
361       get the results.
362
363   rewind
364       Move back to the start of the iterator for this instance of results of
365       a query.
366
367   first
368       Returns the first object in the result set.
369
370       Arguments:
371
372       none
373
374       ; Return value : The first object in the result set
375
376       ; Notes : Resets the current cursor so that calls to curr return this
377       value.
378
379       ; Example
380
381         $obj = $res->first
382
383   last
384       Returns the last object in the result set.
385
386       Arguments:
387
388       none
389
390       ; Return value : The last object in the result set
391
392       ; Notes : Resets the current cursor so that calls to curr return this
393       value.
394
395       ; Example
396
397         $obj = $res->last
398
399   is_last
400       Returns 1 if the cursor is on the last row of the result set, 0 if it
401       is not.
402
403       Arguments:
404
405       none
406
407       ; Return value : Returns 1 if the cursor is on the last row of the
408       result set, 0 if it is not.
409
410       ; Example
411
412         if ( $res->is_last ) {
413            ## do some stuff
414         }
415
416
417
418perl v5.34.0                      2021-07-22Data::ObjectDriver::ResultSet(3pm)
Impressum