Also see the main project readme.
TODO. In the mean-time, we have some learning resources within the API documentation.
The following example programs may be of interest:
API documentation can be found:
randAPI on docs.rs
rand_coreAPI on docs.rs
cargo doc --no-deps --all --all-features
This project is open to contributions from anyone, with the main criteria of review being correctness, utility, project scope, and good documentation. Where correctness is less obvious (PRNGs and some type-conversion algorithms), additional criteria apply (see below).
Additionally we welcome feedback in the form of bug reports, feature requests (preferably with motivation and consideration for the scope of the project), code reviews, and input on current topics of discussion.
Since we must sometimes reject new features in order to limit the project's scope, you may wish to ask first before writing a new feature.
We try to follow semver rules regarding API-breaking changes and
New patch versions should not include API-breaking changes or major new features
Before 1.0, minor versions may include API breaking changes. After 1.0 they should not.
We may make pre-releases like
0.5.0-pre.0. In this case:
Additionally, we must also consider value-breaking changes and portability. A function is value-stable if, given the same inputs:
Note that some Rand functionality is supposed to be value stable, and some functionality is supposed to be non-deterministic (i.e. depend on something external). Some functionality may be deterministic but not value-stable.
A trait should define which of its functions are expected to be value-stable. An implementation of a trait must meet those stability requirements, unless the object for which the trait is implemented is explicitly not value-stable. As an example,
SeedableRng::from_seed is required to be value-stable, but
SeedableRng::from_rng is not. RNGs implementing the trait are value-stable when they guarantee
SeedableRng::from_seed is value-stable, while
SeedableRng::from_rng may receive optimisations.
Before 1.0, we allow any new minor version to break value-stability, though we do expect such changes to be mentioned in the changelog. Post 1.0 we have not yet determined exact stability rules.
Additionally, we expect patch versions not to change the output of any deterministic functions, even if not value-stable (this is not a hard requirement, but exceptions should be noted in the changelog).
Defining which parts of Rand are value-stable is still in progress. Many parts of
rand_core have some documentation on value-stability.
rand_core library has the following scope:
rand library has the following scope:
rand_coreapplicable to end users
thread_rngauto-seeding source of randomness
Note: the scope of the project and above libraries may change. We are currently discussing moving PRNGs (#431) and distributions (#290) to other libraries or projects.
We do not currently have many policies on style other than:
Rand does make use of
unsafe, both for performance and out of necessity. We consider this acceptable so long as correctness is easy to verify. In order to make this as simple as possible, we prefer that all parameters affecting safety of
unsafe blocks are checked or prepared close to the
unsafe code, and wherever possible within the same function (thus making the function safe).
The Rand library includes several pseudo-random number generators, and we have received several requests to adopt new algorithms into the library. We must consider such requests in regards to several things:
In general, we expect the following, though we may make exceptions: