Author: lwall
Date: 2009-12-15 20:08:43 +0100 (Tue, 15 Dec 2009)
New Revision: 29344
Modified:
docs/Perl6/Spec/S32-setting-library/Containers.pod
Log:
[S32/Containers] refine pick concepts on baggy things for IllvilJa++
Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod
===
--- docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-12-13 23:24:44 UTC
(rev 29343)
+++ docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-12-15 19:08:43 UTC
(rev 29344)
@@ -19,8 +19,8 @@
Created: 19 Feb 2009 extracted from S29-functions.pod
-Last Modified: 3 Dec 2009
-Version: 10
+Last Modified: 15 Dec 2009
+Version: 11
The document is a draft.
@@ -856,7 +856,6 @@
as keys are added or deleted. A CSet responds to hash operators as
if it were a CHash of True.
-
=over
=item pick
@@ -876,12 +875,16 @@
class Bag does Associative {...}
+A collection of values that need not be unique, represented by an
+associative mapping from each key value to its replication number.
+The C.elems method returns the sum of all replication values.
+
=over
=item pick
- our multi method pick ( $bag: Int $num = 1, Bool :$replace )
- our multi method pick ( $bag: Whatever, Bool :$replace )
+ our multi method pick ( $bag: Int $num = 1, Bool :$replace, Bool :$enums )
+ our multi method pick ( $bag: Whatever, Bool :$replace, Bool :$enums )
Like an ordinary list Cpick, but returns keys of the bag weighted by
values, as if the keys were replicated the number of times indicated
@@ -889,6 +892,27 @@
mutable form of CBag. A CBag responds to hash operators as
if it were a CHash of UInt.
+The default metaphor for picking is that you're pulling colored
+marbles out a bag. Picking with replacement is easy to implement,
+since the weights never change, and the chance of getting any key is
+simply its replication value over C.elems. Other forms of picking
+require tracking the temporary state, so the CBag is copied to
+a temporary private CKeyBag, and the picks are made from that.
+Picking without replacement (the default), decrements the picked
+key's replication value by one (deleting the key when it goes to 0).
+By definition, C.elems of the private CKeyBag also decreases
+by one, so the probabilities stay consistent as the pick operation
+proceeds.
+
+With the C:enums option, the replication value of the picked key
+is forced immediately to 0, removing all marbles of that color from
+the bag, as it were. Instead of returning keys, the C:enums option
+returns the picked values as a list of CEnum objects, whose keys are
+the deleted keys and whose values are the deleted replication values.
+
+Each C.pick invocation maintains its own private state and has no
+effect on subsequent C.pick invocations.
+
=back
=head2 KeyBag
@@ -904,12 +928,21 @@
and returns only C.keys. CKeySet and CKeyBag are derived from
this type, but constrain their values to be CBool and CUInt,
respectively. A CKeyHash automatically deletes any key whose
-value goes false.
+value goes false. For any CKeyHash, the C.elems methods returns
+the current sum of the values, which the CKeyHash must either track
+or compute on demand. Tracking is preferable for efficient implementation
+of C.pick.
+Since a CKeyHash, unlike a CBag, is mutable, C.pick works
+directly on the CKeyHash, modifying it in place. You must copy
+the CKeyHash first if you don't want it modified in place.
+
=head2 KeyWeight
-A CKeyHash of Num; like a CKeyBag but may have non-integral
-weights for use in weighted picking.
+A CKeyHash of FatRat; like a CKeyBag but may have non-integral
+weights for use in weighted picking. Keys with fractional weights
+are deleted if they go non-positive, but a warning is issued
+for deletion of any element that didn't go exactly to 0.
=head2 junction
