Rename into methods to onto

To allow space for future impls of `Into` or an inherent equivalent

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
  * Breaking change: make encoding onto resizable buffers not clear them, instead appending onto any existing data
+ * Breaking change: rename `into` methods to `onto` to allow for implementing `Into` in the future (or a similar inherent method)
  * Add new `cb58` feature to support injecting and verifying that checksum (by @Zondax)
  * Update `sha2` to 0.10 (by @madninja)
  * Tighten max-encoded length estimation to reduce overallocation of resizable buffers (by @mina86)

benches/decode.rs

@@ -18,11 +18,11 @@ macro_rules! group_decode {
         });
         group.bench_function("decode_bs58_noalloc_slice", |b| {
             let mut output = [0; $decoded_length];
-            b.iter(|| bs58::decode($encoded).into(&mut output[..]).unwrap());
+            b.iter(|| bs58::decode($encoded).onto(&mut output[..]).unwrap());
         });
         group.bench_function("decode_bs58_noalloc_array", |b| {
             let mut output = [0; $decoded_length];
-            b.iter(|| bs58::decode($encoded).into(&mut output).unwrap());
+            b.iter(|| bs58::decode($encoded).onto(&mut output).unwrap());
         });
         group.finish();
     }};
@@ -42,7 +42,7 @@ macro_rules! group_decode_long {
         });
         group.bench_function("decode_bs58_noalloc_slice", |b| {
             let mut output = [0; $decoded_length];
-            b.iter(|| bs58::decode($encoded).into(&mut output[..]).unwrap());
+            b.iter(|| bs58::decode($encoded).onto(&mut output[..]).unwrap());
         });
         // bs58_noalloc_array is not possible because of limited array lengths in trait impls
         group.finish();

benches/encode.rs

@@ -18,7 +18,7 @@ macro_rules! group_encode {
         });
         group.bench_function("encode_bs58_noalloc", |b| {
             let mut output = String::with_capacity($encoded.len());
-            b.iter(|| bs58::encode($decoded).into(&mut output));
+            b.iter(|| bs58::encode($decoded).onto(&mut output));
         });
         group.finish();
     }};

src/decode.rs

@@ -72,7 +72,7 @@ pub enum Error {
     NoChecksum,
 }
 
