[S32/Containers] spec :as for uniq/squish

S32-setting-library/Containers.pod

@@ -449,9 +449,9 @@ C<is canonicalized(&lc)>.)
 
 =item uniq
 
- multi method uniq(List:D: --> List:D)
+ multi method uniq(List:D: --> List:D, :&as)
 
- multi sub uniq(*@values --> List:D)
+ multi sub uniq(*@values --> List:D, :&as)
 
 Returns a list of unique values from the invocant/argument list, such
 that only the first occurrence of each duplicated value remains in the
@@ -465,11 +465,23 @@ duplicates are removed.
 (Use C<squish> instead if you know the input is sorted such that identical
 objects are adjacent.)
 
+The optional C<:as> parameter allows you to normalize/canonicalize the elements
+before uniq-ing. The values are transformed for the purposes of comparison, but
+it's still the original values that make it to the result list:
+
+    say <a A B b c b C>.uniq(:as(&lc))          # a B c
+
+This makes it possible to effectively compare with other comparison operators,
+too. For example, if you want to compare with C< infix:<==> > semantics, this
+might work for you:
+
+    say +uniq [100, 100e0, 200/2], :as(*.Num)   # 1
+
 =item squish
 
- multi method squish(List:D: --> List:D)
+ multi method squish(List:D: --> List:D, :&as)
 
- multi sub squish(*@values --> List:D)
+ multi sub squish(*@values --> List:D, :&as)
 
 Returns a list of values from the invocant/argument list where runs
 of more than one value are replaced with only the first instance.
@@ -482,6 +494,9 @@ are removed.
     say <a a b b b c c>.squish  # a b c
     say <a b b c c b a>.squish  # a b c b a
 
+The optional C< :as > parameter, just like with C< uniq >, allows values to be
+temporarily transformed before comparison.
+
 =item min
 
  multi method min( @values: *&by --> Any )