Skip to content

Commit

Permalink
### Summary of Changes:
Browse files Browse the repository at this point in the history 
- Enhanced the formatting for a more organized and polished appearance.
- Added better alignment for consistency and visual appeal.
- Updated sections for clarity and conciseness.
- Improved readability by refining the wording in various sections.
- Updated README.md
  • Loading branch information
@sebastienrousseau
sebastienrousseau committed Aug 26, 2024
1 parent 3bd66b8 commit a48d9ec
Show file tree
Hide file tree
Showing 4 changed files with 291 additions and 306 deletions.
276 changes: 83 additions & 193 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- markdownlint-disable MD033 MD041 -->

<img src="https://kura.pro/vrd/images/logos/vrd.svg"
alt="Random (VRD) logo" height="261" width="261" align="right" />
alt="Random (VRD) logo" width="66" align="right" />

<!-- markdownlint-enable MD033 MD041 -->

Expand All @@ -10,85 +10,54 @@ alt="Random (VRD) logo" height="261" width="261" align="right" />
A Rust library for generating high-quality random numbers based on the Mersenne
Twister algorithm.

*Part of the [Mini Functions][00] family of libraries.*
[![Made With Love][made-with-rust]][11] [![Crates.io][crates-badge]][06] [![lib.rs][libs-badge]][08] [![Docs.rs][docs-badge]][07] [![Codecov][codecov-badge]][12] [![Build Status][build-badge]][09] [![GitHub][github-badge]][13]

![divider][divider]

<!-- markdownlint-disable MD033 MD041 -->
<center>
<!-- markdownlint-enable MD033 MD041 -->

![Random (VRD) Banner][banner]

[![Made With Rust][made-with-rust-badge]][14] [![Crates.io][crates-badge]][08]
[![Lib.rs][libs-badge]][10] [![Docs.rs][docs-badge]][09]
[![License][license-badge]][02] [![Codecov][codecov-badge]][15]

• [Website][01] • [Documentation][09] • [Report Bug][04]
• [Request Feature][04] • [Contributing Guidelines][05]
• [Website][00] • [Documentation][07] • [Report Bug][03]
• [Request Feature][03] • [Contributing Guidelines][04]

<!-- markdownlint-disable MD033 MD041 -->
</center>
<!-- markdownlint-enable MD033 MD041 -->

![divider][divider]

## Overview 📖

`Random (VRD)` is a Rust library for generating high-quality random numbers
based on the Mersenne Twister algorithm.

The `Random` struct in this library provides a robust interface for generating
a variety of random numbers using the Mersenne Twister algorithm. Additionally,
the `MersenneTwisterConfig` struct allows for advanced configuration of the
algorithm.
## Overview

The Random (VRD) is used to generate random numbers using the Mersenne Twister
algorithm. It generates pseudorandom integers uniformly distributed in
0..(2^32 - 1) starting from any odd seed in 0..(2^32 - 1).
`Random (VRD)` is a Rust library for generating high-quality random numbers based on the Mersenne Twister algorithm.

The index is incremented after each random number is generated. When the index
reaches 624, the array is reinitialized and the index is reset to 0.
The `Random` struct in this library provides a robust interface for generating a variety of random numbers using the Mersenne Twister algorithm. Additionally, the `MersenneTwisterConfig` struct allows for advanced configuration of the algorithm.

## Features ✨
`Random (VRD)` generates pseudorandom integers uniformly distributed in 0..(2^32 - 1), starting from any odd seed in 0..(2^32 - 1). The index is incremented after each random number is generated. When the index reaches 624, the array is reinitialized and the index is reset to 0.

- Create new random number generator and seed it with a value
- Designed for speed and efficiency
- Generate random 32-bit unsigned integers within a given range
- Provide random numbers of different types, including booleans, bytes, chars,
doubles, floats, integers, and unsigned integers
- Mutate the state of the random number generator
- Produce pseudo-random number sequences that are different from each other
- Regulate the randomness of the generated numbers, including the seed value
and the number of bits used
- Select a random element from a slice of values
- Generate random numbers from various probability distributions, including
uniform, normal, exponential, and Poisson
## Features

