Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
distinguish QuantHash role from MixHash instance
  • Loading branch information
TimToady committed Oct 2, 2013
1 parent 2845cf6 commit 1d47100
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 28 deletions.
30 changes: 15 additions & 15 deletions S02-bits.pod
Expand Up @@ -1630,9 +1630,9 @@ because they can be wrapped in place.)
Scalar Perl scalar
Array Perl array
Hash Perl hash
SetHash Setty MixHash[Bool,False]
BagHash Baggy MixHash[UInt,0]
MixHash Mixy MixHash[Real,0.0]
SetHash Setty QuantHash[Bool,False]
BagHash Baggy QuantHash[UInt,0]
MixHash Mixy QuantHash[Real,0.0]
Pair A single key-to-value association
Buf Perl buffer (array of integers with some stringy features)
IO Perl filehandle
Expand All @@ -1646,19 +1646,19 @@ 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<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>
The C<QuantHash> role differs from a normal C<Associative> hash in how it handles default
values. If the value of a C<QuantHash> element is set to the default
value for the C<QuantHash>, the element is deleted. If undeclared,
the default default for a C<QuantHash> is 0 for numeric types, C<False>
for boolean types, and the null string for string and buffer types.
A C<MixHash> of an object type defaults to the undefined prototype
A C<QuantHash> 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<MixHash>
value a C<Nil> would convert to for that value type. A C<QuantHash>
of C<Scalar> deletes elements that go to either 0 or the null string.
A C<MixHash> also autodeletes keys for normal undefined values (that is,
A C<QuantHash> also autodeletes keys for normal undefined values (that is,
those undefined values that do not contain an unthrown exception).

A C<SetHash> is a C<MixHash> of booleans with a default of C<False>.
A C<SetHash> is a C<QuantHash> of booleans with a default of C<False>.
If you use the C<Hash> interface and increment an element of a
C<SetHash> its value becomes true (creating the element if it doesn't
exist already). If you decrement the element it becomes false and
Expand All @@ -1670,7 +1670,7 @@ behaves as a C<Set> of its keys. (Since the only possible value of
a C<SetHash> is the C<True> value, it need not be represented in
the actual implementation with any bits at all.)

A C<BagHash> is a C<MixHash> of C<UInt> with default of 0. If you
A C<BagHash> is a C<QuantHash> 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;
Expand All @@ -1693,9 +1693,9 @@ The following roles are supported:
Scalar
Array Positional Iterable
Hash Associative
SetHash Setty MixHash[Bool]
BagHash Baggy MixHash[UInt]
MixHash Mixy MixHash[Real]
SetHash Setty QuantHash[Bool]
BagHash Baggy QuantHash[UInt]
MixHash Mixy QuantHash[Real]
Pair Associative
PairSeq Associative Positional Iterable
Buf Stringy
Expand Down
26 changes: 13 additions & 13 deletions S32-setting-library/Containers.pod
Expand Up @@ -1206,7 +1206,7 @@ Note that, without an argument, this method basically calculates the powerset.

=head2 SetHash

A mutable Set container, represented as C<MixHash[Bool,False]>.
A mutable Set container, represented as C<QuantHash[Bool,False]>.

=head2 Bag

Expand Down Expand Up @@ -1268,25 +1268,25 @@ Rolling requires no temporary state.

=head2 BagHash

A mutable C<Bag> container, represented as C<MixHash[UInt,0]>.
A mutable C<Bag> container, represented as C<QuantHash[UInt,0]>.

=head2 MixHash
=head2 QuantHash

role MixHash[::T, $default = Any] does Mixy does Associative {...}
role QuantHash[::T, $default = Any] does Mixy does Associative {...}

A C<MixHash> represents a mutable set of objects, represented as the
A C<QuantHash> 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<SetHash> and C<MixBag> are derived
from this type, but constrain their hash values to be C<Bool> and
C<UInt>, respectively. A C<MixHash> automatically deletes any key
C<UInt>, respectively. A C<QuantHash> automatically deletes any key
whose corresponding value goes to the default value for the hash.
For any C<MixHash>, the C<.elems> methods returns the current sum
of the values, which the C<MixHash> must either track or compute
For any C<QuantHash>, the C<.elems> methods returns the current sum
of the values, which the C<QuantHash> must either track or compute
on demand. Tracking is preferable for efficient implementation of
C<.pick> and C<.grab>.

All standard C<MixHash> containers have a default value that is false
All standard C<QuantHash> 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.
Expand All @@ -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<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
Since a C<QuantHash>, unlike a C<Set> or C<Bag>, is mutable, C<.grab>
works directly on the C<QuantHash>, modifying it in place. (You may use
C<.pick> to treat the C<QuantHash> as immutable; this will copy it and grab
only from the temporary copy.)

Grabbing decrements the grabbed
Expand All @@ -1322,7 +1322,7 @@ and whose values are the deleted replication values.

=head2 MixHash

A C<MixHash[Real,0]>; like a C<BagHash> but may have non-integral
A C<QuantHash[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
Expand Down

0 comments on commit 1d47100

Please sign in to comment.