tpl/collections: Add collections.D using Vitter's Method D for sequential random sampling

[bep]

No description provided.

[jmooring]

I had a couple of thoughts, neither of which are terribly important, while creating the documentation:

https://deploy-preview-3184--gohugoio.netlify.app/functions/collections/d/

First, with this signature...

collections.D SEED N MAX

...it seems like the maximum returned should be MAX but it's is actually MAX - 1. You've covered that in the half-open interval description, but I'm wondering if we should just add 1 before calling vitter.D.

Second, we're casting all args to ints, but the cache key is based on the raw value, which might not be an int. So the same result could be cached more than once, but I don't think this is very likely to happen in the wild.

[bep]

...it seems like the maximum returned should be MAX but it's is actually MAX - 1. You've covered that in the half-open interval description, but I'm wondering if we should just add 1 before calling vitter.D.

In my head, the current API would allow for constructs ala:

{{ $pages := site.RegularPages }}
{{ range (collections.D 42 10 ( $pages | len )) }}
   {{ with (index $pages .) }}
   {{ end }}
{{ end }}

The above should be a very effective way to pick 10 random pages without any (potentiallly expensive) shuffling. If we added 1 to MAX, the above would not work (or the user would have to do some subtraction).

So the same result could be cached more than once, but I don't think this is very likely to happen in the wild.

I'm not sure I care too much about that, but I guess it wold look cleaner with ints as the key.

[jmooring]

You're right. The current API works great with a page collection, which I expect will be the predominant use case. I'll update the docs with another example.