Struct seq_io::fasta::Reader

pub struct Reader<R, P = StdPolicy, S = LineStore> where
    R: Read,
    P: BufPolicy,
    S: PositionStore,  { /* fields omitted */ }

FASTA parser

Implementations

impl<R> Reader<R> where
    R: Read, 

pub fn new(reader: R) -> Self

Creates a new reader with the default buffer size of 64 KiB

Example:

use seq_io::prelude::*;
use seq_io::fasta::Reader;
let seq = b"
>id
SEQUENCE
";

let mut reader = Reader::new(&seq[..]);
let record = reader.next().unwrap().unwrap();
assert_eq!(record.id(), Ok("id"))

pub fn with_capacity(reader: R, capacity: usize) -> Self

Creates a new reader with a given buffer capacity. The minimum allowed capacity is 3.

pub fn from_buf_reader(
    rdr: BufReader<R>,
    byte_offset: usize,
    line_idx: u64
) -> Self

Creates a new Reader from an already instantiated BufReader.

impl Reader<File>

pub fn from_path<P: AsRef<Path>>(seq_path: P) -> Result<Reader<File>>

Creates a reader from a file path.

Example:

use seq_io::fasta::Reader;

let seq_path = "seqs.fasta";
let mut reader = Reader::from_path(seq_path).expect("File could not be opened.");

// (... do something with the reader)

impl<R, P, S> Reader<R, P, S> where
    R: Read,
    P: BufPolicy,
    S: PositionStore, 

pub fn set_store<T: PositionStore>(self) -> Reader<R, P, T>

Creates a new reader with a given PositionStore as defined in the type argument of the method. The method consumes the reader and returns a new Reader instance.

Example:

This example makes the reader use seq_io::fastx::LineStore instead of the default one.

use seq_io::prelude::*;
use seq_io::fasta::Reader;
use seq_io::fastx::LineStore;

let seq_path = "seqs.fasta";
let mut reader = Reader::from_path(seq_path)?.set_store::<LineStore>();
// or:
let mut reader: Reader<_, _, LineStore> = Reader::from_path(seq_path)?.set_store();
// ...

pub fn set_policy<T: BufPolicy>(self, buf_policy: T) -> Reader<R, T, S>

Applies a BufPolicy to the current reader. The method consumes the reader and returns a new Reader instance.

pub fn policy(&self) -> &P

Returns a reference to the underlying BufPolicy of the reader

pub fn next(&mut self) -> Option<Result<RefRecord<'_, S>>>

Returns a reader with the given buffer policy applied Searches the next record and returns a RefRecord that borrows its data from the underlying buffer of this reader.

Example:

use seq_io::prelude::*;
use seq_io::fasta::Reader;

let seq_path = "seqs.fasta";
let mut reader = Reader::from_path(seq_path).unwrap();

while let Some(record) = reader.next() {
    let record = record.unwrap();
    println!("{}", record.id().unwrap());
}

pub fn next_unchecked_len(&mut self) -> Option<Result<RefRecord<'_, S>>>

Searches the next FASTQ record and returns a RefRecord exactly like next(), but this function does not compare the lengths of the sequence and quality scores. The check can (and should!) be done later using check_lengths().

Note: not checking lengths this with multi-line FASTQ is a very bad idea, since the parser uses the sequence length as orientation when parsing the quality scores; quality lengths will never be smaller, but they can be larger than sequence lengths, and not doing a length check may lead to confusing errors later, or in the worst case "swallowing" of a record.

pub fn read_record_set(&mut self, record_set: &mut RecordSet<S>) -> Result<bool>

Updates a RecordSet with new data. The contents of the internal buffer are just copied over to the record set and the positions of all records are found. Old data will be erased. Returns None if the input reached its end. Iterating over a record set will yield RefRecord instances.

Example:

use seq_io::prelude::*;
use seq_io::fasta::{Reader, RecordSet};

let seq = b">id1
ACGT
>id2
TGCA
";
// Read records the normal way (for illustration, actually
// we could also use the Reader::records iterator here)
let mut reader = Reader::new(&seq[..]);
let mut records = vec![];
while let Some(res) = reader.next() {
    records.push(res.unwrap().to_owned_record());
}

// Use read_record_set
let mut reader = Reader::new(&seq[..]);
let mut record_set = RecordSet::default(); // initialize once, reuse later
let mut rset_records = vec![];
while reader.read_record_set(&mut record_set).unwrap() {
    for record in &record_set {
        rset_records.push(record.to_owned_record());
    }
}

// The two methods should give the same result
assert_eq!(records, rset_records);

