Statis...dVector(3pm)

🦋 Statis...dVector(3pm) — like, the whole vibe 💅

okay bestie, sit down, hydrate, and let's talk about a page from the User Contributed Perl Documentation — it's called Statis...dVector(3pm) and it's genuinely so good. this is your girl explaining filtered vectors like we're texting at 1am. no cap. 🎀

---

✨ NAME ✨

Statistics::Basic::ComputedVector — a whole class dedicated to computing filtered vectors. it's giving "vector but make it bespoke." 👑

---

🌸 SYNOPSIS 🌸

so here's how you summon it, fr fr:

my $vector   = vector(1,2,3);
my $computed = computed($vector)->set_filter(sub{
    # NOTE: only interested in even numbers:
    grep { !($_ % 2) } @_
});

# nearly the same, opposite order:

my $computed = computed(1,2,3)->set_filter(sub {map{$_+1}@_});
my $vector   = $computed->query_vector;

see how the order can flip and it still eats? versatile icon behavior ✨

---

💖 METHODS 💖

new()

the constructor, obviously. it takes a single array ref OR a single Statistics::Basic::ComputedVector as its argument, and it hands you back a Statistics::Basic::ComputedVector object. slay.

if you pass it stuff that isn't Statistics::Basic::Vector objects, it'll build an appropriate vector object for you anyway — and you can go grab it later with query_vector(). 💁♀️

ngl, normally you'd just use the computed() constructor instead of hand-building these with new(). just saying. 🙈

---

copy()

makes a brand new computed vector object that points at the same source vector and uses the same filter as this one. twin energy. 🫶

my $v1 = vector(1,2,3);
my $c1 = computed($v1); $c1->set_filter(my $s = sub {});

my $copy1 = computed($v1); $copy1->set_filter($s);
my $copy2 = $c1->copy; # just like $c2, but in one step

but if what you actually want is a filtered version of a filtered vector, choose this form instead:

my $v1 = vector(1,2,3);
my $c1 = computed($v1); $c1->set_filter(sub {});
my $c2 = computed($c1); $c2->set_filter(sub {});

layers on layers, bestie. 🧚

---

insert()

drops new values into the input vector. and if that vector was already full (peep set_size()), this will also shift the oldest elements out of the input vector to compensate. balance, babe. ⚖️

$computed->insert( 4, 3 ); # insert a 3 and a 4

heads up: continuing from the SYNOPSIS example, this would certainly insert a 4 and a 3 into the input vector, but the 3 wouldn't be returned from a query() because it is odd. tragic. 💀

this function returns the object itself, for chaining purposes. yes queen, chain away. 🔗

---

append() / ginsert()

same idea — new values go into the input vector. but if the vector was already full (again: set_size()), these two will grow the size of the input vector to fit the new values, rather than shifting things out. expanding, not evicting. 🌱

$computed->append( 4, 3 ); # append a 3 and a 4

same warning as before, no cap: from the SYNOPSIS example, this would certainly insert a 4 and a 3 into the input vector, but the 3 wouldn't be returned from a query() because it is odd. 😭

this function returns the object itself, for chaining purposes. 🔥

---

query()

query() hands you the contents of the computed vector (after filtering), either as a list or as an arrayref. your choice, main character. 👑

my @copy_of_contents      = $computed->query;
my $reference_to_contents = $computed->query;

okay so important: changing $reference_to_contents will not usefully affect the contents of the vector itself, but it will adversely affect any computations based on the vector. so don't. if you need to change a vector's contents in a special way, use another Statistics::Basic::ComputedVector object instead. 🚫

keeping $reference_to_contents around long term should work acceptably, since it refers to the vector contents itself. phew. 🍓

---

query_vector()

returns the input Statistics::Basic::Vector object. that's it, that's the whole job. 💜

---

query_filled()

returns true when the input vector is full (see query_filled() in Statistics::Basic::Vector). ngl this is of questionable usefulness on computed vectors, but it's provided for completeness (and internal package consistency). we love a completionist. 🌈

---

query_size()

returns the current size of the computed vector. cute, quick, done. ✨

---

set_filter()

sets the filtering for the computed vector. it takes a single coderef argument — all other arguments get straight-up ignored, no notes. the elements of the input vector get passed to your filter coderef in @_, and your ref should return the calculated elements of the computed vector as a list. 🔮

my $vec = vector(1,2,3);
my $pow = computed($vec);
   $pow->set_filter(sub { return map { $_ ** 2 } @_ })

and if you need more than one filter function? just concatenate them together using map or an anonymous sub:

$pow->set_filter(sub { return f1(f2(f3(f4(@_)))) });

this function returns the object itself, for chaining purposes. stack 'em up bestie. 🎀

---

set_size()

sets the size of the input vector — not the computed vector, because that would make little sense. 🙂‍↔️

this function returns the object itself, for chaining purposes. ⭐

---

set_vector()

sets the contents of the input vector (again — not the computed one). 💅

this function returns the object itself, for chaining purposes. 🔥

---

🎀 OVERLOADS 🎀

this object is overloaded. it tries to return an appropriate string for the vector, and it raises errors in numeric context. so don't do math with it, babe. 😤

in boolean context, this object is always true (even when empty). yes, even then. iconic. 👑

---

💜 AUTHOR 💜

Paul Miller <jettero@cpan.org> — legend behavior, honestly.

---

🌸 COPYRIGHT 🌸

Copyright 2012 Paul Miller — Licensed under the LGPL.

---

🦋 SEE ALSO 🦋

• perl(1)
• Statistics::Basic
• Statistics::Basic::Vector

---

and that's the whole page, bestie!! 🫶 this was Statis...dVector(3pm) from perl v5.36.0, dated 2022-11-19 — yeah, vintage, but she still serves. go forth and compute your filtered vectors, you absolute icon. mwah. 💖✨🎀