num_primitive/lib.rs
1//! # num-primitive
2//!
3//! Traits for primitive numeric types in Rust.
4//!
5//! These traits provide a simple hierarchy for generic programming with Rust's
6//! primitive floating-point and integer types:
7//!
8//! * [`PrimitiveNumber`]
9//! * [`PrimitiveFloat`]: `f32` and `f64`
10//! * [`PrimitiveInteger`]
11//! * [`PrimitiveSigned`]: `i8`, `i16`, `i32`, `i64`, `i128`, and `isize`
12//! * [`PrimitiveUnsigned`]: `u8`, `u16`, `u32`, `u64`, `u128`, and `usize`
13//!
14//! Each trait includes supertraits for everything implemented in common by these
15//! types, as well as associated constants and methods matching their inherent
16//! items. `PrimitiveFloat` also adds the contents of `core::{float}::consts`.
17//!
18//! [`NonZero`][core::num::NonZero] integer wrappers are similarly supported by
19//! [`NonZeroPrimitiveInteger`], [`NonZeroPrimitiveSigned`], and [`NonZeroPrimitiveUnsigned`].
20//!
21//! It is not a goal of this crate to *add* any functionality to the primitive
22//! types, only to expose what is already available in the standard library in a
23//! more generic way. The traits are also [sealed] against downstream
24//! implementations to allow expansion in a non-breaking way.
25//!
26//! For use-cases that include third-party types, along with features that go beyond
27//! the standard library, consider crates like [`num-traits`] and [`num-integer`].
28//!
29//! [`num-integer`]: https://crates.io/crates/num-integer
30//! [`num-traits`]: https://crates.io/crates/num-traits
31//! [sealed]: https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed
32//!
33//! ## Usage
34//!
35//! Add this to your `Cargo.toml`:
36//!
37//! ```toml
38//! [dependencies]
39//! num-primitive = "0.3"
40//! ```
41//!
42//! ## Features
43//!
44//! This crate can be used without the standard library (`#![no_std]`) by disabling
45//! the default `std` feature. Use this in `Cargo.toml`:
46//!
47//! ```toml
48//! [dependencies.num-primitive]
49//! version = "0.3"
50//! default-features = false
51//! ```
52//!
53//! Some `PrimitiveFloat` methods are only available when the `std` feature is
54//! enabled, just like when using those floating-point types directly.
55
56#![no_std]
57#![cfg_attr(docsrs, feature(doc_cfg))]
58
59#[cfg(feature = "std")]
60extern crate std;
61
62#[macro_use]
63mod macros;
64
65mod bytes;
66mod error;
67mod float;
68mod integer;
69mod number;
70mod signed;
71mod unsigned;
72
73#[cfg(test)]
74mod tests;
75
76pub use self::bytes::PrimitiveBytes;
77pub use self::error::PrimitiveError;
78pub use self::float::{PrimitiveFloat, PrimitiveFloatRef, PrimitiveFloatToInt};
79pub use self::integer::{NonZeroPrimitiveInteger, PrimitiveInteger, PrimitiveIntegerRef};
80pub use self::number::{PrimitiveNumber, PrimitiveNumberAs, PrimitiveNumberRef};
81pub use self::signed::{NonZeroPrimitiveSigned, PrimitiveSigned, PrimitiveSignedRef};
82pub use self::unsigned::{NonZeroPrimitiveUnsigned, PrimitiveUnsigned, PrimitiveUnsignedRef};