Crate dino_seq 

Low-allocation FASTQ and FASTA parsing.

Dino Seq is a library core for downstream scientific tools that need low-allocation streams of ordinary FASTQ records and multiline FASTA records. The default crate is the raw parser core; gzip and BGZF transports are explicit feature opt-ins.

The default feature set builds on stable Rust with no compression dependencies. SIMD acceleration is available through the explicit simd feature on stable Rust targets that expose supported std::arch intrinsics.

Choosing an entry point

Use FastqReader or FastaReader directly over a concrete std::fs::File for raw-file hot paths. Use count_fastq_read for count/stat workloads that do not need record views. Use visit_fastq_bytes when a complete FASTQ byte buffer is already resident in memory. Use open_fastq, open_fastq_with_config, open_fasta, or open_fasta_with_config when file-path convenience and optional gzip/BGZF magic detection are worth the boxed transport. Use PairedFastqReader or open_paired_fastq for ordered R1/R2 streams. Use visit_fasta_bytes for resident multiline FASTA, and visit_two_line_fasta_bytes or visit_two_line_fasta_read for strict canonical two-line FASTA fast paths.

Scope

Dino Seq parses four-line FASTQ records. It validates ordered paired-end reads in separate R1/R2 streams or adjacent interleaved records, but it does not synchronize reordered mates. It does not trim adapters, filter reads, align reads, or generate quality-control reports.

Lifetimes and allocation

Batches borrow from the reader’s reusable storage. A FastqBatch or FastaBatch is valid until the next mutable reader call. Clone or copy record data if it must outlive the batch. This design keeps the parser low-allocation, but it means callers should process each batch before advancing the reader.

Feature flags

• gzip enables ordinary gzip auto-detection and streaming decode.
• bgzf enables BGZF readers, writers, indexing, and adaptive parallel decoding.
• libdeflate enables optional libdeflate BGZF backends.
• gzip-libdeflate enables gzip plus libdeflate for explicit buffered gzip openers.
• mmap enables resident file visitors backed by memory maps.
• transport enables both gzip and bgzf for callers that want the old all-transport convenience build.
• simd enables stable std::arch packing paths where supported.

Example

use dino_seq::FastqReader;

let data = b"@r1\nACGT\n+\nIIII\n";
let mut reader = FastqReader::new(&data[..]);
let mut records = 0;

while let Some(batch) = reader.next_batch()? {
    for record in batch.records() {
        assert_eq!(record.seq(), b"ACGT");
        records += 1;
    }
}

assert_eq!(records, 1);

Paired reads

use dino_seq::PairedFastqReader;

let r1 = b"@frag/1\nACGT\n+\nIIII\n";
let r2 = b"@frag/2\nTGCA\n+\nJJJJ\n";
let mut reader = PairedFastqReader::new(&r1[..], &r2[..]);
let batch = reader.next_pair_batch()?.expect("one paired batch");
let pair = batch.pairs().next().expect("one read pair");

assert_eq!(pair.pair_id(), b"frag");
assert_eq!(pair.first().seq(), b"ACGT");
assert_eq!(pair.second().seq(), b"TGCA");

Modules

pack

Base/quality packing and trusted four-line FASTQ pack paths.

Structs

FastaBatch

A batch of borrowed FASTA records.

FastaConfig

Configuration for FASTA readers.

FastaIndex

A .fai-style FASTA index.

FastaIndexEntry

One .fai-style FASTA index entry.

FastaPartition

One planned reference partition over indexed FASTA sequence coordinates.

FastaPartitionConfig

Configuration for planning balanced indexed-FASTA reference partitions.

FastaReader

Slab-style streaming FASTA reader over any Read input.

FastaRecord

Borrowed view of one FASTA record inside a FastaBatch.

FastaRecordRef

Byte ranges for one FASTA record within a batch.

FastaReferenceChunk

Owned reference sequence chunk from an indexed FASTA source.

FastaReferenceChunkRef

Borrowed reference sequence chunk from an indexed FASTA source.

FastaReferenceChunks

Iterator over owned chunks from an IndexedFastaReader.

FastaStats

Aggregate statistics for sequence-only FASTA workloads.

FastaVisitRecord

Borrowed FASTA record passed to FastaReader::visit_records.

FastqBatch

