Documentation for method pickpairs

Documentation for method pickpairs, assembled from the following types:

role Baggy

From Baggy

(Baggy) method pickpairs

Defined as:

multi method pickpairs(Baggy:D: --> Pair:D)
multi method pickpairs(Baggy:D: $count --> List:D)

Returns a Pair or a List of Pairs depending on the version of the method being invoked. Each Pair returned has an element of the invocant as its key and the elements weight as its value. The elements are 'picked' without replacement. If * is passed as $count, or $count is greater than or equal to the number of elements of the invocant, then all element/weight Pairs from the invocant are returned in a random sequence.

Note that each pickpairs invocation maintains its own private state and has no effect on subsequent pickpairs invocations.

my $breakfast = bag <eggs bacon bacon bacon>;
say $breakfast.pickpairs;                         # OUTPUT: «eggs => 1␤» 
say $breakfast.pickpairs(1);                      # OUTPUT: «(bacon => 3)␤» 
say $breakfast.pickpairs(*);                      # OUTPUT: «(eggs => 1 bacon => 3)␤»