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
/*!
A small collection of datetime primitives to support Jiff.
The primary motivation of this crate is as an implementation detail for
the [Jiff](https://docs.rs/jiff) crate. Indeed, if you're seeing this
documentation, Jiff is probably the crate you want, not this one.
# Motivation
The primary motivation for this crate's existence is so that the `jiff` and
`jiff-static` crates can share code. Prior to the birth of `jiff-core`,
there were some major hacks involved that permitted code sharing by way of
duplication. Therefore, some chunk of code was compiled twice if you depended
on both `jiff` and `jiff-static`.
A secondary motivation is that `jiff-core` provides a useful set of primitives
for datetime handling that others may find useful if they don't want to depend
on Jiff proper. For example, callers looking to convert between timestamps and
datetimes may do so with this crate:
```
use jiff_core::{civil, tz::Offset, Timestamp};
let ts = Timestamp::UNIX_EPOCH;
assert_eq!(ts.to_datetime(Offset::UTC).date(), civil::date(1970, 1, 1));
```
Callers can perform the reverse operation too:
```
use jiff_core::{civil, tz::Offset, Timestamp};
let datetime = civil::date(1970, 1, 1).at(0, 0, 0, 0);
assert_eq!(datetime.to_timestamp(Offset::UTC).unwrap(), Timestamp::UNIX_EPOCH);
```
The above operation is fallible because, like Jiff proper, not all civil
datetimes can be combined with all offsets to produce an instant within this
crate's valid bounds (which it shares with Jiff):
```
use jiff_core::{civil, tz::Offset, Timestamp};
let datetime = civil::date(9999, 12, 31).at(23, 59, 59, 999_999_999);
assert!(datetime.to_timestamp(Offset::UTC).is_err());
// The maximum datetime can be used to produce a timestamp only by using the
// maximum offset from UTC. If any other offset were permitted here, it would
// imply the ability to get a timestamp corresponding to a civil datetime in
// the year 10,000 CE. (And similar for the minimal datetime.)
assert_eq!(datetime.to_timestamp(Offset::MAX).unwrap(), Timestamp::MAX);
```
# What does this crate not do?
The major missing pieces from this crate are:
* Formatting and parsing, although callers may find the `Debug` trait
implementations of types in this crate to be useful.
* Convenient time zone aware handling.
* Platform integration with the [Time Zone Database].
* Any kind of duration type.
* Good documentation demonstrating proper usage of the crate.
* Maturity and stability. Users of this crate should expect more breaking
change releases than Jiff proper.
* There is no way to convert a `jiff-core` type directly into a `jiff` type
or vice versa. You must go through the proper constructors. These conversions
are intentionally missing so that `jiff-core` is not a public dependency of
`jiff`.
[Time Zone Database]: https://www.iana.org/time-zones
*/
extern crate std;
extern crate alloc;
pub use Timestamp;