diff --git a/Cargo.toml b/Cargo.toml index d05c030..5b0163c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "tinystr" description = """ A small ASCII-only bounded length string representation. """ -version = "0.4.5" +version = "0.4.6" authors = [ "Raph Levien ", "Zibi Braniecki ", diff --git a/src/tinystr16.rs b/src/tinystr16.rs index 569bb08..fb261f4 100644 --- a/src/tinystr16.rs +++ b/src/tinystr16.rs @@ -88,7 +88,10 @@ impl TinyStr16 { self.deref() } - /// Gets a representation of this TinyStr16 as a primitive. + /// Gets a representation of this TinyStr16 as a primitive, valid for the + /// current machine. This value is not necessarily compatible with + /// [`TinyStr16::new_unchecked()`], use [`TinyStr16::from_native_unchecked()`] + /// instead. /// /// # Examples /// @@ -110,6 +113,36 @@ impl TinyStr16 { self.0.get() } + /// An unsafe constructor intended for cases where the consumer + /// guarantees that the input is a native endian integer which + /// is a correct representation of a `TinyStr16` string + /// + /// # Examples + /// + /// ``` + /// use tinystr::TinyStr16; + /// + /// let s1: TinyStr16 = "Test".parse() + /// .expect("Failed to parse."); + /// + /// let num: u128 = s1.as_unsigned(); + /// + /// let s2 = unsafe { TinyStr16::new_unchecked(num) }; + /// + /// assert_eq!(s1, s2); + /// assert_eq!(s2.as_str(), "Test"); + /// ``` + /// + /// # Safety + /// + /// The method does not validate the `u32` to be properly encoded + /// value for `TinyStr16`. + /// The value can be retrieved via [`TinyStr16::as_unsigned()`]. + #[inline(always)] + pub const unsafe fn from_native_unchecked(text: u128) -> Self { + Self(NonZeroU128::new_unchecked(text)) + } + /// Checks if the value is composed of ASCII alphabetic characters: /// /// * U+0041 'A' ..= U+005A 'Z', or diff --git a/src/tinystr4.rs b/src/tinystr4.rs index 8a2ab03..5a0cf24 100644 --- a/src/tinystr4.rs +++ b/src/tinystr4.rs @@ -88,7 +88,10 @@ impl TinyStr4 { self.deref() } - /// Gets a representation of this TinyStr4 as a primitive. + /// Gets a representation of this TinyStr4 as a primitive, valid for the + /// current machine. This value is not necessarily compatible with + /// [`TinyStr4::new_unchecked()`], use [`TinyStr4::from_native_unchecked()`] + /// instead. /// /// # Examples /// @@ -110,6 +113,36 @@ impl TinyStr4 { self.0.get() } + /// An unsafe constructor intended for cases where the consumer + /// guarantees that the input is a native endian integer which + /// is a correct representation of a `TinyStr4` string + /// + /// # Examples + /// + /// ``` + /// use tinystr::TinyStr4; + /// + /// let s1: TinyStr4 = "Test".parse() + /// .expect("Failed to parse."); + /// + /// let num: u32 = s1.as_unsigned(); + /// + /// let s2 = unsafe { TinyStr4::new_unchecked(num) }; + /// + /// assert_eq!(s1, s2); + /// assert_eq!(s2.as_str(), "Test"); + /// ``` + /// + /// # Safety + /// + /// The method does not validate the `u32` to be properly encoded + /// value for `TinyStr4`. + /// The value can be retrieved via [`TinyStr4::as_unsigned()`]. + #[inline(always)] + pub const unsafe fn from_native_unchecked(text: u32) -> Self { + Self(NonZeroU32::new_unchecked(text)) + } + /// Checks if the value is composed of ASCII alphabetic characters: /// /// * U+0041 'A' ..= U+005A 'Z', or diff --git a/src/tinystr8.rs b/src/tinystr8.rs index 605f990..c44c20f 100644 --- a/src/tinystr8.rs +++ b/src/tinystr8.rs @@ -88,7 +88,10 @@ impl TinyStr8 { self.deref() } - /// Gets a representation of this TinyStr8 as a primitive. + /// Gets a representation of this TinyStr8 as a primitive, valid for the + /// current machine. This value is not necessarily compatible with + /// [`TinyStr8::new_unchecked()`], use [`TinyStr8::from_native_unchecked()`] + /// instead. /// /// # Examples /// @@ -110,6 +113,36 @@ impl TinyStr8 { self.0.get() } + /// An unsafe constructor intended for cases where the consumer + /// guarantees that the input is a native endian integer which + /// is a correct representation of a `TinyStr8` string + /// + /// # Examples + /// + /// ``` + /// use tinystr::TinyStr8; + /// + /// let s1: TinyStr8 = "Test".parse() + /// .expect("Failed to parse."); + /// + /// let num: u64 = s1.as_unsigned(); + /// + /// let s2 = unsafe { TinyStr8::new_unchecked(num) }; + /// + /// assert_eq!(s1, s2); + /// assert_eq!(s2.as_str(), "Test"); + /// ``` + /// + /// # Safety + /// + /// The method does not validate the `u32` to be properly encoded + /// value for `TinyStr8`. + /// The value can be retrieved via [`TinyStr8::as_unsigned()`]. + #[inline(always)] + pub const unsafe fn from_native_unchecked(text: u64) -> Self { + Self(NonZeroU64::new_unchecked(text)) + } + /// Checks if the value is composed of ASCII alphabetic characters: /// /// * U+0041 'A' ..= U+005A 'Z', or