Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Added docs for Baggy.grab
  • Loading branch information
Jan-Olof Hendig committed Jun 16, 2016
1 parent fad1877 commit 01e959b
Showing 1 changed file with 23 additions and 1 deletion.
24 changes: 23 additions & 1 deletion doc/Type/Baggy.pod
Expand Up @@ -13,7 +13,29 @@ L<Mixy>.
=head2 method grab
=comment TODO
Defined as:
multi method grab(Baggy:D:) returns Any
multi method grab(Baggy:D: $count) returns Array:D
Like L<pick|#method pick>, a C<grab> returns a random selection of elements, weighted
by the values corresponding to each key. Unlike C<pick>, it works only on mutable
structures, e.g. L<BagHash|/type/BagHash>. Use of C<grab> on an immutable structure results in an
C<X::Immutable> exception. 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.
Grabbing decrements the grabbed key's weight by one (deleting the key
when it reaches 0). By definition, the C<total> of the invocant also decreases by one, so the
probabilities stay consistent through subsequent C<grab> operations.
my $cars = ('Ford' => 2, 'Rover' => 3).BagHash;
say $cars.grab; # Ford
say $cars.grab(2); # [Rover Rover]
say $cars.grab(*); # [Rover Ford]
my $breakfast = ('eggs' => 2, 'bacon' => 3).Bag;
say $breakfast.grab; # throws X::Immutable exception
=head2 method grabpairs
Expand Down

0 comments on commit 01e959b

Please sign in to comment.