Author: lwall
Date: 2009-12-03 22:08:54 +0100 (Thu, 03 Dec 2009)
New Revision: 29251
Modified:
docs/Perl6/Spec/S02-bits.pod
docs/Perl6/Spec/S12-objects.pod
docs/Perl6/Spec/S32-setting-library/Containers.pod
Log:
rename PairVal to Enum and PairValSeq to EnumMap, PairSeq to PairMap.
rename .mapping to .enums and apply consistently to hashes and arrays too
(.enums is now the readonly analog to .pairs)
Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod 2009-12-03 19:00:40 UTC (rev 29250)
+++ docs/Perl6/Spec/S02-bits.pod 2009-12-03 21:08:54 UTC (rev 29251)
@@ -1150,8 +1150,8 @@
Range A pair of Ordered endpoints
Set Unordered collection of values that allows no duplicates
Bag Unordered collection of values that allows duplicates
- PairVal An immutable Pair
- PairValSeq Seq of PairVals with no duplicate keys
+ Enum An immutable Pair
+ EnumMap A mapping of Enums with no duplicate keys
Signature Function parameters (left-hand side of a binding)
Parcel List of syntactic objects
Capture Function call arguments (right-hand side of a binding)
@@ -1205,8 +1205,8 @@
Range Iterable
Set Associative[Bool]
Bag Associative[UInt]
- PairVal Associative
- PairValSeq Associative Postional Iterable
+ Enum Associative
+ EnumMap Associative Positional Iterable
Signature
Parcel Positional
Capture Positional Associative
Modified: docs/Perl6/Spec/S12-objects.pod
===================================================================
--- docs/Perl6/Spec/S12-objects.pod 2009-12-03 19:00:40 UTC (rev 29250)
+++ docs/Perl6/Spec/S12-objects.pod 2009-12-03 21:08:54 UTC (rev 29251)
@@ -1701,9 +1701,9 @@
Such declarational forms are not always convenient; to translate
native enum values back to their names operationally, you can pull
-out the enum type's mapping and invert it:
+out the enum type's C<EnumMap> and invert it:
- constant %dayname := Day.mapping.invert;
+ constant %dayname := Day.enums.invert;
%dayname{3} # Wed
The enum type itself is an undefined type object, but supplies convenient
@@ -1711,17 +1711,17 @@
Day.defined # False
3 ~~ Day # True, using Day as a subset of Int
- Day.mapping # hash of key/value pairs
+ Day.enums # map of key/value pairs
-The C<.mapping> method returns a C<PairValSeq> that may be used like
-a constant hash value:
+The C<.enums> method returns an C<EnumMap> that may be used either as
+a constant hash value or as a list of pairs:
my enum CoinFace <Heads Tails>;
- CoinFace.mapping.pairs # (Heads => 0, Tails => 1)
- CoinFace.mapping.keys # ('Heads', 'Tails')
- CoinFace.mapping.values # (0, 1)
- CoinFace.mapping.kv # ('Heads', 0, 'Tails', 1)
- CoinFace.mapping.invert # (0 => 'Heads', 1 => 'Tails')
+ CoinFace.enums.keys # ('Heads', 'Tails')
+ CoinFace.enums.values # (0, 1)
+ CoinFace.enums.kv # ('Heads', 0, 'Tails', 1)
+ CoinFace.enums.invert # (0 => 'Heads', 1 => 'Tails')
+ CoinFace.enums.[1] # Tails => 1
The enum typename itself may be used as a coercion operator from either
the key name or a value. First the argument is looked up as a key;
@@ -1729,11 +1729,11 @@
fails, the value is looked up using an inverted mapping table (which
might have dups if the mapping is not one-to-one):
- Day('Tue') # Tue constant, found as key
- Day::('Tue') # (same thing)
+ Day('Tue') # Tue constant, found as key
+ Day::('Tue') # (same thing)
- Day(3) # Wed constant, found as value
- Day.mapping.invert{3} # (same thing)
+ Day(3) # Wed constant, found as value
+ Day.enums.invert{3} # (same thing)
An anonymous enum just makes sure each string turns into a pair with
sequentially increasing values, so:
@@ -1747,7 +1747,7 @@
%e<ook.> = 1;
%e<ook?> = 2;
-The return value of an anonymous enum is a c<PairValSeq>.
+The return value of an anonymous enum is an c<EnumMap>.
The enum composer inspects list values for pairs, where the value
of the pair sets the next value explicitly. Non-pairs C<++> the
@@ -1957,7 +1957,7 @@
it's time to walk away. Or maybe run.)
To pick from the list of keynames or values, derive them via the
-C<.mapping> method described above.
+C<.enums> method described above.
=head1 Open vs Closed Classes
Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-12-03 19:00:40 UTC
(rev 29250)
+++ docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-12-03 21:08:54 UTC
(rev 29251)
@@ -582,6 +582,7 @@
multi method keys ( @array: Matcher $indextest? ) is export
multi method kv ( @array: Matcher $indextest? ) is export
multi method pairs ( @array: Matcher $indextest? ) is export
+ multi method enums ( @array: Matcher $indextest? ) is export
multi method values ( @array: Matcher $indextest? ) is export
Iterates the elements of C<@array>, in order.
@@ -592,6 +593,9 @@
What is returned at each element of the iteration varies with function.
C<values> returns the value of the associated element; C<kv> returns
a 2 element list in (index, value) order, C<pairs> a C<Pair(index, value)>.
+With C<pairs> the values are references back to the original containers,
+while with C<enums> a snapshot of those values is taken. That is, C<.pairs>
+returns a C<PairMap> while C<enums> returns an C<EnumMap>.
If C<@array> is declared to be multi-dimensional, the keys returned may
in fact be slice lists. (Arrays that are effectively multi-dimensional
@@ -633,6 +637,7 @@
multi method keys ( %hash: Matcher $keytest? ) is export
multi method kv ( %hash: Matcher $keytest? ) is export
multi method pairs ( %hash: Matcher $keytest? ) is export
+ multi method enums ( %hash: Matcher $keytest? ) is export
multi method values ( %hash: Matcher $keytest? ) is export
Iterates the elements of C<%hash>. The order is implementation dependent
@@ -645,6 +650,9 @@
What is returned at each element of the iteration varies with function.
C<keys> only returns the key; C<values> the value; C<kv> returns both as
a 2 element list in (key, value) order, C<pairs> a C<Pair(key, value)>.
+With C<pairs> the values are references back to the original containers,
+while with C<enums> a snapshot of those values is taken. That is, C<.pairs>
+returns a C<PairMap> while C<enums> returns an C<EnumMap>.
Note that C<kv %hash> returns the same as C<zip(keys %hash; values %hash)>
@@ -700,7 +708,7 @@
alternating keys and values; also like in that it returns the new hash.
However, unlike assignment, when a duplicate key is detected,
C<push> coerces the colliding entry's value to an
-array and pushes the Pair's value onto that array. Hence to invert
+array and pushes the C<Pair>'s value onto that array. Hence to invert
a hash containing duplicate values without losing (associative) information,
say:
@@ -720,7 +728,7 @@
=head1 Classes
This documents Buf, List, Seq, Range, Set, Bag, Junction, Array, Hash,
KeyHash, KeySet,
-KeyBag, Pair, and PairSet.
+KeyBag, Pair, and PairMap.
=head2 Seq
@@ -794,12 +802,17 @@
operators is intentionally not defined yet, because I have no idea what
implications on speed and usage they might have --moritz].
-=head2 Pair
+=head2 Enum and Pair
+ class Enum does Associative {...}
class Pair does Associative {...}
-The value of a pair is mutable; the key is not.
+A value formed by associating a single key with a single value.
+In an C<Enum>, both key and value are immutable. In a C<Pair>, the
+key is immutable but the value mutable. C<Enum> works identically
+to C<Pair> unless you try to modify it.)
+
=over
=item invert
@@ -810,22 +823,28 @@
=back
-=head2 PairValSeq
+=head2 EnumMap
- class PairValSeq does Associative does Positional {...}
+ class EnumMap does Associative does Positional {...}
-An immutable hash value, viewable either as a (readonly) hash or
-as a sequence of C<PairVal>s. The keys may not contain duplicates,
-while the values may.
+An immutable hash value, viewable either as a (constant) hash or as
+a sequence of C<Enum>s. The keys may not contain duplicates, while
+the values may. The implemention of C<EnumMap> associativity is not
+guaranteed to be as efficient as a C<Hash> lookup. (A brute force
+linear scan for the matching key is allowed. Optimization
+is also allowed.)
-=head2 PairSeq
+=head2 PairMap
- class PairSeq does Associative does Positional {...}
+ class PairMap does Associative does Positional {...}
A hash value that is mutable only in values, differing from a normal
hash insofar as the key set is frozen. It may be accessed either as
a frozen hash or as a sequence of C<Pair>s. The keys may not contain
-duplicates, while the values may.
+duplicates, while the values may. The implemention of C<PairMap>
+associativity is not guaranteed to be as efficient as a C<Hash> lookup.
+(A brute force linear scan for the matching key is allowed. Optimization
+to something like an ordered hash is also allowed.)
=head2 Set
