]> git.nihav.org Git - nihav.git/commitdiff
core/io: document bytestream reading/writing module
authorKostya Shishkov <kostya.shishkov@gmail.com>
Sat, 15 Feb 2020 17:54:19 +0000 (18:54 +0100)
committerKostya Shishkov <kostya.shishkov@gmail.com>
Sat, 15 Feb 2020 17:54:19 +0000 (18:54 +0100)
nihav-core/src/io/byteio.rs

index a10ccb9d0eef6f3f5169bf8895941bf6bbc46f84..4463b2ba5563d8504afc4923f151d985712ce1ca 100644 (file)
@@ -1,45 +1,91 @@
+//! Bytestream reading/writing functionality.
 pub use std::io::SeekFrom;
 use std::fs::File;
 use std::io::prelude::*;
 use std::ptr;
 
+/// A list specifying general bytestream reading and writing errors.
 #[derive(Debug)]
 pub enum ByteIOError {
+    /// End of stream.
     EOF,
+    /// Wrong seek position was provided.
     WrongRange,
+    /// Tried to call read() on bytestream writer or write() on bytestream reader.
     WrongIOMode,
+    /// Functionality is not implemented.
     NotImplemented,
+    /// Read error.
     ReadError,
+    /// Write error.
     WriteError,
+    /// Seeking failed.
     SeekError,
 }
 
+/// A specialised `Result` type for bytestream operations.
 pub type ByteIOResult<T> = Result<T, ByteIOError>;
 
+/// Common trait for bytestream operations.
 pub trait ByteIO {
+    /// Reads data into provided buffer. Fails if it cannot fill whole buffer.
     fn read_buf(&mut self, buf: &mut [u8]) -> ByteIOResult<usize>;
+    /// Reads data into provided buffer. Partial read is treated as success.
     fn read_buf_some(&mut self, buf: &mut [u8]) -> ByteIOResult<usize>;
+    /// Reads data into provided buffer but does not advance read position.
     fn peek_buf(&mut self, buf: &mut [u8]) -> ByteIOResult<usize>;
+    /// Reads single byte from the stream.
     fn read_byte(&mut self) -> ByteIOResult<u8>;
+    /// Returns the next byte value in the stream without advancing read position.
     fn peek_byte(&mut self) -> ByteIOResult<u8>;
+    /// Writes buffer to the stream.
     fn write_buf(&mut self, buf: &[u8]) -> ByteIOResult<()>;
+    /// Returns current read or write position.
     fn tell(&mut self) -> u64;
+    /// Seeks to the provided position.
     fn seek(&mut self, pos: SeekFrom) -> ByteIOResult<u64>;
+    /// Tells whether this is end of stream.
     fn is_eof(&self) -> bool;
+    /// Reports whether stream is seekable or not.
     fn is_seekable(&mut self) -> bool;
+    /// Returns stream size or -1 if it is not known.
     fn size(&mut self) -> i64;
 }
 
+/// High-level bytestream reader.
+///
+/// User is supposed to create some reader implementing [`ByteIO`] trait e.g. [`MemoryReader`] and use it to create `ByteReader` which can be used for reading e.g. various integer types.
+///
+/// # Examples
+///
+/// ````
+/// use nihav_core::io::byteio::{MemoryReader,ByteReader};
+/// # use nihav_core::io::byteio::ByteIOResult;
+///
+/// # fn foo() -> ByteIOResult<()> {
+/// let memory: [u8; 4] = [ 0, 42, 42, 0 ];
+/// let mut mr = MemoryReader::new_read(&memory);
+/// let mut br = ByteReader::new(&mut mr);
+/// let val = br.read_u16be()?; // read 16-bit big-endian integer, should be 42
+/// let val = br.read_u16le()?; // read 16-bit little-endian integer, should be 42 as well
+/// # Ok(())
+/// # }
+/// ````
+///
+/// [`ByteIO`]: ./trait.ByteIO.html
+/// [`MemoryReader`]: ./struct.MemoryReader.html
 #[allow(dead_code)]
 pub struct ByteReader<'a> {
     io: &'a mut ByteIO,
 }
 
+/// Bytestream reader from memory.
 pub struct MemoryReader<'a> {
     buf:      &'a [u8],
     pos:      usize,
 }
 
