qubit-datatype 0.15.2

Runtime data type descriptors and conversion utilities for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Runtime data type descriptors and policy-driven conversion utilities.
//!
//! The default feature set is empty and exposes the lightweight [`DataType`]
//! vocabulary plus [`DataTypeOf`]. The lightweight `duration` feature adds
//! Duration units, text codecs, and Serde field adapters. Optional `chrono`,
//! `big-integer`, `big-decimal`, `url`, and `json` features add mappings for
//! external types; `big-number` enables both big-number families. The
//! `converter` feature includes `duration` and enables core scalar, string, and
//! Duration conversions. Combine it with a rich-type feature to enable
//! conversions for that family, or use `all`.
//!
//! # Conversion contract
//!
//! With `converter`, representative paths include strings to numeric,
//! boolean, character, and Duration values; core scalars to String; integers
//! to numeric, boolean, and Duration values; and Duration to integers and
//! String. Boolean and character sources also have numeric paths. A path's
//! implementation does not guarantee that every value is accepted: the
//! selected policy and target range still apply. `chrono`, `big-integer`,
//! `big-decimal`, `url`, and `json` add their documented paths when combined
//! with `converter`; JSON also enables StringMap parsing and formatting.
//! Discover paths compiled into the current build with
//! [`ConversionCapabilities::supports`](https://docs.rs/qubit-datatype/latest/qubit_datatype/struct.ConversionCapabilities.html#method.supports)
//! and
//! [`ConversionCapabilities::supported_targets`](https://docs.rs/qubit-datatype/latest/qubit_datatype/struct.ConversionCapabilities.html#method.supported_targets).
//! These APIs are available with `converter`.
//! Other pairs return `DataConversionErrorKind::Unsupported`, and conversions
//! are not chained implicitly.
//!
//! `NumericConversionPolicy` configures fractional-to-integer conversion,
//! numeric-to-float rounding, and text-to-float rounding independently.
//! `NumericConversionLimits` and `ConversionLimits` bound resource usage
//! separately. The strict/default profile rejects truncation and
//! precision loss. `ConversionPolicy::lossy` permits finite
//! decimal/float truncation toward zero, IEEE nearest-even float rounding, and
//! Duration half-up rounding. Duration-to-integer and Duration-to-String
//! require exact divisibility unless `DurationRoundingPolicy::HalfUp` is
//! selected explicitly.
//!
//! A reusable conversion session reports stable resource facts through
//! `DataConversionError` accessors without exposing its accounting backend.
//! The session's output-byte budget is shared by built-in `String`
//! conversions, custom targets using `AdmittedConversion::write_string`, and
//! JSON encoding through `AdmittedConversion::encode_json` when the `json`
//! feature is enabled. It counts UTF-8 `String` bytes and encoded JSON bytes.
//! Each output operation commits its bytes on success. Custom targets'
//! independently produced output is not automatically accounted for.
//! Built-in `String` conversions retain the same accounting for borrowed and
//! owned sources; each `String` source is normalized exactly once.
//!
//! Strings are not trimmed by default and are normalized exactly once.
//! Boolean text defaults to `true` and `false`; numeric 0/1 handling is
//! controlled independently by `BooleanNumericPolicy`. By default, Duration
//! text rejects omitted suffixes and accepts
//! `[0-9]+(ns|us|µs|μs|ms|s|min|h|d)`. Strict mode accepts all three
//! microsecond spellings; lenient mode additionally accepts `m` for minutes.
//!
//! # Example
//!
//! ```
//! # #[cfg(feature = "converter")]
//! # {
//! use qubit_datatype::{
//!     ConversionLimits, ConversionPolicy, DataConversionErrorKind,
//!     DataConverter, InvalidValueReason,
//! };
//!
//! let error = DataConverter::from("3.9").to::<i32>().unwrap_err();
//! assert_eq!(error.kind(), DataConversionErrorKind::InvalidValue);
//! assert_eq!(error.reason(), Some(&InvalidValueReason::PrecisionLoss));
//!
//! let lossy = ConversionPolicy::lossy();
//! let limits = ConversionLimits::default();
//! assert_eq!(
//!     DataConverter::from(" 3.9 ").to_with::<i32>(&lossy, &limits),
//!     Ok(3),
//! );
//! # }
//! ```
//!
//! The example below checks both the compiled capability and the result of a
//! conversion. It is available when the `converter` feature is enabled.
//!
//! ```
//! # #[cfg(feature = "converter")]
//! # fn example() -> Result<(), qubit_datatype::DataConversionError> {
//! use qubit_datatype::ConversionCapabilities;
//! use qubit_datatype::DataConverter;
//! use qubit_datatype::DataType;
//!
//! let capabilities = ConversionCapabilities::current();
//! assert!(capabilities.supports(DataType::Int32, DataType::String));
//! assert_eq!(DataConverter::from(42_i32).to::<String>()?, "42");
//! # Ok(())
//! # }
//! # #[cfg(feature = "converter")]
//! # example().unwrap();
//! ```

#![deny(missing_docs)]

/// Data type descriptors and compile-time type mappings.
pub mod datatype;

/// Policy-driven numeric comparison primitives.
pub mod numeric;

/// Lightweight Duration units and text codecs.
#[cfg(feature = "duration")]
pub mod duration;

#[cfg(feature = "duration")]
#[path = "serde/mod.rs"]
mod serde_impl;

/// Serde adapters for Duration interchange formats.
///
/// Use these modules with `#[serde(with = "...")]` when a field requires a
/// stable numeric or unit-suffixed Duration representation.
#[cfg(feature = "duration")]
pub mod serde {
    pub use super::serde_impl::duration_millis;
    pub use super::serde_impl::duration_millis_with_unit;
    pub use super::serde_impl::duration_millis_with_unit_exact;
    pub use super::serde_impl::duration_with_unit;
}

