tzcraft 0.1.2

A schema-driven date & time library: one 128-bit nanosecond timeline, a const civil calendar, and codec-aware wire formats on nextjson / rustbinary.
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

//! `rustbinary` compact binary facade.
//!
//! The binary profile is not a separate codec — it is the same
//! `NsonSerialize` / `NsonDeserialize` implementations selected by the
//! codec's `is_human_readable() == false`. These helpers just shorten the
//! call path to `rustbinary`'s bounded, self-describing wire format.
//!
//! The dependency is pinned to `rustbinary = "=0.1.7"` with only the
//! `alloc` core enabled (`default-features = false`). Two facts about that
//! version matter here:
//!
//! - **The standard profile is bounded.** `options()` /
//!   [`Config::standard`] rejects trailing bytes, canonicalizes marker
//!   varints, and enforces a per-value byte limit
//!   ([`DEFAULT_SIZE_LIMIT`]) plus a per-collection element limit
//!   ([`DEFAULT_COLLECTION_LIMIT`]). Every helper in this module inherits
//!   those defaults.
//!
//! For untrusted input, tune the limits down with [`decode_bounded`] — the
//! pattern `rustbinary` documents for trust boundaries — instead of relying
//! on the generous defaults.
//!
//! ```
//! # use tzcraft::{Date, Ticks};
//! let date = Date::from_ymd(2024, 6, 15).unwrap();
//! let bytes = tzcraft::binary::encode(&date).unwrap();
//! let back: Date = tzcraft::binary::decode(&bytes).unwrap();
//! assert_eq!(date, back);
//!
//! let back: Date =
//!     tzcraft::binary::decode_bounded(&bytes, 64, 8).unwrap();
//! assert_eq!(date, back);
//! ```

use alloc::vec::Vec;

pub use rustbinary::{
    options, BinaryProfile, Config, Endian, Error as BinaryError, ErrorCategory, IntEncoding,
    Result as BinaryResult, TrailingBytes, DEFAULT_COLLECTION_LIMIT, DEFAULT_SIZE_LIMIT,
};

use nextjson::{NsonDeserialize, NsonSerialize};

/// Encode a value into a `Vec<u8>` with the standard compact profile.
pub fn encode<T: NsonSerialize + ?Sized>(value: &T) -> BinaryResult<Vec<u8>> {
    rustbinary::serialize(value)
}

/// Decode a value from a byte slice with the standard compact profile.
///
/// Borrowed targets may point into `input`. Equivalent to
/// `options().deserialize(input)`.
pub fn decode<'de, T: NsonDeserialize<'de>>(input: &'de [u8]) -> BinaryResult<T> {
    rustbinary::deserialize(input)
}

/// Decode with explicit resource limits for a trust boundary.
///
/// `size_limit` caps the bytes one decoded value may consume;
/// `collection_limit` caps the elements in one sequence or map. This is the
/// `rustbinary` 0.1.7 `Config`-based entry point for untrusted input; the
/// plain [`decode`] uses the crate-wide defaults (64 MiB / 1,000,000).
pub fn decode_bounded<'de, T: NsonDeserialize<'de>>(
    input: &'de [u8],
    size_limit: u64,
    collection_limit: u64,
) -> BinaryResult<T> {
    rustbinary::options()
        .with_limit(size_limit)
        .with_collection_limit(collection_limit)
        .deserialize(input)
}

/// Encode into a caller-owned slice without codec-owned allocation.
///
/// Returns the number of bytes written; `Error::BufferTooSmall` carries the
/// exact required capacity when `output` is undersized.
pub fn encode_into_slice<T: NsonSerialize + ?Sized>(
    output: &mut [u8],
    value: &T,
) -> BinaryResult<usize> {
    rustbinary::serialize_into_slice(output, value)
}

/// Exact serialized byte count without allocating output.
pub fn encoded_size<T: NsonSerialize + ?Sized>(value: &T) -> BinaryResult<u64> {
    rustbinary::serialized_size(value)
}