blosc2/
lib.rs

1#![cfg_attr(deny_warnings, deny(warnings))]
2#![cfg_attr(deny_warnings, deny(missing_docs))]
3#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
4
5//! Rust bindings for blosc2 - a fast, compressed, persistent binary data store library.
6//!
7//! Provide a safe interface to the [blosc2](https://github.com/Blosc/c-blosc2) library, which is a
8//! new major version of the original [blosc](https://github.com/barakugav/blosc-rs) library.
9//!
10//! ### Getting Started
11//!
12//! To use this library, add the following to your `Cargo.toml`:
13//! ```toml
14//! [dependencies]
15//! blosc2 = "0.1"
16//! ```
17//!
18//! In the following example we compress a vector of integers into a chunk of bytes and then
19//! decompress it back:
20//! ```rust
21//! use blosc2::{CParams, Chunk, DParams, Decoder, Encoder};
22//!
23//! let data: [i32; 7] = [1, 2, 3, 4, 5, 6, 7];
24//! let i32len = std::mem::size_of::<i32>();
25//! let data_bytes =
26//!     unsafe { std::slice::from_raw_parts(data.as_ptr() as *const u8, data.len() * i32len) };
27//!
28//! // Compress the data into a Chunk
29//! let cparams = CParams::default()
30//!     .typesize(i32len.try_into().unwrap())
31//!     .clevel(5)
32//!     .nthreads(2)
33//!     .clone();
34//! let chunk: Chunk = Encoder::new(cparams)
35//!     .unwrap()
36//!     .compress(&data_bytes)
37//!     .unwrap();
38//! let chunk_bytes: &[u8] = chunk.as_bytes();
39//!
40//! // Decompress the Chunk
41//! let dparams = DParams::default();
42//! let decompressed = Decoder::new(dparams)
43//!     .unwrap()
44//!     .decompress(chunk_bytes)
45//!     .unwrap();
46//!
47//! // Check that the decompressed data matches the original
48//! assert_eq!(data_bytes, decompressed);
49//!
50//! // A chunk support random access to individual items
51//! assert_eq!(&data_bytes[0..4], chunk.item(0).expect("failed to get the 0-th item"));
52//! assert_eq!(&data_bytes[12..16], chunk.item(3).expect("failed to get the 3-th item"));
53//! assert_eq!(&data_bytes[4..20], chunk.items(1..5).expect("failed to get items 1 to 4"));
54//! ```
55//!
56//! ## Super Chunk
57//! In addition to the basic `Chunk`, this library provides a `SChunk` (Super Chunk) that treat
58//! multiple chunks as a single entity. A super chunk can be saved or loaded from or to files, and
59//! it supports random access to chunks or individual items across all chunks.
60//! ```rust
61//! use blosc2::{CParams, DParams, Encoder, SChunk};
62//!
63//! let i32len = std::mem::size_of::<i32>();
64//! let cparams = CParams::default()
65//!     .typesize(i32len.try_into().unwrap())
66//!     .clone();
67//! let mut schunk = SChunk::new_in_memory(cparams.clone(), DParams::default()).unwrap();
68//!
69//! // Create two data arrays
70//! let data1: [i32; 7] = [1, 2, 3, 4, 5, 6, 7];
71//! let data2: [i32; 7] = [8, 9, 10, 11, 12, 13, 14];
72//! let data1_bytes =
73//!     unsafe { std::slice::from_raw_parts(data1.as_ptr() as *const u8, data1.len() * i32len) };
74//! let data2_bytes =
75//!     unsafe { std::slice::from_raw_parts(data2.as_ptr() as *const u8, data2.len() * i32len) };
76//!
77//! // Append the first data array to the SChunk, which will be compressed using SChunk's CParams
78//! schunk.append(data1_bytes).unwrap();
79//! assert_eq!(schunk.num_chunks(), 1);
80//! assert_eq!(7, schunk.items_num());
81//!
82//! // Append the second data array to the SChunk, as already compressed data
83//! let data2_cparams = CParams::default()
84//!     .typesize(i32len.try_into().unwrap()) // typesize must match the SChunk's CParams
85//!     .clevel(9)
86//!     .clone();
87//! let data2_chunk = Encoder::new(data2_cparams)
88//!     .unwrap()
89//!     .compress(data2_bytes)
90//!     .unwrap();
91//! schunk.append_chunk(data2_chunk.shallow_clone()).unwrap();
92//! assert_eq!(schunk.num_chunks(), 2);
93//! assert_eq!(14, schunk.items_num());
94//!
95//! // Random access a whole chunk within the super-chunk
96//! assert_eq!(
97//!     data2_chunk.decompress().unwrap(),
98//!     schunk.get_chunk(1).unwrap().decompress().unwrap()
99//! );
100//!
101//! // Random access individual items within the super-chunk
102//! assert_eq!(5, i32::from_ne_bytes(schunk.item(4).unwrap().try_into().unwrap()));
103//! assert_eq!(12, i32::from_ne_bytes(schunk.item(11).unwrap().try_into().unwrap()));
104//! ```
105//!
106//! ## Features
107//! Cargo features enable or disable support for various compression codecs such as `zstd` and
108//! `zlib`.
109//!
110//! ## Error Handling
111//! The library follow the C API and returns error codes. In addition, if the environment variable
112//! `BLOSC_TRACE` is set, it will print detailed trace during failures which is useful for
113//! debugging.
114
115mod error;
116pub use error::Error;
117
118mod encode;
119pub use encode::*;
120
121mod misc;
122pub use misc::*;
123
124mod chunk;
125pub use chunk::*;
126
127mod schunk;
128pub use schunk::*;
129
130mod global;
131pub mod util;
132
133mod tracing;
134pub(crate) use tracing::trace;
135
136/// The version of the crate.
137pub const VERSION: &str = env!("CARGO_PKG_VERSION");
138
139/// The version of the underlying C-blosc2 library used by this crate.
140pub const BLOSC2_C_VERSION: &str = {
141    match blosc2_sys::BLOSC2_VERSION_STRING.to_str() {
142        Ok(s) => s,
143        Err(_) => unreachable!(),
144    }
145};
blosc2/lib.rs

blosc2/
lib.rs
