nt_time/
lib.rs

1// SPDX-FileCopyrightText: 2023 Shun Sakai
2//
3// SPDX-License-Identifier: Apache-2.0 OR MIT
4
5//! The `nt-time` crate is a [Windows file time] library.
6//!
7//! The [`FileTime`] is a type that represents the file time, which is a 64-bit
8//! unsigned integer value that represents the number of 100-nanosecond
9//! intervals that have elapsed since "1601-01-01 00:00:00 UTC", and is used as
10//! timestamps such as [NTFS] or [7z]. Windows uses a file time to record when
11//! an application creates, accesses, or writes to a file.
12//!
13//! # Examples
14//!
15//! ## Basic usage
16//!
17//! [`FileTime`] can be converted from and to a type which represents time such
18//! as [`time::UtcDateTime`]. Addition and subtraction are also supported.
19//!
20//! ```
21//! use core::time::Duration;
22//!
23//! use nt_time::{
24//!     FileTime,
25//!     time::{UtcDateTime, macros::utc_datetime},
26//! };
27//!
28//! let ft = FileTime::NT_TIME_EPOCH;
29//! assert_eq!(
30//!     UtcDateTime::try_from(ft),
31//!     Ok(utc_datetime!(1601-01-01 00:00:00))
32//! );
33//!
34//! let ft = ft + Duration::from_hours(3_234_576);
35//! assert_eq!(UtcDateTime::try_from(ft), Ok(UtcDateTime::UNIX_EPOCH));
36//! assert_eq!(ft.to_raw(), 116_444_736_000_000_000);
37//! ```
38//!
39//! ## Conversion from and to other system times
40//!
41//! [`FileTime`] can be converted from and to other system times such as [Unix
42//! time] or [MS-DOS date and time].
43//!
44//! ### Unix time
45//!
46//! ```
47//! use nt_time::{
48//!     FileTime,
49//!     time::{UtcDateTime, macros::utc_datetime},
50//! };
51//!
52//! // `1970-01-01 00:00:00 UTC`.
53//! let dt = UtcDateTime::UNIX_EPOCH;
54//! assert_eq!(dt, utc_datetime!(1970-01-01 00:00:00));
55//!
56//! // Convert to a `FileTime`.
57//! let ft = FileTime::from_unix_time_secs(dt.unix_timestamp()).unwrap();
58//! assert_eq!(ft, FileTime::UNIX_EPOCH);
59//!
60//! // Back to Unix time.
61//! let ut = ft.to_unix_time_secs();
62//! assert_eq!(ut, 0);
63//! ```
64//!
65//! ### MS-DOS date and time
66//!
67//! ```
68//! # #[cfg(feature = "dos-date-time")]
69//! # {
70//! use nt_time::{FileTime, dos_date_time::DateTime};
71//!
72//! // `1980-01-01 00:00:00`.
73//! let dt = DateTime::MIN;
74//! assert_eq!(dt.to_string(), "1980-01-01 00:00:00");
75//!
76//! // Convert to a `FileTime`.
77//! let ft = FileTime::from(dt);
78//! assert_eq!(ft, FileTime::new(119_600_064_000_000_000));
79//!
80//! // Back to MS-DOS date and time.
81//! let dt = DateTime::try_from(ft).unwrap();
82//! assert_eq!(
83//!     (dt.date().to_raw(), dt.time().to_raw()),
84//!     (0b0000_0000_0010_0001, u16::MIN)
85//! );
86//! # }
87//! ```
88//!
89//! ## Formatting and printing the file time
90//!
91//! The [`Display`](core::fmt::Display) trait for [`FileTime`] is implemented to
92//! show the underlying [`u64`] value. If you need a human-readable date and
93//! time, convert [`FileTime`] to a type which represents time such as
94//! [`time::UtcDateTime`].
95//!
96//! ```
97//! use nt_time::{FileTime, time::UtcDateTime};
98//!
99//! let ft = FileTime::NT_TIME_EPOCH;
100//! assert_eq!(format!("{ft}"), "0");
101//!
102//! let dt = UtcDateTime::try_from(ft).unwrap();
103//! assert_eq!(format!("{dt}"), "1601-01-01 0:00:00.0 +00");
104//! ```
105//!
106//! [Windows file time]: https://learn.microsoft.com/en-us/windows/win32/sysinfo/file-times
107//! [NTFS]: https://en.wikipedia.org/wiki/NTFS
108//! [7z]: https://www.7-zip.org/7z.html
109//! [Unix time]: https://en.wikipedia.org/wiki/Unix_time
110//! [MS-DOS date and time]: https://learn.microsoft.com/en-us/windows/win32/sysinfo/ms-dos-date-and-time
111
112#![doc(html_root_url = "https://docs.rs/nt-time/0.14.0/")]
113#![no_std]
114#![cfg_attr(docsrs, feature(doc_cfg))]
115// Lint levels of rustc.
116#![deny(missing_docs)]
117
118#[cfg(test)]
119#[macro_use]
120extern crate alloc;
121#[cfg(feature = "std")]
122extern crate std;
123
124pub mod error;
125mod file_time;
126#[cfg(feature = "serde")]
127pub mod serde_with;
128
129#[cfg(feature = "chrono")]
130pub use chrono;
131#[cfg(feature = "dos-date-time")]
132pub use dos_date_time;
133#[cfg(feature = "jiff")]
134pub use jiff;
135#[cfg(feature = "rand")]
136pub use rand;
137#[cfg(feature = "serde")]
138pub use serde;
139pub use time;
140
141pub use crate::file_time::FileTime;
nt_time/lib.rs

nt_time/
lib.rs