+/// Bytestream reader from file.
 pub struct FileReader<'a> {
     file:     &'a File,
     eof:      bool,
@@ -67,6 +113,7 @@ macro_rules! peek_int {
 
 macro_rules! read_int_func {
     ($s: ident, $inttype: ty, $size: expr, $which: ident) => {
+/// Reads integer of certain size and endianness.
         pub fn $s(src: &[u8]) -> ByteIOResult<$inttype> {
             if src.len() < $size { return Err(ByteIOError::ReadError); }
             unsafe {
@@ -85,21 +132,41 @@ read_int_func!(read_u32le, u32, 4, to_le);
 read_int_func!(read_u64be, u64, 8, to_be);
 read_int_func!(read_u64le, u64, 8, to_le);
 
+/// Reads 24-bit big-endian integer.
+///
+/// # Example
+///
+/// ````
+/// use nihav_core::io::byteio::read_u24be;
+/// # use nihav_core::io::byteio::ByteIOResult;
+///
+/// # fn foo() -> ByteIOResult<()> {
+/// let src: [u8; 3] = [ 1, 2, 3];
+/// let value = read_u24be(&src)?; // should return 0x010203
+/// # Ok(())
+/// # }
+/// ````
 pub fn read_u24be(src: &[u8]) -> ByteIOResult<u32> {
     if src.len() < 3 { return Err(ByteIOError::ReadError); }
     Ok((u32::from(src[0]) << 16) | (u32::from(src[1]) << 8) | u32::from(src[2]))
 }
+/// Reads 24-bit little-endian integer.
 pub fn read_u24le(src: &[u8]) -> ByteIOResult<u32> {
     if src.len() < 3 { return Err(ByteIOError::ReadError); }
     Ok((u32::from(src[2]) << 16) | (u32::from(src[1]) << 8) | u32::from(src[0]))
 }
+/// Reads 32-bit big-endian floating point number.
 pub fn read_f32be(src: &[u8]) -> ByteIOResult<f32> { Ok(f32::from_bits(read_u32be(src)?)) }
+/// Reads 32-bit little-endian floating point number.
 pub fn read_f32le(src: &[u8]) -> ByteIOResult<f32> { Ok(f32::from_bits(read_u32le(src)?)) }
+/// Reads 64-bit big-endian floating point number.
 pub fn read_f64be(src: &[u8]) -> ByteIOResult<f64> { Ok(f64::from_bits(read_u64be(src)?)) }
+/// Reads 64-bit little-endian floating point number.
 pub fn read_f64le(src: &[u8]) -> ByteIOResult<f64> { Ok(f64::from_bits(read_u64le(src)?)) }
 
 macro_rules! write_int_func {
     ($s: ident, $inttype: ty, $size: expr, $which: ident) => {
+/// Writes integer of certain size and endianness into byte buffer.
         pub fn $s(dst: &mut [u8], val: $inttype) -> ByteIOResult<()> {
             if dst.len() < $size { return Err(ByteIOError::WriteError); }
             unsafe {
@@ -118,6 +185,21 @@ write_int_func!(write_u32le, u32, 4, to_le);
 write_int_func!(write_u64be, u64, 8, to_be);
 write_int_func!(write_u64le, u64, 8, to_le);
 
+/// Writes 24-bit big-endian integer to the provided buffer.
+///
+/// # Example
+///
+/// ````
+/// use nihav_core::io::byteio::write_u24be;
+/// # use nihav_core::io::byteio::ByteIOResult;
+///
+/// # fn foo() -> ByteIOResult<()> {
+/// let mut dst = [0u8; 3];
+/// write_u24be(&mut dst, 0x010203)?;
+/// // dst should contain [ 1, 2, 3] now
+/// # Ok(())
+/// # }
+/// ````
 pub fn write_u24be(dst: &mut [u8], val: u32) -> ByteIOResult<()> {
     if dst.len() < 3 { return Err(ByteIOError::WriteError); }
     dst[0] = (val >> 16) as u8;
@@ -125,6 +207,7 @@ pub fn write_u24be(dst: &mut [u8], val: u32) -> ByteIOResult<()> {
     dst[2] = (val >>  0) as u8;
     Ok(())
 }
+/// Writes 24-bit little-endian integer to the provided buffer.
 pub fn write_u24le(dst: &mut [u8], val: u32) -> ByteIOResult<()> {
     if dst.len() < 3 { return Err(ByteIOError::WriteError); }
     dst[0] = (val >>  0) as u8;
@@ -132,138 +215,187 @@ pub fn write_u24le(dst: &mut [u8], val: u32) -> ByteIOResult<()> {
     dst[2] = (val >> 16) as u8;
     Ok(())
 }
+/// Writes 32-bit big-endian floating point number to the provided buffer.
 pub fn write_f32be(dst: &mut [u8], val: f32) -> ByteIOResult<()> { write_u32be(dst, val.to_bits()) }
+/// Writes 32-bit little-endian floating point number to the provided buffer.
 pub fn write_f32le(dst: &mut [u8], val: f32) -> ByteIOResult<()> { write_u32le(dst, val.to_bits()) }
+/// Writes 64-bit big-endian floating point number to the provided buffer.
 pub fn write_f64be(dst: &mut [u8], val: f64) -> ByteIOResult<()> { write_u64be(dst, val.to_bits()) }
+/// Writes 64-bit little-endian floating point number to the provided buffer.
 pub fn write_f64le(dst: &mut [u8], val: f64) -> ByteIOResult<()> { write_u64le(dst, val.to_bits()) }
 
 impl<'a> ByteReader<'a> {
+    /// Constructs a new instance of bytestream reader.
+    ///
+    /// # Examples
+    ///
+    /// ````
+    /// use nihav_core::io::byteio::{MemoryReader,ByteReader};
+    /// # use nihav_core::io::byteio::ByteIOResult;
+    ///
+    /// # fn foo() -> ByteIOResult<()> {
+    /// let memory: [u8; 4] = [ 0, 42, 42, 0 ];
+    /// let mut mr = MemoryReader::new_read(&memory);
+    /// let mut br = ByteReader::new(&mut mr);
+    /// # Ok(())
+    /// # }
+    /// ````
     pub fn new(io: &'a mut ByteIO) -> Self { ByteReader { io } }
 
+    /// Reads data into provided buffer. Partial read is treated as success.
     pub fn read_buf(&mut self, buf: &mut [u8])  -> ByteIOResult<usize> {
         self.io.read_buf(buf)
     }
 
+    /// Reads data into provided buffer. Partial read is treated as success.
     pub fn read_buf_some(&mut self, buf: &mut [u8])  -> ByteIOResult<usize> {
         self.io.read_buf_some(buf)
     }
 
+    /// Reads data into provided buffer but does not advance read position.
     pub fn peek_buf(&mut self, buf: &mut [u8])  -> ByteIOResult<usize> {
         self.io.peek_buf(buf)
     }
 
+    /// Reads single byte from the stream.
     pub fn read_byte(&mut self) -> ByteIOResult<u8> {
         self.io.read_byte()
     }
 
+    /// Returns the next byte value in the stream without advancing read position.
     pub fn peek_byte(&mut self) -> ByteIOResult<u8> {
         self.io.peek_byte()
     }
 
+    /// Reads 16-bit big-endian integer from the stream.
     pub fn read_u16be(&mut self) -> ByteIOResult<u16> {
         read_int!(self, u16, 2, to_be)
     }
 
+    /// Reads 16-bit big-endian integer from the stream without advancing read position.
     pub fn peek_u16be(&mut self) -> ByteIOResult<u16> {
         peek_int!(self, u16, 2, to_be)
     }
 
+    /// Reads 24-bit big-endian integer from the stream.
     pub fn read_u24be(&mut self) -> ByteIOResult<u32> {
         let p16 = self.read_u16be()?;
         let p8 = self.read_byte()?;
         Ok((u32::from(p16) << 8) | u32::from(p8))
     }
 
+    /// Reads 24-bit big-endian integer from the stream without advancing read position.
     pub fn peek_u24be(&mut self) -> ByteIOResult<u32> {
         let mut src: [u8; 3] = [0; 3];
         self.peek_buf(&mut src)?;
         Ok((u32::from(src[0]) << 16) | (u32::from(src[1]) << 8) | u32::from(src[2]))
     }
 
+    /// Reads 32-bit big-endian integer from the stream.
     pub fn read_u32be(&mut self) -> ByteIOResult<u32> {
         read_int!(self, u32, 4, to_be)
     }
 
+    /// Reads 32-bit big-endian integer from the stream without advancing read position.
     pub fn peek_u32be(&mut self) -> ByteIOResult<u32> {
         peek_int!(self, u32, 4, to_be)
     }
 
+    /// Reads 64-bit big-endian integer from the stream.
     pub fn read_u64be(&mut self) -> ByteIOResult<u64> {
         read_int!(self, u64, 8, to_be)
     }
 
+    /// Reads 64-bit big-endian integer from the stream without advancing read position.
     pub fn peek_u64be(&mut self) -> ByteIOResult<u64> {
         peek_int!(self, u64, 8, to_be)
     }
 
+    /// Reads 32-bit big-endian floating point number from the stream.
     pub fn read_f32be(&mut self) -> ByteIOResult<f32> {
         Ok(f32::from_bits(self.read_u32be()?))
     }
 
+    /// Reads 32-bit big-endian floating point number from the stream without advancing read position.
     pub fn peek_f32be(&mut self) -> ByteIOResult<f32> {
         Ok(f32::from_bits(self.peek_u32be()?))
     }
 
+    /// Reads 64-bit big-endian floating point number from the stream.
     pub fn read_f64be(&mut self) -> ByteIOResult<f64> {
         Ok(f64::from_bits(self.read_u64be()?))
     }
 
+    /// Reads 64-bit big-endian floating point number from the stream without advancing read position.
     pub fn peek_f64be(&mut self) -> ByteIOResult<f64> {
         Ok(f64::from_bits(self.peek_u64be()?))
     }
 
+    /// Reads 16-bit little-endian integer from the stream.
     pub fn read_u16le(&mut self) -> ByteIOResult<u16> {
         read_int!(self, u16, 2, to_le)
     }
 
+    /// Reads 16-bit little-endian integer from the stream without advancing read position.
     pub fn peek_u16le(&mut self) -> ByteIOResult<u16> {
         peek_int!(self, u16, 2, to_le)
     }
 
+    /// Reads 24-bit little-endian integer from the stream.
     pub fn read_u24le(&mut self) -> ByteIOResult<u32> {
         let p8 = self.read_byte()?;
         let p16 = self.read_u16le()?;
         Ok((u32::from(p16) << 8) | u32::from(p8))
     }
 
+    /// Reads 24-bit little-endian integer from the stream without advancing read position.
     pub fn peek_u24le(&mut self) -> ByteIOResult<u32> {
         let mut src: [u8; 3] = [0; 3];
         self.peek_buf(&mut src)?;
         Ok(u32::from(src[0]) | (u32::from(src[1]) << 8) | (u32::from(src[2]) << 16))
     }
 
+    /// Reads 32-bit little-endian integer from the stream.
     pub fn read_u32le(&mut self) -> ByteIOResult<u32> {
         read_int!(self, u32, 4, to_le)
     }
 
+    /// Reads 32-bit little-endian integer from the stream without advancing read position.
     pub fn peek_u32le(&mut self) -> ByteIOResult<u32> {
         peek_int!(self, u32, 4, to_le)
     }
 
+    /// Reads 64-bit little-endian integer from the stream.
     pub fn read_u64le(&mut self) -> ByteIOResult<u64> {
         read_int!(self, u64, 8, to_le)
     }
 
+    /// Reads 64-bit little-endian integer from the stream without advancing read position.
     pub fn peek_u64le(&mut self) -> ByteIOResult<u64> {
         peek_int!(self, u64, 8, to_le)
     }
 
+    /// Reads 32-bit little-endian floating point number from the stream.
     pub fn read_f32le(&mut self) -> ByteIOResult<f32> {
         Ok(f32::from_bits(self.read_u32le()?))
     }
 
+    /// Reads 32-bit little-endian floating point number from the stream without advancing read position.
     pub fn peek_f32le(&mut self) -> ByteIOResult<f32> {
         Ok(f32::from_bits(self.peek_u32le()?))
     }
 
+    /// Reads 64-bit little-endian floating point number from the stream.
     pub fn read_f64le(&mut self) -> ByteIOResult<f64> {
         Ok(f64::from_bits(self.read_u64le()?))
     }
 
+    /// Reads 64-bit little-endian floating point number from the stream without advancing read position.
     pub fn peek_f64le(&mut self) -> ByteIOResult<f64> {
         Ok(f64::from_bits(self.peek_u64le()?))
     }
 
+    /// Skips requested number of bytes.
     pub fn read_skip(&mut self, len: usize) -> ByteIOResult<()> {
         if self.io.is_seekable() {
             self.io.seek(SeekFrom::Current(len as i64))?;
@@ -283,22 +415,27 @@ impl<'a> ByteReader<'a> {
         Ok(())
     }
 
+    /// Returns current read position.
     pub fn tell(&mut self) -> u64 {
         self.io.tell()
     }
 
+    /// Seeks to the provided position.
     pub fn seek(&mut self, pos: SeekFrom) -> ByteIOResult<u64> {
         self.io.seek(pos)
     }
 
+    /// Tells whether this is end of stream.
     pub fn is_eof(&self) -> bool {
         self.io.is_eof()
     }
 
+    /// Returns stream size or -1 if it is not known.
     pub fn size(&mut self) -> i64 {
         self.io.size()
     }
 
+    /// Reports number of bytes left in the stream.
     pub fn left(&mut self) -> i64 {
         let size = self.io.size();
         if size == -1 { return -1; }
@@ -307,7 +444,7 @@ impl<'a> ByteReader<'a> {
 }
 
 impl<'a> MemoryReader<'a> {
-
+    /// Constructs a new instance of `MemoryReader`.
     pub fn new_read(buf: &'a [u8]) -> Self {
         MemoryReader { buf, pos: 0 }
     }
@@ -389,6 +526,7 @@ impl<'a> ByteIO for MemoryReader<'a> {
 
 impl<'a> FileReader<'a> {
 
+    /// Constructs a new instance of `FileReader`.
     pub fn new_read(file: &'a mut File) -> Self {
         FileReader { file, eof : false }
     }
@@ -462,96 +600,138 @@ impl<'a> ByteIO for FileReader<'a> {
     }
 }
 
+/// High-level bytestream writer.
+///
+/// User is supposed to create some writer implementing [`ByteIO`] trait e.g. [`MemoryWriter`] and use it to create `ByteWriter` which can be used for writing e.g. various integer types.
+///
+/// # Examples
+///
+/// ````
+/// use nihav_core::io::byteio::{MemoryWriter,ByteWriter};
+/// # use nihav_core::io::byteio::ByteIOResult;
+///
+/// # fn foo() -> ByteIOResult<()> {
+/// let mut memory = [0u8; 4];
+/// let mut mw = MemoryWriter::new_write(&mut memory);
+/// let mut bw = ByteWriter::new(&mut mw);
+/// let val = bw.write_u16be(42)?; // memory should be [ 0, 42, 0, 0 ]
+/// let val = bw.write_u16le(42)?; // memory should be [ 0, 42, 42, 0 ]
+/// # Ok(())
+/// # }
+/// ````
+///
+/// [`ByteIO`]: ./trait.ByteIO.html
+/// [`MemoryWriter`]: ./struct.MemoryWriter.html
 #[allow(dead_code)]
 pub struct ByteWriter<'a> {
     io: &'a mut ByteIO,
 }
 
+/// Bytestream writer to memory.
 pub struct MemoryWriter<'a> {
     buf:      &'a mut [u8],
     pos:      usize,
 }
 
+/// Bytestream writer to file.
 pub struct FileWriter {
     file:     File,
 }
 
 impl<'a> ByteWriter<'a> {
+    /// Constructs a new instance of `ByteWriter`.
     pub fn new(io: &'a mut ByteIO) -> Self { ByteWriter { io } }
 
+    /// Writes byte array to the output.
     pub fn write_buf(&mut self, buf: &[u8])  -> ByteIOResult<()> {
         self.io.write_buf(buf)
     }
 
+    /// Writes single byte to the output.
     pub fn write_byte(&mut self, val: u8) -> ByteIOResult<()> {
         let buf: [u8; 1] = [val];
         self.io.write_buf(&buf)
     }
 
+    /// Writes 16-bit big-endian integer to the output.
     pub fn write_u16be(&mut self, val: u16) -> ByteIOResult<()> {
         let buf: [u8; 2] = [((val >> 8) & 0xFF) as u8, (val & 0xFF) as u8];
         self.io.write_buf(&buf)
     }
 
+    /// Writes 16-bit little-endian integer to the output.
     pub fn write_u16le(&mut self, val: u16) -> ByteIOResult<()> {
         let buf: [u8; 2] = [(val & 0xFF) as u8, ((val >> 8) & 0xFF) as u8];
         self.io.write_buf(&buf)
     }
 
+    /// Writes 24-bit big-endian integer to the output.
     pub fn write_u24be(&mut self, val: u32) -> ByteIOResult<()> {
         let buf: [u8; 3] = [((val >> 16) & 0xFF) as u8, ((val >> 8) & 0xFF) as u8, (val & 0xFF) as u8];
         self.write_buf(&buf)
     }
 
+    /// Writes 24-bit little-endian integer to the output.
     pub fn write_u24le(&mut self, val: u32) -> ByteIOResult<()> {
         let buf: [u8; 3] = [(val & 0xFF) as u8, ((val >> 8) & 0xFF) as u8, ((val >> 16) & 0xFF) as u8];
         self.write_buf(&buf)
     }
 
+    /// Writes 32-bit big-endian integer to the output.
     pub fn write_u32be(&mut self, val: u32) -> ByteIOResult<()> {
         self.write_u16be(((val >> 16) & 0xFFFF) as u16)?;
         self.write_u16be((val & 0xFFFF) as u16)
     }
 
+    /// Writes 32-bit little-endian integer to the output.
     pub fn write_u32le(&mut self, val: u32) -> ByteIOResult<()> {
         self.write_u16le((val & 0xFFFF) as u16)?;
         self.write_u16le(((val >> 16) & 0xFFFF) as u16)
     }
 
+    /// Writes 64-bit big-endian integer to the output.
     pub fn write_u64be(&mut self, val: u64) -> ByteIOResult<()> {
         self.write_u32be((val >> 32) as u32)?;
         self.write_u32be(val as u32)
     }
 
+    /// Writes 64-bit little-endian integer to the output.
     pub fn write_u64le(&mut self, val: u64) -> ByteIOResult<()> {
         self.write_u32le(val as u32)?;
         self.write_u32le((val >> 32) as u32)
     }
 
+    /// Writes 32-bit big-endian floating point number to the output.
     pub fn write_f32be(&mut self, val: f32) -> ByteIOResult<()> {
         self.write_u32be(val.to_bits())
     }
 
+    /// Writes 32-bit little-endian floating point number to the output.
     pub fn write_f32le(&mut self, val: f32) -> ByteIOResult<()> {
         self.write_u32le(val.to_bits())
     }
 
+    /// Writes 64-bit big-endian floating point number to the output.
     pub fn write_f64be(&mut self, val: f64) -> ByteIOResult<()> {
         self.write_u64be(val.to_bits())
     }
 
+    /// Writes 64-bit little-endian floating point number to the output.
     pub fn write_f64le(&mut self, val: f64) -> ByteIOResult<()> {
         self.write_u64le(val.to_bits())
     }
 
+    /// Reports the current write position.
     pub fn tell(&mut self) -> u64 {
         self.io.tell()
     }
 
+    /// Seeks to the requested position.
     pub fn seek(&mut self, pos: SeekFrom) -> ByteIOResult<u64> {
         self.io.seek(pos)
     }
 
+    /// Reports the amount of bytes the writer can still write (-1 if unknown).
     pub fn size_left(&mut self) -> i64 {
         let sz = self.io.size();
         if sz == -1 { return -1; }
@@ -561,6 +741,7 @@ impl<'a> ByteWriter<'a> {
 
 impl<'a> MemoryWriter<'a> {
 
+    /// Constructs a new instance of `MemoryWriter`.
     pub fn new_write(buf: &'a mut [u8]) -> Self {
         MemoryWriter { buf, pos: 0 }
     }
@@ -637,6 +818,7 @@ impl<'a> ByteIO for MemoryWriter<'a> {
 }
 
 impl FileWriter {
+    /// Constructs a new instance of `FileWriter`.
     pub fn new_write(file: File) -> Self {
         FileWriter { file }
     }