Document 'unique' and 'squish', mostly copying the descriptions from S32.

Author: edwinst

lib/Type/List.pod

@@ -314,6 +314,54 @@ Examples:
     say (3, -4, 7, -1, 2, 0).sort: *.abs;           # 0 -1 2 3 -4 7
     say (3, -4, 7, -1, 2, 0).sort: { $^b leg $^a }; # 7 3 2 0 -4 -1
 
+=head2 routine unique
+
+    multi sub    unique(*@values, :&as) returns List:D
+    multi method unique(List:D:,  :&as) returns List:D
+
+Returns a list of unique values from the invocant/argument list, such
+that only the first occurrence of each duplicated value remains in the
+result list. C<unique> uses C<< &infix:<===> >> semantics to compare whether
+two objects are the same. The order of the original list is preserved even as
+duplicates are removed.
+
+Examples:
+
+    say <a a b b b c c>.unique    # a b c
+    say <a b b c c b a>.unique    # a b c
+
+(Use L<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 unique-ing. The values are transformed for the purposes of comparison, but
+it's still the original values that make it to the result list:
+
+Example:
+
+    say <a A B b c b C>.unique(:as(&lc))          # a B c
+
+=head2 routine squish
+
+    multi sub    squish(*@values, :&as) returns List:D
+    multi method squish(List:D:,  :&as) returns List:D
+
+Returns a list of values from the invocant/argument list where runs
+of more than one value are replaced with only the first instance.
+Like L<C<unique>>, C<squish> uses C<< &infix:<===> >> semantics to compare
+whether two objects are the same. Unlike L<C<unique>>, this function only
+removes adjacent duplicates; identical values further apart are still
+kept. The order of the original list is preserved even as duplicates
+are removed.
+
+Examples:
+
+    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 L<C<unique>>, allows values to be
+temporarily transformed before comparison.
+
 =head2 routine reduce
 
     multi sub    reduce(&with, *@elems)