Merge pull request #142 from marshallpierce/mp/string-writer

Add EncoderStringWriter

Author: marshallpierce

RELEASE-NOTES.md

@@ -1,6 +1,13 @@
+# Next
+
+- Config methods are const
+- Added `EncoderStringWriter` to allow encoding directly to a String
+- `EncoderWriter` now owns its delegate writer rather than keeping a reference to it (though refs still work)
+    - As a consequence, it is now possible to extract the delegate writer from an `EncoderWriter` via `finish()`, which returns `Result<W>` instead of `Result<()>`.
+
 # 0.12.2
 
-Add `BinHex` alphabet
+- Add `BinHex` alphabet
 
 # 0.12.1
 

benches/benchmarks.rs

@@ -123,6 +123,32 @@ fn do_encode_bench_stream(b: &mut Bencher, &size: &usize) {
     });
 }
 
+fn do_encode_bench_string_stream(b: &mut Bencher, &size: &usize) {
+    let mut v: Vec<u8> = Vec::with_capacity(size);
+    fill(&mut v);
+
+    b.iter(|| {
+        let mut stream_enc = write::EncoderStringWriter::new(TEST_CONFIG);
+        stream_enc.write_all(&v).unwrap();
+            stream_enc.flush().unwrap();
+        let _ = stream_enc.into_inner();
+    });
+}
+
+fn do_encode_bench_string_reuse_buf_stream(b: &mut Bencher, &size: &usize) {
+    let mut v: Vec<u8> = Vec::with_capacity(size);
+    fill(&mut v);
+
+    let mut buf = String::new();
+    b.iter(|| {
+        buf.clear();
+        let mut stream_enc = write::EncoderStringWriter::from(&mut buf, TEST_CONFIG);
+        stream_enc.write_all(&v).unwrap();
+        stream_enc.flush().unwrap();
+        let _ = stream_enc.into_inner();
+    });
+}
+
 fn fill(v: &mut Vec<u8>) {
     let cap = v.capacity();
     // weak randomness is plenty; we just want to not be completely friendly to the branch predictor
@@ -147,6 +173,8 @@ fn encode_benchmarks(byte_sizes: &[usize]) -> ParameterizedBenchmark<usize> {
         .with_function("encode_reuse_buf", do_encode_bench_reuse_buf)
         .with_function("encode_slice", do_encode_bench_slice)
         .with_function("encode_reuse_buf_stream", do_encode_bench_stream)
+        .with_function("encode_string_stream", do_encode_bench_string_stream)
+        .with_function("encode_string_reuse_buf_stream", do_encode_bench_string_reuse_buf_stream)
 }
 
 fn decode_benchmarks(byte_sizes: &[usize]) -> ParameterizedBenchmark<usize> {

examples/make_tables.rs

@@ -164,8 +164,14 @@ fn print_decode_table(alphabet: &[u8], const_name: &str, indent_depth: usize) {
 }
 
 fn check_alphabet(alphabet: &[u8]) {
+    // ensure all characters are distinct
     assert_eq!(64, alphabet.len());
     let mut set: HashSet<u8> = HashSet::new();
     set.extend(alphabet);
     assert_eq!(64, set.len());
+
+    // must be ASCII to be valid as single UTF-8 bytes
+    for &b in alphabet {
+        assert!(b <= 0x7F_u8);
+    }
 }

src/write/encoder.rs

@@ -25,27 +25,24 @@ const MIN_ENCODE_CHUNK_SIZE: usize = 3;
 /// use std::io::Write;
 ///
 /// // use a vec as the simplest possible `Write` -- in real code this is probably a file, etc.
-/// let mut wrapped_writer = Vec::new();
-/// {
-///     let mut enc = base64::write::EncoderWriter::new(
-///         &mut wrapped_writer, base64::STANDARD);
+/// let mut enc = base64::write::EncoderWriter::new(Vec::new(), base64::STANDARD);
 ///
-///     // handle errors as you normally would
-///     enc.write_all(b"asdf").unwrap();
-///     // could leave this out to be called by Drop, if you don't care
-///     // about handling errors
-///     enc.finish().unwrap();
+/// // handle errors as you normally would
+/// enc.write_all(b"asdf").unwrap();
 ///
-/// }
+/// // could leave this out to be called by Drop, if you don't care
+/// // about handling errors or getting the delegate writer back
+/// let delegate = enc.finish().unwrap();
 ///
 /// // base64 was written to the writer
-/// assert_eq!(b"YXNkZg==", &wrapped_writer[..]);
+/// assert_eq!(b"YXNkZg==", &delegate[..]);
 ///
 /// ```
 ///
 /// # Panics
 ///
-/// Calling `write()` after `finish()` is invalid and will panic.
+/// Calling `write()` (or related methods) or `finish()` after `finish()` has completed without
+/// error is invalid and will panic.
 ///
 /// # Errors
 ///
@@ -56,10 +53,12 @@ const MIN_ENCODE_CHUNK_SIZE: usize = 3;
 ///
 /// It has some minor performance loss compared to encoding slices (a couple percent).
 /// It does not do any heap allocation.
-pub struct EncoderWriter<'a, W: 'a + Write> {
+pub struct EncoderWriter<W: Write> {
     config: Config,
-    /// Where encoded data is written to
-    w: &'a mut W,
+    /// Where encoded data is written to. It's an Option as it's None immediately before Drop is
+    /// called so that finish() can return the underlying writer. None implies that finish() has
+    /// been called successfully.
+    delegate: Option<W>,
     /// Holds a partial chunk, if any, after the last `write()`, so that we may then fill the chunk
     /// with the next `write()`, encode it, then proceed with the rest of the input normally.
     extra_input: [u8; MIN_ENCODE_CHUNK_SIZE],
@@ -70,13 +69,11 @@ pub struct EncoderWriter<'a, W: 'a + Write> {
     output: [u8; BUF_SIZE],
     /// How much of `output` is occupied with encoded data that couldn't be written last time
     output_occupied_len: usize,
-    /// True iff padding / partial last chunk has been written.
-    finished: bool,
     /// panic safety: don't write again in destructor if writer panicked while we were writing to it
     panicked: bool,
 }
 
-impl<'a, W: Write> fmt::Debug for EncoderWriter<'a, W> {
+impl<W: Write> fmt::Debug for EncoderWriter<W> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(
             f,
@@ -89,38 +86,58 @@ impl<'a, W: Write> fmt::Debug for EncoderWriter<'a, W> {
     }
 }
 
-impl<'a, W: Write> EncoderWriter<'a, W> {
+impl<W: Write> EncoderWriter<W> {
     /// Create a new encoder that will write to the provided delegate writer `w`.
-    pub fn new(w: &'a mut W, config: Config) -> EncoderWriter<'a, W> {
+    pub fn new(w: W, config: Config) -> EncoderWriter<W> {
         EncoderWriter {
             config,
-            w,
+            delegate: Some(w),
             extra_input: [0u8; MIN_ENCODE_CHUNK_SIZE],
             extra_input_occupied_len: 0,
             output: [0u8; BUF_SIZE],
             output_occupied_len: 0,
-            finished: false,
             panicked: false,
         }
     }
 
     /// Encode all remaining buffered data and write it, including any trailing incomplete input
     /// triples and associated padding.
     ///
-    /// Once this succeeds, no further writes can be performed, as that would produce invalid
-    /// base64.
+    /// Once this succeeds, no further writes or calls to this method are allowed.
     ///
-    /// This may write to the delegate writer multiple times if the delegate writer does not accept all input provided
-    /// to its `write` each invocation.
+    /// This may write to the delegate writer multiple times if the delegate writer does not accept
+    /// all input provided to its `write` each invocation.
+    ///
+    /// If you don't care about error handling, it is not necessary to call this function, as the
+    /// equivalent finalization is done by the Drop impl.
+    ///
+    /// Returns the writer that this was constructed around.
     ///
     /// # Errors
     ///
-    /// The first error that is not of [`ErrorKind::Interrupted`] will be returned.
-    pub fn finish(&mut self) -> Result<()> {
-        if self.finished {
-            return Ok(());
+    /// The first error that is not of `ErrorKind::Interrupted` will be returned.
+    pub fn finish(&mut self) -> Result<W> {
+        // If we could consume self in finish(), we wouldn't have to worry about this case, but
+        // finish() is retryable in the face of I/O errors, so we can't consume here.
+        if self.delegate.is_none() {
+            panic!("Encoder has already had finish() called")
         };
 
+        self.write_final_leftovers()?;
+
+        let writer = self.delegate.take().expect("Writer must be present");
+
+        Ok(writer)
+    }
+
+    /// Write any remaining buffered data to the delegate writer.
+    fn write_final_leftovers(&mut self) -> Result<()> {
+        if self.delegate.is_none() {
+            // finish() has already successfully called this, and we are now in drop() with a None
+            // writer, so just no-op
+            return Ok(());
+        }
+
         self.write_all_encoded_output()?;
 
         if self.extra_input_occupied_len > 0 {
@@ -138,7 +155,6 @@ impl<'a, W: Write> EncoderWriter<'a, W> {
             self.extra_input_occupied_len = 0;
         }
 
-        self.finished = true;
         Ok(())
     }
 
@@ -152,7 +168,11 @@ impl<'a, W: Write> EncoderWriter<'a, W> {
     /// that no write took place.
     fn write_to_delegate(&mut self, current_output_len: usize) -> Result<()> {
         self.panicked = true;
-        let res = self.w.write(&self.output[..current_output_len]);
+        let res = self
+            .delegate
+            .as_mut()
+            .expect("Writer must be present")
+            .write(&self.output[..current_output_len]);
         self.panicked = false;
 
         res.map(|consumed| {
@@ -197,7 +217,7 @@ impl<'a, W: Write> EncoderWriter<'a, W> {
     }
 }
 
-impl<'a, W: Write> Write for EncoderWriter<'a, W> {
+impl<W: Write> Write for EncoderWriter<W> {
     /// Encode input and then write to the delegate writer.
     ///
     /// Under non-error circumstances, this returns `Ok` with the value being the number of bytes
@@ -215,7 +235,7 @@ impl<'a, W: Write> Write for EncoderWriter<'a, W> {
     ///
     /// Any errors emitted by the delegate writer are returned.
     fn write(&mut self, input: &[u8]) -> Result<usize> {
-        if self.finished {
+        if self.delegate.is_none() {
             panic!("Cannot write more after calling finish()");
         }
 
@@ -339,17 +359,23 @@ impl<'a, W: Write> Write for EncoderWriter<'a, W> {
 
     /// Because this is usually treated as OK to call multiple times, it will *not* flush any
     /// incomplete chunks of input or write padding.
+    /// # Errors
+    ///
+    /// The first error that is not of [`ErrorKind::Interrupted`] will be returned.
     fn flush(&mut self) -> Result<()> {
         self.write_all_encoded_output()?;
-        self.w.flush()
+        self.delegate
+            .as_mut()
+            .expect("Writer must be present")
+            .flush()
     }
 }
 
-impl<'a, W: Write> Drop for EncoderWriter<'a, W> {
+impl<W: Write> Drop for EncoderWriter<W> {
     fn drop(&mut self) {
         if !self.panicked {
             // like `BufWriter`, ignore errors during drop
-            let _ = self.finish();
+            let _ = self.write_final_leftovers();
         }
     }
 }