Add encode_mut_str to guarantee UTF-8 for safe callers (#137)

Fixes #136

Author: ia0

bin/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.7-git
+
+### Patch
+
+- Update `data-encoding` version
+
 ## 0.3.6
 
 ### Patch

bin/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding-bin"
-version = "0.3.6"
+version = "0.3.7-git"
 authors = ["Julien Cretin <[email protected]>"]
 license = "MIT"
 edition = "2021"
@@ -17,5 +17,5 @@ name = "data-encoding"
 path = "src/main.rs"
 
 [dependencies]
-data-encoding = { version = "2.8.0", path = "../lib" }
+data-encoding = { version = "2.9.0-git", path = "../lib" }
 getopts = "0.2"

lib/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.9.0-git
+
+### Minor
+
+- Add `Encoding::encode_mut_str()` to guarantee UTF-8 for safe callers (fixes #136)
+
 ## 2.8.0
 
 ### Minor

lib/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding"
-version = "2.8.0"
+version = "2.9.0-git"
 authors = ["Julien Cretin <[email protected]>"]
 license = "MIT"
 edition = "2018"

lib/fuzz/Cargo.toml

@@ -30,24 +30,32 @@ name = "impl_decode"
 path = "fuzz_targets/impl_decode.rs"
 
 [[bin]]
-name = "impl_new_encoder"
-path = "fuzz_targets/impl_new_encoder.rs"
+name = "impl_encode_mut_str"
+path = "fuzz_targets/impl_encode_mut_str.rs"
+
+[[bin]]
+name = "impl_encode_append"
+path = "fuzz_targets/impl_encode_append.rs"
 
 [[bin]]
 name = "impl_encode_write_buffer"
 path = "fuzz_targets/impl_encode_write_buffer.rs"
 
 [[bin]]
-name = "spec_spec_base"
-path = "fuzz_targets/spec_spec_base.rs"
+name = "impl_new_encoder"
+path = "fuzz_targets/impl_new_encoder.rs"
+
+[[bin]]
+name = "spec_decode_encode"
+path = "fuzz_targets/spec_decode_encode.rs"
 
 [[bin]]
 name = "spec_encode_decode"
 path = "fuzz_targets/spec_encode_decode.rs"
 
 [[bin]]
-name = "spec_decode_encode"
-path = "fuzz_targets/spec_decode_encode.rs"
+name = "spec_spec_base"
+path = "fuzz_targets/spec_spec_base.rs"
 
 [lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(fuzzing)'] }

lib/fuzz/fuzz_targets/impl_encode_append.rs

@@ -0,0 +1 @@
+template.rs

lib/fuzz/fuzz_targets/impl_encode_mut_str.rs

@@ -0,0 +1 @@
+template.rs

lib/fuzz/src/cmd.rs

@@ -50,6 +50,17 @@ pub fn execute(target: &str, mut input: &[u8]) -> Output {
             output.insert("decode_ok", actual.is_ok() as usize);
             assert_eq!(actual.ok(), spec::decode(&spec, input));
         }
+        "impl_encode_mut_str" => {
+            let (spec, base) = gen_spec_base(&mut input, &mut output);
+            let mut output = vec![0; base.encode_len(input.len())];
+            assert_eq!(base.encode_mut_str(input, &mut output), spec::encode(&spec, input));
+        }
+        "impl_encode_append" => {
+            let (spec, base) = gen_spec_base(&mut input, &mut output);
+            let mut output = String::new();
+            base.encode_append(input, &mut output);
+            assert_eq!(output, spec::encode(&spec, input));
+        }
         "impl_encode_write_buffer" => {
             let (_, base) = gen_spec_base(&mut input, &mut output);
             let mut buffer = vec![0; gen::nat(&mut input, 510, 2050)];

lib/macro/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding-macro"
-version = "0.1.17"
+version = "0.1.18-git"
 authors = ["Julien Cretin <[email protected]>"]
 license = "MIT"
 edition = "2018"
@@ -14,5 +14,5 @@ description = "Macros for data-encoding"
 include = ["Cargo.toml", "LICENSE", "README.md", "src/lib.rs"]
 
 [dependencies]
-data-encoding = { version = "2.8.0", path = "..", default-features = false }
-data-encoding-macro-internal = { version = "0.1.15", path = "internal" }
+data-encoding = { version = "2.9.0-git", path = "..", default-features = false }
+data-encoding-macro-internal = { version = "0.1.16-git", path = "internal" }

lib/macro/internal/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "data-encoding-macro-internal"
-version = "0.1.15"
+version = "0.1.16-git"
 authors = ["Julien Cretin <[email protected]>"]
 license = "MIT"
 edition = "2018"
@@ -14,7 +14,7 @@ include = ["Cargo.toml", "LICENSE", "README.md", "src/lib.rs"]
 proc-macro = true
 
 [dependencies.data-encoding]
-version = "2.8.0"
+version = "2.9.0-git"
 path = "../.."
 default-features = false
 features = ["alloc"]

lib/src/lib.rs

@@ -1298,6 +1298,34 @@ impl Encoding {
         }
     }
 
+    /// Encodes `input` in `output` and returns it as a `&str`
+    ///
+    /// It is guaranteed that `output` and the return value only differ by their type. They both
+    /// point to the same range of memory (pointer and length).
+    ///
+    /// # Panics
+    ///
+    /// Panics if the `output` length does not match the result of [`encode_len`] for the `input`
+    /// length.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use data_encoding::BASE64;
+    /// # let mut buffer = vec![0; 100];
+    /// let input = b"Hello world";
+    /// let output = &mut buffer[0 .. BASE64.encode_len(input.len())];
+    /// assert_eq!(BASE64.encode_mut_str(input, output), "SGVsbG8gd29ybGQ=");
+    /// ```
+    ///
+    /// [`encode_len`]: struct.Encoding.html#method.encode_len
+    pub fn encode_mut_str<'a>(&self, input: &[u8], output: &'a mut [u8]) -> &'a str {
+        self.encode_mut(input, output);
+        safety_assert!(output.is_ascii());
+        // SAFETY: Ensured by correctness guarantees of encode_mut (and asserted above).
+        unsafe { core::str::from_utf8_unchecked(output) }
+    }
+
     /// Appends the encoding of `input` to `output`
     ///
     /// # Examples