[Enhancement] Write to std::io::Writers (#78)

* Added ::= Writer

* Added ::= Writer::write_silently

* Added ::= Writer::write_loudly

* Added ::= tests for ``Writer``

* Create summary of recent changes

* Update 20240128_160529_GitHub_Actions_writer.ron

---------

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>

changelog.d/20240128_160529_GitHub_Actions_writer.ron

@@ -0,0 +1,11 @@
+(
+  references: {},
+  changes: {
+    "Added": [
+      "Writer",
+      "Writer::write_loudly",
+      "Writer::write_silently",
+      "tests for Writer",
+    ],
+  },
+)

src/lib.rs

@@ -132,7 +132,7 @@ mod reading;
 mod writing;
 
 pub use reading::{BufReadReader, OptionReader, PathBufLikeReader};
-pub use writing::PathBufLikeTruncation;
+pub use writing::{PathBufLikeTruncation, Writer};
 
 /// This crate's name.
 pub const NAME: &str = "aeruginous-io";

src/writing.rs

@@ -120,4 +120,72 @@ where
     }
 }
 
+/// Write to a [`std::io::Write`]r.
+pub trait Writer<T>
+where
+    T: std::io::Write,
+{
+    /// Write the data this method is called on to the given destination.
+    ///
+    /// This method behaves just like [`crate::Writer::write_silently`] despite
+    /// also printing error messages to [`std::io::Stderr`].
+    ///
+    /// # Errors
+    ///
+    /// See [`sysexits::ExitCode`].
+    fn write_loudly(self, destination: T) -> Result<()>;
+
+    /// Write the data this method is called on to the given destination.
+    ///
+    /// The data this method is called on will be converted to a [`String`] and
+    /// written to the given destination.  The data therefore needs to implement
+    /// [`ToString`].  The destination needs to implement [`std::io::Write`].
+    ///
+    /// The return value is either the unit type, in case of success, or a
+    /// [`sysexits::ExitCode`] to describe the error cause, otherwise.
+    ///
+    /// Error messages are not written to [`std::io::Stderr`].
+    ///
+    /// # Errors
+    ///
+    /// See [`sysexits::ExitCode`].
+    fn write_silently(self, destination: T) -> Result<()>;
+}
+
+impl<T: ToString, W: Write> Writer<W> for T {
+    fn write_loudly(self, mut destination: W) -> Result<()> {
+        let bytes = self.to_string().as_bytes().to_vec();
+
+        match destination.write(&bytes) {
+            Err(e) => {
+                eprintln!("{e}");
+                Err(e.into())
+            }
+            Ok(n) => {
+                if n == bytes.len() {
+                    Ok(())
+                } else {
+                    eprintln!("Creating an exact copy was not possible.");
+                    Err(sysexits::ExitCode::IoErr)
+                }
+            }
+        }
+    }
+
+    fn write_silently(self, mut destination: W) -> Result<()> {
+        let bytes = self.to_string().as_bytes().to_vec();
+
+        match destination.write(&bytes) {
+            Err(e) => Err(e.into()),
+            Ok(n) => {
+                if n == bytes.len() {
+                    Ok(())
+                } else {
+                    Err(sysexits::ExitCode::IoErr)
+                }
+            }
+        }
+    }
+}
+
 /******************************************************************************/

tests/writing.rs

@@ -101,4 +101,24 @@ mod path_buf_like_truncation {
     }
 }
 
+mod writer {
+    use aeruginous_io::Writer;
+
+    #[test]
+    fn write_loudly_success() {
+        let mut buffer = Vec::new();
+
+        assert!("test".write_loudly(&mut buffer).is_ok());
+        assert_eq!(buffer, b"test");
+    }
+
+    #[test]
+    fn write_silently_success() {
+        let mut buffer = Vec::new();
+
+        assert!("test".write_silently(&mut buffer).is_ok());
+        assert_eq!(buffer, b"test");
+    }
+}
+
 /******************************************************************************/