Qubit Datatype

qubit-datatype helps Rust services turn configuration, protocol, and ingestion values into typed values when their source type is known only at run time. It provides stable type descriptors, exact mixed-numeric comparison, and policy-driven conversion so precision loss, accepted text, and resource use remain explicit. API-level details are available on docs.rs.

Installation

The default build has no optional dependencies and provides DataType, DataTypeOf, NumberRef, and numeric comparison:

[dependencies]
qubit-datatype = "0.15"

Enable runtime conversion only with the rich type families your service needs:

[dependencies]
qubit-datatype = { version = "0.15", default-features = false, features = ["converter", "chrono"] }

Rich-type features do not enable converter themselves.

Quick start: typed deployment settings

For a service that receives PORT=8080, ADMIN_ENABLED=yes, and RETRY_DELAY=1500ms, select the environment-oriented policy explicitly and convert each value to its requested Rust type:

use std::time::Duration;

use qubit_datatype::{ConversionLimits, ConversionPolicy, DataConversionError, DataConverter};

fn main() -> Result<(), DataConversionError> {
    let policy = ConversionPolicy::env_friendly();
    let limits = ConversionLimits::default();

    let port = DataConverter::from("8080").to_with::<u16>(&policy, &limits)?;
    let admin = DataConverter::from(" yes ").to_with::<bool>(&policy, &limits)?;
    let retry = DataConverter::from("1500ms").to_with::<Duration>(&policy, &limits)?;

    assert_eq!(port, 8080);
    assert!(admin);
    assert_eq!(retry, Duration::from_millis(1500));
    Ok(())
}

The result is observable: each value has its requested type, and no trimming, Boolean alias, rounding, or Duration interpretation was selected implicitly.

Why this crate exists

Runtime values cross trust and representation boundaries. Ad hoc parsing can quietly round a number, accept an unintended spelling, or let a large value consume unbounded work. This crate keeps three concerns separate:

• DataType and DataTypeOf provide a stable vocabulary for schemas and metadata.
• NumberRef compares unlike numeric representations without routing integers through f64; use Exact for validation, storage, deterministic ordering, and keys.
• DataConverter, ConversionPolicy, and ConversionLimits make conversion semantics and resource bounds explicit. Use ConversionSession only when several calls must share a cumulative operation budget.

What it provides—and does not provide

The crate supports its documented source/target pairs and reports unsupported pairs as DataConversionErrorKind::Unsupported. It is not a general-purpose serialization framework and does not make arbitrary pairs convertible.

Strict conversion is the default: it preserves whitespace and rejects fractional-to-integer truncation, numeric-to-float rounding, text-to-float rounding, and inexact Duration output. ConversionPolicy::lossy() and ConversionPolicy::env_friendly() are deliberate alternatives. Errors retain stable kind and type context, but not source values, so the crate does not expose secrets such as environment-variable contents.

Numeric text syntax is target-specific: BigDecimal preserves underscore forms accepted by its parser, while integer targets reject them. See the numeric text section of the user guide.

Text converted to chrono::DateTime<Utc> must use RFC 3339 with an explicit offset and at most nine fractional second digits. Inputs with more digits are rejected, including trailing zeros, under every conversion policy. Apply any domain-specific rounding before conversion, or pass an already constructed DateTime<Utc>.

DataType's lowercase spellings, returned by as_str, accepted by Serde, and listed in DataType::ALL, are a compatibility surface. Platform-sized isize and usize are intentionally omitted because their representation is target-dependent.

Learn more

Read the English user guide or the 中文用户手册 for the full configuration scenario, sessions, diagnostics, Duration text, and troubleshooting. See the design note, 中文设计说明, and API documentation for further detail. For a runnable scalar-string-to-list example covering skipped entries, original error indices, and a shared item budget, see Read a deployment port list or run cargo run --example deployment_lists --features converter.

Testing

# Run tests with the default feature set
cargo test

# Run tests with all declared features
cargo test --all-features

# Project CI checks
./.infra/bin/ci-check.sh

# Check code coverage
./.infra/bin/coverage.sh

License

Copyright (c) 2025 - 2026. Haixing Hu. All rights reserved.

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Contributing

Contributions are welcome. Please follow the Rust API guidelines, keep public API documentation and tests current, and run ./.infra/bin/align-ci.sh to format code and ./.infra/bin/ci-check.sh to satisfy CI requirements before submitting a pull request.

Author

Haixing Hu - Qubit Co. Ltd.

Repository: https://github.com/qubit-ltd/rs-datatype