qubit_measure/lib.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! # qubit-measure
9//!
10//! Persistent typed Decimal measurement values with explicit units.
11//!
12//! The default build contains the exact Decimal core only. Enable the
13//! default-off `uom` Cargo feature to expose approximate `uom/f64` adapters.
14//! Built-in exact conversion definitions share crate-wide constants grouped by
15//! quantity.
16//!
17//! # Examples
18//!
19//! Parse a measurement, derive a rounded conversion, and persist the original
20//! value with its unit. The converted measurement is a derived value; JSON
21//! serialization retains the original value and unit, including the Decimal
22//! scale supplied by the input.
23//!
24//! ```
25//! use qubit_measure::{ConversionOptions, measurement, unit};
26//! use rust_decimal::RoundingStrategy;
27//! use serde_json::json;
28//!
29//! let original = measurement::Length::parse_strict("50.0 cm")?;
30//! let meters = original.convert_to_with_options(
31//! unit::Length::Meter,
32//! ConversionOptions::fixed_scale(4, RoundingStrategy::MidpointNearestEven)?,
33//! )?;
34//! assert_eq!(meters.to_string(), "0.5000 m");
35//!
36//! let stored = serde_json::to_value(original)?;
37//! assert_eq!(stored, json!({"quantity":"length","value":"50.0","unit":"cm"}));
38//!
39//! let restored: measurement::Length = serde_json::from_value(stored)?;
40//! assert_eq!(restored.value, original.value);
41//! assert_eq!(restored.unit, unit::Length::Centimeter);
42//! assert_eq!(restored.value.scale(), 1);
43//! assert_eq!(restored.to_string(), "50.0 cm");
44//! # Ok::<(), Box<dyn std::error::Error>>(())
45//! ```
46//!
47//! # Further reading
48//!
49//! Explore [`Measurement`], [`ConversionOptions`], [`Unit`], and
50//! [`measurement_text`] for the core value model, conversion policies, unit
51//! definitions, and text parsing and formatting APIs. The English and Chinese
52//! guides are available in the [README](https://github.com/qubit-ltd/rs-measure/blob/main/README.md)
53//! and [中文 README](https://github.com/qubit-ltd/rs-measure/blob/main/README.zh_CN.md).
54
55#![deny(missing_docs)]
56#![deny(unsafe_op_in_unsafe_fn)]
57
58#[doc(hidden)]
59#[path = "private.rs"]
60pub mod __private;
61mod consts;
62mod measure;
63pub mod measurement;
64pub mod measurement_text;
65pub mod unit;
66
67pub use measure::ConversionFactor;
68pub use measure::ConversionOptions;
69pub use measure::Measurement;
70pub use measure::MeasurementError;
71pub use measure::MeasurementParseOptions;
72pub use measure::Unit;
73pub use measure::UnitDefinition;
74#[cfg(feature = "uom")]
75pub use measure::UomUnit;
76pub use measure::assert_unit_family_valid;