Attempt to document Baggy.pick

gistfile1.txt

=head2 method pick

Defined as:

    multi method pick(Baggy:D:) returns Any
    multi method pick(Baggy:D: $count) returns Seq:D

Like an ordinary list L<pick|/type/List#routine_pick>, but returns keys
of the invocant weighted by their values, as if the keys were replicated
the number of times indicated by the corresponding value and then list
pick used. The underlying metaphor for picking is that you're pulling
colored marbles out a bag. (For "picking with replacement" see
L<roll|#method roll> instead). If C<*> is passed as C<$count>, or C<$count> is
greater than or equal to the L<total|#method total> of the invocant, then
C<total> elements from the invocant are returned in a random sequence.

Note that each C<pick> invocation maintains its own private state and has
no effect on subsequent C<pick> invocations.

    my $breakfast = bag <eggs bacon bacon bacon>;
    say $breakfast.pick;                              # eggs
    say $breakfast.pick(2);                           # (eggs bacon)

    say $breakfast.total;                             # 4
    say $breakfast.pick(*);                           # (bacon bacon bacon eggs)