Fix shuffle() function errors

[paulhauner]

I updated the shuffle() function as discussed in #55.

The following changes were implemented:

1. sample_max was made distinct from rand_max.
2. rand_max now represents the greatest value returned by the RNG
   instead of the length of the range. This is consistent with the cstdlib RAND_MAX constant.
3. while condition fixed to stop infinite loop.
4. Comments updated.

After fixing (2) I noticed that there was an error in generating sample_max caused by rand_max being too high. This affects the output of the shuffle. All clients should update their shuffler if this PR is accepted.

I have used the shuffling_sandbox to fuzz this code against my reference implementation.

[paulhauner]

Thanks for the comments @JustinDrake!

I've added my responses and will await further direction from the repository maintainers.

[paulhauner]

Thanks for the feedback. I will implement the following changes:

1. Introduce a rand_bytes constant set to 3 and use it wherever possible.
2. Set the range on the byte-sampling for loop to: range(0, 32 - (32 % rand_bytes), rand_bytes)
3. Ensure all comments are on the line above to the statement (instead of inline).

I could use additional direction regarding assert values_count <= sample_max. I see @hwwhww suggested throwing a ValueError, is this how we should handle it?

[djrtwo]

I'm cool with an assert in the spec code as long as there is a comment about why it is there and how it is up to a client on how to proceed. Similar to the commented assert in add_validator

If we want to remove asserts entirely (there are many), we can do it in a separate issue.

[paulhauner]

All updates have been pushed :)

[djrtwo]

lgtm!