-/// Represents a buffer that can be decoded into. See [`DecodeBuilder::into`] and the provided
+/// Represents a buffer that can be decoded into. See [`DecodeBuilder::onto`] and the provided
 /// implementations for more details.
 pub trait DecodeTarget {
     /// Decodes into this buffer, provides the maximum length for implementations that wish to
@@ -294,7 +294,7 @@ impl<'a, I: AsRef<[u8]>> DecodeBuilder<'a, I> {
     #[cfg(feature = "alloc")]
     pub fn into_vec(self) -> Result<Vec<u8>> {
         let mut output = Vec::new();
-        self.into(&mut output)?;
+        self.onto(&mut output)?;
         Ok(output)
     }
 
@@ -317,7 +317,7 @@ impl<'a, I: AsRef<[u8]>> DecodeBuilder<'a, I> {
     ///
     /// ```rust
     /// let mut output = b"hello ".to_vec();
-    /// assert_eq!(5, bs58::decode("EUYUqQf").into(&mut output)?);
+    /// assert_eq!(5, bs58::decode("EUYUqQf").onto(&mut output)?);
     /// assert_eq!(b"hello world", output.as_slice());
     /// # Ok::<(), bs58::decode::Error>(())
     /// ```
@@ -326,11 +326,11 @@ impl<'a, I: AsRef<[u8]>> DecodeBuilder<'a, I> {
     ///
     /// ```rust
     /// let mut output = b"hello ".to_owned();
-    /// assert_eq!(5, bs58::decode("EUYUqQf").into(&mut output)?);
+    /// assert_eq!(5, bs58::decode("EUYUqQf").onto(&mut output)?);
     /// assert_eq!(b"world ", output.as_ref());
     /// # Ok::<(), bs58::decode::Error>(())
     /// ```
-    pub fn into(self, mut output: impl DecodeTarget) -> Result<usize> {
+    pub fn onto(self, mut output: impl DecodeTarget) -> Result<usize> {
         let max_decoded_len = self.input.as_ref().len();
         match self.check {
             Check::Disabled => output.decode_with(max_decoded_len, |output| {

src/encode.rs

@@ -30,7 +30,7 @@ pub enum Error {
     BufferTooSmall,
 }
 
-/// Represents a buffer that can be encoded into. See [`EncodeBuilder::into`] and the provided
+/// Represents a buffer that can be encoded into. See [`EncodeBuilder::onto`] and the provided
 /// implementations for more details.
 pub trait EncodeTarget {
     /// Encodes into this buffer, provides the maximum length for implementations that wish to
@@ -314,7 +314,7 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     #[cfg(feature = "alloc")]
     pub fn into_string(self) -> String {
         let mut output = String::new();
-        self.into(&mut output).unwrap();
+        self.onto(&mut output).unwrap();
         output
     }
 
@@ -329,16 +329,16 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     #[cfg(feature = "alloc")]
     pub fn into_vec(self) -> Vec<u8> {
         let mut output = Vec::new();
-        self.into(&mut output).unwrap();
+        self.onto(&mut output).unwrap();
         output
     }
 
-    /// Encode into the given buffer.
+    /// Encode onto the given buffer.
     ///
-    /// Returns the length written into the buffer.
+    /// Returns the length written onto the buffer.
     ///
     /// If the buffer is resizeable it will be extended and the new data will be written to the end
-    /// of it.
+    /// of it, otherwise the data will be overwritten from the start.
     ///
     /// If the buffer is not resizeable bytes after the final character will be left alone, except
     /// up to 3 null bytes may be written to an `&mut str` to overwrite remaining characters of a
@@ -354,7 +354,7 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     /// ```rust
     /// let input = [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58];
     /// let mut output = b"goodbye world ".to_vec();
-    /// bs58::encode(input).into(&mut output)?;
+    /// bs58::encode(input).onto(&mut output)?;
     /// assert_eq!(b"goodbye world he11owor1d", output.as_slice());
     /// # Ok::<(), bs58::encode::Error>(())
     /// ```
@@ -364,7 +364,7 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     /// ```rust
     /// let input = [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58];
     /// let mut output = b"goodbye world".to_owned();
-    /// bs58::encode(input).into(&mut output[..])?;
+    /// bs58::encode(input).onto(&mut output[..])?;
     /// assert_eq!(b"he11owor1drld", output.as_ref());
     /// # Ok::<(), bs58::encode::Error>(())
     /// ```
@@ -374,7 +374,7 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     /// ```rust
     /// let input = [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58];
     /// let mut output = "goodbye world ".to_owned();
-    /// bs58::encode(input).into(&mut output)?;
+    /// bs58::encode(input).onto(&mut output)?;
     /// assert_eq!("goodbye world he11owor1d", output);
     /// # Ok::<(), bs58::encode::Error>(())
     /// ```
@@ -384,7 +384,7 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     /// ```rust
     /// let input = [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58];
     /// let mut output = "goodbye world".to_owned();
-    /// bs58::encode(input).into(output.as_mut_str())?;
+    /// bs58::encode(input).onto(output.as_mut_str())?;
     /// assert_eq!("he11owor1drld", output);
     /// # Ok::<(), bs58::encode::Error>(())
     /// ```
@@ -394,11 +394,11 @@ impl<'a, I: AsRef<[u8]>> EncodeBuilder<'a, I> {
     /// ```rust
     /// let input = [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58];
     /// let mut output = "goodbye w®ld".to_owned();
-    /// bs58::encode(input).into(output.as_mut_str())?;
+    /// bs58::encode(input).onto(output.as_mut_str())?;
     /// assert_eq!("he11owor1d\0ld", output);
     /// # Ok::<(), bs58::encode::Error>(())
     /// ```
-    pub fn into(self, mut output: impl EncodeTarget) -> Result<usize> {
+    pub fn onto(self, mut output: impl EncodeTarget) -> Result<usize> {
         let input = self.input.as_ref();
         match self.check {
             Check::Disabled => output.encode_with(max_encoded_len(input.len()), |output| {

src/lib.rs

@@ -71,8 +71,8 @@
 //!
 //! ```rust
 //! let (mut decoded, mut encoded) = ([0xFF; 8], String::with_capacity(10));
-//! bs58::decode("he11owor1d").into(&mut decoded)?;
-//! bs58::encode(decoded).into(&mut encoded)?;
+//! bs58::decode("he11owor1d").onto(&mut decoded)?;
+//! bs58::encode(decoded).onto(&mut encoded)?;
 //! assert_eq!("he11owor1d", encoded);
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
@@ -130,7 +130,7 @@ enum Check {
 ///
 /// ```rust
 /// let mut output = [0xFF; 10];
-/// assert_eq!(8, bs58::decode("he11owor1d").into(&mut output)?);
+/// assert_eq!(8, bs58::decode("he11owor1d").onto(&mut output)?);
 /// assert_eq!(
 ///     [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58, 0xFF, 0xFF],
 ///     output);
@@ -165,7 +165,7 @@ enum Check {
 /// let mut output = [0; 7];
 /// assert_eq!(
 ///     bs58::decode::Error::BufferTooSmall,
-///     bs58::decode("he11owor1d").into(&mut output).unwrap_err());
+///     bs58::decode("he11owor1d").onto(&mut output).unwrap_err());
 /// ```
 pub fn decode<I: AsRef<[u8]>>(input: I) -> decode::DecodeBuilder<'static, I> {
     decode::DecodeBuilder::from_input(input)
@@ -198,7 +198,7 @@ pub fn decode<I: AsRef<[u8]>>(input: I) -> decode::DecodeBuilder<'static, I> {
 /// ```rust
 /// let input = [0x04, 0x30, 0x5e, 0x2b, 0x24, 0x73, 0xf0, 0x58];
 /// let mut output = "goodbye world ".to_owned();
-/// bs58::encode(input).into(&mut output)?;
+/// bs58::encode(input).onto(&mut output)?;
 /// assert_eq!("goodbye world he11owor1d", output);
 /// # Ok::<(), bs58::encode::Error>(())
 /// ```
@@ -214,7 +214,7 @@ pub fn decode<I: AsRef<[u8]>>(input: I) -> decode::DecodeBuilder<'static, I> {
 /// let mut output = [0; 7];
 /// assert_eq!(
 ///     bs58::encode::Error::BufferTooSmall,
-///     bs58::encode(input).into(&mut output[..]).unwrap_err());
+///     bs58::encode(input).onto(&mut output[..]).unwrap_err());
 /// ```
 pub fn encode<I: AsRef<[u8]>>(input: I) -> encode::EncodeBuilder<'static, I> {
     encode::EncodeBuilder::from_input(input)

tests/decode.rs

@@ -12,22 +12,22 @@ fn test_decode() {
 
         {
             let mut vec = PREFIX.to_vec();
-            assert_eq!(Ok(val.len()), bs58::decode(s).into(&mut vec));
+            assert_eq!(Ok(val.len()), bs58::decode(s).onto(&mut vec));
             assert_eq!((PREFIX, val), vec.split_at(3));
         }
 
         #[cfg(feature = "smallvec")]
         {
             let mut vec = smallvec::SmallVec::<[u8; 36]>::from(PREFIX);
-            assert_eq!(Ok(val.len()), bs58::decode(s).into(&mut vec));
+            assert_eq!(Ok(val.len()), bs58::decode(s).onto(&mut vec));
             assert_eq!((PREFIX, val), vec.split_at(3));
         }
 
         #[cfg(feature = "tinyvec")]
         {
             {
                 let mut vec = tinyvec::ArrayVec::<[u8; 36]>::from_iter(PREFIX.iter().copied());
-                let res = bs58::decode(s).into(&mut vec);
+                let res = bs58::decode(s).onto(&mut vec);
                 if PREFIX.len() + val.len() <= vec.capacity() {
                     assert_eq!(Ok(val.len()), res);
                     assert_eq!((PREFIX, val), vec.split_at(3));
@@ -40,7 +40,7 @@ fn test_decode() {
                 let mut array = [0; 36];
                 array[..PREFIX.len()].copy_from_slice(PREFIX);
                 let mut vec = tinyvec::SliceVec::from_slice_len(&mut array, PREFIX.len());
-                let res = bs58::decode(s).into(&mut vec);
+                let res = bs58::decode(s).onto(&mut vec);
                 if PREFIX.len() + val.len() <= vec.capacity() {
                     assert_eq!(Ok(val.len()), res);
                     assert_eq!((PREFIX, val), vec.split_at(3));
@@ -51,7 +51,7 @@ fn test_decode() {
 
             {
                 let mut vec = tinyvec::TinyVec::<[u8; 36]>::from(PREFIX);
-                assert_eq!(Ok(val.len()), bs58::decode(s).into(&mut vec));
+                assert_eq!(Ok(val.len()), bs58::decode(s).onto(&mut vec));
                 assert_eq!((PREFIX, val), vec.split_at(3));
             }
         }
@@ -62,7 +62,7 @@ fn test_decode() {
 fn test_decode_small_buffer_err() {
     let mut output = [0; 2];
     assert_eq!(
-        bs58::decode("a3gV").into(&mut output),
+        bs58::decode("a3gV").onto(&mut output),
         Err(bs58::decode::Error::BufferTooSmall)
     );
 }
@@ -111,13 +111,13 @@ fn test_check_ver_failed() {
 #[test]
 fn append() {
     let mut buf = b"hello world".to_vec();
-    bs58::decode("a").into(&mut buf).unwrap();
+    bs58::decode("a").onto(&mut buf).unwrap();
     assert_eq!(b"hello world!", buf.as_slice());
 }
 
 #[test]
 fn no_append() {
     let mut buf = b"hello world".to_owned();
-    bs58::decode("a").into(buf.as_mut()).unwrap();
+    bs58::decode("a").onto(buf.as_mut()).unwrap();
     assert_eq!(b"!ello world", buf.as_ref());
 }