r26135 - docs/Perl6/Spec/S32-setting-library

[pugs-commits]

Author: lwall
Date: 2009-04-08 21:21:21 +0200 (Wed, 08 Apr 2009)
New Revision: 26135

Modified:
   docs/Perl6/Spec/S32-setting-library/Containers.pod
Log:
[S32/Containers] make it possible to reverse a hash without (too much) loss of
        information when there are duplicate values or list values


Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Containers.pod  2009-04-08 18:45:34 UTC 
(rev 26134)
+++ docs/Perl6/Spec/S32-setting-library/Containers.pod  2009-04-08 19:21:21 UTC 
(rev 26135)
@@ -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: 18 Mar 2009
- Version:       3
+ Last Modified: 8 Apr 2009
+ Version:       4
 
 The document is a draft.
 
@@ -28,19 +28,19 @@
 
 =head2 Positional
 
-role   Positional {...}
+    role Positional {...}
 
 The C<Positional> role implies the ability to support C<< postcircumfix:<[ ]> 
>>.
 
 =head2 Associative
 
-role   Associative {...}
+    role Associative {...}
 
 The C<Associative> role implies the ability to support C<< postcircumfix:<{ }> 
>>.
 
 =head2 Container
 
-role   Container {...}
+    role Container {...}
 
 =over
 
@@ -112,7 +112,7 @@
 
 The following are defined in the C<List> role/class:
 
-role   List does Container does Positional {...}
+    role List does Container does Positional {...}
 
 =over
 
@@ -267,13 +267,6 @@
 
 =item reverse
 
- role Hash {
-     our Hash multi method reverse ( %hash: ) is export {
-       (my %result){%hash.values} = %hash.keys;
-       %result;
-     }
- }
-
  our List multi method reverse ( @values: ) is export
  our List multi reverse ( *...@values ) {
     gather {
@@ -404,7 +397,7 @@
 
 All these methods are defined in the C<Array> role/class.
 
-role   Array does List {...}
+    role Array does List {...}
 
 =over
 
@@ -554,7 +547,7 @@
 
 The following are defined in the C<Hash> role.
 
-role   Hash does Container does Associative {...}
+    role Hash does Container does Associative {...}
 
 =over 4
 
@@ -643,11 +636,44 @@
 Returns a junction which will only match against another value if none of 
 the keys in the hash matches.
 
+=item reverse
+
+ our List multi method reverse ( %hash: ) is export {
+     map -> $k, $v { $v X=> $k }, %hash.kv;
+ }
+
+Produces a backmapping of values to keys, expanding list values
+into multiple pairs.  (The C<< X=> >> expands C<$v> if it is a list.)
+[NB: this may need refinement to handle keys that do C<Positional>.]
+
+=item push
+
+ our Int multi method push ( @hash: *...@values ) is export
+
+Like hash assignment insofar as it accepts either C<Pair> objects or
+alternating keys and values; however, unlike assignment, when
+a duplicate key is detected, coerces the colliding entry's value to an
+array and pushes the Pair's value onto that array.  Hence to reverse
+a hash containing duplicate values without losing information, say:
+
+    %out.push(%in.reverse)
+
+Note that when reading the values of such a hash, you must not assume
+that all the elements are arrays, since the first instance of a key
+merely sets the value without turning it into an array.  (Fortunately,
+most list operators create a list of one element when used on an object
+that is not a list.)
+
+The intention is that
+
+    %bar.push(%foo.reverse);
+    %baz.push(%bar.reverse);
+
 =back
 
 =head2 Tieable
 
-role   Tieable {...}
+    role Tieable {...}
 
 =head1 Classes
 
@@ -658,41 +684,47 @@
 
 =head2 Seq
 
-class  Seq does Positional {...}
+    class Seq does Positional {...}
 
 =head2 Range
 
-class  Range does Positional {
+    class Range does Positional {
        method from() {...}
        method to() {...}
        method min() {...}
        method max() {...}
        method List minmax() {...}
-}
+    }
 
 =head2 Buf
 
-class  Buf does Positional {...}
+    class Buf does Positional {...}
 
 =head2 Pair
 
-class  Pair does Associative {...}
+    class Pair does Associative {...}
 
+=item reverse
+
+    our List multi method reverse ( $pair: ) is export {
+     $pair.value X=> $pair.key
+    }
+
 =head2 Mapping
 
-class  Mapping does Associative {...}
+    class Mapping does Associative {...}
 
 =head2 Set
 
-class  Set does Associative {...}
+    class Set does Associative {...}
 
 =head2 Bag
 
-class  Bag does Associative {...}
+    class Bag does Associative {...}
 
 =head2 KeyHash
 
-class  KeyHash does Associative {...}
+    class KeyHash does Associative {...}
 
 =head2 junction