2024/10/27-17:13:24 (Linux VDI0092.zit.bam.de x86_64)

src/granges_table.rs

@@ -43,6 +43,19 @@ pub struct OptionPrintStrand(pub bool);
 
 impl GRanges {
 
+    /// Reads a table from a buffered reader and populates the `GRanges` structure.
+    ///
+    /// This method reads from the provided `BufRead` instance, interpreting the first line
+    /// as a header and subsequent lines as data. It utilizes `MetaTableReader` to read metadata
+    /// and `GRangesTableReader` for genomic ranges.
+    ///
+    /// # Arguments
+    /// - `buf_reader`: A mutable buffered reader to read from.
+    /// - `names`: An array of expected column names.
+    /// - `types`: An array of expected column types.
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if any issues arise during reading.
     pub fn bufread_table<R: BufRead>(&mut self, mut buf_reader: R, names: &[&str], types: &[&str]) -> io::Result<()> {
         let mut mreader = MetaTableReader   ::new(names, types);
         let mut greader = GRangesTableReader::new();
@@ -76,6 +89,17 @@ impl GRanges {
         Ok(())
     }
 
+    /// Writes the `GRanges` table to the specified writer.
+    ///
+    /// This method formats and writes the contents of the `GRanges` structure to the provided writer,
+    /// optionally printing scientific notation or strand information based on the given arguments.
+    ///
+    /// # Arguments
+    /// - `writer`: A mutable reference to a writer where the table will be output.
+    /// - `args`: An array of dynamic arguments that may include options for scientific notation and strand.
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if writing fails.
     pub fn write_table<W: Write>(&self, writer: &mut W, args: &[&dyn Any]) -> io::Result<()> {
 
         let mut use_scientific = false;
@@ -110,6 +134,18 @@ impl GRanges {
 
 impl GRanges {
 
+    /// Reads a table from a reader and populates the `GRanges` structure.
+    ///
+    /// This method wraps the buffered reading functionality, creating a `BufReader` and
+    /// invoking `bufread_table` to read from it.
+    ///
+    /// # Arguments
+    /// - `reader`: A reader to read from.
+    /// - `names`: An array of expected column names.
+    /// - `types`: An array of expected column types.
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if reading fails.
     pub fn read_table<R: Read>(&mut self, reader: R, names: &[&str], types: &[&str]) -> io::Result<()> {
 
         let buf_reader = BufReader::new(reader);
@@ -124,6 +160,19 @@ impl GRanges {
 
 impl GRanges {
 
+    /// Imports a table from a file and populates the `GRanges` structure.
+    ///
+    /// This method opens the specified file, optionally decompressing it if required,
+    /// and reads the data into the `GRanges` instance using `bufread_table`.
+    ///
+    /// # Arguments
+    /// - `filename`: The path to the file to import.
+    /// - `names`: An array of expected column names.
+    /// - `types`: An array of expected column types.
+    /// - `compress`: A boolean indicating whether the file is compressed.
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if reading fails.
     pub fn import_table(&mut self, filename: &str, names: &[&str], types: &[&str], compress: bool) -> io::Result<()> {
         let file = File::open(filename)?;
         let mut reader: Box<dyn BufRead> = if compress {
@@ -137,6 +186,18 @@ impl GRanges {
         Ok(())
     }
 
+    /// Exports the `GRanges` table to a file.
+    ///
+    /// This method creates a file at the specified path, optionally compressing the output,
+    /// and writes the `GRanges` data to it using `write_table`.
+    ///
+    /// # Arguments
+    /// - `filename`: The path to the file to export to.
+    /// - `compress`: A boolean indicating whether to compress the output file.
+    /// - `args`: An array of dynamic arguments that may include options for writing.
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if writing fails.
     pub fn export_table(&self, filename: &str, compress: bool, args: &[&dyn Any]) -> io::Result<()> {
         let file = File::create(filename)?;
         let mut writer: Box<dyn Write> = if compress {

src/granges_table_reader.rs

@@ -18,14 +18,19 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
- use std::io;
- use std::str::FromStr;
+use std::io;
+use std::str::FromStr;
 
- use crate::range::Range;
- use crate::granges::GRanges;
+use crate::range::Range;
+use crate::granges::GRanges;
 
- /* -------------------------------------------------------------------------- */
+/* -------------------------------------------------------------------------- */
 
+/// A reader for processing `GRanges` data from a tabular format.
+///
+/// This struct reads data from a table format, interpreting it as genomic ranges. It
+/// identifies the relevant columns in the header and reads subsequent lines to populate
+/// the associated `GRanges` structure.
 pub struct GRangesTableReader {
     col_seqname: i32,
     col_from   : i32,
@@ -38,6 +43,13 @@ pub struct GRangesTableReader {
 
 impl GRangesTableReader {
 
+    /// Creates a new instance of `GRangesTableReader`.
+    ///
+    /// This constructor initializes the column indices to -1, indicating that they have not yet been assigned,
+    /// and creates a default `GRanges` instance to store the read data.
+    ///
+    /// # Returns
+    /// A new instance of `GRangesTableReader`.
     pub fn new() -> Self {
         GRangesTableReader{
             col_seqname: -1,
@@ -48,6 +60,17 @@ impl GRangesTableReader {
         }
     }
 
+    /// Reads the header line of the input data to determine column positions.
+    ///
+    /// This method analyzes the given line to set the indices of the columns corresponding
+    /// to the sequence names, start, end, and strand. It raises an error if any of the required
+    /// columns are missing.
+    ///
+    /// # Arguments
+    /// - `line`: A reference to a string containing the header line.
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if a required column is missing.
     pub fn read_header(&mut self, line: &String) -> io::Result<()> {
 
         let fields: Vec<&str> = line.trim().split_whitespace().collect();
@@ -75,6 +98,18 @@ impl GRangesTableReader {
         Ok(())
     }
 
+    /// Reads a line of data and populates the `GRanges` instance.
+    ///
+    /// This method processes the given line, extracts the relevant fields based on the previously
+    /// determined column indices, and adds the data to the `GRanges` instance. It raises an error if the
+    /// data is invalid or if parsing fails.
+    ///
+    /// # Arguments
+    /// - `line`: A reference to a string containing the line to read.
+    /// - `i`: The index of the line being processed (used for error reporting).
+    ///
+    /// # Returns
+    /// An `io::Result<()>`, which will be `Ok(())` if the operation succeeds, or an error if parsing fails.
     pub fn read_line(&mut self, line: &String, i: i32) -> io::Result<()> {
 
         let fields: Vec<&str> = line.trim().split_whitespace().collect();
@@ -101,10 +136,17 @@ impl GRangesTableReader {
         Ok(())
     }
 
+    /// Copies the data from the internal `GRanges` instance to another `GRanges` instance.
+    ///
+    /// This method takes a mutable reference to a `GRanges` instance and populates it with the
+    /// sequence names, ranges, and strand information from the reader's internal `GRanges`.
+    ///
+    /// # Arguments
+    /// - `granges`: A mutable reference to a `GRanges` instance to which the data will be copied.
     pub fn push(&mut self, granges: &mut GRanges) {
         granges.seqnames = self.granges.seqnames.clone();
         granges.ranges   = self.granges.ranges  .clone();
         granges.strand   = self.granges.strand  .clone();
     }
 
-}
+}

src/granges_table_writer.rs

@@ -28,7 +28,7 @@ use crate::granges::GRanges;
 
 /// A writer for formatting and outputting a `GRanges` instance as a table.
 ///
-/// This struct holds a reference to a `GRanges` instance and is responsible for determining the width of 
+/// This struct holds a reference to a `GRanges` instance and is responsible for determining the width of
 /// columns based on the content of the `GRanges` and for writing the formatted output to a specified writer.
 pub struct GRangesTableWriter<'a> {
     granges       : &'a GRanges,
@@ -61,7 +61,7 @@ impl<'a> GRangesTableWriter<'a> {
 
     /// Determines the maximum widths of columns based on the data in the `GRanges` instance.
     ///
-    /// This method updates the `widths` field by calculating the lengths of each column's contents 
+    /// This method updates the `widths` field by calculating the lengths of each column's contents
     /// for all rows. It is called to ensure proper alignment when writing the table.
     ///
     /// # Returns