Data::...::Array(3pm)

💖 NAME 💖

Data::Perl::Role::Collection::Array — a wrapping class for Perl's built-in array structure. yes bestie, it's exactly what it sounds like 🫶

---

✨ VERSION ✨

version 0.002011

---

🌸 SYNOPSIS 🌸

use Data::Perl qw/array/;

my $array = array(1, 2, 3);

$array->push(5);

$array->grep(sub { $_ > 2 })->map(sub { $_ ** 2 })->elements; # (3, 5);

---

🦋 DESCRIPTION 🦋

okay so this class is a whole wrapper + method collection for messing around with an array. it's giving "array but make it an object" 💅

and here's the tea: every method that returns a list does it through a Data::Perl::Collection::Array object. not a bare list. an object. keep that in mind, it's lowkey the most important thing here 👑

---

🎀 PROVIDED METHODS 🎀

new($value, $value, ....)

Builds you a brand-new Data::Perl::Collection::Array object, all filled up with the values you handed over, and gives it right back to you. iconic behavior fr fr ✨

count

Tells you how many elements are chilling in the array. that's it. that's the method.

$stuff = Data::Perl::Collection::Array->new(qw/foo bar baz boo/);

print $stuff->count; # prints 4

This method does not accept any arguments. no notes. 🚫

is_empty

Returns a boolean that's true when the array has literally zero elements. vibe check: is it empty or not 💀

$stuff->is_empty ? die "No options!\n" : print "Good boy.\n";

This method does not accept any arguments. periodt.

elements/all

Returns ALL the elements of the array as an actual array (not an array reference!! important!!).

my @options = $stuff->elements;
print "@options\n";    # prints "foo bar baz boo"

This method does not accept any arguments. slay.

get($index)

Grabs you one element by its index. and yes you can use negative index numbers too, exactly like Perl's core array handling does. it's the same energy 🧚

my $option = $stuff->get(1);
print "$option\n";    # prints "bar"

If the element you asked for doesn't exist, this returns undef. sobbing.

This method accepts just one argument.

pop

Just like Perl's builtin pop. we love a classic 💅

This method does not accept any arguments.

push($value1, $value2, value3 ...)

Just like Perl's builtin push. it returns the number of elements in the new array, so you know how big things got 📈

This method accepts any number of arguments.

shift

Just like Perl's builtin shift. no cap.

This method does not accept any arguments.

unshift($value1, $value2, value3 ...)

Just like Perl's builtin unshift. it hands back the number of elements in the new array.

This method accepts any number of arguments.

splice($offset, $length, @values)

Just like Perl's builtin splice. plot twist incoming 👀 — in scalar context it returns the last element that got removed, or undef if literally nothing was removed. in list context it returns all the removed elements, all wrapped up in a Collection::Array object.

This method requires at least one argument.

first( sub { ... } )

Returns the first matching item in the array, exactly like List::Util's first function. the matching is done with a subroutine reference YOU pass in. that sub gets called against each element until one of them matches, or until every single element has been checked and nobody matched 😭

my $found = $stuff->find_option( sub {/^b/} );
print "$found\n";    # prints "bar"

This method requires a single argument.

first_index( sub { ... } )

Returns the index of the first matching item in the array, just like List::MoreUtils's first_index function. again, the matching runs through the subroutine reference you passed. the sub gets called on each element until something matches or all elements have been checked.

This method requires a single argument.

grep( sub { ... } )

Returns every element that matches a given criteria, just like Perl's core grep function. you gotta pass a subroutine that implements the matching logic. and the returned list comes back as a Collection::Array object ✨

my @found = $stuff->grep( sub {/^b/} );
print "@found\n";    # prints "bar baz boo"

This method requires a single argument.

map( sub { ... } )

Transforms every element in the array and returns a fresh new array, just like Perl's core map function. you pass a subroutine that implements the transformation. and yeah, the returned list is a Collection::Array object 🦋

my @mod_options = $stuff->map( sub { $_ . "-tag" } );
print "@mod_options\n";    # prints "foo-tag bar-tag baz-tag boo-tag"

This method requires a single argument.

reduce( sub { ... } )

Turns a whole array into a single value by passing a function the value-so-far and the next value in the array, just like List::Util's reduce function. the reducing happens through the subroutine reference you pass in. main character energy tbh 👑

my $found = $stuff->reduce( sub { $_[0] . $_[1] } );
print "$found\n";    # prints "foobarbazboo"

This method requires a single argument.

sort

sort( sub { ... } )

Returns the elements of the array in sorted order.

