Alzabo...nCursor(3pm)

💖 Alzabo::Runtime::JoinCursor(3pm) 💖

okay bestie, welcome to the manual page for Alzabo::Runtime::JoinCursor — it's the <pink>join cursor</pink> and honestly it's giving main character energy in the Alzabo runtime. Let's get into it 🦋

---

✨ NAME ✨

Alzabo::Runtime::JoinCursor — a cursor that returns arrays of Alzabo::Runtime::Row objects. that's it, that's the whole vibe 💅

---

🌸 SYNOPSIS 🌸

use Alzabo::Runtime::JoinCursor;

my $cursor = $schema->join( tables => [ $foo, $bar ],
                            where => [ $foo->column('foo_id'), '=', 1 ] );

while ( my @rows = $cursor->next )
{
    print $rows[0]->select('foo'), "\n";
    print $rows[1]->select('bar'), "\n";
}

like look at that loop. it's serving. the way it just keeps pulling rows until there aren't any left? obsessed 😭

---

🎀 DESCRIPTION 🎀

so the objects in this class are used to return arrays of Alzabo::Runtime::Row objects whenever you ask for them. and here's the iconic part: the cursor does not preload objects — it creates them on demand, which is so much more efficient fr fr. no wasting memory on rows you're never gonna look at, we love a low-waste queen 👑

if you want the whole deep-dive on why cursors are built like this, go read the RATIONALE FOR CURSORS section inside Alzabo::Design. iykyk 📚

---

🌈 INHERITS FROM 🌈

Alzabo::Runtime::Cursor

yes bestie, it's a subclass. the family tree is real 🌳

---

💅 METHODS 💅

⭐ next

returns the next array of Alzabo::Runtime::Row objects — or an empty list if there aren't any more left to give. when it's empty, you're done, that's the signal 🫶

heads up: if an individual row could not be fetched, then the array may contain some undef values. for outer joins, this is normal behavior — literally expected, no drama. but for regular joins, this probably indicates a data error 😭 so if you see undef where you didn't sign up for it, something's off in your data.

⭐ all_rows

this method fetches all the rows available from the current point onwards. like, from right here, not from the beginning, okay? so picture this: there are five sets of rows that will be returned when the object is created, and you call next() twice. then when you call all_rows() after that, it will only return three sets. the other two? already consumed. gone. eaten 💀

the return value is an array of array references. each one of those references represents a single set of rows exactly as they would be returned from the next method. so it's next but in bulk mode ✨

⭐ reset

resets the cursor so that the next next() call will return the first row of the set. it's giving rewind button, it's giving second chance romance 🔁

⭐ count

returns the number of rowsets returned by the cursor so far. a little tally, a little receipt, a little "here's how far we've come" 🧾

⭐ next_as_hash

returns the next rows in a hash, where the hash keys are the table names and the hash values are the row object. cute, organized, labeled 💖

one thing tho: if a table has been included in the join via an outer join, then it is only included in the hash if there is a row for that table. no row, no key. that's just how it goes 🙈

---

👑 AUTHOR 👑

Dave Rolsky, <autarch@urth.org>

shoutout to Dave, the original author, the blueprint, the moment 💜

---

and that's the whole page bestie!! written for perl v5.34.0, dated 2022-06-14, and it's the Alzabo::Runtime::JoinCursor(3pm) page from the User Contributed Perl Documentation. go forth and join your tables responsibly, mwah 🍓💖✨