## Getting Started 🚀
- Create a new random number generator and seed it with a value.
- Designed for speed and efficiency.
- Generate random 32-bit unsigned integers within a given range.
- Provide random numbers of different types, including booleans, bytes, chars, doubles, floats, integers, and unsigned integers.
- Mutate the state of the random number generator.
- Produce pseudorandom number sequences that are different from each other.
- Regulate the randomness of the generated numbers, including the seed value and the number of bits used.
- Select a random element from a slice of values.
- Generate random numbers from various probability distributions, including uniform, normal, exponential, and Poisson.

It takes just a few minutes to get up and running with `Random (VRD)`.
## Installation

### Installation

To install `Random (VRD)`, you need to have the Rust toolchain installed on
your machine. You can install the Rust toolchain by following the instructions
on the [Rust website][14].

Once you have the Rust toolchain installed, you can install `Random (VRD)`
using the following command:

```shell
cargo install vrd
```

Add the following to your `Cargo.toml` file:
Add this to your `Cargo.toml`:

```toml
[dependencies]
vrd = "0.0.8"
serde = { version = "1.0.160", features = ["derive"] }
serde = { version = "1.0.209", features = ["derive"] }
```

### Usage
## Usage

Here's a quick example on how to use Random (VRD) to generate random numbers:

```rust
use vrd::random::Random;
Expand All @@ -104,161 +73,82 @@ let rand_bytes = rng.bytes(10);
println!("Random bytes: {:?}", rand_bytes);
```

### Examples
## Documentation

To get started with `Random (VRD)`, you can use the examples provided in the
`examples` directory of the project.
For full API documentation, please visit <https://doc.libyml.com/vrd/> or <https://docs.rs/vrd>.

To run the examples, clone the repository and run the following command in your
terminal from the project root directory.
## Rust Version Compatibility

Compiler support: requires rustc 1.56.0+

## Examples

`Random (VRD)` provides a set of comprehensive examples. You can find them in the `examples` directory of the project. To run the examples, clone the repository and execute the following command in your terminal from the project:

```shell
cargo run --example vrd
cargo run --example example
```

## Macros 🦀
## Macros

The `Random (VRD)` library provides a set of macros that simplify the usage of
the library. These macros offer a convenient way to generate random numbers of
different types and distributions.
The `Random (VRD)` library provides a set of macros that simplify the usage of the library. These macros offer a convenient way to generate random numbers of different types and distributions.

Here are some of the available macros:

- `rand_bool!(rng, probability)`: Generate a random boolean with the provided
probability.
- `rand_bytes!(rng, length)`: Generate a vector of random bytes with the
specified length.
- `rand_bool!(rng, probability)`: Generate a random boolean with the provided probability.
- `rand_bytes!(rng, length)`: Generate a vector of random bytes with the specified length.
- `rand_char!(rng)`: Generate a random character within the range 'a'..='z'.
- `rand_choose!(rng, values)`: Generate a random element from a slice of values.
- `rand_float!(rng)`: Generate a random float.
- `rand_int!(rng, min, max)`: Generate a random integer within the given range.
- `rand_uint!(rng, min, max)`: Generate a random 32-bit unsigned integer within
the given range.
- `rand_uint!(rng, min, max)`: Generate a random 32-bit unsigned integer within the given range.
- `rand_double!(rng)`: Generate a random double.
- `rand_string!(rng, length)`: Generate a random string of the specified length.
- `rand_alphanumeric!(rng)`: Generate a random alphanumeric character.
- `rand_shuffle!(rng, slice)`: Shuffle a mutable slice randomly.
- `rand_weighted_choice!(rng, choices, weights)`: Select a random element from
a slice based on the provided weights.
- `rand_normal!(rng, mu, sigma)`: Generate a normally distributed random number
with the given mean and standard deviation.
- `rand_exponential!(rng, rate)`: Generate a random number from the exponential
distribution with the given rate parameter.
- `rand_poisson!(rng, mean)`: Generate a random number from a Poisson
distribution with the specified mean parameter.

