Merge pull request #36 from rust-bio/improve-cigar-api

Improve CIGAR API.

Author: johanneskoester

src/bam/mod.rs

@@ -580,20 +580,14 @@ pub struct HeaderView {
 
 
 impl HeaderView {
+    /// Create a new HeaderView from the underlying Htslib type, and own it.
     pub fn new(inner: *mut htslib::bam_hdr_t) -> Self {
         HeaderView {
             inner: inner,
             owned: true,
         }
     }
 
-    fn borrow(inner: *mut htslib::bam_hdr_t) -> Self {
-        HeaderView {
-            inner: inner,
-            owned: false,
-        }
-    }
-
     #[inline]
     pub fn inner(&self) -> htslib::bam_hdr_t {
         unsafe { (*self.inner) }
@@ -652,12 +646,12 @@ impl Drop for HeaderView {
 mod tests {
     extern crate tempdir;
     use super::*;
-    use super::record::{Cigar,Aux};
+    use super::record::{Cigar, CigarString, Aux};
     use super::header::HeaderRecord;
     use std::str;
     use std::path::Path;
 
-    fn gold() -> ([&'static [u8]; 6], [u16; 6], [&'static [u8]; 6], [&'static [u8]; 6], [[Cigar; 3]; 6]) {
+    fn gold() -> ([&'static [u8]; 6], [u16; 6], [&'static [u8]; 6], [&'static [u8]; 6], [CigarString; 6]) {
         let names = [&b"I"[..], &b"II.14978392"[..], &b"III"[..], &b"IV"[..], &b"V"[..], &b"VI"[..]];
         let flags = [16u16, 16u16, 16u16, 16u16, 16u16, 2048u16];
         let seqs = [
@@ -677,12 +671,12 @@ mod tests {
             &b"#############################@B?8B?BA@@DDBCDDCBC@CDCDCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC"[..],
         ];
         let cigars = [
-            [Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)],
-            [Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)],
-            [Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)],
-            [Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)],
-            [Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)],
-            [Cigar::Match(27), Cigar::Del(100000), Cigar::Match(73)],
+            CigarString(vec![Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)]),
+            CigarString(vec![Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)]),
+            CigarString(vec![Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)]),
+            CigarString(vec![Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)]),
+            CigarString(vec![Cigar::Match(27), Cigar::Del(1), Cigar::Match(73)]),
+            CigarString(vec![Cigar::Match(27), Cigar::Del(100000), Cigar::Match(73)]),
         ];
         (names, flags, seqs, quals, cigars)
     }

src/bam/record.rs

@@ -7,6 +7,7 @@
 use std::slice;
 use std::ffi;
 use std::ops;
+use std::fmt;
 
 use itertools::Itertools;
 
@@ -227,10 +228,10 @@ impl Record {
         unsafe { slice::from_raw_parts(self.data()[self.qname_len()..].as_ptr() as *const u32, self.cigar_len()) }
     }
 
-    /// Get cigar sequence. Complexity: O(k) with k being the length of the cigar string.
-    pub fn cigar(&self) -> Vec<Cigar> {
+    /// Get cigar string. Complexity: O(k) with k being the length of the cigar string.
+    pub fn cigar(&self) -> CigarString {
         let raw = self.raw_cigar();
-        raw.iter().map(|&c| {
+        CigarString(raw.iter().map(|&c| {
             let len = c >> 4;
             match c & 0b1111 {
                 0 => Cigar::Match(len),
@@ -245,7 +246,7 @@ impl Record {
                 9 => Cigar::Back(len),
                 _ => panic!("Unexpected cigar type"),
             }
-        }).collect()
+        }).collect())
     }
 
     fn seq_len(&self) -> usize {
@@ -453,7 +454,7 @@ unsafe impl<'a> Send for Seq<'a> {}
 unsafe impl<'a> Sync for Seq<'a> {}
 
 
-#[derive(PartialEq, Debug)]
+#[derive(PartialEq, Eq, Debug, Clone)]
 pub enum Cigar {
     Match(u32),  // M
     Ins(u32),  // I
@@ -483,8 +484,115 @@ impl Cigar {
             Cigar::Back(len)     => len << 4 | 9,
         }
     }
+
+    /// Return the length the CIGAR.
+    pub fn len(&self) -> u32 {
+        match *self {
+            Cigar::Match(len)    => len,
+            Cigar::Ins(len)      => len,
+            Cigar::Del(len)      => len,
+            Cigar::RefSkip(len)  => len,
+            Cigar::SoftClip(len) => len,
+            Cigar::HardClip(len) => len,
+            Cigar::Pad(len)      => len,
+            Cigar::Equal(len)    => len,
+            Cigar::Diff(len)     => len,
+            Cigar::Back(len)     => len
+        }
+    }
+
+    /// Return the character representing the CIGAR.
+    pub fn char(&self) -> char {
+        match *self {
+            Cigar::Match(_)    => 'M',
+            Cigar::Ins(_)      => 'I',
+            Cigar::Del(_)      => 'D',
+            Cigar::RefSkip(_)  => 'N',
+            Cigar::SoftClip(_) => 'S',
+            Cigar::HardClip(_) => 'H',
+            Cigar::Pad(_)      => 'P',
+            Cigar::Equal(_)    => '=',
+            Cigar::Diff(_)     => 'X',
+            Cigar::Back(_)     => 'B'
+        }
+    }
+}
+
+
+impl fmt::Display for Cigar {
+    fn fmt(&self, fmt: &mut fmt::Formatter) -> Result<(), fmt::Error> {
+        fmt.write_fmt(format_args!("{}{}", self.len(), self.char()))
+    }
 }
 
 
 unsafe impl Send for Cigar {}
 unsafe impl Sync for Cigar {}
+
+
+custom_derive! {
+    /// A CIGAR string. This type wraps around a `Vec<Cigar>`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use rust_htslib::bam::record::{Cigar, CigarString};
+    ///
+    /// let cigar = CigarString(vec![Cigar::Match(100), Cigar::SoftClip(10)]);
+    ///
+    /// // access by index
+    /// assert_eq!(cigar[0], Cigar::Match(100));
+    /// // format into classical string representation
+    /// assert_eq!(format!("{}", cigar), "100M10S");
+    /// // iterate
+    /// for op in &cigar {
+    ///    println!("{}", op);
+    /// }
+    /// ```
+    #[derive(NewtypeDeref,
+             NewtypeIndex(usize),
+             NewtypeIndexMut(usize),
+             PartialEq,
+             Eq,
+             NewtypeDebug,
+             Clone
+    )]
+    pub struct CigarString(pub Vec<Cigar>);
+}
+
+
+impl<'a> IntoIterator for &'a CigarString {
+    type Item = &'a Cigar;
+    type IntoIter = ::std::slice::Iter<'a, Cigar>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        (&(self.0)).into_iter()
+    }
+}
+
+
+impl fmt::Display for CigarString {
+    fn fmt(&self, fmt: &mut fmt::Formatter) -> Result<(), fmt::Error> {
+        for op in self {
+            fmt.write_fmt(format_args!("{}{}", op.len(), op.char()))?;
+        }
+        Ok(())
+    }
+}
+
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_cigar_string() {
+        let cigar = CigarString(vec![Cigar::Match(100), Cigar::SoftClip(10)]);
+
+        assert_eq!(cigar[0], Cigar::Match(100));
+        assert_eq!(format!("{}", cigar), "100M10S");
+        for op in &cigar {
+            println!("{}", op);
+        }
+    }
+}