Documentation for routine grab

Documentation for routine grab, assembled from the following types:

role Baggy

From Baggy

(Baggy) method grab

Defined as:

multi method grab(Baggy:D: --> Any)
multi method grab(Baggy:D: $count --> Seq:D)

Like pick, a grab returns a random selection of elements, weighted by the values corresponding to each key. Unlike pick, it works only on mutable structures, e.g. BagHash. Use of grab on an immutable structure results in an X::Immutable exception. If * is passed as $count, or $count is greater than or equal to the total of the invocant, then total elements from the invocant are returned in a random sequence.

Grabbing decrements the grabbed key's weight by one (deleting the key when it reaches 0). By definition, the total of the invocant also decreases by one, so the probabilities stay consistent through subsequent grab operations.

my $cars = ('Ford' => 2'Rover' => 3).BagHash;
say $cars.grab;                                   # OUTPUT: «Ford␤» 
say $cars.grab(2);                                # OUTPUT: «(Rover Rover)␤» 
say $cars.grab(*);                                # OUTPUT: «(Rover Ford)␤» 
my $breakfast = ('eggs' => 2'bacon' => 3).Bag;
say $breakfast.grab;
CATCH { default { put .^name''.Str } };
# OUTPUT: «X::Immutable: Cannot call 'grab' on an immutable 'Bag'␤» 

role Setty

From Setty

(Setty) method grab

method grab($count = 1)

Removes and returns $count elements chosen at random (without repetition) from the set.

If * is passed as $count, or $count is greater than or equal to the size of the set, then all its elements are removed and returned in random order.

Only works on mutable sets; When used on an immutable set, it results in an exception.

class Supply

From Supply

(Supply) method grab

method grab(Supply:D: &when-done --> Supply:D)

Waits until the given Supply is done. It will then call the &when-done closure passing all of the values seen, Then creates a Supply to which all values returned from the &when-done closure are emitted.

my $s = Supply.from-list(41032);
my $t = $s.grab(&sum);
$t.tap(&say);           # OUTPUT: «19␤»