/// Runtime value conversion utilities.
#[cfg(feature = "converter")]
pub mod converter;

#[cfg(feature = "converter")]
pub use converter::AdmittedConversion;
#[cfg(feature = "converter")]
pub use converter::AdmittedScalarItem;
#[cfg(feature = "converter")]
pub use converter::AdmittedScalarSource;
#[cfg(feature = "converter")]
pub use converter::BlankStringPolicy;
#[cfg(feature = "converter")]
pub use converter::BooleanConversionPolicy;
#[cfg(feature = "converter")]
pub use converter::BooleanConversionPolicyBuilder;
#[cfg(feature = "converter")]
pub use converter::BooleanLiteralConflictError;
#[cfg(feature = "converter")]
pub use converter::BooleanNumericPolicy;
#[cfg(feature = "converter")]
pub use converter::CollectionConversionLimits;
#[cfg(feature = "converter")]
pub use converter::CollectionConversionLimitsBuilder;
#[cfg(feature = "converter")]
pub use converter::CollectionConversionPolicy;
#[cfg(feature = "converter")]
pub use converter::CollectionConversionPolicyBuilder;
#[cfg(feature = "converter")]
pub use converter::ConversionCapabilities;
#[cfg(feature = "converter")]
pub use converter::ConversionLimits;
#[cfg(feature = "converter")]
pub use converter::ConversionLimitsBuilder;
#[cfg(feature = "converter")]
pub use converter::ConversionOperationLimits;
#[cfg(feature = "converter")]
pub use converter::ConversionOperationLimitsBuilder;
#[cfg(feature = "converter")]
pub use converter::ConversionPolicy;
#[cfg(feature = "converter")]
pub use converter::ConversionPolicyBuilder;
#[cfg(feature = "converter")]
pub use converter::ConversionResource;
#[cfg(feature = "converter")]
pub use converter::ConversionSession;
#[cfg(feature = "converter")]
pub use converter::ConversionStringWriter;
#[cfg(feature = "converter")]
pub use converter::DataConversionError;
#[cfg(feature = "converter")]
pub use converter::DataConversionErrorKind;
#[cfg(feature = "converter")]
pub use converter::DataConversionTarget;
#[cfg(feature = "converter")]
pub use converter::DataConverter;
#[cfg(feature = "converter")]
pub use converter::DataConverters;
#[cfg(feature = "converter")]
pub use converter::DataFormat;
#[cfg(feature = "converter")]
pub use converter::DataListConversionError;
#[cfg(feature = "converter")]
pub use converter::DurationConversionLimits;
#[cfg(feature = "converter")]
pub use converter::DurationConversionLimitsBuilder;
#[cfg(feature = "converter")]
pub use converter::DurationConversionPolicy;
#[cfg(feature = "converter")]
pub use converter::DurationConversionPolicyBuilder;
#[cfg(feature = "converter")]
pub use converter::DurationRoundingPolicy;
#[cfg(feature = "converter")]
pub use converter::EmptyItemPolicy;
#[cfg(feature = "converter")]
pub use converter::FloatRoundingPolicy;
#[cfg(feature = "converter")]
pub use converter::FractionalToIntegerPolicy;
#[cfg(feature = "converter")]
pub use converter::InvalidValueReason;
#[cfg(feature = "converter")]
pub use converter::JsonConversionDiagnostic;
#[cfg(feature = "converter")]
pub use converter::JsonConversionErrorCategory;
#[cfg(feature = "converter")]
pub use converter::NumericConversionLimits;
#[cfg(feature = "converter")]
pub use converter::NumericConversionLimitsBuilder;
#[cfg(feature = "converter")]
pub use converter::NumericConversionPolicy;
#[cfg(feature = "converter")]
pub use converter::NumericConversionPolicyBuilder;
#[cfg(feature = "converter")]
pub use converter::ScalarItem;
#[cfg(feature = "converter")]
pub use converter::ScalarItemError;
#[cfg(feature = "converter")]
pub use converter::ScalarItems;
#[cfg(feature = "converter")]
pub use converter::ScalarStringDataConverters;
#[cfg(feature = "converter")]
pub use converter::StringConversionPolicy;
#[cfg(feature = "converter")]
pub use converter::StringConversionPolicyBuilder;
#[cfg(feature = "converter")]
pub use converter::StringNormalizationError;
#[cfg(feature = "converter")]
pub use converter::StructuredConversionLimits;
#[cfg(feature = "converter")]
pub use converter::StructuredConversionLimitsBuilder;
pub use datatype::DataType;
pub use datatype::DataTypeCategory;
pub use datatype::DataTypeOf;
pub use datatype::DataTypeParseError;
#[cfg(feature = "duration")]
pub use duration::DurationOverflowError;
#[cfg(feature = "duration")]
pub use duration::DurationParseError;
#[cfg(feature = "duration")]
pub use duration::DurationPrecisionLossError;
#[cfg(feature = "duration")]
pub use duration::DurationTextOptions;
#[cfg(feature = "duration")]
pub use duration::DurationTextOptionsBuilder;
#[cfg(feature = "duration")]
pub use duration::DurationUnit;
#[cfg(feature = "duration")]
pub use duration::DurationUnitParseMode;
#[cfg(feature = "duration")]
pub use duration::SuffixlessDurationPolicy;
#[cfg(feature = "duration")]
pub use duration::format_duration_exact;
#[cfg(feature = "duration")]
pub use duration::parse_duration_text;
pub use numeric::NumberRef;
pub use numeric::NumericComparisonPolicy;