D-Programming-Language/phobos — pull request #893 by monarchdodra (2012-10-26 10:43:38+00:00)
Title: Reference semantics in std.random

This development addresses http://forum.dlang.org/thread/oiczxzkzxketxitncghl@forum.dlang.org which has raised bugs, such as Issue 8247 ( http://d.puremagic.com/issues/show_bug.cgi?id=8247 )

Basically, it gives all PRNG reference semantics: Cheap copy (as a reminder, a Merseen is a 1.5 KB object...), but more importantly: No hidden save on copy.

Using RefRange was not an option, because:
1. It requires explicit usage
2. It does not lazily initialize.

About the development:

The current "stack" based implementation where left as-is, but made private. I provided some new PRNGs, which simply wrap a pointer to said implementation, and forward all calls correctly. This was done "by hand" (as opposed to using a mixin), so that everything could be documented. The "stack based" implementations were purposefully kept as is because:
1. Less impact
2. We can imagine they will one day *also* be kept inside aggressive containers.

Regarding the discussion in the thread, I did not provide ANY new functionality, workaround or feature for accessing the stack implementation. I fear adding new functionality now would bite us in the ass if we decided to move std.random in some other direction later.

Also in this Pull Request:

* I added an entire StdDdoc section to provide a "unified" documentation for all PRNGs. I think there are 2 kinds of documentations: The one relative to PRNGs in the generic sense, and the one relative to a specific implementation. This is the generic documentation.

* Debug traces. Helps a lot.

* safe + nothrow + const where possible.

NOT in this pull request:

* I think saving a PRNG should be deprecated. I think it is OK to dupe one if the developer explicitly wants it, but it really doesn't make sense for a PRNG to be a ForwardRange (as opposed to a simple InputRange).