diff --git a/benches/bench.rs b/benches/bench.rs index ed0a091..1f2d4f9 100644 --- a/benches/bench.rs +++ b/benches/bench.rs @@ -20,7 +20,7 @@ fn bench_to_str(b: &mut Bencher) { let ulid = Ulid::new(); b.iter(|| { let mut buffer = [0; ULID_LEN]; - ulid.to_str(&mut buffer).unwrap(); + ulid.array_to_str(&mut buffer); }); } diff --git a/src/base32.rs b/src/base32.rs index e2e012c..6cf4658 100644 --- a/src/base32.rs +++ b/src/base32.rs @@ -57,6 +57,10 @@ impl fmt::Display for EncodeError { } /// Encode a u128 value to a given buffer. The provided buffer should be at least `ULID_LEN` long. +#[deprecated( + since = "1.2.0", + note = "Use the infallible `encode_to_array` instead." +)] pub fn encode_to(mut value: u128, buffer: &mut [u8]) -> Result { // NOTE: This function can't be made const because mut refs aren't allowed for some reason @@ -72,11 +76,21 @@ pub fn encode_to(mut value: u128, buffer: &mut [u8]) -> Result>= 5; + } +} + #[cfg(feature = "std")] pub fn encode(value: u128) -> String { let mut buffer: [u8; ULID_LEN] = [0; ULID_LEN]; - encode_to(value, &mut buffer).expect("unexpected encoding error"); + encode_to_array(value, &mut buffer); String::from_utf8(buffer.to_vec()).expect("unexpected failure in base32 encode for ulid") } diff --git a/src/lib.rs b/src/lib.rs index 399d1a9..83878ba 100755 --- a/src/lib.rs +++ b/src/lib.rs @@ -190,11 +190,32 @@ impl Ulid { /// /// assert_eq!(new_text, text); /// ``` + #[deprecated(since = "1.2.0", note = "Use the infallible `array_to_str` instead.")] pub fn to_str<'buf>(&self, buf: &'buf mut [u8]) -> Result<&'buf mut str, EncodeError> { + #[allow(deprecated)] let len = base32::encode_to(self.0, buf)?; Ok(unsafe { core::str::from_utf8_unchecked_mut(&mut buf[..len]) }) } + /// Creates a Crockford Base32 encoded string that represents this Ulid + /// + /// # Example + /// ```rust + /// use ulid::Ulid; + /// + /// let text = "01D39ZY06FGSCTVN4T2V9PKHFZ"; + /// let ulid = Ulid::from_string(text).unwrap(); + /// + /// let mut buf = [0; ulid::ULID_LEN]; + /// let new_text = ulid.array_to_str(&mut buf); + /// + /// assert_eq!(new_text, text); + /// ``` + pub fn array_to_str<'buf>(&self, buf: &'buf mut [u8; ULID_LEN]) -> &'buf mut str { + base32::encode_to_array(self.0, buf); + unsafe { core::str::from_utf8_unchecked_mut(buf) } + } + /// Creates a Crockford Base32 encoded string that represents this Ulid /// /// # Example @@ -336,7 +357,7 @@ impl FromStr for Ulid { impl fmt::Display for Ulid { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> { let mut buffer = [0; ULID_LEN]; - write!(f, "{}", self.to_str(&mut buffer).unwrap()) + write!(f, "{}", self.array_to_str(&mut buffer)) } } diff --git a/src/serde.rs b/src/serde.rs index f6b221f..c9b297a 100644 --- a/src/serde.rs +++ b/src/serde.rs @@ -15,7 +15,7 @@ impl Serialize for Ulid { S: Serializer, { let mut buffer = [0; ULID_LEN]; - let text = self.to_str(&mut buffer).unwrap(); + let text = self.array_to_str(&mut buffer); text.serialize(serializer) } }