diff options
author | Robin Krahl <me@robin-krahl.de> | 2018-12-11 23:50:45 +0100 |
---|---|---|
committer | Daniel Mueller <deso@posteo.net> | 2018-12-17 07:52:13 -0800 |
commit | 986ad2f782cf944990e4eda8bf88ea1821233302 (patch) | |
tree | 1717075a4eb11861c32e5c45d01e47360fb1264d /rand/README.md | |
parent | e97c287c01cf22a1b582a7da9b309b58f3935d0e (diff) | |
download | nitrocli-986ad2f782cf944990e4eda8bf88ea1821233302.tar.gz nitrocli-986ad2f782cf944990e4eda8bf88ea1821233302.tar.bz2 |
Add nitrokey as a dependency to nitrocli
The nitrokey crate provides a simple interface to the Nitrokey Storage
and the Nitrokey Pro based on the libnitrokey library developed by
Nitrokey UG. The low-level bindings to this library are available in
the nitrokey-sys crate.
This patch adds version v0.2.1 of the nitrokey crate as a dependency
for nitrocli. It includes the indirect dependencies nitrokey-sys
(version 3.4.1) and rand (version 0.4.3).
Import subrepo nitrokey/:nitrokey at 2eccc96ceec2282b868891befe9cda7f941fbe7b
Import subrepo nitrokey-sys/:nitrokey-sys at f1a11ebf72610fb9cf80ac7f9f147b4ba1a5336f
Import subrepo rand/:rand at d7d5da49daf7ceb3e5940072940d495cced3a1b3
Diffstat (limited to 'rand/README.md')
-rw-r--r-- | rand/README.md | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/rand/README.md b/rand/README.md new file mode 100644 index 0000000..f72bd51 --- /dev/null +++ b/rand/README.md @@ -0,0 +1,139 @@ +rand +==== + +A Rust library for random number generators and other randomness functionality. + +[![Build Status](https://travis-ci.org/rust-lang-nursery/rand.svg?branch=master)](https://travis-ci.org/rust-lang-nursery/rand) +[![Build status](https://ci.appveyor.com/api/projects/status/rm5c9o33k3jhchbw?svg=true)](https://ci.appveyor.com/project/alexcrichton/rand) + +[Documentation](https://docs.rs/rand) + +## Usage + +Add this to your `Cargo.toml`: + +```toml +[dependencies] +rand = "0.4" +``` + +and this to your crate root: + +```rust +extern crate rand; +``` + +### Versions + +Version `0.4`was released in December 2017. It contains almost no breaking +changes since the `0.3` series, but nevertheless contains some significant +new code, including a new "external" entropy source (`JitterRng`) and `no_std` +support. + +Version `0.5` is in development and contains significant performance +improvements for the ISAAC random number generators. + +## Examples + +There is built-in support for a random number generator (RNG) associated with each thread stored in thread-local storage. This RNG can be accessed via thread_rng, or used implicitly via random. This RNG is normally randomly seeded from an operating-system source of randomness, e.g. /dev/urandom on Unix systems, and will automatically reseed itself from this source after generating 32 KiB of random data. + +```rust +let tuple = rand::random::<(f64, char)>(); +println!("{:?}", tuple) +``` + +```rust +use rand::Rng; + +let mut rng = rand::thread_rng(); +if rng.gen() { // random bool + println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>()) +} +``` + +It is also possible to use other RNG types, which have a similar interface. The following uses the "ChaCha" algorithm instead of the default. + +```rust +use rand::{Rng, ChaChaRng}; + +let mut rng = rand::ChaChaRng::new_unseeded(); +println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>()) +``` + +## Features + +By default, `rand` is built with all stable features available. The following +optional features are available: + +- `i128_support` enables support for generating `u128` and `i128` values +- `nightly` enables all unstable features (`i128_support`) +- `std` enabled by default; by setting "default-features = false" `no_std` + mode is activated; this removes features depending on `std` functionality: + + - `OsRng` is entirely unavailable + - `JitterRng` code is still present, but a nanosecond timer must be + provided via `JitterRng::new_with_timer` + - Since no external entropy is available, it is not possible to create + generators with fresh seeds (user must provide entropy) + - `thread_rng`, `weak_rng` and `random` are all disabled + - exponential, normal and gamma type distributions are unavailable + since `exp` and `log` functions are not provided in `core` + - any code requiring `Vec` or `Box` +- `alloc` can be used instead of `std` to provide `Vec` and `Box` + +## Testing + +Unfortunately, `cargo test` does not test everything. The following tests are +recommended: + +``` +# Basic tests for rand and sub-crates +cargo test --all + +# Test no_std support (build only since nearly all tests require std) +cargo build --all --no-default-features + +# Test 128-bit support (requires nightly) +cargo test --all --features nightly + +# Benchmarks (requires nightly) +cargo bench +# or just to test the benchmark code: +cargo test --benches +``` + +# `derive(Rand)` + +You can derive the `Rand` trait for your custom type via the `#[derive(Rand)]` +directive. To use this first add this to your Cargo.toml: + +```toml +rand = "0.4" +rand_derive = "0.3" +``` + +Next in your crate: + +```rust +extern crate rand; +#[macro_use] +extern crate rand_derive; + +#[derive(Rand, Debug)] +struct MyStruct { + a: i32, + b: u32, +} + +fn main() { + println!("{:?}", rand::random::<MyStruct>()); +} +``` + + +# License + +`rand` is primarily distributed under the terms of both the MIT +license and the Apache License (Version 2.0). + +See LICENSE-APACHE, and LICENSE-MIT for details. |