Struct Parser

pub struct Parser<R: Read> { /* private fields */ }

Parser for fastq files.

Implementations

impl<'a, R: 'a + Read> Parser<R>

pub fn new(reader: R) -> Parser<R>

Create a new fastq parser.

pub fn ref_iter(self) -> RecordRefIter<R>

Get a RecordRefIter for this parser. Should only be used in custom iteration scenarios.

pub fn each<F>(self, func: F) -> Result<bool>

where F: FnMut(RefRecord<'_>) -> bool,

Apply a function to each fastq record in an file.

Stop the parser if the closure returns false. Return true, if the parser reached the end of the file.

impl<R: Read> Parser<R>

pub fn parallel_each<O, S, F>(self, n_threads: usize, func: F) -> Result<S>

where S: FromIterator<O>, O: Send + 'static, F: Send + Sync + 'static + Fn(Box<dyn Iterator<Item = RecordSet>>) -> O,

Apply a function to each record, but distribute the work on a number of threads.

Parameters

• n_threads: The number of worker threads to start.
• func: A closure that is executed on each new thread and takes an Iterator of RecordSets as argument.

This function parses the fastq file and passes record sets to the worker threads.

It terminates if one of the following happes:

• The parser exhauts the fastq file. This function waits for all worker threads to terminate (their iterator will not yield new values after they finish buffered ones). It collects their return values and returns them.
• The parser finds a syntax error. The iterators in the worker threads stop yielding new record sets. (The worker threads are not notified of the error). The function waits for them to terminate, discards their return values and returns an IO error with error kind std::error::ErrorKind::InvalidData.
• The underlying Reader yields an io error other an Interrupted. The behaviour is the same as the previous, but it returns the error value of the inner reader.
• A worker thread terminates before its iterator is exhausted. The parser stops, waits for all workers to exit and returns the collected return values. If the caller wants to know whether we parsed the whole file, this information must be encoded in the return values of the worker threads.
• A worker panics. The parser stops and this function panics.

Panics

Panics, if one of the worker threads panics.

Examples

Parse a fastq file and print a sequence starting with ATTAATTA if the file contains one (it might not be the first one):

use std::io::{Result, ErrorKind, Cursor};
use fastq::{Parser, Record};

let reader = Cursor::new(b"@hi\nATTAATTAATTA\n+\n++++++++++++\n");
let parser = Parser::new(reader);
let result: Result<Vec<_>> = parser.parallel_each(4, |record_sets| {
    for record_set in record_sets {
        for record in record_set.iter() {
            if record.seq().starts_with(b"ATTAATTA") {
                // Early return stops the parser
                return Some(record.seq().to_vec());
            }
        }
    };
    None
});
match result {
    Ok(res) => {
        match res.iter().filter(|x| x.is_some()).next() {
            None => { assert!(false) } // nothing found
            Some(seq) => {
                // Yay! we found it.
                assert_eq!(seq.as_ref().unwrap(), b"ATTAATTAATTA")
            }
        }
    },
    Err(e) => {
        if e.kind() == ErrorKind::InvalidData {
            assert!(false);  // this is not a valid fastq file.
        } else {
            assert!(false);  // some other io error.
        }
    }
}