pub fn records(&mut self) -> RecordsIter<'_, R, P, S>

Returns a borrowed iterator over all FASTA records. The records are owned (OwnedRecord), this is therefore slower than using Reader::next().

Example

use seq_io::prelude::*;
use seq_io::fasta::{Reader, OwnedRecord};

let seq = b">id1
ACGT
>id2
TGCA
";

let mut reader = Reader::new(&seq[..]);

let records: Result<Vec<_>, _> = reader
    .records()
    .collect();

assert_eq!(records?,
vec![
OwnedRecord {head: b"id1".to_vec(), seq: b"ACGT".to_vec()},
OwnedRecord {head: b"id2".to_vec(), seq: b"TGCA".to_vec()}
]);

pub fn into_records(self) -> RecordsIntoIter<R, P, S>

Returns an iterator over all records like Reader::records(), but with the difference that it owns the underlying reader.

pub fn position(&self) -> Position

Returns the position of the current record (found by the previous call to next()). Useful with seek().

Example

use seq_io::prelude::*;
use seq_io::fasta::Reader;
use seq_io::Position;

let seq = b"
>id
SEQUENCE
";

let mut reader = Reader::new(&seq[..]);

// find first record
reader.next().unwrap();

assert_eq!(
    &reader.position(),
    Position::new().set_line(1).set_byte(1).set_record(0)
);

impl<R, P, S> Reader<R, P, S> where
    R: Read + Seek,
    P: BufPolicy,
    S: PositionStore, 

pub fn seek(&mut self, pos: &Position) -> Result<()>

Seeks to a specified position. Keeps the underyling buffer if the seek position is found within it, otherwise it has to be discarded. If an error was returned before, seeking to that position will return the same error. The same is not always true with None. If there is no newline character at the end of the file, the last record will be returned instead of None.

Example

use seq_io::Position;
use seq_io::prelude::*;
use seq_io::fasta::Reader;
use std::io::Cursor;

let seq = b">id1
ACGT
>id2
TGCA
";

let mut cursor = Cursor::new(&seq[..]);
let mut reader = Reader::new(cursor);

// Read the first record and get its position.
let record0 = reader.next().unwrap().unwrap().to_owned_record();
let pos0 = reader.position();

// Read the second record.
reader.next().unwrap().unwrap();

// Now seek to position of first record.
reader.seek(&pos0);

// The two records should be the same.
let record1 = reader.next().unwrap().unwrap().to_owned_record();
assert_eq!(record0, record1);

Trait Implementations

impl<R, P, S> FastxReader<R, P, S> for Reader<R, P, S> where
    R: Read,
    P: BufPolicy,
    S: PositionStore, 

fn next_fastx(&mut self) -> Option<Result<RefRecord<'_, S>>>

Returns the next fastx::RefRecord, if any.

fn read_record_set_fastx(
    &mut self,
    record_set: &mut RecordSet<S>
) -> Result<bool>

Updates a fastx::RecordSet with new data.

fn format(&self) -> Option<SeqFormat>

Returns the sequence format (SeqFormat::FASTA or SeqFormat::FASTQ) if known. For FASTA / FASTQ readers, the format is known in the beginning already, for FASTX readers, a first record has to be returned successfully (without error) before the format can be known. If not able to call this method in the middle of a parsing process because of borrowing issues, there is also has_quality() method, which can be called on individual sequence records and essentially gives the same information.

fn fastx_records(&mut self) -> RecordsIter<'_, R, P, S>

Returns a borrowed iterator over all records.

fn into_fastx_records<'a>(self) -> RecordsIntoIter<'a, R, P, S> where
    R: 'a,
    P: 'a,
    S: 'a, 

Returns an iterator over all records like FastxReader::records(), but with the difference that it owns the underlying reader.

fn position_fastx(&self) -> Position

Returns the position of the current record (found by the previous call to next_fastx()). Equivalent to the position() method of individual readers. Useful with seek_fastx().

impl<R, P, S> FastxSeekReader<R, P, S> for Reader<R, P, S> where
    R: Read + Seek,
    P: BufPolicy,
    S: PositionStore, 

fn seek_fastx(&mut self, pos: &Position) -> Result<()>

Seeks to a specified position. Equivalent to the seek() method of the individual readers.

impl<R, P, S> RecordSetReader for Reader<R, P, S> where
    R: Read,
    P: BufPolicy + Send,
    S: PositionStore, 

type RecordSet = RecordSet<S>

type Err = Error

fn fill_data(&mut self, rset: &mut RecordSet<S>) -> Result<bool, Error>