A batch of borrowed FASTQ records from one reader slab.

FastqChunkConfig

Chunking policy for FastqReader::next_chunk_with_sink.

FastqChunkStats

Summary for one chunk emitted by FastqReader::next_chunk_with_sink.

FastqConfig

Configuration for FASTQ batch readers.

FastqPair

Borrowed view of an ordered read pair.

FastqPosition

Location of a FASTQ or FASTA parsing error.

FastqReader

Slab-based FASTQ reader over any Read input.

FastqRecord

Borrowed view of one FASTQ record inside a FastqBatch.

FastqStats

Aggregate statistics for sequence-only FASTQ workloads.

FastqVisitRecord

Borrowed FASTQ record passed to FastqReader::visit_records.

IndexedFastaReader

Seekable FASTA reader backed by a .fai index.

InterleavedPairs

Iterator over adjacent pairs in an interleaved FastqBatch.

OwnedFastaBatch

Owned FASTA batch that can be moved to worker threads.

OwnedFastaRecord

Borrowed record view over an OwnedFastaBatch.

PairedFastqBatch

A paired-end batch produced by PairedFastqReader.

PairedFastqPairs

Iterator over read pairs in a PairedFastqBatch.

PairedFastqReader

Stateful reader for ordered separate-file paired-end FASTQ streams.

PairedRecords

Iterator over paired records from two separate FastqBatch values.

RecordRef

Byte ranges for a four-line FASTQ record within a batch slab.

Enums

DetectedInputKind

Compression/container detected from input file magic.

FastaShape

Detected FASTA physical layout for resident inputs.

FastqError

Error type for FASTQ, FASTA, gzip, and BGZF operations.

PairValidation

Identifier validation policy for paired-end data.

PairingMode

Pairing interpretation for a single FASTQ stream.

Traits

FastaRecordSink

Sink trait for FASTA record visitors.

FastaReferenceChunkSink

Sink trait for borrowed indexed FASTA reference chunks.

FastqChunkSinkExt

Optional extension point for sinks that can preallocate per chunk.

FastqRecordSink

Caller-provided sink for single-pass FASTQ record processing.

Functions

build_fasta_index

Build a .fai-style index over an ordinary FASTA stream.

count_fasta_bytes

Count records and bases from resident FASTA bytes.

count_fasta_read

Count records and bases from an ordinary FASTA stream.

count_fastq_bytes

Count records and bases from an already resident FASTQ byte slice.

count_fastq_read

Count records and bases from a FASTQ reader without building record views.

count_fastq_read_with_config

Count records and bases from a FASTQ reader with explicit parser settings.

count_two_line_fasta_bytes

Count strict two-line FASTA records from resident bytes.

count_two_line_fasta_read

Count strict two-line FASTA records from a stream.

detect_fasta_shape

Detect whether resident FASTA bytes are strict two-line FASTA.

detect_file_input_kind

Detect raw, gzip, or BGZF input by file magic.

open_fasta

Open a FASTA file with default configuration.

open_fasta_for_reference

Open a FASTA reference genome with parser settings tuned for long records.

open_fasta_with_config

Open a FASTA file with explicit parser configuration.

open_fastq

Open a FASTQ file with default configuration.

open_fastq_with_config

Open a FASTQ file with explicit parser configuration.

open_paired_fastq

Open ordered R1/R2 FASTQ files with default configuration.

open_paired_fastq_with_config

Open ordered R1/R2 FASTQ files with the same configuration for both mates.

open_paired_fastq_with_configs

Open ordered R1/R2 FASTQ files with separate mate configurations.

paired_records

Validate and zip two separate FASTQ batches by ordered mate identifiers.

plan_fasta_partitions

Plan balanced reference partitions from a FASTA index.

strip_pair_suffix

Strip a terminal /1 or /2 pair suffix from an identifier token.

visit_fasta_bytes

Visit records from an already resident FASTA byte slice.

visit_fasta_bytes_auto

Visit resident FASTA bytes with automatic two-line fast-path detection.

visit_fastq_bytes

Visit records from an already resident FASTQ byte slice.

visit_two_line_fasta_bytes

Visit records from a resident, strict two-line FASTA byte slice.

visit_two_line_fasta_read

Visit records from a strict two-line FASTA stream.

Type Aliases

Result

Crate-local result type.