diff --git a/.config/artichoke.dic b/.config/artichoke.dic new file mode 100644 index 000000000..c14451398 --- /dev/null +++ b/.config/artichoke.dic @@ -0,0 +1,22 @@ +250 +@generated +CPUs +Lopopolo +Makoto +Matsumoto +Mersenne +PRNG +RNG/S +autogenerated +callouts +cryptographic +endian +impl/S +mt +mt64 +natively +pseudorandom +rand_mt +src +struct/S +tokio diff --git a/.config/spellcheck.toml b/.config/spellcheck.toml new file mode 100644 index 000000000..f591b9812 --- /dev/null +++ b/.config/spellcheck.toml @@ -0,0 +1,65 @@ +# Also take into account developer comments +dev_comments = true +# Skip the README.md file as defined in the cargo manifest +skip_readme = false + +[Hunspell] +# lang and name of `.dic` file +lang = "en_US" +# OS specific additives +# Linux: [ /usr/share/myspell ] +# Windows: [] +# macOS [ /home/alice/Libraries/hunspell, /Libraries/hunspell ] + +# Additional search paths, which take presedence over the default +# os specific search dirs, searched in order, defaults last +search_dirs = ["."] + +# Adds additional dictionaries, can be specified as +# absolute paths or relative in the search dirs (in this order). +# Relative paths are resolved relative to the configuration file +# which is used. +# Refer to `man 5 hunspell` +# or https://www.systutorials.com/docs/linux/man/4-hunspell/#lbAE +# on how to define a custom dictionary file. +extra_dictionaries = ["artichoke.dic"] + +# If set to `true`, the OS specific default search paths +# are skipped and only explicitly specified ones are used. +skip_os_lookups = false + +# Use the builtin dictionaries if none were found in +# in the configured lookup paths. +# Usually combined with `skip_os_lookups=true` +# to enforce the `builtin` usage for consistent +# results across distributions and CI runs. +# Setting this will still use the dictionaries +# specified in `extra_dictionaries = [..]` +# for topic specific lingo. +use_builtin = true + + +[Hunspell.quirks] +# Transforms words that are provided by the tokenizer +# into word fragments based on the capture groups which are to +# be checked. +# If no capture groups are present, the matched word is whitelisted. +transform_regex = ["^'([^\\s])'$", "^[0-9]+x$"] +# Accepts `alphabeta` variants if the checker provides a replacement suggestion +# of `alpha-beta`. +allow_concatenation = true +# And the counterpart, which accepts words with dashes, when the suggestion has +# recommendations without the dashes. This is less common. +allow_dashed = false + +[NlpRules] +# Allows the user to override the default included +# exports of LanguageTool, with other custom +# languages + +# override_rules = "/path/to/rules_binencoded.bin" +# override_tokenizer = "/path/to/tokenizer_binencoded.bin" + +[Reflow] +# Reflows doc comments to adhere to adhere to a given maximum line width limit. +max_line_length = 80 diff --git a/.gitignore b/.gitignore index fc3224bc9..d590539b2 100644 --- a/.gitignore +++ b/.gitignore @@ -96,3 +96,11 @@ tags [._]*.un~ # End of https://www.toptal.com/developers/gitignore/api/vim,rust,ruby + +# Overrides + +# Cargo and other Rust tool configuration lives in a top-level `.config/` directory. +!/.config/ +# https://github.com/sourcefrog/cargo-mutants/blob/main/.gitignore +mutants.out +mutants.out.old diff --git a/Cargo.toml b/Cargo.toml index 389a43e81..8e16a6c77 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "rand_mt" -version = "4.2.0" # remember to set `html_root_url` in `src/lib.rs`. +version = "4.2.1" # remember to set `html_root_url` in `src/lib.rs`. authors = ["David Creswick ", "Ryan Lopopolo "] license = "MIT OR Apache-2.0" edition = "2018" diff --git a/README.md b/README.md index cc35c559f..750ff7518 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![API](https://docs.rs/rand_mt/badge.svg)](https://docs.rs/rand_mt) [![API trunk](https://img.shields.io/badge/docs-trunk-blue.svg)](https://artichoke.github.io/rand_mt/rand_mt/) -Implemenents a selection of Mersenne Twister random number generators. +Implements a selection of Mersenne Twister random number generators. > A very fast random number generator of period 219937-1. (Makoto > Matsumoto, 1997). @@ -17,7 +17,7 @@ The Mersenne Twister algorithms are not suitable for cryptographic uses, but are ubiquitous. See the [Mersenne Twister website]. A variant of Mersenne Twister is the [default PRNG in Ruby]. -This crate optionally depends on [rand_core] and implements `RngCore` on the +This crate optionally depends on [`rand_core`] and implements `RngCore` on the RNGs in this crate. ## Usage @@ -26,7 +26,7 @@ Add this to your `Cargo.toml`: ```toml [dependencies] -rand_mt = "4.2.0" +rand_mt = "4.2.1" ``` Then create a RNG like: @@ -48,9 +48,9 @@ are enabled by default: - **std** - Enables a dependency on the Rust Standard Library. Activating this feature enables [`std::error::Error`] impls on error types in this crate. -Mersenne Twister requires ~2.5KB of internal state. To make the RNGs implemented -in this crate practical to embed in other structs, you may wish to store the RNG -in a `Box`. +Mersenne Twister requires approximately 2.5 kilobytes of internal state. To make +the RNGs implemented in this crate practical to embed in other structs, you may +wish to store the RNG in a `Box`. ### Minimum Supported Rust Version @@ -69,7 +69,7 @@ releases. [mersenne twister website]: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html [default prng in ruby]: https://ruby-doc.org/core-3.1.2/Random.html -[rand_core]: https://crates.io/crates/rand_core +[`rand_core`]: https://crates.io/crates/rand_core [`rand_core`]: https://crates.io/crates/rand_core [`std::error::error`]: https://doc.rust-lang.org/std/error/trait.Error.html [`1.1.1`]: https://github.com/dcrewi/rust-mersenne-twister/tree/1.1.1 diff --git a/src/lib.rs b/src/lib.rs index 155803aeb..fcd728496 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. @@ -42,9 +42,9 @@ //! `MT19937` and produces 64-bit output. This is a good choice on 64-bit //! CPUs. //! -//! Both of these use 2.5KB of state. [`Mt19937GenRand32`] uses a 32-bit seed. -//! [`Mt19937GenRand64`] uses a 64-bit seed. Both can be seeded from an iterator -//! of seeds. +//! Both of these RNGs use approximately 2.5 kilobytes of state. +//! [`Mt19937GenRand32`] uses a 32-bit seed. [`Mt19937GenRand64`] uses a 64-bit +//! seed. Both can be seeded from an iterator of seeds. //! //! Both RNGs implement a `recover` constructor which can reconstruct the RNG //! state from a sequence of output samples. @@ -83,14 +83,26 @@ //! this feature enables [`std::error::Error`] impls on error types in this //! crate. //! -//! Mersenne Twister requires ~2.5KB of internal state. To make the RNGs -//! implemented in this crate practical to embed in other structs, you may wish -//! to store the RNG in a `Box`. +//! Mersenne Twister requires approximately 2.5 kilobytes of internal state. To +//! make the RNGs implemented in this crate practical to embed in other structs, +//! you may wish to store the RNG in a [`Box`]. +//! +#![cfg_attr( + not(feature = "std"), + doc = "[`std::error::Error`]: https://doc.rust-lang.org/std/error/trait.Error.html" +)] +#![cfg_attr(feature = "std", doc = "[`Box`]: std::boxed::Box")] +#![cfg_attr( + not(feature = "std"), + doc = "[`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html" +)] +#![cfg_attr( + not(feature = "rand_core"), + doc = "[`rand_core`]: https://crates.io/crates/rand_core" +)] //! -//! [`rand_core`]: https://crates.io/crates/rand_core -//! [`std::error::error`]: https://doc.rust-lang.org/std/error/trait.Error.html -#![doc(html_root_url = "https://docs.rs/rand_mt/4.2.0")] +#![doc(html_root_url = "https://docs.rs/rand_mt/4.2.1")] #![no_std] #[cfg(feature = "std")] @@ -178,7 +190,7 @@ mod tests { } } -// Ensure code blocks in README.md compile +// Ensure code blocks in `README.md` compile. // // This module and macro declaration should be kept at the end of the file, in // order to not interfere with code coverage. diff --git a/src/mt.rs b/src/mt.rs index 37f65e3f5..fe267da7e 100644 --- a/src/mt.rs +++ b/src/mt.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. @@ -33,9 +33,9 @@ const LOWER_MASK: Wrapping = Wrapping(0x7fff_ffff); /// /// # Size /// -/// `Mt19937GenRand32` requires approximately 2.5KB of internal state. +/// `Mt19937GenRand32` requires approximately 2.5 kilobytes of internal state. /// -/// You may wish to store an `Mt19937GenRand32` on the heap in a `Box` to make +/// You may wish to store an `Mt19937GenRand32` on the heap in a [`Box`] to make /// it easier to embed in another struct. /// /// `Mt19937GenRand32` is also the same size as @@ -47,6 +47,11 @@ const LOWER_MASK: Wrapping = Wrapping(0x7fff_ffff); /// assert_eq!(2504, mem::size_of::()); /// assert_eq!(mem::size_of::(), mem::size_of::()); /// ``` +#[cfg_attr(feature = "std", doc = "[`Box`]: std::boxed::Box")] +#[cfg_attr( + not(feature = "std"), + doc = "[`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html" +)] #[derive(Clone, Hash, PartialEq, Eq, PartialOrd, Ord)] #[allow(clippy::module_name_repetitions)] pub struct Mt19937GenRand32 { @@ -256,7 +261,7 @@ impl Mt19937GenRand32 { /// Generate next `u64` output. /// /// This function is implemented by generating two `u32`s from the RNG and - /// shifting + masking them into a `u64` output. + /// performing shifting and masking to turn them into a `u64` output. /// /// # Examples /// @@ -455,20 +460,20 @@ fn temper(mut x: u32) -> u32 { #[inline] fn untemper(mut x: u32) -> u32 { - // reverse "x ^= x>>18;" + // reverse `x ^= x>>18;` x ^= x >> 18; - // reverse "x ^= (x<<15) & 0xefc6_0000;" + // reverse `x ^= (x<<15) & 0xefc6_0000;` x ^= (x << 15) & 0x2fc6_0000; x ^= (x << 15) & 0xc000_0000; - // reverse "x ^= (x<< 7) & 0x9d2c_5680;" + // reverse `x ^= (x<< 7) & 0x9d2c_5680;` x ^= (x << 7) & 0x0000_1680; x ^= (x << 7) & 0x000c_4000; x ^= (x << 7) & 0x0d20_0000; x ^= (x << 7) & 0x9000_0000; - // reverse "x ^= x>>11;" + // reverse `x ^= x>>11;` x ^= x >> 11; x ^= x >> 22; diff --git a/src/mt/rand.rs b/src/mt/rand.rs index 9bdb0e877..911f4ff54 100644 --- a/src/mt/rand.rs +++ b/src/mt/rand.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. @@ -42,7 +42,7 @@ impl RngCore for Mt19937GenRand32 { /// Generate next `u64` output. /// /// This function is implemented by generating two `u32`s from the RNG and - /// shifting + masking them into a `u64` output. + /// performing shifting and masking to turn them into a `u64` output. /// /// # Examples /// diff --git a/src/mt64.rs b/src/mt64.rs index bffa403ab..e64216225 100644 --- a/src/mt64.rs +++ b/src/mt64.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. @@ -31,9 +31,9 @@ const LM: Wrapping = Wrapping(0x7fff_ffff); // Least significant 31 bits /// /// # Size /// -/// `Mt19937GenRand64` requires approximately 2.5KB of internal state. +/// `Mt19937GenRand64` requires approximately 2.5 kilobytes of internal state. /// -/// You may wish to store an `Mt19937GenRand64` on the heap in a `Box` to make it +/// You may wish to store an `Mt19937GenRand64` on the heap in a [`Box`] to make it /// easier to embed in another struct. /// /// `Mt19937GenRand64` is also the same size as @@ -45,6 +45,11 @@ const LM: Wrapping = Wrapping(0x7fff_ffff); // Least significant 31 bits /// assert_eq!(2504, mem::size_of::()); /// assert_eq!(mem::size_of::(), mem::size_of::()); /// ``` +#[cfg_attr(feature = "std", doc = "[`Box`]: std::boxed::Box")] +#[cfg_attr( + not(feature = "std"), + doc = "[`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html" +)] #[derive(Clone, Hash, PartialEq, Eq, PartialOrd, Ord)] pub struct Mt19937GenRand64 { idx: usize, @@ -264,8 +269,8 @@ impl Mt19937GenRand64 { /// Generate next `u32` output. /// - /// This function is implemented by generating one `u64`s from the RNG and - /// shifting + masking them into a `u32` output. + /// This function is implemented by generating one `u64` from the RNG and + /// performing shifting and masking to turn it into a `u32` output. /// /// # Examples /// @@ -439,18 +444,18 @@ fn temper(mut x: u64) -> u64 { #[inline] fn untemper(mut x: u64) -> u64 { - // reverse "x ^= x >> 43;" + // reverse `x ^= x >> 43;` x ^= x >> 43; - // reverse "x ^= (x << 37) & 0xfff7_eee0_0000_0000;" + // reverse `x ^= (x << 37) & 0xfff7_eee0_0000_0000;` x ^= (x << 37) & 0xfff7_eee0_0000_0000; - // reverse "x ^= (x << 17) & 0x71d6_7fff_eda6_0000;" + // reverse `x ^= (x << 17) & 0x71d6_7fff_eda6_0000;` x ^= (x << 17) & 0x0000_0003_eda6_0000; x ^= (x << 17) & 0x0006_7ffc_0000_0000; x ^= (x << 17) & 0x71d0_0000_0000_0000; - // reverse "x ^= (x >> 29) & 0x5555_5555_5555_5555;" + // reverse `x ^= (x >> 29) & 0x5555_5555_5555_5555;` x ^= (x >> 29) & 0x0000_0005_5555_5540; x ^= (x >> 29) & 0x0000_0000_0000_0015; diff --git a/src/mt64/rand.rs b/src/mt64/rand.rs index 4d579634a..ce6888deb 100644 --- a/src/mt64/rand.rs +++ b/src/mt64/rand.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. @@ -59,8 +59,8 @@ impl RngCore for Mt19937GenRand64 { /// Generate next `u32` output. /// - /// This function is implemented by generating one `u64`s from the RNG and - /// shifting + masking them into a `u32` output. + /// This function is implemented by generating one `u64` from the RNG and + /// performing shifting and masking to turn it into a `u32` output. /// /// # Examples /// diff --git a/src/vectors.rs b/src/vectors.rs index 74eba2981..a0a928dd8 100644 --- a/src/vectors.rs +++ b/src/vectors.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. diff --git a/src/vectors/mt.rs b/src/vectors/mt.rs index 84aabe2c7..c3d949fc7 100644 --- a/src/vectors/mt.rs +++ b/src/vectors/mt.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms. diff --git a/src/vectors/mt64.rs b/src/vectors/mt64.rs index f99daf328..e20a8bf0e 100644 --- a/src/vectors/mt64.rs +++ b/src/vectors/mt64.rs @@ -4,8 +4,8 @@ // Copyright (c) 2020 Ryan Lopopolo // // Licensed under the Apache License, Version 2.0 -// or the MIT -// license , at your +// or or the MIT +// license or , at your // option. All files in the project carrying such notice may not be copied, // modified, or distributed except according to those terms.