dos_date_time/
lib.rs

1// SPDX-FileCopyrightText: 2025 Shun Sakai
2//
3// SPDX-License-Identifier: Apache-2.0 OR MIT
4
5//! The `dos-date-time` crate is an [MS-DOS date and time] library.
6//!
7//! The [`DateTime`] is a type that represents MS-DOS date and time, which are
8//! packed 16-bit unsigned integer values that specify the date and time an
9//! MS-DOS file was last written to, and are used as timestamps such as [FAT] or
10//! [ZIP] file format.
11//!
12//! <div class="warning">
13//!
14//! The resolution of MS-DOS date and time is 2 seconds.
15//!
16//! </div>
17//!
18//! # Examples
19//!
20//! ## Basic usage
21//!
22//! [`DateTime`] can be converted from and to a type which represents time such
23//! as [`time::PrimitiveDateTime`].
24//!
25//! ```
26//! use core::time::Duration;
27//!
28//! use dos_date_time::{
29//!     DateTime,
30//!     time::{
31//!         PrimitiveDateTime,
32//!         macros::{date, datetime, time},
33//!     },
34//! };
35//!
36//! let dt = DateTime::MIN;
37//! let dt = PrimitiveDateTime::from(dt);
38//! assert_eq!(dt, datetime!(1980-01-01 00:00:00));
39//!
40//! // <https://devblogs.microsoft.com/oldnewthing/20030905-02/?p=42653>.
41//! let dt = dt + Duration::from_secs(722_805_900);
42//! assert_eq!(dt, datetime!(2002-11-26 19:25:00));
43//! let dt = DateTime::try_from(dt).unwrap();
44//! assert_eq!(
45//!     (dt.date(), dt.time()),
46//!     (0b0010_1101_0111_1010, 0b1001_1011_0010_0000)
47//! );
48//!
49//! // The largest MS-DOS date and time.
50//! assert_eq!(
51//!     DateTime::from_date_time(date!(2107 - 12 - 31), time!(23:59:58)),
52//!     Ok(DateTime::MAX)
53//! );
54//! ```
55//!
56//! ## Formatting and printing MS-DOS date and time
57//!
58//! The [`Display`](core::fmt::Display) trait for [`DateTime`] is implemented to
59//! show the value in the well-known [RFC 3339 format]. If you need a different
60//! date and time format, convert [`DateTime`] to a type which represents time
61//! such as [`time::PrimitiveDateTime`].
62//!
63//! ```
64//! use dos_date_time::{
65//!     DateTime,
66//!     time::{PrimitiveDateTime, format_description::well_known::Rfc2822},
67//! };
68//!
69//! let dt = DateTime::MIN;
70//! assert_eq!(format!("{dt}"), "1980-01-01 00:00:00");
71//!
72//! let dt = PrimitiveDateTime::from(dt)
73//!     .as_utc()
74//!     .format(&Rfc2822)
75//!     .unwrap();
76//! assert_eq!(format!("{dt}"), "Tue, 01 Jan 1980 00:00:00 +0000");
77//! ```
78//!
79//! [MS-DOS date and time]: https://learn.microsoft.com/en-us/windows/win32/sysinfo/ms-dos-date-and-time
80//! [FAT]: https://en.wikipedia.org/wiki/File_Allocation_Table
81//! [ZIP]: https://en.wikipedia.org/wiki/ZIP_(file_format)
82//! [RFC 3339 format]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
83
84#![doc(html_root_url = "https://docs.rs/dos-date-time/0.1.0/")]
85#![no_std]
86#![cfg_attr(docsrs, feature(doc_cfg))]
87// Lint levels of rustc.
88#![deny(missing_docs)]
89
90#[cfg(test)]
91#[macro_use]
92extern crate alloc;
93#[cfg(feature = "std")]
94extern crate std;
95
96mod date_time;
97pub mod error;
98
99#[cfg(feature = "chrono")]
100pub use chrono;
101#[cfg(feature = "jiff")]
102pub use jiff;
103pub use time;
104
105pub use crate::date_time::DateTime;
dos_date_time/lib.rs

dos_date_time/
lib.rs
