From f007f2f771dd05ac58618abee9d31a3388836754 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gon=C3=A7alo=20Rica=20Pais=20da=20Silva?= Date: Tue, 27 Feb 2024 12:42:18 +0100 Subject: [PATCH] docs: Unify README content, add docs.rs config --- Cargo.toml | 3 +++ README.md | 10 ++++++---- src/hasher.rs | 4 ++-- src/lib.rs | 39 +++++---------------------------------- 4 files changed, 16 insertions(+), 40 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 3af99ef..996d397 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -32,3 +32,6 @@ serde_test = "1.0" [[bench]] name = "rand_bench" harness = false + +[package.metadata.docs.rs] +all-features = true diff --git a/README.md b/README.md index e8aff3e..577bc7e 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,12 @@ [![Cargo](https://img.shields.io/crates/v/wyrand.svg)](https://crates.io/crates/wyrand) [![Documentation](https://docs.rs/wyrand/badge.svg)](https://docs.rs/wyrand) -A fast & portable non-cryptographic pseudorandom number generator written in Rust, and optionally, -the hashing algorithm as well. +A fast & portable non-cryptographic pseudorandom number generator written in Rust, and optionally, the hashing algorithm as well. The implementations for both the PRNG and hasher are based on the final v4 C implementation [wyhash](https://github.com/wangyi-fudan/wyhash), a simple and fast hasher but **not** cryptographically secure. It's known to be extremely fast and performant while still having great statistical properties. +This crate provides both the v4.2 final implementation of the WyRand/WyHash algorithm (by default), or the older final v4 implementation. The two versions have different outputs due to changes in the algorithm and also with the constants used. + This crate can be used on its own or be integrated with `rand_core`/`rand`, and it is `no-std` compatible. Minimum compatible Rust version is 1.60. This crate is also implemented with no unsafe code via `#![forbid(unsafe_code)]`. ## Example @@ -27,13 +28,14 @@ let value = rng.rand(); ## Features -The crate will always export `WyRand` and will do so when set as `default-features = false` in the Cargo.toml. By default, it will have the `rand_core` & `debug` features enabled. +The crate will always export `WyRand` and will do so when set as `default-features = false` in the Cargo.toml. By default, it will have the `rand_core`, `debug` & `v4_2` features enabled. - **`rand_core`** - Enables support for `rand_core`, implementing `RngCore` & `SeedableRng` on `WyRand`. -- **`debug`** - Enables `core::fmt::Debug` implementation for `WyRand`. +- **`debug`** - Enables `core::fmt::Debug` implementation for `WyRand`/`WyHash`. - **`serde1`** - Enables `Serialize` and `Deserialize` derives on `WyRand`. - **`hash`** - Enables `core::hash::Hash` implementation for `WyRand`. - **`wyhash`** - Enables `WyHash`, a fast & portable hashing algorithm. Based on the final v4 C implementation. +- **`v4_2`** - Switches the PRNG/Hashing algorithms to use the final v4.2 implementation. On by default. ## License diff --git a/src/hasher.rs b/src/hasher.rs index 18a0fc0..95b4a2d 100644 --- a/src/hasher.rs +++ b/src/hasher.rs @@ -1,7 +1,7 @@ -mod read; -mod secret; #[cfg(feature = "v4_2")] mod primes; +mod read; +mod secret; use core::hash::Hasher; diff --git a/src/lib.rs b/src/lib.rs index 2f4531f..c98db17 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,39 +1,9 @@ -//! A fast & portable non-cryptographic pseudorandom number generator written in Rust. -//! -//! The implementation is based on [wyhash](https://github.com/wangyi-fudan/wyhash), a -//! simple and fast hasher but **not**cryptographically secure. It's known to be extremely -//! fast and performant while still having great statistical properties. -//! -//! This crate can be used on its own or be integrated with `rand_core`/`rand`, and it is -//! `no-std` compatible. Minimum compatible Rust version is 1.60. -//! -//! # Example -//! -//! Generate a random value: -//! -//! ```rust -//! use wyrand::WyRand; -//! -//! // Provide a seed to the PRNG -//! let mut rng = WyRand::new(Default::default()); -//! -//! let value = rng.rand(); -//! ``` -//! -//! # Features -//! -//! The crate will always export [`WyRand`] and will do so when set as -//! `default-features = false` in the Cargo.toml. By default, it will have the`rand_core` -//! & `debug` features enabled. -//! -//! * **`rand_core`** - Enables support for `rand_core`, implementing `RngCore` & -//! `SeedableRng` on [`WyRand`]. -//! * **`debug`** - Enables [`core::fmt::Debug`] implementation for [`WyRand`]. -//! * **`serde1`** - Enables `Serialize` and `Deserialize` derives on [`WyRand`]. -//! * **`hash`** - Enables [`core::hash::Hash`] implementation for [`WyRand`]. -#![warn(missing_docs)] +#![deny(missing_docs)] #![forbid(unsafe_code)] +#![cfg_attr(docsrs, feature(doc_cfg))] +#![cfg_attr(docsrs, allow(unused_attributes))] #![no_std] +#![doc = include_str!("../README.md")] mod constants; #[cfg(feature = "wyhash")] @@ -42,5 +12,6 @@ mod rand; mod utils; #[cfg(feature = "wyhash")] +#[cfg_attr(docsrs, doc(cfg(feature = "wyhash")))] pub use hasher::WyHash; pub use rand::WyRand;