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] and [7z]. Windows uses a file time to record when
11//! an application creates, accesses, or writes to a file.
12//!
13//! <div class="warning">
14//!
15//! Note that many environments, such as the [Win32 API], may limit the largest
16//! value of the file time to "+30828-09-14 02:48:05.477580700 UTC", which is
17//! equal to [`i64::MAX`], the largest value of a 64-bit signed integer type
18//! when represented as an underlying integer value. This is the largest file
19//! time accepted by the [`FileTimeToSystemTime`] function of the Win32 API.
20//!
21//! </div>
22//!
23//! # Examples
24//!
25//! ## Basic usage
26//!
27//! [`FileTime`] can be converted from and to a type which represents time such
28//! as [`time::OffsetDateTime`]. Addition and subtraction are also supported.
29//!
30//! ```
31//! use core::time::Duration;
32//!
33//! use nt_time::{
34//!     FileTime,
35//!     time::{OffsetDateTime, macros::datetime},
36//! };
37//!
38//! let ft = FileTime::NT_TIME_EPOCH;
39//! assert_eq!(
40//!     OffsetDateTime::try_from(ft),
41//!     Ok(datetime!(1601-01-01 00:00 UTC))
42//! );
43//!
44//! let ft = ft + Duration::from_secs(11_644_473_600);
45//! assert_eq!(OffsetDateTime::try_from(ft), Ok(OffsetDateTime::UNIX_EPOCH));
46//! assert_eq!(ft.to_raw(), 116_444_736_000_000_000);
47//!
48//! // The practical largest file time.
49//! assert_eq!(FileTime::try_from(i64::MAX), Ok(FileTime::SIGNED_MAX));
50//! // The theoretical largest file time.
51//! assert_eq!(FileTime::new(u64::MAX), FileTime::MAX);
52//! ```
53//!
54//! ## Conversion from and to other system times
55//!
56//! [`FileTime`] can be converted from and to other system times such as [Unix
57//! time] or [MS-DOS date and time].
58//!
59//! ```
60//! use core::time::Duration;
61//!
62//! use nt_time::{
63//!     FileTime,
64//!     time::{OffsetDateTime, UtcOffset},
65//! };
66//!
67//! // `1970-01-01 00:00:00 UTC`.
68//! let ut = i64::default();
69//! assert_eq!(
70//!     OffsetDateTime::from_unix_timestamp(ut),
71//!     Ok(OffsetDateTime::UNIX_EPOCH)
72//! );
73//!
74//! let ft = FileTime::from_unix_time_secs(ut).unwrap();
75//! assert_eq!(ft, FileTime::UNIX_EPOCH);
76//!
77//! // `1980-01-01 00:00:00 UTC`.
78//! let ft = ft + Duration::from_secs(315_532_800);
79//! let dos_dt = ft.to_dos_date_time(Some(UtcOffset::UTC));
80//! assert_eq!(
81//!     dos_dt,
82//!     Ok((0x0021, u16::MIN, u8::MIN, Some(UtcOffset::UTC)))
83//! );
84//! ```
85//!
86//! ## Formatting and printing the file time
87//!
88//! The formatting traits for [`FileTime`] are implemented to show the
89//! underlying [`u64`] value. If you need a human-readable date and time,
90//! convert [`FileTime`] to a type which represents time such as
91//! [`time::OffsetDateTime`].
92//!
93//! ```
94//! use nt_time::{FileTime, time::OffsetDateTime};
95//!
96//! let ft = FileTime::NT_TIME_EPOCH;
97//! assert_eq!(format!("{ft}"), "0");
98//!
99//! let dt = OffsetDateTime::try_from(ft).unwrap();
100//! assert_eq!(format!("{dt}"), "1601-01-01 0:00:00.0 +00:00:00");
101//! ```
102//!
103//! [Windows file time]: https://docs.microsoft.com/en-us/windows/win32/sysinfo/file-times
104//! [NTFS]: https://en.wikipedia.org/wiki/NTFS
105//! [7z]: https://www.7-zip.org/7z.html
106//! [Win32 API]: https://learn.microsoft.com/en-us/windows/win32/
107//! [`FileTimeToSystemTime`]: https://learn.microsoft.com/en-us/windows/win32/api/timezoneapi/nf-timezoneapi-filetimetosystemtime
108//! [Unix time]: https://en.wikipedia.org/wiki/Unix_time
109//! [MS-DOS date and time]: https://learn.microsoft.com/en-us/windows/win32/sysinfo/ms-dos-date-and-time
110
111#![doc(html_root_url = "https://docs.rs/nt-time/0.11.0/")]
112#![no_std]
113#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
114// Lint levels of rustc.
115#![deny(missing_docs)]
116
117#[cfg(test)]
118#[macro_use]
119extern crate alloc;
120#[cfg(feature = "std")]
121extern crate std;
122
123pub mod error;
124mod file_time;
125#[cfg(feature = "serde")]
126pub mod serde_with;
127
128#[cfg(feature = "chrono")]
129pub use chrono;
130#[cfg(feature = "rand")]
131pub use rand;
132#[cfg(feature = "serde")]
133pub use serde;
134pub use time;
135
136pub use crate::file_time::FileTime;
nt_time/lib.rs

nt_time/
lib.rs