You can hand over an optional subroutine reference to sort with (same deal as Perl's core sort function). BUT. and this is the part everyone gets wrong — instead of using $a and $b inside that subroutine, you need to use $_[0] and $_[1]. don't forget it, bestie 🫠 The returned list is provided as a Collection::Array object.

# ascending ASCIIbetical
my @sorted = $stuff->sort();

# Descending alphabetical order
my @sorted_options = $stuff->sort( sub { lc $_[1] cmp lc $_[0] } );
print "@sorted_options\n";    # prints "foo boo baz bar"

This method accepts a single argument.

sort_in_place

sort_in_place( sub { ... } )

Sorts the array in place, meaning it actually modifies the value of the attribute. it changes the thing itself, not a copy 🔥

You can pass an optional subroutine reference to sort with (again, just like Perl's core sort function). but instead of $a and $b, you use $_[0] and $_[1]. The returned list is provided as a Collection::Array object.

This method accepts a single argument.

reverse

Returns the elements of the array in reversed order. The returned list is provided as a Collection::Array object.

This method does not accept any arguments.

shuffle

Returns the elements of the array in random order, like shuffle from List::Util. The returned list is provided as a Collection::Array object. chaos but make it a feature 🎲

This method does not accept any arguments.

uniq

Returns the array with all duplicate elements removed, like uniq from List::MoreUtils. The returned list is provided as a Collection::Array object. dedupe era 💅

This method does not accept any arguments.

head($count)

Returns the first $count elements of the array. If $count is bigger than the number of elements in the array, you just get the array back (and no, without any spurious undefs sneaking in 🙈). A negative $count means "all but the last $count elements". The returned list is provided as a Collection::Array object.

tail($count)

Returns the last $count elements of the array. If $count is bigger than the number of elements in the array, you get the array back (again, no spurious undefs ✨). A negative $count means "all but the first $count elements". The returned list is provided as a Collection::Array object.

join($str)

Joins every element of the array using the separator you give it as the argument, just like Perl's core join function.

my $joined = $stuff->join(':');
print "$joined\n";    # prints "foo:bar:baz:boo"

This method requires a single argument.

print($handle, $str)

Prints the output of join($str) to $handle. $handle defaults to STDOUT, and join $str defaults to join()'s default of ','.

$joined = $stuff->print(*STDERR, ';'); # prints foo;bar;baz to STDERR

set($index, $value)

Given an index and a value, it sets the specified array element's value. simple as that.

This method returns the value at $index after the set.

This method requires two arguments.

delete($index)

Removes the element at the given index from the array. gone. bye bestie 👋

This method returns the deleted value, either as an array or scalar as dependent on splice context semantics. Note that if no value exists, it will

return undef.

This method requires one argument.

insert($index, $value)

Inserts a new element into the array at the given index. making room, we love to see it 🌸

This method returns the new value at $index, either as an array or scalar as dependent on splice context semantics.

This method requires two arguments.

clear

Empties the entire array, like @array = (). nuked. gone. empty. 💀

This method does not define a return value.

This method does not accept any arguments.

accessor($index)

accessor($index, $value)

Provides a get/set accessor for the array, based on array indexes. If you pass one argument, it returns the value at the specified index. If you pass two arguments, it sets the value of the specified index. one method, two moods 🫶

When called as a setter, this method returns the new value at $index.

This method accepts one or two arguments.

natatime($n)

natatime($n, $code)

Returns an iterator which, on each call, returns $n more items from the array, in order, like natatime from List::MoreUtils. You can optionally hand it a coderef; it will be called on each group of $n elements in the array. batch processing but make it cute 🎀

This method accepts one or two arguments.

shallow_clone

Returns a shallow clone of the array reference. The return value is a reference to a new array with the same elements. It's shallow because any elements that were references in the original will be the same references in the clone. same objects, different wrapper, iykyk 🪞

flatten

Returns a list of elements in the array. This method is an alias to the elements method. same thing, different name ✨

flatten_deep($level)

Returns a flattened list of elements in the array. It'll flatten arrays contained within the root array recursively — and the depth is controlled by the optional $level parameter. down the rabbit hole we go 🕳️🐇

---

💜 SEE ALSO 💜

• Data::Perl
• MooX::HandlesVia

---

👑 AUTHOR 👑

Matthew Phillips <mattp@cpan.org>

---

🌈 COPYRIGHT AND LICENSE 🌈

This software is copyright (c) 2020 by Matthew Phillips <mattp@cpan.org>.

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

---

and that's the whole page, bestie! 🥳 this gem came to you courtesy of perl v5.36.0, dated 2022-10-16, and yes that version string is on Data::...::Array(3pm) — go forth and array responsibly, mwah 💋🫶