Add "shuffle" method to replace random(List)

Now random(List) returns a random element of the list

Author: d-torrance

M2/Macaulay2/m2/exports.m2

@@ -1143,6 +1143,7 @@ export {
 	"showStructure",
 	"showTex",
 	"showUserStructure",
+	"shuffle",
 	"sign",
 	"sin",
 	"singularLocus",

M2/Macaulay2/m2/lists.m2

@@ -228,7 +228,10 @@ flexibleOperators = sort flexibleOperators
 fixedOperators = sort fixedOperators
 allOperators = sort allOperators
 
-random List := opts -> s -> (
+random List := opts -> x -> x#(random(#x))
+
+shuffle = method()
+shuffle List := s -> (
      n := #s;
      if n <= 1 then return s;
      s = new MutableList from s;

M2/Macaulay2/packages/Macaulay2Doc/functions.m2

@@ -250,6 +250,7 @@ load "./functions/setup-doc.m2"
 load "./functions/setupLift-doc.m2"
 load "./functions/setupPromote-doc.m2"
 load "./functions/show-doc.m2"
+load "./functions/shuffle-doc.m2"
 load "./functions/sign-doc.m2"
 load "./functions/sin-doc.m2"
 load "./functions/sinh-doc.m2"

M2/Macaulay2/packages/Macaulay2Doc/functions/random-doc.m2

@@ -180,19 +180,19 @@ Node
   Key
     (random, List)
   Headline
-    shuffle a list randomly
+    select a random element of a list
   Usage
     random L
   Inputs
     L:List
   Outputs
-    :List
-      a new list containing the elements of @TT "L"@ in a shuffled random order
+    :Thing -- random element of @VAR "L"@
   Description
     Example
       random toList (0 .. 12)
   SeeAlso
     setRandomSeed
+    shuffle
 
 Node
   Key

M2/Macaulay2/packages/Macaulay2Doc/functions/shuffle-doc.m2

@@ -0,0 +1,20 @@
+doc ///
+  Key
+    shuffle
+    (shuffle, List)
+  Headline
+    shuffle a list randomly
+  Usage
+    shuffle L
+  Inputs
+    L:List
+  Outputs
+    :List
+      a new list containing the elements of @TT "L"@ in a shuffled random order
+  Description
+    Example
+      shuffle toList (0 .. 12)
+  SeeAlso
+    setRandomSeed
+    (random, List)
+///

M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2

@@ -121,6 +121,7 @@ Node
     inversePermutation
     partitions
     random
+    shuffle
     Set
     rays
     cone

M2/Macaulay2/packages/PathSignatures.m2

@@ -21,7 +21,6 @@ export {
     "tensorParametrization",
     "wordAlgebra",
     "sgnVolTensor",
-    "shuffle",
     "halfshuffle",
     "wordFormat",
     "wordString",

M2/Macaulay2/packages/PathSignatures/algebra.m2

@@ -102,7 +102,6 @@ shuffleHelper(NCRingElement, NCRingElement) := (f,g) -> (
 
 -- Exposed versions of shuffle
 
-shuffle = method();
 shuffle (NCRingElement, NCRingElement) := (a, b) -> shuffleHelper(a,b); 
 
 NCRingElement ** NCRingElement := shuffle

M2/Macaulay2/packages/PieriMaps.m2

@@ -90,7 +90,7 @@ isStandard = T -> (
 -- entries (ignoring that some entries might be equal). The output is given in 
 -- the form a hash table where the keys are the resulting tableau and the 
 -- values are -1
-shuffle = (T, col, row1, row2) -> (
+shuffle(List, ZZ, ZZ, ZZ) := (T, col, row1, row2) -> (
      len1 := #(T#row1);
      len2 := #(T#row2);
      truncatedrow1 := (T#row1)_{0..col-2}; -- grab row1 entries