Data::...sultSet(3pm)

📦

version 0.230.0 · 7 versions

0.230.0 · opensuse-leap 16.0 (latest)
0.25 · fedora 43
0.21 · ubuntu jammy
0.26 · fedora 44
0.22 · debian bookworm, ubuntu noble
0.27 · ubuntu resolute, ubuntu stonking
0.25 · debian trixie, ubuntu questing

✨ NAME ✨

Data::ObjectDriver::ResultSet — Manage a DB query.

Bestie, this is the manual for Data::ObjectDriver::ResultSet(3pm), and it's literally the object that manages your DB query and the data that comes back. 💅

🌸 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. It manages a query and the resulting data. It lets you add extra search terms and arguments, and it 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 actually 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. Slay. ✨

💅 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. It's giving "data already loaded, let's just vibe through it." 😌

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: (the original leaves this blank, bestie 🫶)

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: (blank in the original—spooky 🫥)

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'' (yes, that's literally what it says 😭)

Example:

$res->add_order('ascend')

`clear_order`

Clear any offset value in the result. (Original fr says offset here—I'm not fixing it, I'm just reporting it 💀)

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. It's giving "look, don't touch." 👀

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. That's the whole note, bestie 🫶

`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.42.0 · 2024-10-24 · Data::ObjectDriver::ResultSet(3pm) — that's the footer, bestie, mwah 💋✨

📦 where this page comes from

opensuse-leap 16.0: perl-Data-ObjectDriver 0.230.0-bp160.1.12 · Artistic-1.0 OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Data::...sultSet(3pm)

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

💅 METHODS 💅

💖 $result_set = $class->result($terms, $args) 💖

🎀 $new_result = Data::ObjectDriver::ResultSet->iterator(\@data) 🎀

add_constraint

add_term

clear_term

add_limit

clear_limit

add_offset

clear_offset

add_order

clear_order

index

next

peek_next

prev

curr

slice

count

is_finished

dod_debug

rewind

first

last

is_last

💖 `$result_set = $class->result($terms, $args)` 💖

🎀 `$new_result = Data::ObjectDriver::ResultSet->iterator(\@data)` 🎀

`add_constraint`

`add_term`

`clear_term`

`add_limit`

`clear_limit`

`add_offset`

`clear_offset`

`add_order`

`clear_order`

`index`

`next`

`peek_next`

`prev`

`curr`

`slice`

`count`

`is_finished`

`dod_debug`

`rewind`

`first`

`last`

`is_last`