chore(release): Release version 0.10.3

.bumpversion.toml

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0 OR MIT
 
 [tool.bumpversion]
-current_version = "0.10.2"
+current_version = "0.10.3"
 
 [[tool.bumpversion.files]]
 filename = "README.md"

CHANGELOG.adoc

@@ -14,6 +14,13 @@ All notable changes to this project will be documented in this file.
 The format is based on https://keepachangelog.com/[Keep a Changelog], and this
 project adheres to https://semver.org/[Semantic Versioning].
 
+== {compare-url}/v0.10.2\...v0.10.3[0.10.3] - 2024-11-09
+
+=== Added
+
+* Add `FileTime::to_ne_bytes` and `FileTime::from_ne_bytes`
+  ({pull-request-url}/243[#243])
+
 == {compare-url}/v0.10.1\...v0.10.2[0.10.2] - 2024-11-08
 
 === Changed

Cargo.toml

@@ -4,7 +4,7 @@
 
 [package]
 name = "nt-time"
-version = "0.10.2"
+version = "0.10.3"
 authors = ["Shun Sakai <[email protected]>"]
 edition = "2021"
 rust-version = "1.67.0"

README.md

@@ -20,7 +20,7 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-nt-time = "0.10.2"
+nt-time = "0.10.3"
 ```
 
 ### Crate features

benches/file_time.rs

@@ -37,6 +37,11 @@ fn to_le_bytes(b: &mut Bencher) {
     b.iter(|| FileTime::NT_TIME_EPOCH.to_le_bytes());
 }
 
+#[bench]
+fn to_ne_bytes(b: &mut Bencher) {
+    b.iter(|| FileTime::NT_TIME_EPOCH.to_ne_bytes());
+}
+
 #[bench]
 fn from_be_bytes(b: &mut Bencher) {
     b.iter(|| FileTime::from_be_bytes([u8::MIN; 8]));
@@ -47,6 +52,11 @@ fn from_le_bytes(b: &mut Bencher) {
     b.iter(|| FileTime::from_le_bytes([u8::MIN; 8]));
 }
 
+#[bench]
+fn from_ne_bytes(b: &mut Bencher) {
+    b.iter(|| FileTime::from_ne_bytes([u8::MIN; 8]));
+}
+
 #[bench]
 fn default(b: &mut Bencher) {
     b.iter(FileTime::default);

src/file_time.rs

@@ -106,7 +106,7 @@ impl FileTime {
     }
 
     /// Returns the memory representation of this `FileTime` as a byte array in
-    /// big-endian byte order.
+    /// big-endian (network) byte order.
     ///
     /// # Examples
     ///
@@ -147,8 +147,37 @@ impl FileTime {
         self.to_raw().to_le_bytes()
     }
 
+    /// Returns the memory representation of this `FileTime` as a byte array in
+    /// native byte order.
+    ///
+    /// As the target platform's native endianness is used, portable code should
+    /// use [`FileTime::to_be_bytes`] or [`FileTime::to_le_bytes`], as
+    /// appropriate, instead.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use nt_time::FileTime;
+    /// #
+    /// assert_eq!(FileTime::NT_TIME_EPOCH.to_ne_bytes(), [u8::MIN; 8]);
+    /// assert_eq!(
+    ///     FileTime::UNIX_EPOCH.to_ne_bytes(),
+    ///     if cfg!(target_endian = "big") {
+    ///         [0x01, 0x9d, 0xb1, 0xde, 0xd5, 0x3e, 0x80, 0x00]
+    ///     } else {
+    ///         [0x00, 0x80, 0x3e, 0xd5, 0xde, 0xb1, 0x9d, 0x01]
+    ///     }
+    /// );
+    /// assert_eq!(FileTime::MAX.to_ne_bytes(), [u8::MAX; 8]);
+    /// ```
+    #[must_use]
+    #[inline]
+    pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
+        self.to_raw().to_ne_bytes()
+    }
+
     /// Creates a native endian `FileTime` value from its representation as a
-    /// byte array in big-endian.
+    /// byte array in big endian.
     ///
     /// # Examples
     ///
@@ -172,7 +201,7 @@ impl FileTime {
     }
 
     /// Creates a native endian `FileTime` value from its representation as a
-    /// byte array in little-endian.
+    /// byte array in little endian.
     ///
     /// # Examples
     ///
@@ -194,6 +223,38 @@ impl FileTime {
     pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
         Self::new(u64::from_le_bytes(bytes))
     }
+
+    /// Creates a native endian `FileTime` value from its memory representation
+    /// as a byte array in native endianness.
+    ///
+    /// As the target platform's native endianness is used, portable code likely
+    /// wants to use [`FileTime::from_be_bytes`] or [`FileTime::from_le_bytes`],
+    /// as appropriate instead.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use nt_time::FileTime;
+    /// #
+    /// assert_eq!(
+    ///     FileTime::from_ne_bytes([u8::MIN; 8]),
+    ///     FileTime::NT_TIME_EPOCH
+    /// );
+    /// assert_eq!(
+    ///     FileTime::from_ne_bytes(if cfg!(target_endian = "big") {
+    ///         [0x01, 0x9d, 0xb1, 0xde, 0xd5, 0x3e, 0x80, 0x00]
+    ///     } else {
+    ///         [0x00, 0x80, 0x3e, 0xd5, 0xde, 0xb1, 0x9d, 0x01]
+    ///     }),
+    ///     FileTime::UNIX_EPOCH
+    /// );
+    /// assert_eq!(FileTime::from_ne_bytes([u8::MAX; 8]), FileTime::MAX);
+    /// ```
+    #[must_use]
+    #[inline]
+    pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
+        Self::new(u64::from_ne_bytes(bytes))
+    }
 }
 
 impl Default for FileTime {
@@ -264,6 +325,12 @@ impl FromStr for FileTime {
 mod tests {
     use super::*;
 
+    #[test]
+    fn size_of() {
+        assert_eq!(mem::size_of::<FileTime>(), 8);
+        assert_eq!(mem::size_of::<FileTime>(), mem::size_of::<u64>());
+    }
+
     #[test]
     fn clone() {
         assert_eq!(FileTime::NT_TIME_EPOCH.clone(), FileTime::NT_TIME_EPOCH);
@@ -376,6 +443,33 @@ mod tests {
         const _: [u8; 8] = FileTime::NT_TIME_EPOCH.to_le_bytes();
     }
 
+    #[test]
+    fn to_ne_bytes() {
+        assert_eq!(FileTime::NT_TIME_EPOCH.to_ne_bytes(), [u8::MIN; 8]);
+        assert_eq!(
+            FileTime::UNIX_EPOCH.to_ne_bytes(),
+            if cfg!(target_endian = "big") {
+                [0x01, 0x9d, 0xb1, 0xde, 0xd5, 0x3e, 0x80, 0x00]
+            } else {
+                [0x00, 0x80, 0x3e, 0xd5, 0xde, 0xb1, 0x9d, 0x01]
+            }
+        );
+        assert_eq!(FileTime::MAX.to_ne_bytes(), [u8::MAX; 8]);
+    }
+
+    #[cfg(feature = "std")]
+    #[test_strategy::proptest]
+    fn to_ne_bytes_roundtrip(ft: FileTime) {
+        use proptest::prop_assert_eq;
+
+        prop_assert_eq!(ft.to_ne_bytes(), ft.to_raw().to_ne_bytes());
+    }
+
+    #[test]
+    const fn to_ne_bytes_is_const_fn() {
+        const _: [u8; 8] = FileTime::NT_TIME_EPOCH.to_ne_bytes();
+    }
+
     #[test]
     fn from_be_bytes() {
         assert_eq!(
@@ -434,6 +528,39 @@ mod tests {
         const _: FileTime = FileTime::from_le_bytes([u8::MIN; 8]);
     }
 
+    #[test]
+    fn from_ne_bytes() {
+        assert_eq!(
+            FileTime::from_ne_bytes([u8::MIN; 8]),
+            FileTime::NT_TIME_EPOCH
+        );
+        assert_eq!(
+            FileTime::from_ne_bytes(if cfg!(target_endian = "big") {
+                [0x01, 0x9d, 0xb1, 0xde, 0xd5, 0x3e, 0x80, 0x00]
+            } else {
+                [0x00, 0x80, 0x3e, 0xd5, 0xde, 0xb1, 0x9d, 0x01]
+            }),
+            FileTime::UNIX_EPOCH
+        );
+        assert_eq!(FileTime::from_ne_bytes([u8::MAX; 8]), FileTime::MAX);
+    }
+
+    #[cfg(feature = "std")]
+    #[test_strategy::proptest]
+    fn from_ne_bytes_roundtrip(bytes: [u8; mem::size_of::<FileTime>()]) {
+        use proptest::prop_assert_eq;
+
+        prop_assert_eq!(
+            FileTime::from_ne_bytes(bytes),
+            FileTime::new(u64::from_ne_bytes(bytes))
+        );
+    }
+
+    #[test]
+    const fn from_ne_bytes_is_const_fn() {
+        const _: FileTime = FileTime::from_ne_bytes([u8::MIN; 8]);
+    }
+
     #[test]
     fn default() {
         assert_eq!(FileTime::default(), FileTime::NT_TIME_EPOCH);

src/lib.rs

@@ -87,7 +87,7 @@
 //! [Unix time]: https://en.wikipedia.org/wiki/Unix_time
 //! [MS-DOS date and time]: https://learn.microsoft.com/en-us/windows/win32/sysinfo/ms-dos-date-and-time
 
-#![doc(html_root_url = "https://docs.rs/nt-time/0.10.2/")]
+#![doc(html_root_url = "https://docs.rs/nt-time/0.10.3/")]
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
 // Lint levels of rustc.