byteorder: add doc tests for WriteBytesExt methods

Closes #129

1 files changed, 216 insertions, 0 deletions

diff --git a/src/io.rs b/src/io.rs
index 546907e..76256a1 100644
--- a/src/io.rs
+++ b/src/io.rs
@@ -1056,6 +1056,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 8 bit integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::WriteBytesExt;
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_u8(2).unwrap();
+    /// wtr.write_u8(5).unwrap();
+    /// assert_eq!(wtr, b"\x02\x05");
+    /// ```
     #[inline]
     fn write_u8(&mut self, n: u8) -> Result<()> {
         self.write_all(&[n])
@@ -1071,6 +1084,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write signed 8 bit integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::WriteBytesExt;
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_i8(2).unwrap();
+    /// wtr.write_i8(-5).unwrap();
+    /// assert_eq!(wtr, b"\x02\xfb");
+    /// ```
     #[inline]
     fn write_i8(&mut self, n: i8) -> Result<()> {
         self.write_all(&[n as u8])
@@ -1083,6 +1109,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 16 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_u16::<BigEndian>(517).unwrap();
+    /// wtr.write_u16::<BigEndian>(768).unwrap();
+    /// assert_eq!(wtr, b"\x02\x05\x03\x00");
+    /// ```
     #[inline]
     fn write_u16<T: ByteOrder>(&mut self, n: u16) -> Result<()> {
         let mut buf = [0; 2];
@@ -1097,6 +1136,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write signed 16 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_i16::<BigEndian>(193).unwrap();
+    /// wtr.write_i16::<BigEndian>(-132).unwrap();
+    /// assert_eq!(wtr, b"\x00\xc1\xff\x7c");
+    /// ```
     #[inline]
     fn write_i16<T: ByteOrder>(&mut self, n: i16) -> Result<()> {
         let mut buf = [0; 2];
@@ -1111,6 +1163,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 24 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_u24::<BigEndian>(267).unwrap();
+    /// wtr.write_u24::<BigEndian>(120111).unwrap();
+    /// assert_eq!(wtr, b"\x00\x01\x0b\x01\xd5\x2f");
+    /// ```
     #[inline]
     fn write_u24<T: ByteOrder>(&mut self, n: u32) -> Result<()> {
         let mut buf = [0; 3];
@@ -1125,6 +1190,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write signed 24 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_i24::<BigEndian>(-34253).unwrap();
+    /// wtr.write_i24::<BigEndian>(120111).unwrap();
+    /// assert_eq!(wtr, b"\xff\x7a\x33\x01\xd5\x2f");
+    /// ```
     #[inline]
     fn write_i24<T: ByteOrder>(&mut self, n: i32) -> Result<()> {
         let mut buf = [0; 3];
@@ -1139,6 +1217,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 32 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_u32::<BigEndian>(267).unwrap();
+    /// wtr.write_u32::<BigEndian>(1205419366).unwrap();
+    /// assert_eq!(wtr, b"\x00\x00\x01\x0b\x47\xd9\x3d\x66");
+    /// ```
     #[inline]
     fn write_u32<T: ByteOrder>(&mut self, n: u32) -> Result<()> {
         let mut buf = [0; 4];
@@ -1153,6 +1244,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write signed 32 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_i32::<BigEndian>(-34253).unwrap();
+    /// wtr.write_i32::<BigEndian>(1205419366).unwrap();
+    /// assert_eq!(wtr, b"\xff\xff\x7a\x33\x47\xd9\x3d\x66");
+    /// ```
     #[inline]
     fn write_i32<T: ByteOrder>(&mut self, n: i32) -> Result<()> {
         let mut buf = [0; 4];
@@ -1167,6 +1271,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 48 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_u48::<BigEndian>(52360336390828).unwrap();
+    /// wtr.write_u48::<BigEndian>(541).unwrap();
+    /// assert_eq!(wtr, b"\x2f\x9f\x17\x40\x3a\xac\x00\x00\x00\x00\x02\x1d");
+    /// ```
     #[inline]
     fn write_u48<T: ByteOrder>(&mut self, n: u64) -> Result<()> {
         let mut buf = [0; 6];
@@ -1181,6 +1298,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write signed 48 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_i48::<BigEndian>(-108363435763825).unwrap();
+    /// wtr.write_i48::<BigEndian>(77).unwrap();
+    /// assert_eq!(wtr, b"\x9d\x71\xab\xe7\x97\x8f\x00\x00\x00\x00\x00\x4d");
+    /// ```
     #[inline]
     fn write_i48<T: ByteOrder>(&mut self, n: i64) -> Result<()> {
         let mut buf = [0; 6];
@@ -1195,6 +1325,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 64 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_u64::<BigEndian>(918733457491587).unwrap();
+    /// wtr.write_u64::<BigEndian>(143).unwrap();
+    /// assert_eq!(wtr, b"\x00\x03\x43\x95\x4d\x60\x86\x83\x00\x00\x00\x00\x00\x00\x00\x8f");
+    /// ```
     #[inline]
     fn write_u64<T: ByteOrder>(&mut self, n: u64) -> Result<()> {
         let mut buf = [0; 8];
@@ -1209,6 +1352,19 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write signed 64 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_i64::<BigEndian>(i64::min_value()).unwrap();
+    /// wtr.write_i64::<BigEndian>(i64::max_value()).unwrap();
+    /// assert_eq!(wtr, b"\x80\x00\x00\x00\x00\x00\x00\x00\x7f\xff\xff\xff\xff\xff\xff\xff");
+    /// ```
     #[inline]
     fn write_i64<T: ByteOrder>(&mut self, n: i64) -> Result<()> {
         let mut buf = [0; 8];
@@ -1246,6 +1402,19 @@ pub trait WriteBytesExt: io::Write {
     ///
     /// If the given integer is not representable in the given number of bytes,
     /// this method panics. If `nbytes > 8`, this method panics.
+    ///
+    /// # Examples
+    ///
+    /// Write unsigned 40 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_uint::<BigEndian>(312550384361, 5).unwrap();
+    /// wtr.write_uint::<BigEndian>(43, 5).unwrap();
+    /// assert_eq!(wtr, b"\x48\xc5\x74\x62\xe9\x00\x00\x00\x00\x2b");
+    /// ```
     #[inline]
     fn write_uint<T: ByteOrder>(
         &mut self,
@@ -1269,6 +1438,19 @@ pub trait WriteBytesExt: io::Write {
     ///
     /// If the given integer is not representable in the given number of bytes,
     /// this method panics. If `nbytes > 8`, this method panics.
+    ///
+    /// # Examples
+    ///
+    /// Write signed 56 bit big-endian integers to a `Write`:
+    ///
+    /// ```rust
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_int::<BigEndian>(-3548172039376767, 7).unwrap();
+    /// wtr.write_int::<BigEndian>(43, 7).unwrap();
+    /// assert_eq!(wtr, b"\xf3\x64\xf4\xd1\xfd\xb0\x81\x00\x00\x00\x00\x00\x00\x2b");
+    /// ```
     #[inline]
     fn write_int<T: ByteOrder>(
         &mut self,
@@ -1320,6 +1502,20 @@ pub trait WriteBytesExt: io::Write {
     /// This method returns the same errors as [`Write::write_all`].
     ///
     /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write a big-endian single-precision floating point number to a `Write`:
+    ///
+    /// ```rust
+    /// use std::f32;
+    ///
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_f32::<BigEndian>(f32::consts::PI).unwrap();
+    /// assert_eq!(wtr, b"\x40\x49\x0f\xdb");
+    /// ```
     #[inline]
     fn write_f32<T: ByteOrder>(&mut self, n: f32) -> Result<()> {
         let mut buf = [0; 4];
@@ -1329,6 +1525,26 @@ pub trait WriteBytesExt: io::Write {
 
     /// Writes a IEEE754 double-precision (8 bytes) floating point number to
     /// the underlying writer.
+    ///
+    /// # Errors
+    ///
+    /// This method returns the same errors as [`Write::write_all`].
+    ///
+    /// [`Write::write_all`]: https://doc.rust-lang.org/std/io/trait.Write.html#method.write_all
+    ///
+    /// # Examples
+    ///
+    /// Write a big-endian double-precision floating point number to a `Write`:
+    ///
+    /// ```rust
+    /// use std::f64;
+    ///
+    /// use byteorder::{BigEndian, WriteBytesExt};
+    ///
+    /// let mut wtr = Vec::new();
+    /// wtr.write_f64::<BigEndian>(f64::consts::PI).unwrap();
+    /// assert_eq!(wtr, b"\x40\x09\x21\xfb\x54\x44\x2d\x18");
+    /// ```
     #[inline]
     fn write_f64<T: ByteOrder>(&mut self, n: f64) -> Result<()> {
         let mut buf = [0; 8];