Struct noodles_sam::io::reader::Reader

pub struct Reader<R> { /* private fields */ }

A SAM reader.

The SAM format is comprised of two parts: 1) a header and 2) a list of records.

Each header line is prefixed with an @ (at sign). The header is optional and may be empty.

SAM records are line-based and follow directly after the header or the start of the file until EOF.

Examples

use noodles_sam as sam;

let mut reader = sam::io::reader::Builder::default().build_from_path("sample.sam")?;
let header = reader.read_header()?;

for result in reader.records() {
    let record = result?;
    // ...
}

Implementations

impl<R> Reader<R>

pub fn get_ref(&self) -> &R

Returns a reference to the underlying reader.

Examples

use noodles_sam as sam;
let data = [];
let reader = sam::io::Reader::new(&data[..]);
assert!(reader.get_ref().is_empty());

pub fn get_mut(&mut self) -> &mut R

Returns a mutable reference to the underlying reader.

Examples

use noodles_sam as sam;
let data = [];
let mut reader = sam::io::Reader::new(&data[..]);
assert!(reader.get_mut().is_empty());

pub fn into_inner(self) -> R

Returns the underlying reader.

Examples

use noodles_sam as sam;
let data = [];
let reader = sam::io::Reader::new(&data[..]);
assert!(reader.into_inner().is_empty());

impl<R> Reader<R>

where R: BufRead,

pub fn new(inner: R) -> Self

Creates a SAM reader.

Examples

use noodles_sam as sam;

let data = b"@HD\tVN:1.6
*\t4\t*\t0\t255\t*\t*\t0\t0\t*\t*
";

let reader = sam::io::Reader::new(&data[..]);

pub fn read_header(&mut self) -> Result<Header>

Reads the SAM header.

The position of the stream is expected to be at the start.

The SAM header is optional, and if it is missing, an empty Header is returned.

Examples

use noodles_sam as sam;

let data = b"@HD\tVN:1.6
*\t4\t*\t0\t255\t*\t*\t0\t0\t*\t*
";

let mut reader = sam::io::Reader::new(&data[..]);
let actual = reader.read_header()?;

let expected = sam::Header::builder()
    .set_header(Default::default())
    .build();

assert_eq!(actual, expected);

pub fn read_record_buf( &mut self, header: &Header, record: &mut RecordBuf ) -> Result<usize>

Reads a record into an alignment record buffer.

This reads a line from the underlying stream until a newline is reached and parses that line into the given record.

The stream is expected to be directly after the header or at the start of another record.

It is more ergonomic to read records using an iterator (see Self::records and Self::query), but using this method directly allows reuse of a RecordBuf.

If successful, the number of bytes read is returned. If the number of bytes read is 0, the stream reached EOF.

Examples

use noodles_sam::{self as sam, alignment::RecordBuf};

let data = b"@HD\tVN:1.6
*\t4\t*\t0\t255\t*\t*\t0\t0\t*\t*
";

let mut reader = sam::io::Reader::new(&data[..]);
let header = reader.read_header()?;

let mut record = RecordBuf::default();
reader.read_record_buf(&header, &mut record)?;

assert_eq!(record, RecordBuf::default());

pub fn record_bufs<'a>(&'a mut self, header: &'a Header) -> RecordBufs<'a, R>

Returns an iterator over alignment record buffers starting from the current stream position.

The stream is expected to be directly after the header or at the start of another record.

Examples

use noodles_sam as sam;

let data = b"@HD\tVN:1.6
*\t4\t*\t0\t255\t*\t*\t0\t0\t*\t*
";

let mut reader = sam::io::Reader::new(&data[..]);
let header = reader.read_header()?;

let mut records = reader.record_bufs(&header);
assert!(records.next().is_some());
assert!(records.next().is_none());

pub fn read_record(&mut self, record: &mut Record) -> Result<usize>

Reads a record.

This reads SAM fields from the underlying stream into the given record’s buffer until a newline is reached. No fields are decoded, meaning the record is not necessarily valid. However, the structure of the buffer is guaranteed to be record-like.

The stream is expected to be directly after the header or at the start of another record.

If successful, the number of bytes read is returned. If the number of bytes read is 0, the stream reached EOF.

Examples

use noodles_sam as sam;

let data = b"@HD\tVN:1.6
*\t4\t*\t0\t255\t*\t*\t0\t0\t*\t*
";

let mut reader = sam::io::Reader::new(&data[..]);
reader.read_header()?;

let mut record = sam::Record::default();
reader.read_record(&mut record)?;

pub fn records(&mut self) -> impl Iterator<Item = Result<Record>> + '_

Returns an iterator over records.

The stream is expected to be directly after the reference sequences or at the start of another record.

Examples

use noodles_sam as sam;

let data = b"@HD\tVN:1.6
*\t4\t*\t0\t255\t*\t*\t0\t0\t*\t*
";

let mut reader = sam::io::Reader::new(&data[..]);
reader.read_header()?;

for result in reader.records() {
    let record = result?;
    // ...
}

impl<R> Reader<R>

where R: BufRead + Seek,

pub fn query<'a, I>( &'a mut self, header: &'a Header, index: &I, region: &Region ) -> Result<impl Iterator<Item = Result<Record>> + 'a>

where I: BinningIndex,

Returns an iterator over records that intersect the given region.

To query for unmapped records, use Self::query_unmapped.

Examples

use noodles_bgzf as bgzf;
use noodles_csi as csi;
use noodles_sam as sam;

let mut reader = File::open("sample.sam.gz")
    .map(bgzf::Reader::new)
    .map(sam::io::Reader::new)?;

let header = reader.read_header()?;

let index = csi::read("sample.sam.gz.csi")?;
let region = "sq0:8-13".parse()?;
let query = reader.query(&header, &index, &region)?;

for result in query {
    let record = result?;
    // ...
}

pub fn query_unmapped<I>( &mut self, index: &I ) -> Result<impl Iterator<Item = Result<Record>> + '_>

where I: BinningIndex,

Returns an iterator of unmapped records after querying for the unmapped region.

use noodles_bgzf as bgzf;
use noodles_csi as csi;
use noodles_sam as sam;

let mut reader = File::open("sample.sam.gz")
    .map(bgzf::Reader::new)
    .map(sam::io::Reader::new)?;

reader.read_header()?;

let index = csi::read("sample.sam.gz.csi")?;
let query = reader.query_unmapped(&index)?;

for result in query {
    let record = result?;
    // ...
}

Trait Implementations

impl<R: Debug> Debug for Reader<R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R> From<R> for Reader<R>

where R: BufRead,

fn from(inner: R) -> Self

Converts to this type from the input type.

impl<R> Read<R> for Reader<R>

where R: BufRead,

fn read_alignment_header(&mut self) -> Result<Header>

Reads a SAM header.

fn alignment_records<'a>( &'a mut self, header: &'a Header ) -> Box<dyn Iterator<Item = Result<Box<dyn Record>>> + 'a>

Returns an iterator over records.