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//! # Examples
13//!
14//! ## Basic usage
15//!
16//! [`DateTime`] can be converted from and to a type which represents time such
17//! as [`time::PrimitiveDateTime`].
18//!
19//! ```
20//! use core::time::Duration;
21//!
22//! use dos_date_time::{
23//!     DateTime,
24//!     time::{PrimitiveDateTime, macros::datetime},
25//! };
26//!
27//! let dt = DateTime::MIN;
28//! let dt = PrimitiveDateTime::from(dt);
29//! assert_eq!(dt, datetime!(1980-01-01 00:00:00));
30//!
31//! // <https://devblogs.microsoft.com/oldnewthing/20030905-02/?p=42653>.
32//! let dt = dt + Duration::from_secs(722_805_900);
33//! assert_eq!(dt, datetime!(2002-11-26 19:25:00));
34//! let dt = DateTime::try_from(dt).unwrap();
35//! assert_eq!(
36//!     (dt.date().to_raw(), dt.time().to_raw()),
37//!     (0b0010_1101_0111_1010, 0b1001_1011_0010_0000)
38//! );
39//! ```
40//!
41//! ## Formatting and printing MS-DOS date and time
42//!
43//! The [`Display`](core::fmt::Display) trait for [`DateTime`] is implemented to
44//! show the value in the well-known [RFC 3339 format]. If you need a different
45//! date and time format, convert [`DateTime`] to a type which represents time
46//! such as [`time::PrimitiveDateTime`].
47//!
48//! ```
49//! use dos_date_time::{
50//!     DateTime,
51//!     time::{PrimitiveDateTime, format_description::well_known::Rfc2822},
52//! };
53//!
54//! let dt = DateTime::MIN;
55//! assert_eq!(format!("{dt}"), "1980-01-01 00:00:00");
56//!
57//! let dt = PrimitiveDateTime::from(dt)
58//!     .as_utc()
59//!     .format(&Rfc2822)
60//!     .unwrap();
61//! assert_eq!(format!("{dt}"), "Tue, 01 Jan 1980 00:00:00 +0000");
62//! ```
63//!
64//! [MS-DOS date and time]: https://learn.microsoft.com/en-us/windows/win32/sysinfo/ms-dos-date-and-time
65//! [FAT]: https://en.wikipedia.org/wiki/File_Allocation_Table
66//! [ZIP]: https://en.wikipedia.org/wiki/ZIP_(file_format)
67//! [RFC 3339 format]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
68
69#![doc(html_root_url = "https://docs.rs/dos-date-time/0.2.2/")]
70#![no_std]
71#![cfg_attr(docsrs, feature(doc_cfg))]
72// Lint levels of rustc.
73#![deny(missing_docs)]
74
75#[cfg(test)]
76#[macro_use]
77extern crate alloc;
78#[cfg(feature = "std")]
79extern crate std;
80
81mod dos_date;
82mod dos_date_time;
83mod dos_time;
84pub mod error;
85
86#[cfg(feature = "chrono")]
87pub use chrono;
88#[cfg(feature = "jiff")]
89pub use jiff;
90pub use time;
91
92pub use crate::{dos_date::Date, dos_date_time::DateTime, dos_time::Time};
dos_date_time/lib.rs

dos_date_time/
lib.rs