For more details on how to use these macros, please refer to the
[documentation](https://docs.rs/vrd).

### Platform support

`Random (VRD)` is supported and tested on the following platforms:

#### Tier 1 platforms 🏆

| Operating System | Target | Description |
| --- | --- | --- |
| Linux | aarch64-unknown-linux-gnu | 64-bit Linux systems on ARM architecture |
| Linux | i686-unknown-linux-gnu | 32-bit Linux (kernel 3.2+, glibc 2.17+) |
| Linux | x86_64-unknown-linux-gnu | 64-bit Linux (kernel 2.6.32+, glibc 2.11+) |
| macOS | x86_64-apple-darwin | 64-bit macOS (10.7 Lion or later) |
| Windows | i686-pc-windows-gnu | 32-bit Windows (7 or later) |
| Windows | i686-pc-windows-msvc | 32-bit Windows (7 or later) |
| Windows | x86_64-pc-windows-gnu | 64-bit Windows (7 or later) |
| Windows | x86_64-pc-windows-msvc | 64-bit Windows (7 or later) |

#### Tier 2 platforms 🥈

| Operating System | Target | Description |
| --- | --- | --- |
| 64-bit Linux | x86_64-unknown-linux-musl | 64-bit Linux (kernel 2.6.32+, musl libc) |
| ARM64 Linux | aarch64-unknown-linux-musl | 64-bit Linux systems on ARM architecture |
| ARM64 macOS | aarch64-apple-darwin | 64-bit macOS on Apple Silicon |
| ARM64 Windows | aarch64-pc-windows-msvc | 64-bit Windows (aarch64-pc-windows-msvc) |
| ARMv6 Linux | arm-unknown-linux-gnueabi | ARMv6 Linux (kernel 3.2, glibc 2.17) |
| ARMv6 Linux, hardfloat | arm-unknown-linux-gnueabihf | ARMv7 Linux, hardfloat (kernel 3.2, glibc 2.17) |
| ARMv7 Linux, hardfloat | armv7-unknown-linux-gnueabihf | ARMv7 Linux, hardfloat (kernel 3.2, glibc 2.17) |
| FreeBSD | x86_64-unknown-freebsd | 64-bit FreeBSD on x86-64 |
| MIPS (LE) Linux | mipsel-unknown-linux-gnu | MIPSel Linux (kernel 2.6.32+, glibc 2.11+) |
| MIPS Linux | mips-unknown-linux-gnu | MIPS Linux (kernel 2.6.32+, glibc 2.11+) |
| MIPS64 (LE) Linux | mips64el-unknown-linux-gnuabi64 | MIPS64el Linux (kernel 2.6.32+, glibc 2.11+) |
| MIPS64 Linux | mips64-unknown-linux-gnuabi64 | MIPS64 Linux (kernel 2.6.32+, glibc 2.11+) |
| NetBSD | x86_64-unknown-netbsd | 64-bit NetBSD on x86-64 |
| PowerPC Linux | powerpc-unknown-linux-gnu | PowerPC Linux (kernel 3.2, glibc 2.17) |
| PPC64 Linux | powerpc64-unknown-linux-gnu | PowerPC64 Linux (kernel 3.2, glibc 2.17) |
| PPC64LE Linux | powerpc64le-unknown-linux-gnu | PowerPC64le Linux (kernel 3.2, glibc 2.17) |
| RISC-V Linux | riscv64gc-unknown-linux-gnu | RISC-V Linux (kernel 3.2, glibc 2.17) |
| S390x Linux | s390x-unknown-linux-gnu | s390x Linux (kernel 3.2, glibc 2.17) |

The [GitHub Actions][11] shows the platforms in which the `Random (VRD)`
library tests are run.

## Documentation 📚

For detailed documentation, please visit:

- [Website](https://vrdlib.com)
- [Docs.rs](https://docs.rs/vrd)
- [Lib.rs](https://lib.rs/crates/vrd)
- [Crates.io](https://crates.io/crates/vrd)

## Semantic Versioning Policy 🚥

For transparency into our release cycle and in striving to maintain backward
compatibility, `Random (VRD)` follows [semantic versioning][07].

## License 📝

The project is licensed under the terms of both the MIT license and the Apache
License (Version 2.0).

- [Apache License, Version 2.0][02]
- [MIT license][03]

## Contribution 🤝

We welcome all people who want to contribute. Please see the
[contributing instructions][05] for more information.

Contributions in any form (issues, pull requests, etc.) to this project must
adhere to the [Rust's Code of Conduct][12].

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

## Acknowledgements 💙

A big thank you to all the awesome contributors of [vrd][06] for their help and
support.

A special thank you goes to the [Rust Reddit][13] community for providing a
lot of useful suggestions on how to improve this project.

*Made with ❤️ by [Sébastien Rousseau](https://sebastienrousseau.com)*

[00]: https://minifunctions.com/ "MiniFunctions"
[01]: https://vrdlib.com "Random (VRD)"
[02]: https://opensource.org/license/apache-2-0/ "Apache License, Version 2.0"
[03]: https://opensource.org/licenses/MIT "MIT license"
[04]: https://github.com/sebastienrousseau/vrd/issues "Issues"
[05]: https://github.com/sebastienrousseau/vrd/blob/main/CONTRIBUTING.md "Contributing Instructions"
[06]: https://github.com/sebastienrousseau/vrd/graphs/contributors "Contributors"
[07]: http://semver.org/ "Semantic Versioning"
[08]: https://crates.io/crates/vrd "Crates.io"
[09]: https://docs.rs/vrd "Docs.rs"
[10]: https://lib.rs/crates/vrd "Lib.rs"
[11]: https://github.com/sebastienrousseau/vrd/actions "GitHub Actions"
[12]: https://www.rust-lang.org/policies/code-of-conduct "Rust's Code of Conduct"
[13]: https://reddit.com/r/rust "Rust Reddit"
[14]: https://www.rust-lang.org "The Rust Programming Language"
[15]: https://codecov.io/gh/sebastienrousseau/vrd "Codecov"

[banner]: https://kura.pro/vrd/images/titles/title-vrd.svg 'Random (VRD) Banner'
- `rand_weighted_choice!(rng, choices, weights)`: Select a random element from a slice based on the provided weights.
- `rand_normal!(rng, mu, sigma)`: Generate a normally distributed random number with the given mean and standard deviation.
- `rand_exponential!(rng, rate)`: Generate a random number from the exponential distribution with the given rate parameter.
- `rand_poisson!(rng, mean)`: Generate a random number from a Poisson distribution with the specified mean parameter.

For more details on how to use these macros, please refer to the [documentation](https://docs.rs/vrd).

## Contributing

Contributions are welcome! Please submit a Pull Request on [GitHub][04].

## Credits and Acknowledgements

A big thank you to all the awesome contributors of [vrd][05] for their help and support.

A special thank you goes to the [Rust Reddit][10] community for providing a lot of useful suggestions on how to improve this project.

## License

Licensed under either of the [Apache License][01] or the [MIT license][02] at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

[00]: https://vrdlib.com "Random (VRD)"
[01]: https://opensource.org/license/apache-2-0/ "Apache License, Version 2.0"
[02]: https://opensource.org/licenses/MIT "MIT license"
[03]: https://github.com/sebastienrousseau/vrd/issues "Issues"
[04]: https://github.com/sebastienrousseau/vrd/blob/main/CONTRIBUTING.md "Contributing Instructions"
[05]: https://github.com/sebastienrousseau/vrd/graphs/contributors "Contributors"
[06]: https://crates.io/crates/vrd "Crates.io"
[07]: https://docs.rs/vrd "Docs.rs"
[08]: https://lib.rs/crates/vrd "Lib.rs"
[09]: https://github.com/sebastienrousseau/vrd/actions?query=branch%3Amain
[10]: https://reddit.com/r/rust "Rust Reddit"
[11]: https://www.rust-lang.org "The Rust Programming Language"
[12]: https://codecov.io/gh/sebastienrousseau/vrd "Codecov"
[13]: https://github.com/sebastienrousseau/vrd/ "GitHub"

[build-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/vrd/release.yml?branch=main&style=for-the-badge&logo=github "Build Status"
[codecov-badge]: https://img.shields.io/codecov/c/github/sebastienrousseau/vrd?style=for-the-badge&token=oEisyTucB5 'Codecov'
[crates-badge]: https://img.shields.io/crates/v/vrd.svg?style=for-the-badge 'Crates.io badge'
[divider]: https://kura.pro/common/images/elements/divider.svg "divider"
[docs-badge]: https://img.shields.io/docsrs/vrd.svg?style=for-the-badge 'Docs.rs badge'
[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.4-orange.svg?style=for-the-badge 'Lib.rs badge'
[license-badge]: https://img.shields.io/crates/l/vrd.svg?style=for-the-badge 'License badge'
[made-with-rust-badge]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust 'Made With Rust badge'
[github-badge]: https://img.shields.io/badge/github-sebastienrousseau/vrd-8da0cb?style=for-the-badge&labelColor=555555&logo=github "GitHub"
[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.8-orange.svg?style=for-the-badge 'Lib.rs badge'
[made-with-rust]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust 'Made With Rust'
Loading

0 comments on commit a48d9ec

Please sign in to comment.