From 28aadcc66ec8e3bc015111001df155c6c4df39b8 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Mon, 9 Dec 2024 14:09:36 +0100 Subject: [PATCH 1/2] add links in the documentation comments fixes some typos too --- src/bufread.rs | 6 +++--- src/lib.rs | 16 +++++++++------- src/mem.rs | 17 ++++++++++------- src/write.rs | 30 ++++++++++++++++++++++-------- 4 files changed, 44 insertions(+), 25 deletions(-) diff --git a/src/bufread.rs b/src/bufread.rs index 04be4a46..37b1b44e 100644 --- a/src/bufread.rs +++ b/src/bufread.rs @@ -7,7 +7,7 @@ use crate::{Action, Compress, Compression, Decompress, Status}; /// A bz2 encoder, or compressor. /// -/// This structure implements a `BufRead` interface and will read uncompressed +/// This structure implements a [`BufRead`] interface and will read uncompressed /// data from an underlying stream and emit a stream of compressed data. pub struct BzEncoder { obj: R, @@ -17,7 +17,7 @@ pub struct BzEncoder { /// A bz2 decoder, or decompressor. /// -/// This structure implements a `BufRead` interface and takes a stream of +/// This structure implements a [`BufRead`] interface and takes a stream of /// compressed data as input, providing the decompressed data when read from. pub struct BzDecoder { obj: R, @@ -234,7 +234,7 @@ impl Write for BzDecoder { /// A bzip2 streaming decoder that decodes all members of a multistream. /// /// Wikipedia, particularly, uses bzip2 multistream for their dumps, and the -/// `pbzip2` tool creates such data as well; +/// `pbzip2` tool creates such data as well. pub struct MultiBzDecoder(BzDecoder); impl MultiBzDecoder { diff --git a/src/lib.rs b/src/lib.rs index a2805f18..9a0267dc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,18 +1,20 @@ //! Bzip compression for Rust //! -//! This library contains bindings to libbz2 to support bzip compression and +//! This library contains bindings to [`libbz2`] to support bzip compression and //! decompression for Rust. The streams offered in this library are primarily -//! found in the `reader` and `writer` modules. Both compressors and +//! found in the [`mod@read`] and [`mod@write`] modules. Both compressors and //! decompressors are available in each module depending on what operation you //! need. //! -//! Access to the raw decompression/compression stream is also provided through -//! the `raw` module which has a much closer interface to libbz2. +//! A more low-level interface, much closer to the interface of [`libbz2`], is +//! available via the [`Compress`] and [`Decompress`] structs. +//! +//! [`libbz2`]: https://sourceware.org/bzip2/manual/manual.html //! //! # Example //! //! ``` -//! use std::io::prelude::*; +//! use std::io::{BufRead, Read, Write}; //! use bzip2::Compression; //! use bzip2::read::{BzEncoder, BzDecoder}; //! @@ -41,8 +43,8 @@ //! `MultiBzDecoder`. //! //! All methods are internally capable of working with streams that may return -//! `ErrorKind::WouldBlock` when they're not ready to perform the particular -//! operation. +//! [`ErrorKind::WouldBlock`](std::io::ErrorKind::WouldBlock) when they're not +//! ready to perform the particular operation. //! //! Note that care needs to be taken when using these objects, however. The //! Tokio runtime, in particular, requires that data is fully flushed before diff --git a/src/mem.rs b/src/mem.rs index cf88d3b0..8842a6ec 100644 --- a/src/mem.rs +++ b/src/mem.rs @@ -12,14 +12,14 @@ use crate::{ffi, Compression}; /// Representation of an in-memory compression stream. /// -/// An instance of `Compress` can be used to compress a stream of bz2 data. +/// An instance of [`Compress`] can be used to compress a stream of bz2 data. pub struct Compress { inner: Stream, } /// Representation of an in-memory decompression stream. /// -/// An instance of `Decompress` can be used to inflate a stream of bz2-encoded +/// An instance of [`Decompress`] can be used to decompress a stream of bz2-encoded /// data. pub struct Decompress { inner: Stream, @@ -46,7 +46,7 @@ enum DirDecompress {} pub enum Action { /// Normal compression. Run = ffi::BZ_RUN as isize, - /// Request that the current compression block is terminate. + /// Flush any existing output, but do not read any more input Flush = ffi::BZ_FLUSH as isize, /// Request that the compression stream be finalized. Finish = ffi::BZ_FINISH as isize, @@ -61,7 +61,7 @@ pub enum Status { /// The Flush action on a compression went ok. FlushOk, - /// THe Run action on compression went ok. + /// The Run action on compression went ok. RunOk, /// The Finish action on compression went ok. @@ -135,8 +135,11 @@ impl Compress { /// Compress a block of input into a block of output. /// - /// If anything other than BZ_OK is seen, `Err` is returned. The action - /// given must be one of Run, Flush or Finish. + /// If anything other than [`BZ_OK`] is seen, `Err` is returned. + /// + /// The action given must be one of [`Action::Run`], [`Action::Flush`] or [`Action::Finish`]. + /// + /// [`BZ_OK`]: ffi::BZ_OK pub fn compress( &mut self, input: &[u8], @@ -209,7 +212,7 @@ impl Decompress { /// If `small` is true, then the library will use an alternative /// decompression algorithm which uses less memory but at the cost of /// decompressing more slowly (roughly speaking, half the speed, but the - /// maximum memory requirement drops to around 2300k). See + /// maximum memory requirement drops to around 2300k). pub fn new(small: bool) -> Decompress { unsafe { let mut raw = Box::new(mem::zeroed()); diff --git a/src/write.rs b/src/write.rs index 7ae89409..5d80000e 100644 --- a/src/write.rs +++ b/src/write.rs @@ -64,12 +64,14 @@ impl BzEncoder { /// /// Note that this function can only be used once data has finished being /// written to the output stream. After this function is called then further - /// calls to `write` may result in a panic. + /// calls to [`write`] may result in a panic. /// /// # Panics /// /// Attempts to write data to this stream may result in a panic after this /// function is called. + /// + /// [`write`]: Self::write pub fn try_finish(&mut self) -> io::Result<()> { while !self.done { self.dump()?; @@ -89,9 +91,11 @@ impl BzEncoder { /// /// Note that this function may not be suitable to call in a situation where /// the underlying stream is an asynchronous I/O stream. To finish a stream - /// the `try_finish` (or `shutdown`) method should be used instead. To + /// the [`try_finish`] (or `shutdown`) method should be used instead. To /// re-acquire ownership of a stream it is safe to call this method after - /// `try_finish` or `shutdown` has returned `Ok`. + /// [`try_finish`] or `shutdown` has returned `Ok`. + /// + /// [`try_finish`]: Self::try_finish pub fn finish(mut self) -> io::Result { self.try_finish()?; Ok(self.obj.take().unwrap()) @@ -100,8 +104,11 @@ impl BzEncoder { /// Returns the number of bytes produced by the compressor /// /// Note that, due to buffering, this only bears any relation to - /// `total_in()` after a call to `flush()`. At that point, + /// [`total_in`] after a call to [`flush`]. At that point, /// `total_out() / total_in()` is the compression ratio. + /// + /// [`flush`]: Self::flush + /// [`total_in`]: Self::total_in pub fn total_out(&self) -> u64 { self.data.total_out() } @@ -187,12 +194,14 @@ impl BzDecoder { /// /// Note that this function can only be used once data has finished being /// written to the output stream. After this function is called then further - /// calls to `write` may result in a panic. + /// calls to [`write`] may result in a panic. /// /// # Panics /// /// Attempts to write data to this stream may result in a panic after this /// function is called. + /// + /// [`write`]: Self::write pub fn try_finish(&mut self) -> io::Result<()> { while !self.done { let _ = self.write(&[])?; @@ -204,9 +213,11 @@ impl BzDecoder { /// /// Note that this function may not be suitable to call in a situation where /// the underlying stream is an asynchronous I/O stream. To finish a stream - /// the `try_finish` (or `shutdown`) method should be used instead. To + /// the [`try_finish`] (or `shutdown`) method should be used instead. To /// re-acquire ownership of a stream it is safe to call this method after - /// `try_finish` or `shutdown` has returned `Ok`. + /// [`try_finish`] or `shutdown` has returned `Ok`. + /// + /// [`try_finish`]: Self::try_finish pub fn finish(&mut self) -> io::Result { self.try_finish()?; Ok(self.obj.take().unwrap()) @@ -215,8 +226,11 @@ impl BzDecoder { /// Returns the number of bytes produced by the decompressor /// /// Note that, due to buffering, this only bears any relation to - /// `total_in()` after a call to `flush()`. At that point, + /// [`total_in`] after a call to [`flush`]. At that point, /// `total_in() / total_out()` is the compression ratio. + /// + /// [`flush`]: Self::flush + /// [`total_in`]: Self::total_in pub fn total_out(&self) -> u64 { self.data.total_out() } From c03d510b150a6d4cb0d338a85239df9bcd0cb0a3 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Mon, 9 Dec 2024 14:50:50 +0100 Subject: [PATCH 2/2] update the README --- README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 52177323..f383784b 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,19 @@ [Documentation](https://docs.rs/bzip2) -A streaming compression/decompression library for rust with bindings to libbz2. +A streaming compression/decompression library for rust with bindings to `libbz2`. -```toml -# Cargo.toml -[dependencies] -bzip2 = "0.4" -``` +## Features +By default, `bzip2-rs` attempts to use the system `libbz2`. When `libbz2` is not available, the library +is built from source. A from source build requires a functional C toolchain for your target, and may not +work for all targets (in particular webassembly). -# License +*`static`* + +Always build `libbz2` from source, and statically link it. + +## License This project is licensed under either of