Crate nt_time

Source
Expand description

The nt-time crate is a Windows file time library.

The FileTime is a type that represents the file time, which is a 64-bit unsigned integer value that represents the number of 100-nanosecond intervals that have elapsed since “1601-01-01 00:00:00 UTC”, and is used as timestamps such as NTFS and 7z. Windows uses a file time to record when an application creates, accesses, or writes to a file.

Note that many environments, such as the Win32 API, may limit the largest value of the file time to “+30828-09-14 02:48:05.477580700 UTC”, which is equal to i64::MAX, the largest value of a 64-bit signed integer type when represented as an underlying integer value. This is the largest file time accepted by the FileTimeToSystemTime function of the Win32 API.

§Examples

§Basic usage

FileTime can be converted from and to a type which represents time such as time::OffsetDateTime. Addition and subtraction are also supported.

use core::time::Duration;

use nt_time::{
    time::{macros::datetime, OffsetDateTime},
    FileTime,
};

let ft = FileTime::NT_TIME_EPOCH;
assert_eq!(
    OffsetDateTime::try_from(ft).unwrap(),
    datetime!(1601-01-01 00:00 UTC)
);

let ft = ft + Duration::from_secs(11_644_473_600);
assert_eq!(
    OffsetDateTime::try_from(ft).unwrap(),
    OffsetDateTime::UNIX_EPOCH
);
assert_eq!(ft.to_raw(), 116_444_736_000_000_000);

// The practical largest file time.
assert_eq!(FileTime::try_from(i64::MAX).unwrap(), FileTime::SIGNED_MAX);
// The theoretical largest file time.
assert_eq!(FileTime::new(u64::MAX), FileTime::MAX);

§Conversion from and to other system times

FileTime can be converted from and to other system times such as Unix time or MS-DOS date and time.

use core::time::Duration;

use nt_time::{
    time::{OffsetDateTime, UtcOffset},
    FileTime,
};

// `1970-01-01 00:00:00 UTC`.
let ut = i64::default();
assert_eq!(
    OffsetDateTime::from_unix_timestamp(ut).unwrap(),
    OffsetDateTime::UNIX_EPOCH
);

let ft = FileTime::from_unix_time_secs(ut).unwrap();
assert_eq!(ft, FileTime::UNIX_EPOCH);

// `1980-01-01 00:00:00 UTC`.
let ft = ft + Duration::from_secs(315_532_800);
let dos_dt = ft.to_dos_date_time(Some(UtcOffset::UTC)).unwrap();
assert_eq!(dos_dt, (0x0021, u16::MIN, u8::MIN, Some(UtcOffset::UTC)));

§Formatting and printing the file time

The formatting traits for FileTime are implemented to show the underlying u64 value. If you need a human-readable date and time, convert FileTime to a type which represents time such as time::OffsetDateTime.

use nt_time::{time::OffsetDateTime, FileTime};

let ft = FileTime::NT_TIME_EPOCH;
assert_eq!(format!("{ft}"), "0");
assert_eq!(
    format!("{}", OffsetDateTime::try_from(ft).unwrap()),
    "1601-01-01 0:00:00.0 +00:00:00"
);

Re-exports§

Modules§

Structs§