reliakit_primitives/
lib.rs

1//! Type-safe primitives for constrained and reliability-oriented values.
2//!
3//! `reliakit-primitives` provides small owned wrapper types for values that
4//! should satisfy common constraints before they move through an application or
5//! library boundary.
6//!
7//! The crate is useful when a public API should accept a validated value instead
8//! of an unchecked `String`, integer, or float. Constructors validate once at the
9//! boundary and then carry the invariant in the type.
10//!
11//! The crate has no dependencies and forbids unsafe code.
12//!
13//! # Examples
14//!
15//! Basic service configuration:
16//!
17//! ```
18//! use reliakit_primitives::{NonEmptyStr, Port};
19//!
20//! fn configure(name: NonEmptyStr, port: Port) {
21//!     assert_eq!(name.as_str(), "api");
22//!     assert_eq!(port.get(), 8080);
23//! }
24//!
25//! let name = NonEmptyStr::new("api")?;
26//! let port = Port::new(8080)?;
27//!
28//! configure(name, port);
29//! # Ok::<(), reliakit_primitives::PrimitiveError>(())
30//! ```
31//!
32//! Text and structured values:
33//!
34//! ```
35//! use reliakit_primitives::{Email, HumanDuration, HttpUrl, SemVer};
36//!
37//! let contact = Email::new("ops@example.com")?;
38//! let healthcheck = HttpUrl::new("https://example.com/health")?;
39//! let version = SemVer::parse("1.2.3-beta.1")?;
40//! let timeout = HumanDuration::parse("30s")?;
41//!
42//! assert_eq!(contact.domain(), "example.com");
43//! assert!(healthcheck.is_https());
44//! assert!(version.is_pre_release());
45//! assert_eq!(timeout.as_secs(), 30);
46//! # Ok::<(), reliakit_primitives::PrimitiveError>(())
47//! ```
48//!
49//! # Feature flags
50//!
51//! - `std` (default) enables `std::error::Error` for [`PrimitiveError`] and
52//!   implies `alloc`.
53//! - `alloc` enables the allocation-backed owned types and collection helpers
54//!   listed below.
55//!
56//! # `no_std`
57//!
58//! The crate supports `no_std`. Building with `--no-default-features` (no `std`,
59//! no `alloc`) provides the allocation-free primitives:
60//!
61//! - numeric: [`Percent`], [`PercentageF64`], [`Port`], [`PositiveInt`],
62//!   [`PositiveFloat`], [`ByteSize`],
63//! - [`Uuid`], [`MacAddress`], and [`HumanDuration`] (parsing and `Display` do
64//!   not allocate),
65//! - the error types ([`PrimitiveError`], [`PrimitiveErrorKind`],
66//!   [`PrimitiveResult`]).
67//!
68//! Enabling the `alloc` feature additionally provides the owned, allocation-backed
69//! types: [`Slug`], [`Email`], [`HttpUrl`], [`HexString`], [`Base64`],
70//! [`Identifier`], [`Hostname`], [`NonEmptyStr`], [`BoundedStr`], [`NonEmptyVec`],
71//! and [`SemVer`]. The default `std` build enables `alloc` for normal application
72//! use.
73
74#![cfg_attr(not(feature = "std"), no_std)]
75#![forbid(unsafe_code)]
76#![warn(missing_docs)]
77
78#[cfg(feature = "alloc")]
79extern crate alloc;
80
81/// Bounded string primitive.
82#[cfg(feature = "alloc")]
83pub mod bounded;
84/// Non-empty vector primitive.
85#[cfg(feature = "alloc")]
86pub mod collections;
87/// Human-readable duration primitive.
88pub mod duration;
89/// Shared primitive error type.
90pub mod error;
91/// MAC address primitive.
92pub mod mac;
93/// IP network (CIDR) primitive.
94pub mod net;
95/// Non-empty string primitive.
96#[cfg(feature = "alloc")]
97pub mod non_empty;
98/// Numeric primitives.
99pub mod numeric;
100/// Semantic version primitive.
101#[cfg(feature = "alloc")]
102pub mod semver;
103/// Text validation primitives.
104#[cfg(feature = "alloc")]
105pub mod text;
106/// UUID primitive.
107pub mod uuid;
108
109#[cfg(feature = "alloc")]
110pub use bounded::BoundedStr;
111#[cfg(feature = "alloc")]
112pub use collections::NonEmptyVec;
113pub use duration::HumanDuration;
114pub use error::{PrimitiveError, PrimitiveErrorKind, PrimitiveResult};
115pub use mac::MacAddress;
116pub use net::Cidr;
117#[cfg(feature = "alloc")]
118pub use non_empty::NonEmptyStr;
119pub use numeric::{ByteSize, Percent, PercentageF64, Port, PositiveFloat, PositiveInt};
120#[cfg(feature = "alloc")]
121pub use semver::SemVer;
122#[cfg(feature = "alloc")]
123pub use text::{Base32, Base64, Email, HexString, Hostname, HttpUrl, Identifier, Slug};
124pub use uuid::Uuid;
reliakit_primitives/lib.rs

reliakit_primitives/
lib.rs
