Rename random(List) to shuffle(List) so that random(List) returns a single element

[d-torrance]

This addresses #4161.

I've also found the current behavior confusing. Broadly speaking, the other random methods take a "set" and return a random element of that set (whether that set is a ring, a number representing an upper bound of an interval, or what have you -- it's the same basic idea). But random(List) doesn't do that.

So we change its behavior so that it does, and introduce shuffle(List) to take on the previous behavior.

i1 : x = toList(1..20)

o1 = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}

o1 : List

i2 : random x

o2 = 6

i3 : shuffle x

o3 = {11, 10, 18, 12, 16, 20, 7, 15, 6, 14, 4, 9, 17, 8, 13, 1, 2, 19, 3, 5}

o3 : List

This was a pretty big change and I had to fix a bunch of packages that this change broke. Maybe we can discuss at the next M2internals for a consensus on whether it would be worth merging?

[d-torrance]

I've implemented the suggestions from this afternoon's M2internals:

i1 : x = toList(0..12)

o1 = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}

o1 : List

i2 : random x
 -- the behavior of random(List) will change soon; use shuffle(List) instead

o2 = {0, 7, 9, 4, 5, 3, 8, 12, 10, 11, 6, 2, 1}

o2 : List

i3 : random x

o3 = {5, 9, 1, 7, 12, 8, 10, 0, 6, 3, 4, 11, 2}

o3 : List

i4 : randomElement x

o4 = 0

i5 : shuffle x

o5 = {1, 4, 0, 9, 8, 3, 2, 5, 7, 10, 11, 6, 12}

o5 : List

[mahrud]

Not important for this PR, but related to #4230, I've noticed that something like the following is sometimes a little faster. I'd like to understand which interpreter optimizations come into play here better.

Suggested change

	randomElement List := x -> (
	if #x == 0 then error "expected a nonempty list";
	x#(random(#x)))
	randomElement List := x -> if #x > 0 then x#(random(#x)) else error "expected a nonempty list"

(I forget, it's possible the then and else clauses need to be swapped for best performance)

[d-torrance]

Discussed with Mike

[mahrud]

Did you check if there are any the behavior of... strings printed in the package examples?

[d-torrance]

There shouldn't be. In earlier commits prior to the M2internals discussion, I'd changed the behavior of random(List) already, so everything that called it has been changed to shuffle or randomSubset so the builds would pass.