Skip to content

Commit 30250d3

Browse files
committed
flate: add documentation
1 parent bbd034c commit 30250d3

File tree

1 file changed

+26
-20
lines changed

1 file changed

+26
-20
lines changed

src/libflate/lib.rs

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@
1010

1111
/*!
1212
13-
Simple compression
13+
Simple [DEFLATE][def]-based compression. This is a wrapper around the
14+
[`miniz`][mz] library, which is a one-file pure-C implementation of zlib.
15+
16+
[def]: https://en.wikipedia.org/wiki/DEFLATE
17+
[mz]: https://code.google.com/p/miniz/
1418
1519
*/
1620

@@ -31,23 +35,21 @@ extern crate libc;
3135
use std::c_vec::CVec;
3236
use libc::{c_void, size_t, c_int};
3337

34-
35-
pub mod rustrt {
36-
use libc::{c_void, size_t, c_int};
37-
#[link(name = "miniz", kind = "static")]
38-
extern {
39-
pub fn tdefl_compress_mem_to_heap(psrc_buf: *c_void,
40-
src_buf_len: size_t,
41-
pout_len: *mut size_t,
42-
flags: c_int)
43-
-> *mut c_void;
44-
45-
pub fn tinfl_decompress_mem_to_heap(psrc_buf: *c_void,
46-
src_buf_len: size_t,
47-
pout_len: *mut size_t,
48-
flags: c_int)
49-
-> *mut c_void;
50-
}
38+
#[link(name = "miniz", kind = "static")]
39+
extern {
40+
/// Raw miniz compression function.
41+
fn tdefl_compress_mem_to_heap(psrc_buf: *c_void,
42+
src_buf_len: size_t,
43+
pout_len: *mut size_t,
44+
flags: c_int)
45+
-> *mut c_void;
46+
47+
/// Raw miniz decompression function.
48+
fn tinfl_decompress_mem_to_heap(psrc_buf: *c_void,
49+
src_buf_len: size_t,
50+
pout_len: *mut size_t,
51+
flags: c_int)
52+
-> *mut c_void;
5153
}
5254

5355
static LZ_NORM : c_int = 0x80; // LZ with 128 probes, "normal"
@@ -57,7 +59,7 @@ static TDEFL_WRITE_ZLIB_HEADER : c_int = 0x01000; // write zlib header and adler
5759
fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
5860
unsafe {
5961
let mut outsz : size_t = 0;
60-
let res = rustrt::tdefl_compress_mem_to_heap(bytes.as_ptr() as *c_void,
62+
let res = tdefl_compress_mem_to_heap(bytes.as_ptr() as *c_void,
6163
bytes.len() as size_t,
6264
&mut outsz,
6365
flags);
@@ -69,18 +71,20 @@ fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
6971
}
7072
}
7173

74+
/// Compress a buffer, without writing any sort of header on the output.
7275
pub fn deflate_bytes(bytes: &[u8]) -> Option<CVec<u8>> {
7376
deflate_bytes_internal(bytes, LZ_NORM)
7477
}
7578

79+
/// Compress a buffer, using a header that zlib can understand.
7680
pub fn deflate_bytes_zlib(bytes: &[u8]) -> Option<CVec<u8>> {
7781
deflate_bytes_internal(bytes, LZ_NORM | TDEFL_WRITE_ZLIB_HEADER)
7882
}
7983

8084
fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
8185
unsafe {
8286
let mut outsz : size_t = 0;
83-
let res = rustrt::tinfl_decompress_mem_to_heap(bytes.as_ptr() as *c_void,
87+
let res = tinfl_decompress_mem_to_heap(bytes.as_ptr() as *c_void,
8488
bytes.len() as size_t,
8589
&mut outsz,
8690
flags);
@@ -92,10 +96,12 @@ fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
9296
}
9397
}
9498

99+
/// Decompress a buffer, without parsing any sort of header on the input.
95100
pub fn inflate_bytes(bytes: &[u8]) -> Option<CVec<u8>> {
96101
inflate_bytes_internal(bytes, 0)
97102
}
98103

104+
/// Decompress a buffer that starts with a zlib header.
99105
pub fn inflate_bytes_zlib(bytes: &[u8]) -> Option<CVec<u8>> {
100106
inflate_bytes_internal(bytes, TINFL_FLAG_PARSE_ZLIB_HEADER)
101107
}

0 commit comments

Comments
 (0)