List::...:Typed(3pm)

💖 List::Objects::WithUtils::Role::Array::Typed — the vibe check edition 💖

okay bestie, so this is a User Contributed Perl Documentation page for a Perl module called List::Objects::WithUtils::Role::Array::Typed, and honestly? it's giving type-checking array behavior and nothing less. the manual name is a mouthful but we move 💅

---

✨ NAME ✨

List::Objects::WithUtils::Role::Array::Typed — it's a role that does type-checking array behavior. that's the whole thing. that's the assignment. periodt.

---

🌸 SYNOPSIS 🌸

okay so first you gotta roll up like this — via List::Objects::WithUtils::Array::Typed:

use List::Objects::WithUtils 'array_of';
use Types::Standard -all;
use List::Objects::Types -all;

# Array of Ints:
my $arr = array_of Int() => (1,2,3);

# Array of array objects of Ints (coerced from ARRAYs):
my $arr = array_of TypedArray[Int] => [1,2,3], [4,5,6];

look at that. an array of Ints, and then an array of array objects of Ints that got coerced from ARRAYs. the way that just works 😭👑

---

🦋 DESCRIPTION 🦋

so this role is the main character that uses Type::Tie to sprinkle type-checking behavior onto all the consumers of List::Objects::WithUtils::Role::Array. no cap, it's literally just vibes with a safety net.

here's the important bit: the first argument you hand to the constructor should be a Type::Tiny type — or any other object that conforms to Type::API, as of v2.25:

use Types::Standard -all;
my $arr = array_of Str() => qw/foo bar baz/;

and every single element gets checked against the type you specified when the object is constructed or when new elements are added. every one. she is thorough.

and if that initial type-check fails? bestie, a coercion is attempted. so she's not just gonna give up on you immediately, she's gonna try to make it work first 🫶

but — and this is the serious part — values that cannot be coerced will throw an exception. like, an actual exception. so don't play games. 💀

also go peek at Types::Standard and List::Objects::Types, they're the supporting cast. also see them, fr fr.

🔥 type 🔥

returns the Type::Tiny type that the object was created with. like, it tells you her whole origin story. iconic.

🌈 untyped 🌈

returns a (shallow) clone that is a plain List::Objects::WithUtils::Array. no type checking, no drama, just a regular little list object living her life.

and here's why you'd want that: since most methods that return a new list will (attempt to) return a list object of the same type as their parent, this can be super useful to avoid type check failures in a method chain that creates intermediate lists. basically it's the escape hatch for when your chain keeps making little baby lists that don't pass the vibe check. use it wisely 💅

---

💜 AUTHOR 💜

Jon Portnoy <avenj@cobaltirc.org> with significant contributions from Toby Inkster (CPAN: TOBYINK). we stan both of them honestly, they ate 🔥

---

okay and for the lil sign-off: this whole thing is running on perl v5.38.2, dated 2024-03-07, and it's part of the User Contributed Perl Documentation set. go forth and type-check your arrays, bestie, you got this 🎀✨🦋