NAME

DBIx::Squirrel::Iterator - an iterator over a statement's results

SYNOPSIS

my $it = $dbh->iterate(
    'SELECT id, name FROM artist WHERE name LIKE :pattern',
    pattern => 'A%',
    sub ($row) { $row->[1] },
);
while (my($name) = $it->next) {
    say $name;
}

# A stage can leave its signature out, and use $_
my @names = $dbh->iterate('SELECT id, name FROM artist', sub { $_->[1] })->all;

my $sth = $dbh->prepare(
    'SELECT * FROM artist WHERE id = $1',
    {ekorn_slice => {}},
);
my $artist = $sth->iterate(42)->single;

DESCRIPTION

An iterator executes a statement and hands out its rows one at a time, each run through a pipeline of stages, as DBIx::Squirrel::Pipeline runs them: a stage can change a row, drop it, return several values in its place, or stop the iteration with DBIx::Squirrel::Stop. A result is whatever comes out of the stages; with none, it's the row. A stage can ask about the result it's making with DBIx::Squirrel::Context.

An iterator is made by "iterate" in DBIx::Squirrel::db or "iterate" in DBIx::Squirrel::st. It executes the statement when its first result is asked for, and finishes the statement when the results run out.

Rows are fetched 100 at a time, with "fetchall_arrayref" in DBI, or, by "all" without stages, all at once; each as an array, or, with the ekorn_slice attribute, in the shape it gives:

$dbh = DBIx::Squirrel->connect($dsn, $user, $pass, {ekorn_slice => {}});
$sth = $dbh->prepare($statement, {ekorn_slice => {}});

ekorn_slice is a slice as "fetchall_arrayref" in DBI takes it: an array reference, for rows as arrays, or a hash reference, for rows as hashes. Given to connect, it's the default for each statement the handle prepares; given to prepare, it's for that statement.

One statement handle can have one iterator going through its results at a time.

METHODS

new

$it = DBIx::Squirrel::Iterator->new($sth, @bind_values, @stages);

Returns an iterator over the rows of $sth, a DBIx::Squirrel::st, executed with @bind_values, in any form "execute" in DBIx::Squirrel::st takes, and run through @stages, the code references at the end of the arguments. It doesn't execute the statement.

next

while (my($result) = $it->next) { ... }

Returns the next result, or an empty list when there are no more. A stage can return undef as a result, so read next in list context, as above, rather than testing whether what it returns is defined.

Once a stage dies, the iterator has ended: next returns an empty list on every call after, all nothing, and the statement is finished. "reset" runs it again, from the start.

all

@results = $it->all;
$count   = $it->all;

Returns the results not yet fetched, or, in scalar context, how many there were. Either way, they're fetched, and next returns nothing after.

Without stages, the rows are the results, so all takes what's left of the batch fetched last, and fetches the rest with one fetchall_arrayref, nearly as quickly as the DBI's own selectall_arrayref. With stages, each row goes through them in turn, which costs a little for each row. So to change every row of a large result, when nothing needs to stop early, map over all is quicker than a stage:

my @names = map { $_->[0] } $dbh->iterate('SELECT name FROM artist')->all;

Stages are for when the rows should come one at a time, from next, or may stop early, or should go with the statement, as in a Sugar statement.

single

$result = $it->single;

Executes the statement again, and returns its one result, or nothing if it has none. It croaks if there's more than one. Either way, it's done: next returns nothing after.

reset

$it = $it->reset;
$it = $it->reset(@bind_values, @stages);

Executes the statement again, ready to iterate from its first row, finishing it first if it's still active, and returns the iterator. Bind values given replace those given before. Stages given are added to those given to "new". Both are kept until others are given.

A statement taking a list, as "Lists" in DBIx::Squirrel::st describes, is prepared again, on a new statement handle, if a list given has a different number of values from the one before; "sth" then returns the new handle.

count

$n = $it->count;

Returns the number of results fetched so far.

column_names

@names = $it->column_names;

Returns the names of the statement's columns, as fetchrow_hashref would key them, following the FetchHashKeyName attribute, executing the statement first if it hasn't been. They're read when it's executed, as some drivers, such as DBD::mysql, give none once the last row is fetched. A statement without columns has none, as does one that couldn't be executed. A stage can ask for them through "iterator" in DBIx::Squirrel::Context.

sth

$sth = $it->sth;

Returns the statement handle, which changes if "reset" prepares a statement taking a list again.

DIAGNOSTICS

Expected a statement handle

"new" wasn't given a DBIx::Squirrel::st.

Expected one result, not more

"single" found a second result.

Expected the statement handle's other iterator to be finished

The iterator's statement handle has another iterator, which has results left to hand out. Read that one to the end, or let it go out of scope, before executing this one.

SEE ALSO

DBIx::Squirrel, DBIx::Squirrel::Context, DBIx::Squirrel::Pipeline

AUTHOR

Iain Campbell <cpanic@cpan.org>

LICENSE

Copyright (c) 2024-2026 by Iain Campbell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.