gix_date/lib.rs
1//! Date and time parsing similar to what git can do.
2//!
3//! Note that this is not a general purpose time library.
4//!
5//! ## Examples
6//!
7//! ```
8//! use gix_date::{
9//! parse,
10//! parse_header,
11//! time::{format, Format},
12//! };
13//!
14//! let time = parse("Thu, 18 Aug 2022 12:45:06 +0800", None).unwrap();
15//! assert_eq!(time.offset, 8 * 60 * 60);
16//! assert_eq!(time.format(Format::Raw).unwrap(), "1660797906 +0800");
17//! assert_eq!(time.format(Format::Custom(format::ISO8601)).unwrap(), "2022-08-18 12:45:06 +0800");
18//!
19//! let from_header = parse_header("1660797906 +0800").unwrap();
20//! assert_eq!(from_header, time);
21//! ```
22//! ## Feature Flags
23#![cfg_attr(
24 all(doc, feature = "document-features"),
25 doc = ::document_features::document_features!()
26)]
27#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg))]
28#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
29///
30pub mod time;
31
32///
33pub mod parse;
34pub use parse::function::{parse, parse_header};
35
36pub use gix_error::ValidationError as Error;
37
38/// A timestamp with timezone.
39#[derive(Default, PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
40#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
41pub struct Time {
42 /// The seconds that have passed since UNIX epoch. This makes it UTC, or `<seconds>+0000`.
43 pub seconds: SecondsSinceUnixEpoch,
44 /// The time's offset in seconds, which may be negative to match the `sign` field.
45 pub offset: OffsetInSeconds,
46}
47
48/// The number of seconds since unix epoch.
49///
50/// Note that negative dates represent times before the unix epoch.
51///
52/// ### Deviation
53///
54/// `git` only supports dates *from* the UNIX epoch, whereas we chose to be more flexible at the expense of stopping time
55/// a few million years before the heat-death of the universe.
56pub type SecondsSinceUnixEpoch = i64;
57/// time offset in seconds.
58pub type OffsetInSeconds = i32;