jiff_core/lib.rs
1/*!
2A small collection of datetime primitives to support Jiff.
3
4The primary motivation of this crate is as an implementation detail for
5the [Jiff](https://docs.rs/jiff) crate. Indeed, if you're seeing this
6documentation, Jiff is probably the crate you want, not this one.
7
8# Motivation
9
10The primary motivation for this crate's existence is so that the `jiff` and
11`jiff-static` crates can share code. Prior to the birth of `jiff-core`,
12there were some major hacks involved that permitted code sharing by way of
13duplication. Therefore, some chunk of code was compiled twice if you depended
14on both `jiff` and `jiff-static`.
15
16A secondary motivation is that `jiff-core` provides a useful set of primitives
17for datetime handling that others may find useful if they don't want to depend
18on Jiff proper. For example, callers looking to convert between timestamps and
19datetimes may do so with this crate:
20
21```
22use jiff_core::{civil, tz::Offset, Timestamp};
23
24let ts = Timestamp::UNIX_EPOCH;
25assert_eq!(ts.to_datetime(Offset::UTC).date(), civil::date(1970, 1, 1));
26```
27
28Callers can perform the reverse operation too:
29
30```
31use jiff_core::{civil, tz::Offset, Timestamp};
32
33let datetime = civil::date(1970, 1, 1).at(0, 0, 0, 0);
34assert_eq!(datetime.to_timestamp(Offset::UTC).unwrap(), Timestamp::UNIX_EPOCH);
35```
36
37The above operation is fallible because, like Jiff proper, not all civil
38datetimes can be combined with all offsets to produce an instant within this
39crate's valid bounds (which it shares with Jiff):
40
41```
42use jiff_core::{civil, tz::Offset, Timestamp};
43
44let datetime = civil::date(9999, 12, 31).at(23, 59, 59, 999_999_999);
45assert!(datetime.to_timestamp(Offset::UTC).is_err());
46// The maximum datetime can be used to produce a timestamp only by using the
47// maximum offset from UTC. If any other offset were permitted here, it would
48// imply the ability to get a timestamp corresponding to a civil datetime in
49// the year 10,000 CE. (And similar for the minimal datetime.)
50assert_eq!(datetime.to_timestamp(Offset::MAX).unwrap(), Timestamp::MAX);
51```
52
53# What does this crate not do?
54
55The major missing pieces from this crate are:
56
57* Formatting and parsing, although callers may find the `Debug` trait
58 implementations of types in this crate to be useful.
59* Convenient time zone aware handling.
60* Platform integration with the [Time Zone Database].
61* Any kind of duration type.
62* Good documentation demonstrating proper usage of the crate.
63* Maturity and stability. Users of this crate should expect more breaking
64 change releases than Jiff proper.
65* There is no way to convert a `jiff-core` type directly into a `jiff` type
66 or vice versa. You must go through the proper constructors. These conversions
67 are intentionally missing so that `jiff-core` is not a public dependency of
68 `jiff`.
69
70[Time Zone Database]: https://www.iana.org/time-zones
71*/
72
73#![no_std]
74#![cfg_attr(docsrs_jiff, feature(doc_cfg))]
75#![warn(missing_debug_implementations)]
76#![deny(missing_docs)]
77
78#[cfg(any(test, feature = "std"))]
79extern crate std;
80
81#[cfg(any(test, feature = "alloc"))]
82extern crate alloc;
83
84pub use self::timestamp::Timestamp;
85
86#[macro_use]
87mod logging;
88mod macros;
89
90pub mod bounds;
91pub mod civil;
92pub mod constants;
93mod timestamp;
94pub mod tz;
95pub mod util;