Skip to content
Browse files

rename all the Key* types, add missing "Mix"

Set	-> Set does Setty
Bag	-> Bag does Baggy
	-> Mix does Mixy
KeySet	-> SetHash does Setty does MixHash[Bool,False]
KeyBag	-> BagHash does Baggy does MixHash[Uint,0]
KeyHash	-> MixHash does Mixy  does MixHash[Real,0.0]
  • Loading branch information...
1 parent f617adf commit 2845cf6aefdc9bd0baaefe956302a480fe2a84db @TimToady TimToady committed
Showing with 63 additions and 56 deletions.
  1. +29 −25 S02-bits.pod
  2. +10 −7 S03-operators.pod
  3. +24 −24 S32-setting-library/Containers.pod
View
54 S02-bits.pod
@@ -13,8 +13,8 @@ Synopsis 2: Bits and Pieces
Created: 10 Aug 2004
- Last Modified: 26 Sep 2013
- Version: 277
+ Last Modified: 2 Oct 2013
+ Version: 278
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -1442,6 +1442,7 @@ C<$x.WHICH> eqv C<$y.WHICH>).
Range A pair of Ordered endpoints
Set Unordered collection of values that allows no duplicates
Bag Unordered collection of values that allows duplicates
+ Mix Unordered collection of values with weights
Enum An immutable Pair
EnumMap A mapping of Enums with no duplicate keys
Signature Function parameters (left-hand side of a binding)
@@ -1455,6 +1456,7 @@ C<$x.WHICH> eqv C<$y.WHICH>).
C<Set> values may be composed with the C<set> listop or method.
C<Bag> values may be composed with the C<bag> listop or method.
+C<Mix> values may be composed with the C<mix> listop or method.
C<Instant>s and C<Duration>s are measured in atomic seconds with
fractions. Notionally they are real numbers which may be implemented
@@ -1581,8 +1583,9 @@ These types do (at least) the following roles:
Bool Boolean
Block Callable
Range Iterable
- Set Associative[Bool] Iterable
- Bag Associative[UInt] Iterable
+ Set Setty Iterable
+ Bag Baggy Iterable
+ Mix Mixy Iterable
Enum Associative
EnumMap Associative Positional Iterable
Signature
@@ -1612,7 +1615,7 @@ simultaneously, but an iterator/list itself has only one thread of
consumption. Every time you do C<get> on an iterator, a value
disappears from its list.
-Note that C<Set> and C<Bag> iterators return only keys, not values. You
+Note that C<Set>, C<Bag>, and C<Mix> iterators return only keys, not values. You
must explicitly use c<.pairs> to get key/value pairs.
=head2 Mutable types
@@ -1627,8 +1630,9 @@ because they can be wrapped in place.)
Scalar Perl scalar
Array Perl array
Hash Perl hash
- KeySet KeyHash of Bool (does Set in list/array context)
- KeyBag KeyHash of UInt (does Bag in list/array context)
+ SetHash Setty MixHash[Bool,False]
+ BagHash Baggy MixHash[UInt,0]
+ MixHash Mixy MixHash[Real,0.0]
Pair A single key-to-value association
Buf Perl buffer (array of integers with some stringy features)
IO Perl filehandle
@@ -1642,38 +1646,38 @@ because they can be wrapped in place.)
Stash A symbol table hash (package, module, class, lexpad, etc)
SoftRoutine A routine that is committed to staying mutable
-The C<KeyHash> role differs from a normal C<Associative> hash in how it handles default
-values. If the value of a C<KeyHash> element is set to the default
-value for the C<KeyHash>, the element is deleted. If undeclared,
-the default default for a C<KeyHash> is 0 for numeric types, C<False>
+The C<MixHash> role differs from a normal C<Associative> hash in how it handles default
+values. If the value of a C<MixHash> element is set to the default
+value for the C<MixHash>, the element is deleted. If undeclared,
+the default default for a C<MixHash> is 0 for numeric types, C<False>
for boolean types, and the null string for string and buffer types.
-A C<KeyHash> of an object type defaults to the undefined prototype
+A C<MixHash> of an object type defaults to the undefined prototype
for that type. More generally, the default default is whatever defined
-value a C<Nil> would convert to for that value type. A C<KeyHash>
+value a C<Nil> would convert to for that value type. A C<MixHash>
of C<Scalar> deletes elements that go to either 0 or the null string.
-A C<KeyHash> also autodeletes keys for normal undefined values (that is,
+A C<MixHash> also autodeletes keys for normal undefined values (that is,
those undefined values that do not contain an unthrown exception).
-A C<KeySet> is a C<KeyHash> of booleans with a default of C<False>.
+A C<SetHash> is a C<MixHash> of booleans with a default of C<False>.
If you use the C<Hash> interface and increment an element of a
-C<KeySet> its value becomes true (creating the element if it doesn't
+C<SetHash> its value becomes true (creating the element if it doesn't
exist already). If you decrement the element it becomes false and
is automatically deleted. Decrementing a non-existing value results
in a C<False> value. Incrementing an existing value results in C<True>.
When not used as a C<Hash> (that is,
-when used as an C<Array> or list or C<Set> object) a C<KeySet>
+when used as an C<Array> or list or C<Set> object) a C<SetHash>
behaves as a C<Set> of its keys. (Since the only possible value of
-a C<KeySet> is the C<True> value, it need not be represented in
+a C<SetHash> is the C<True> value, it need not be represented in
the actual implementation with any bits at all.)
-A C<KeyBag> is a C<KeyHash> of C<UInt> with default of 0. If you
-use the C<Hash> interface and increment an element of a C<KeyBag>
+A C<BagHash> is a C<MixHash> of C<UInt> with default of 0. If you
+use the C<Hash> interface and increment an element of a C<BagHash>
its value is increased by one (creating the element if it doesn't exist
already). If you decrement the element the value is decreased by one;
if the value goes to 0 the element is automatically deleted. An attempt
to decrement a non-existing value returns a C<Failure> value. When not
used as a C<Hash> (that is, when used as an C<Array> or list or C<Bag>
-object) a C<KeyBag> behaves as a C<Bag> of its keys, with each key
+object) a C<BagHash> behaves as a C<Bag> of its keys, with each key
replicated the number of times specified by its corresponding value.
(Use C<.kv> or C<.pairs> to suppress this behavior in list context.)
@@ -1689,9 +1693,9 @@ The following roles are supported:
Scalar
Array Positional Iterable
Hash Associative
- KeySet KeyHash[Bool]
- KeyBag KeyHash[UInt]
- KeyHash Associative
+ SetHash Setty MixHash[Bool]
+ BagHash Baggy MixHash[UInt]
+ MixHash Mixy MixHash[Real]
Pair Associative
PairSeq Associative Positional Iterable
Buf Stringy
@@ -1955,7 +1959,7 @@ C<Range>, C<Buf>, C<Parcel>, or C<Capture>. The C<Positional>
role implies the ability to support C<< postcircumfix:<[ ]> >>.
Likewise, C<%x> may be bound to any object that does the C<Associative>
-role, such as C<Pair>, C<PairSet>, C<Set>, C<Bag>, C<KeyHash>, or
+role, such as C<Pair>, C<PairSet>, C<Set>, C<Bag>, C<Mix>, or
C<Capture>. The C<Associative> role implies the ability to support
C<< postcircumfix:<{ }> >>.
View
17 S03-operators.pod
@@ -14,8 +14,8 @@ Synopsis 3: Perl 6 Operators
Created: 8 Mar 2004
- Last Modified: 13 Jul 2013
- Version: 267
+ Last Modified: 2 Oct 2013
+ Version: 268
=head1 Overview
@@ -538,8 +538,8 @@ not be overridden.)
Increment of a C<Bool> (in a suitable container) turns it true.
Decrement turns it false regardless of how many times it was
previously incremented. This is useful if your C<%seen> hash is
-actually a C<KeySet>, in which case decrement actually deletes it
-from the C<KeySet>.
+actually a C<SetHash>, in which case decrement actually deletes the key
+from the C<SetHash>.
Increment/decrement of an undefined C<Numeric>, C<Cool>, or C<Any> variable
sets the variable to 0 and then performs the increment/decrement. Hence a
@@ -3688,7 +3688,7 @@ the table assumes the following types will behave similarly:
Actual type Use entries for
=========== ===============
Iterator Seq Array
- KeySet KeyBag KeyHash Hash
+ SetHash BagHash MixHash Hash
named values created with
Class, Enum, or Role,
or generic type binding Type
@@ -3856,11 +3856,14 @@ by returning an object that can return a list in list context, or that
can return a boolean in a boolean context. In the case regex matching
the C<Match> object is a kind of C<Capture>, which has these capabilities.
-For the purpose of smartmatching, all C<Set> and C<Bag> values are
-considered to be of type C<KeyHash>, that is, C<Hash> containers
+For the purpose of smartmatching, all C<Set>, C<Bag>, and C<Mix>
+values are considered equivalent to the corresponding hash type,
+C<SetHash>, C<BagHash>, and C<MixHash>, that is, C<Hash> containers
where the keys represent the unique objects and the values represent
the replication count of those unique keys. (Obviously, a C<Set> can
have only 0 or 1 replication because of the guarantee of uniqueness).
+So all of these C<Mixy> types only compare keys, not values. Use C<eqv>
+instead to test the equivalence of both keys and values.
Despite the need for an implementation to examine the bounds of a
range in order to perform smartmatching, the result of smartmatching
View
48 S32-setting-library/Containers.pod
@@ -18,8 +18,8 @@ DRAFT: Synopsis 32: Setting Library - Containers.pod
Created: 19 Feb 2009 extracted from S29-functions.pod
- Last Modified: 26 Sep 2013
- Version: 42
+ Last Modified: 2 Oct 2013
+ Version: 43
If you read the HTML version, it is generated from the Pod in the specs
repository under
@@ -1006,8 +1006,8 @@ to the original hash.
=head1 Classes and Roles
-This documents Buf, List, Range, Set, Bag, Junction, Array, Hash, KeyHash, KeySet,
-KeyBag, Pair, and PairMap.
+This documents Buf, List, Range, Set, Bag, Junction, Array, Hash, MixHash, SetHash,
+BagHash, Pair, and PairMap.
=head2 Range
@@ -1151,7 +1151,7 @@ that is, when used as a hash, a set always treats the set's elements
as the keys of the hash, returning C<True> for existing set elements,
and C<False> for any key not found in the set.
-See C<KeySet> for a container that can represent different sets as
+See C<SetHash> for a container that can represent different sets as
keys are added or deleted.
Regardless of their behavior as hashes, set (and bag) types do not
@@ -1204,9 +1204,9 @@ Note that, without an argument, this method basically calculates the powerset.
=back
-=head2 KeySet
+=head2 SetHash
-A mutable Set container, represented as C<KeyHash of Bool>.
+A mutable Set container, represented as C<MixHash[Bool,False]>.
=head2 Bag
@@ -1234,14 +1234,14 @@ rather than a constructor.)
Like an ordinary list C<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
+by the corresponding value and then list pick used. C<BagHash> is the
mutable form of C<Bag>. A C<Bag> responds to hash operators as
if it were a C<Hash of UInt>.
The underlying metaphor for picking is that you're pulling colored
marbles out a bag. (For "picking with replacement" see C<roll> instead.)
Picking require tracking the temporary state, so the immutable C<Bag> is copied to
-a temporary private C<KeyBag>, and the picks are made from that
+a temporary private C<BagHash>, and the picks are made from that
using the corresponding C<.grab> or C<.grabpairs> method (see below).
Each C<.pick> invocation maintains its own private state and has no
@@ -1266,27 +1266,27 @@ Rolling requires no temporary state.
=back
-=head2 KeyBag
+=head2 BagHash
-A mutable C<Bag> container, represented as C<KeyHash of UInt>.
+A mutable C<Bag> container, represented as C<MixHash[UInt,0]>.
-=head2 KeyHash
+=head2 MixHash
- role KeyHash[::T, $default = Any] does Associative {...}
+ role MixHash[::T, $default = Any] does Mixy does Associative {...}
-A C<KeyHash> represents a mutable set of objects, represented as the
+A C<MixHash> represents a mutable set of objects, represented as the
keys of a C<Hash>. When asked to behave as a list it ignores its
C<.values> and returns only C<.keys> (possibly replicated by weight
-in the case of bag types). C<KeySet> and C<KeyBag> are derived
+in the case of bag types). C<SetHash> and C<MixBag> are derived
from this type, but constrain their hash values to be C<Bool> and
-C<UInt>, respectively. A C<KeyHash> automatically deletes any key
+C<UInt>, respectively. A C<MixHash> automatically deletes any key
whose corresponding value goes to the default value for the hash.
-For any C<KeyHash>, the C<.elems> methods returns the current sum
-of the values, which the C<KeyHash> must either track or compute
+For any C<MixHash>, the C<.elems> methods returns the current sum
+of the values, which the C<MixHash> must either track or compute
on demand. Tracking is preferable for efficient implementation of
C<.pick> and C<.grab>.
-All standard C<KeyHash> containers have a default value that is false
+All standard C<MixHash> containers have a default value that is false
(such as C<0> or C<''> or C<Nil> or C<Bool::False>), and keep around
only those entries with non-default values, automatically deleting
any entry if its value goes to that (false) default value.
@@ -1302,9 +1302,9 @@ any entry if its value goes to that (false) default value.
Like C<pick>, a C<grab> returns a random selection of elements, weighted
by the values corresponding to each key.
-Since a C<KeyHash>, unlike a C<Set> or C<Bag>, is mutable, C<.grab>
-works directly on the C<KeyHash>, modifying it in place. (You may use
-C<.pick> to treat the C<KeyHash> as immutable; this will copy it and grab
+Since a C<MixHash>, unlike a C<Set> or C<Bag>, is mutable, C<.grab>
+works directly on the C<MixHash>, modifying it in place. (You may use
+C<.pick> to treat the C<MixHash> as immutable; this will copy it and grab
only from the temporary copy.)
Grabbing decrements the grabbed
@@ -1320,9 +1320,9 @@ and whose values are the deleted replication values.
=back
-=head2 KeyWeight
+=head2 MixHash
-A C<KeyHash of FatRat>; like a C<KeyBag> but may have non-integral
+A C<MixHash[Real,0]>; like a C<BagHash> but may have non-integral
weights for use in weighted picking. Keys with fractional weights
are deleted if they go to 0. Negative weights are not deleted, but
the implementation may complain if it notices you attempting to use

0 comments on commit 2845cf6

Please sign in to comment.
Something went wrong with that request. Please try again.