noodles_bgzf/lib.rs
1//! **noodles-bgzf** handles the reading and writing of the blocked gzip format (BGZF).
2//!
3//! While the gzip format is typically a single stream, a BGZF is the concatenation of many gzip
4//! streams. Each stream is called a block, with its uncompressed data size being constrained to
5//! less than 64 KiB. This multistream gzip allows random access using [`virtual positions`].
6//!
7//! noodles-bgzf abstracts away the concept of blocks, implementing [`std::io::Read`] for the
8//! reader and [`std::io::Write`] for the writer.
9//!
10//! [`virtual positions`]: VirtualPosition
11//!
12//! # Examples
13//!
14//! ## Read an entire BGZF file
15//!
16//! ```no_run
17//! # use std::{fs::File, io::{self, Read}};
18//! use noodles_bgzf as bgzf;
19//! let mut reader = File::open("data.gz").map(bgzf::io::Reader::new)?;
20//! let mut data = Vec::new();
21//! reader.read_to_end(&mut data)?;
22//! # Ok::<(), io::Error>(())
23//! ```
24//!
25//! ## Write a BGZF file
26//!
27//! ```no_run
28//! # use std::{fs::File, io::{self, Write}};
29//! use noodles_bgzf as bgzf;
30//! let mut writer = File::create("data.gz").map(bgzf::io::Writer::new)?;
31//! writer.write_all(b"noodles-bgzf")?;
32//! # Ok::<(), io::Error>(())
33//! ```
34
35#[cfg(feature = "async")]
36pub mod r#async;
37
38pub(crate) mod deflate;
39pub mod fs;
40mod gz;
41pub mod gzi;
42pub mod io;
43pub mod virtual_position;
44
45pub use self::virtual_position::VirtualPosition;
46
47// XLEN (2)
48const GZIP_XLEN_SIZE: usize = 2;
49
50// SI1 (1) + SI2 (1) + SLEN (2) + BSIZE (2)
51const BGZF_XLEN: usize = 6;
52
53// ยง 4.1 The BGZF compression format (2021-06-03): "Thus while `ISIZE` is stored as a `uint32_t` as
54// per the gzip format, in BGZF it is limited to the range [0, 65536]."
55const BGZF_MAX_ISIZE: usize = 1 << 16;
56
57pub(crate) const BGZF_HEADER_SIZE: usize = gz::HEADER_SIZE + GZIP_XLEN_SIZE + BGZF_XLEN;