Author: lwall
Date: 2009-05-06 00:20:38 +0200 (Wed, 06 May 2009)
New Revision: 26685
Modified:
docs/Perl6/Spec/S32-setting-library/Containers.pod
Log:
[Containers] some work on various structures related to KeyHash
define .pick to work rationally on structures whose values represent weights.
Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-05-05 17:32:04 UTC
(rev 26684)
+++ docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-05-05 22:20:38 UTC
(rev 26685)
@@ -15,8 +15,8 @@
Moritz Lenz <mor...@faui2k3.org>
Tim Nelson <wayl...@wayland.id.au>
Date: 19 Feb 2009 extracted from S29-functions.pod
- Last Modified: 3 May 2009
- Version: 6
+ Last Modified: 5 May 2009
+ Version: 7
The document is a draft.
@@ -674,17 +674,11 @@
=back
-=head2 Tieable
-
- role Tieable {...}
-
=head1 Classes
This documents Buf, List, Seq, Range, Set, Bag, Junction, Array, Hash,
KeyHash, KeySet,
KeyBag, Pair, and Mapping.
-XXX So where are KeySet and KeyBag.
-
=head2 Seq
class Seq does Positional {...}
@@ -703,10 +697,15 @@
class Buf does Positional {...}
+A mutable container for an array of integer values in contiguous
+memory.
+
=head2 Pair
class Pair does Associative {...}
+The value of a pair is mutable; the key is not.
+
=item invert
our List multi method invert ( $pair: ) is export {
@@ -717,18 +716,76 @@
class Mapping does Associative {...}
+An immutable hash value, essentially. The keys may
+not contain duplicates, while the values may.
+
=head2 Set
class Set does Associative {...}
+A set of unique values. When used as a hash always treats the set's
+values as the keys of the hash, returning C<True> for set elements.
+See C<KeySet> for a container that can represent different sets
+as keys are added or delete.
+
+=over
+
+=item pick
+
+ our multi method pick ( $set: Int $num = 1, Bool :$repl )
+ our multi method pick ( $set: Whatever, Bool :$repl )
+
+Like an ordinary list pick, but returns keys of the bag weighted by
+values, as if the keys were replicated the number of times indicated
+by the corresponding value and then list pick used. C<KeySet> is the
+mutable form of C<Set>. A C<Set> responds to hash operators as
+if it were a C<Hash of True>.
+
+=back
+
+=head2 KeySet
+
+A mutable Set container, represented as C<KeyHash of True>.
+
=head2 Bag
class Bag does Associative {...}
+=over
+
+=item pick
+
+ our multi method pick ( $bag: Int $num = 1, Bool :$repl )
+ our multi method pick ( $bag: Whatever, Bool :$repl )
+
+Like an ordinary list pick, but returns keys of the bag weighted by
+values, as if the keys were replicated the number of times indicated
+by the corresponding value and then list pick used. C<KeyBag> is the
+mutable form of C<Bag>. A C<Bag> responds to hash operators as
+if it were a C<Hash of UInt>.
+
+=back
+
+=head2 KeyBag
+
+A mutable C<Bag> container, represented as C<KeyHash of UInt>.
+
=head2 KeyHash
class KeyHash does Associative {...}
+A KeyHash represents a mutable set of values, represented as the keys
+of a C<Hash>. When asked to behave as a list it ignores its values
+and returns only C<.keys>. C<KeySet> and C<KeyBag> are derived from
+this type, but constrain their values to be C<Bool> and C<UInt>,
+respectively. A C<KeyHash> automatically deletes any key whose
+value goes false.
+
+=head2 KeyWeight
+
+A C<KeyHash of Num>; like a C<KeyBag> but may have non-integral
+weights for use in weighted picking.
+
=head2 junction
All method calls on junctions autothread because the type provides no public
methods.
