kamu_money_core/lib.rs
1//! Exact ISO 4217 money with compile-time currency identity.
2//!
3//! [`Money<USD>`](Money) and [`Money<IDR>`](Money) are different types, so
4//! cross-currency arithmetic is a compile error. Addition and subtraction are
5//! exact. Division returns a [`Division`] and requires a named residue decision
6//! before releasing its quotient.
7//!
8//! # Start here
9//!
10//! ```
11//! use kamu_money_core::{Money, iso::USD};
12//!
13//! let whole = Money::<USD>::try_from_major(10)?;
14//! let parts = whole.allocate(&[1, 1, 1])?;
15//! assert_eq!(Money::<USD>::try_sum(parts)?, whole);
16//! # Ok::<(), Box<dyn std::error::Error>>(())
17//! ```
18//!
19//! The crate root holds the common path. Browse deeper only when needed:
20//!
21//! - [`locale`] and [`text`] own display and canonical text;
22//! - [`errors`] groups narrow operation errors;
23//! - [`advanced`] exposes raw-unit kernels, domain constants, residue internals,
24//! and stable hashing;
25//! - feature-gated `wire` and [`adapters`] expose boundary integrations.
26//!
27//! # What this crate is not
28//!
29//! It represents amounts. It does not model tax, accounting rules, or FX policy, and exactness
30//! does not stand in for any of them: an amount this crate can hold and carry without error is
31//! still only as right as the decision that produced it. Each type states its own guarantees
32//! beside the things it deliberately does not guarantee — start with [`Money`] and [`Rate`].
33// Enables per-item "Available on crate feature ..." banners on docs.rs. `cfg_attr` keeps the
34// nightly-only feature out of stable builds.
35#![cfg_attr(docsrs, feature(doc_cfg))]
36#![deny(unsafe_code, missing_docs)]
37#![deny(clippy::all, clippy::pedantic, clippy::cargo)]
38// This workspace-wide lint flags published feature names owned by other crates.
39#![allow(clippy::redundant_feature_names)]
40// Select strict lints individually; restriction and nursery are not stable aggregate policies.
41#![deny(
42 clippy::arithmetic_side_effects,
43 clippy::as_conversions,
44 clippy::cast_lossless,
45 clippy::cast_possible_truncation,
46 clippy::cast_possible_wrap,
47 clippy::cast_precision_loss,
48 clippy::cast_sign_loss,
49 clippy::missing_const_for_fn,
50 clippy::use_self
51)]
52mod allocation;
53mod arithmetic;
54mod currency;
55mod domain;
56mod macros;
57mod money;
58mod rate;
59mod residue;
60mod rounding;
61mod sealed {
62 pub trait Sealed {}
63}
64mod stable_hash;
65
66pub mod adapters;
67pub mod advanced;
68pub mod errors;
69pub mod iso;
70pub mod locale;
71pub mod text;
72#[cfg(feature = "serde")]
73#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
74pub mod wire;
75
76pub use allocation::SplitParts;
77pub use currency::StaticCurrency;
78pub use errors::MoneyError;
79pub use iso::Iso4217;
80pub use money::Money;
81pub use rate::Rate;
82pub use residue::{Division, Residue};
83pub use rounding::Rounding;