--- /dev/null
+#![no_std]
+//! Minimal safe wrapper around zstd-sys.
+//!
+//! This crates provides a minimal translation of the [zstd-sys] methods.
+//! For a more comfortable high-level library, see the [zstd] crate.
+//!
+//! [zstd-sys]: https://crates.io/crates/zstd-sys
+//! [zstd]: https://crates.io/crates/zstd
+//!
+//! Most of the functions here map 1-for-1 to a function from
+//! [the C zstd library][zstd-c] mentioned in their descriptions.
+//! Check the [source documentation][doc] for more information on their
+//! behaviour.
+//!
+//! [doc]: https://facebook.github.io/zstd/zstd_manual.html
+//! [zstd-c]: https://facebook.github.io/zstd/
+//!
+//! Features denoted as experimental in the C library are hidden behind an
+//! `experimental` feature.
+#![cfg_attr(feature = "doc-cfg", feature(doc_cfg))]
+
+#[cfg(feature = "std")]
+extern crate std;
+
+#[cfg(test)]
+mod tests;
+
+// Re-export zstd-sys
+pub use zstd_sys;
+
+/// How to compress data.
+pub use zstd_sys::ZSTD_strategy as Strategy;
+
+/// Reset directive.
+// pub use zstd_sys::ZSTD_ResetDirective as ResetDirective;
+
+#[cfg(feature = "std")]
+use std::os::raw::{c_char, c_int, c_ulonglong, c_void};
+
+#[cfg(not(feature = "std"))]
+use libc::{c_char, c_int, c_ulonglong, c_void};
+
+use core::marker::PhantomData;
+use core::num::{NonZeroU32, NonZeroU64};
+use core::ops::{Deref, DerefMut};
+use core::ptr::NonNull;
+use core::str;
+
+include!("constants.rs");
+
+#[cfg(feature = "experimental")]
+include!("constants_experimental.rs");
+
+/// Represents the compression level used by zstd.
+pub type CompressionLevel = i32;
+
+/// Represents a possible error from the zstd library.
+pub type ErrorCode = usize;
+
+/// Wrapper result around most zstd functions.
+///
+/// Either a success code (usually number of bytes written), or an error code.
+pub type SafeResult = Result<usize, ErrorCode>;
+
+/// Indicates an error happened when parsing the frame content size.
+///
+/// The stream may be corrupted, or the given frame prefix was too small.
+#[derive(Debug)]
+pub struct ContentSizeError;
+
+impl core::fmt::Display for ContentSizeError {
+ fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+ f.write_str("Could not get content size")
+ }
+}
+
+/// Returns true if code represents error.
+fn is_error(code: usize) -> bool {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_isError(code) != 0 }
+}
+
+/// Parse the result code
+///
+/// Returns the number of bytes written if the code represents success,
+/// or the error message code otherwise.
+fn parse_code(code: usize) -> SafeResult {
+ if !is_error(code) {
+ Ok(code)
+ } else {
+ Err(code)
+ }
+}
+
+/// Parse a content size value.
+///
+/// zstd uses 2 special content size values to indicate either unknown size or parsing error.
+fn parse_content_size(
+ content_size: u64,
+) -> Result<Option<u64>, ContentSizeError> {
+ match content_size {
+ CONTENTSIZE_ERROR => Err(ContentSizeError),
+ CONTENTSIZE_UNKNOWN => Ok(None),
+ other => Ok(Some(other)),
+ }
+}
+
+fn ptr_void(src: &[u8]) -> *const c_void {
+ src.as_ptr() as *const c_void
+}
+
+fn ptr_mut_void(dst: &mut (impl WriteBuf + ?Sized)) -> *mut c_void {
+ dst.as_mut_ptr() as *mut c_void
+}
+
+/// Returns the ZSTD version.
+///
+/// Returns `major * 10_000 + minor * 100 + patch`.
+/// So 1.5.3 would be returned as `10_503`.
+pub fn version_number() -> u32 {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_versionNumber() as u32 }
+}
+
+/// Returns a string representation of the ZSTD version.
+///
+/// For example "1.5.3".
+pub fn version_string() -> &'static str {
+ // Safety: Assumes `ZSTD_versionString` returns a valid utf8 string.
+ unsafe { c_char_to_str(zstd_sys::ZSTD_versionString()) }
+}
+
+/// Returns the minimum (fastest) compression level supported.
+///
+/// This is likely going to be a _very_ large negative number.
+pub fn min_c_level() -> CompressionLevel {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_minCLevel() as CompressionLevel }
+}
+
+/// Returns the maximum (slowest) compression level supported.
+pub fn max_c_level() -> CompressionLevel {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_maxCLevel() as CompressionLevel }
+}
+
+/// Wraps the `ZSTD_compress` function.
+///
+/// This will try to compress `src` entirely and write the result to `dst`, returning the number of
+/// bytes written.
+///
+/// For streaming operations that don't require to store the entire input/ouput in memory, see
+/// `compress_stream`.
+pub fn compress<C: WriteBuf + ?Sized>(
+ dst: &mut C,
+ src: &[u8],
+ compression_level: CompressionLevel,
+) -> SafeResult {
+ // Safety: ZSTD_compress indeed returns how many bytes have been written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_compress(
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ compression_level,
+ ))
+ })
+ }
+}
+
+/// Wraps the `ZSTD_decompress` function.
+pub fn decompress<C: WriteBuf + ?Sized>(
+ dst: &mut C,
+ src: &[u8],
+) -> SafeResult {
+ // Safety: ZSTD_decompress indeed returns how many bytes have been written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_decompress(
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ))
+ })
+ }
+}
+
+/// Wraps the `ZSTD_getDecompressedSize` function.
+///
+/// Returns `None` if the size could not be found, or if the content is actually empty.
+#[deprecated(note = "Use ZSTD_getFrameContentSize instead")]
+pub fn get_decompressed_size(src: &[u8]) -> Option<NonZeroU64> {
+ // Safety: Just FFI
+ NonZeroU64::new(unsafe {
+ zstd_sys::ZSTD_getDecompressedSize(ptr_void(src), src.len()) as u64
+ })
+}
+
+/// Maximum compressed size in worst case single-pass scenario
+pub fn compress_bound(src_size: usize) -> usize {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_compressBound(src_size) }
+}
+
+/// Compression context
+///
+/// It is recommended to allocate a single context per thread and re-use it
+/// for many compression operations.
+pub struct CCtx<'a>(NonNull<zstd_sys::ZSTD_CCtx>, PhantomData<&'a ()>);
+
+impl Default for CCtx<'_> {
+ fn default() -> Self {
+ CCtx::create()
+ }
+}
+
+impl<'a> CCtx<'a> {
+ /// Tries to create a new context.
+ ///
+ /// Returns `None` if zstd returns a NULL pointer - may happen if allocation fails.
+ pub fn try_create() -> Option<Self> {
+ // Safety: Just FFI
+ Some(CCtx(
+ NonNull::new(unsafe { zstd_sys::ZSTD_createCCtx() })?,
+ PhantomData,
+ ))
+ }
+
+ /// Wrap `ZSTD_createCCtx`
+ ///
+ /// # Panics
+ ///
+ /// If zstd returns a NULL pointer.
+ pub fn create() -> Self {
+ Self::try_create()
+ .expect("zstd returned null pointer when creating new context")
+ }
+
+ /// Wraps the `ZSTD_compressCCtx()` function
+ pub fn compress<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ compression_level: CompressionLevel,
+ ) -> SafeResult {
+ // Safety: ZSTD_compressCCtx returns how many bytes were written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_compressCCtx(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ compression_level,
+ ))
+ })
+ }
+ }
+
+ /// Wraps the `ZSTD_compress2()` function.
+ pub fn compress2<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ ) -> SafeResult {
+ // Safety: ZSTD_compress2 returns how many bytes were written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_compress2(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ))
+ })
+ }
+ }
+
+ /// Wraps the `ZSTD_compress_usingDict()` function.
+ pub fn compress_using_dict<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ dict: &[u8],
+ compression_level: CompressionLevel,
+ ) -> SafeResult {
+ // Safety: ZSTD_compress_usingDict returns how many bytes were written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_compress_usingDict(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ptr_void(dict),
+ dict.len(),
+ compression_level,
+ ))
+ })
+ }
+ }
+
+ /// Wraps the `ZSTD_compress_usingCDict()` function.
+ pub fn compress_using_cdict<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ cdict: &CDict<'_>,
+ ) -> SafeResult {
+ // Safety: ZSTD_compress_usingCDict returns how many bytes were written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_compress_usingCDict(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ cdict.0.as_ptr(),
+ ))
+ })
+ }
+ }
+
+ /// Initializes the context with the given compression level.
+ ///
+ /// This is equivalent to running:
+ /// * `reset()`
+ /// * `set_parameter(CompressionLevel, compression_level)`
+ pub fn init(&mut self, compression_level: CompressionLevel) -> SafeResult {
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_initCStream(self.0.as_ptr(), compression_level)
+ };
+ parse_code(code)
+ }
+
+ /// Wraps the `ZSTD_initCStream_srcSize()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ #[deprecated]
+ pub fn init_src_size(
+ &mut self,
+ compression_level: CompressionLevel,
+ pledged_src_size: u64,
+ ) -> SafeResult {
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_initCStream_srcSize(
+ self.0.as_ptr(),
+ compression_level as c_int,
+ pledged_src_size as c_ulonglong,
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Wraps the `ZSTD_initCStream_usingDict()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ #[deprecated]
+ pub fn init_using_dict(
+ &mut self,
+ dict: &[u8],
+ compression_level: CompressionLevel,
+ ) -> SafeResult {
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_initCStream_usingDict(
+ self.0.as_ptr(),
+ ptr_void(dict),
+ dict.len(),
+ compression_level,
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Wraps the `ZSTD_initCStream_usingCDict()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ #[deprecated]
+ pub fn init_using_cdict<'b>(&mut self, cdict: &CDict<'b>) -> SafeResult
+ where
+ 'b: 'a, // Dictionary outlives the stream.
+ {
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_initCStream_usingCDict(
+ self.0.as_ptr(),
+ cdict.0.as_ptr(),
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Tries to load a dictionary.
+ ///
+ /// The dictionary content will be copied internally and does not need to be kept alive after
+ /// calling this function.
+ ///
+ /// If you need to use the same dictionary for multiple contexts, it may be more efficient to
+ /// create a `CDict` first, then loads that.
+ ///
+ /// The dictionary will apply to all compressed frames, until a new dictionary is set.
+ pub fn load_dictionary(&mut self, dict: &[u8]) -> SafeResult {
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_loadDictionary(
+ self.0.as_ptr(),
+ ptr_void(dict),
+ dict.len(),
+ )
+ })
+ }
+
+ /// Wraps the `ZSTD_CCtx_refCDict()` function.
+ ///
+ /// Dictionary must outlive the context.
+ pub fn ref_cdict<'b>(&mut self, cdict: &CDict<'b>) -> SafeResult
+ where
+ 'b: 'a,
+ {
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_refCDict(self.0.as_ptr(), cdict.0.as_ptr())
+ })
+ }
+
+ /// Return to "no-dictionary" mode.
+ ///
+ /// This will disable any dictionary/prefix previously registered for future frames.
+ pub fn disable_dictionary(&mut self) -> SafeResult {
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_loadDictionary(
+ self.0.as_ptr(),
+ core::ptr::null(),
+ 0,
+ )
+ })
+ }
+
+ /// Use some prefix as single-use dictionary for the next compressed frame.
+ ///
+ /// Just like a dictionary, decompression will need to be given the same prefix.
+ ///
+ /// This is best used if the "prefix" looks like the data to be compressed.
+ pub fn ref_prefix<'b>(&mut self, prefix: &'b [u8]) -> SafeResult
+ where
+ 'b: 'a,
+ {
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_refPrefix(
+ self.0.as_ptr(),
+ ptr_void(prefix),
+ prefix.len(),
+ )
+ })
+ }
+
+ /// Performs a step of a streaming compression operation.
+ ///
+ /// This will read some data from `input` and/or write some data to `output`.
+ ///
+ /// # Returns
+ ///
+ /// A hint for the "ideal" amount of input data to provide in the next call.
+ ///
+ /// This hint is only for performance purposes.
+ ///
+ /// Wraps the `ZSTD_compressStream()` function.
+ pub fn compress_stream<C: WriteBuf + ?Sized>(
+ &mut self,
+ output: &mut OutBuffer<'_, C>,
+ input: &mut InBuffer<'_>,
+ ) -> SafeResult {
+ let mut output = output.wrap();
+ let mut input = input.wrap();
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_compressStream(
+ self.0.as_ptr(),
+ ptr_mut(&mut output),
+ ptr_mut(&mut input),
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Performs a step of a streaming compression operation.
+ ///
+ /// This will read some data from `input` and/or write some data to `output`.
+ ///
+ /// The `end_op` directive can be used to specify what to do after: nothing special, flush
+ /// internal buffers, or end the frame.
+ ///
+ /// # Returns
+ ///
+ /// An lower bound for the amount of data that still needs to be flushed out.
+ ///
+ /// This is useful when flushing or ending the frame: you need to keep calling this function
+ /// until it returns 0.
+ ///
+ /// Wraps the `ZSTD_compressStream2()` function.
+ pub fn compress_stream2<C: WriteBuf + ?Sized>(
+ &mut self,
+ output: &mut OutBuffer<'_, C>,
+ input: &mut InBuffer<'_>,
+ end_op: zstd_sys::ZSTD_EndDirective,
+ ) -> SafeResult {
+ let mut output = output.wrap();
+ let mut input = input.wrap();
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_compressStream2(
+ self.0.as_ptr(),
+ ptr_mut(&mut output),
+ ptr_mut(&mut input),
+ end_op,
+ )
+ })
+ }
+
+ /// Flush any intermediate buffer.
+ ///
+ /// To fully flush, you should keep calling this function until it returns `Ok(0)`.
+ ///
+ /// Wraps the `ZSTD_flushStream()` function.
+ pub fn flush_stream<C: WriteBuf + ?Sized>(
+ &mut self,
+ output: &mut OutBuffer<'_, C>,
+ ) -> SafeResult {
+ let mut output = output.wrap();
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_flushStream(self.0.as_ptr(), ptr_mut(&mut output))
+ };
+ parse_code(code)
+ }
+
+ /// Ends the stream.
+ ///
+ /// You should keep calling this function until it returns `Ok(0)`.
+ ///
+ /// Wraps the `ZSTD_endStream()` function.
+ pub fn end_stream<C: WriteBuf + ?Sized>(
+ &mut self,
+ output: &mut OutBuffer<'_, C>,
+ ) -> SafeResult {
+ let mut output = output.wrap();
+ // Safety: Just FFI
+ let code = unsafe {
+ zstd_sys::ZSTD_endStream(self.0.as_ptr(), ptr_mut(&mut output))
+ };
+ parse_code(code)
+ }
+
+ /// Returns the size currently used by this context.
+ ///
+ /// This may change over time.
+ pub fn sizeof(&self) -> usize {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_sizeof_CCtx(self.0.as_ptr()) }
+ }
+
+ /// Resets the state of the context.
+ ///
+ /// Depending on the reset mode, it can reset the session, the parameters, or both.
+ ///
+ /// Wraps the `ZSTD_CCtx_reset()` function.
+ pub fn reset(&mut self, reset: ResetDirective) -> SafeResult {
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_reset(self.0.as_ptr(), reset.as_sys())
+ })
+ }
+
+ /// Sets a compression parameter.
+ ///
+ /// Some of these parameters need to be set during de-compression as well.
+ pub fn set_parameter(&mut self, param: CParameter) -> SafeResult {
+ // TODO: Until bindgen properly generates a binding for this, we'll need to do it here.
+
+ #[cfg(feature = "experimental")]
+ use zstd_sys::ZSTD_cParameter::{
+ ZSTD_c_experimentalParam1 as ZSTD_c_rsyncable,
+ ZSTD_c_experimentalParam10 as ZSTD_c_stableOutBuffer,
+ ZSTD_c_experimentalParam11 as ZSTD_c_blockDelimiters,
+ ZSTD_c_experimentalParam12 as ZSTD_c_validateSequences,
+ ZSTD_c_experimentalParam13 as ZSTD_c_useBlockSplitter,
+ ZSTD_c_experimentalParam14 as ZSTD_c_useRowMatchFinder,
+ ZSTD_c_experimentalParam15 as ZSTD_c_deterministicRefPrefix,
+ ZSTD_c_experimentalParam16 as ZSTD_c_prefetchCDictTables,
+ ZSTD_c_experimentalParam17 as ZSTD_c_enableSeqProducerFallback,
+ ZSTD_c_experimentalParam18 as ZSTD_c_maxBlockSize,
+ ZSTD_c_experimentalParam19 as ZSTD_c_searchForExternalRepcodes,
+ ZSTD_c_experimentalParam2 as ZSTD_c_format,
+ ZSTD_c_experimentalParam3 as ZSTD_c_forceMaxWindow,
+ ZSTD_c_experimentalParam4 as ZSTD_c_forceAttachDict,
+ ZSTD_c_experimentalParam5 as ZSTD_c_literalCompressionMode,
+ ZSTD_c_experimentalParam6 as ZSTD_c_targetCBlockSize,
+ ZSTD_c_experimentalParam7 as ZSTD_c_srcSizeHint,
+ ZSTD_c_experimentalParam8 as ZSTD_c_enableDedicatedDictSearch,
+ ZSTD_c_experimentalParam9 as ZSTD_c_stableInBuffer,
+ };
+
+ use zstd_sys::ZSTD_cParameter::*;
+ use CParameter::*;
+
+ let (param, value) = match param {
+ #[cfg(feature = "experimental")]
+ RSyncable(rsyncable) => (ZSTD_c_rsyncable, rsyncable as c_int),
+ #[cfg(feature = "experimental")]
+ Format(format) => (ZSTD_c_format, format as c_int),
+ #[cfg(feature = "experimental")]
+ ForceMaxWindow(force) => (ZSTD_c_forceMaxWindow, force as c_int),
+ #[cfg(feature = "experimental")]
+ ForceAttachDict(force) => (ZSTD_c_forceAttachDict, force as c_int),
+ #[cfg(feature = "experimental")]
+ LiteralCompressionMode(mode) => {
+ (ZSTD_c_literalCompressionMode, mode as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ TargetCBlockSize(value) => {
+ (ZSTD_c_targetCBlockSize, value as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ SrcSizeHint(value) => (ZSTD_c_srcSizeHint, value as c_int),
+ #[cfg(feature = "experimental")]
+ EnableDedicatedDictSearch(enable) => {
+ (ZSTD_c_enableDedicatedDictSearch, enable as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ StableInBuffer(stable) => (ZSTD_c_stableInBuffer, stable as c_int),
+ #[cfg(feature = "experimental")]
+ StableOutBuffer(stable) => {
+ (ZSTD_c_stableOutBuffer, stable as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ BlockDelimiters(value) => (ZSTD_c_blockDelimiters, value as c_int),
+ #[cfg(feature = "experimental")]
+ ValidateSequences(validate) => {
+ (ZSTD_c_validateSequences, validate as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ UseBlockSplitter(split) => {
+ (ZSTD_c_useBlockSplitter, split as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ UseRowMatchFinder(mode) => {
+ (ZSTD_c_useRowMatchFinder, mode as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ DeterministicRefPrefix(deterministic) => {
+ (ZSTD_c_deterministicRefPrefix, deterministic as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ PrefetchCDictTables(prefetch) => {
+ (ZSTD_c_prefetchCDictTables, prefetch as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ EnableSeqProducerFallback(enable) => {
+ (ZSTD_c_enableSeqProducerFallback, enable as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ MaxBlockSize(value) => (ZSTD_c_maxBlockSize, value as c_int),
+ #[cfg(feature = "experimental")]
+ SearchForExternalRepcodes(value) => {
+ (ZSTD_c_searchForExternalRepcodes, value as c_int)
+ }
+ CompressionLevel(level) => (ZSTD_c_compressionLevel, level),
+ WindowLog(value) => (ZSTD_c_windowLog, value as c_int),
+ HashLog(value) => (ZSTD_c_hashLog, value as c_int),
+ ChainLog(value) => (ZSTD_c_chainLog, value as c_int),
+ SearchLog(value) => (ZSTD_c_searchLog, value as c_int),
+ MinMatch(value) => (ZSTD_c_minMatch, value as c_int),
+ TargetLength(value) => (ZSTD_c_targetLength, value as c_int),
+ Strategy(strategy) => (ZSTD_c_strategy, strategy as c_int),
+ EnableLongDistanceMatching(flag) => {
+ (ZSTD_c_enableLongDistanceMatching, flag as c_int)
+ }
+ LdmHashLog(value) => (ZSTD_c_ldmHashLog, value as c_int),
+ LdmMinMatch(value) => (ZSTD_c_ldmMinMatch, value as c_int),
+ LdmBucketSizeLog(value) => {
+ (ZSTD_c_ldmBucketSizeLog, value as c_int)
+ }
+ LdmHashRateLog(value) => (ZSTD_c_ldmHashRateLog, value as c_int),
+ ContentSizeFlag(flag) => (ZSTD_c_contentSizeFlag, flag as c_int),
+ ChecksumFlag(flag) => (ZSTD_c_checksumFlag, flag as c_int),
+ DictIdFlag(flag) => (ZSTD_c_dictIDFlag, flag as c_int),
+
+ NbWorkers(value) => (ZSTD_c_nbWorkers, value as c_int),
+
+ JobSize(value) => (ZSTD_c_jobSize, value as c_int),
+
+ OverlapSizeLog(value) => (ZSTD_c_overlapLog, value as c_int),
+ };
+
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_setParameter(self.0.as_ptr(), param, value)
+ })
+ }
+
+ /// Guarantee that the input size will be this value.
+ ///
+ /// If given `None`, assumes the size is unknown.
+ ///
+ /// Unless explicitly disabled, this will cause the size to be written in the compressed frame
+ /// header.
+ ///
+ /// If the actual data given to compress has a different size, an error will be returned.
+ pub fn set_pledged_src_size(
+ &mut self,
+ pledged_src_size: Option<u64>,
+ ) -> SafeResult {
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_CCtx_setPledgedSrcSize(
+ self.0.as_ptr(),
+ pledged_src_size.unwrap_or(CONTENTSIZE_UNKNOWN) as c_ulonglong,
+ )
+ })
+ }
+
+ /// Creates a copy of this context.
+ ///
+ /// This only works before any data has been compressed. An error will be
+ /// returned otherwise.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn try_clone(
+ &self,
+ pledged_src_size: Option<u64>,
+ ) -> Result<Self, ErrorCode> {
+ // Safety: Just FFI
+ let context = NonNull::new(unsafe { zstd_sys::ZSTD_createCCtx() })
+ .ok_or(0usize)?;
+
+ // Safety: Just FFI
+ parse_code(unsafe {
+ zstd_sys::ZSTD_copyCCtx(
+ context.as_ptr(),
+ self.0.as_ptr(),
+ pledged_src_size.unwrap_or(CONTENTSIZE_UNKNOWN),
+ )
+ })?;
+
+ Ok(CCtx(context, self.1))
+ }
+
+ /// Wraps the `ZSTD_getBlockSize()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn get_block_size(&self) -> usize {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_getBlockSize(self.0.as_ptr()) }
+ }
+
+ /// Wraps the `ZSTD_compressBlock()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn compress_block<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ ) -> SafeResult {
+ // Safety: ZSTD_compressBlock returns the number of bytes written.
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_compressBlock(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ))
+ })
+ }
+ }
+
+ /// Returns the recommended input buffer size.
+ ///
+ /// Using this size may result in minor performance boost.
+ pub fn in_size() -> usize {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_CStreamInSize() }
+ }
+
+ /// Returns the recommended output buffer size.
+ ///
+ /// Using this may result in minor performance boost.
+ pub fn out_size() -> usize {
+ // Safety: Just FFI
+ unsafe { zstd_sys::ZSTD_CStreamOutSize() }
+ }
+}
+
+impl<'a> Drop for CCtx<'a> {
+ fn drop(&mut self) {
+ // Safety: Just FFI
+ unsafe {
+ zstd_sys::ZSTD_freeCCtx(self.0.as_ptr());
+ }
+ }
+}
+
+unsafe impl<'a> Send for CCtx<'a> {}
+// CCtx can't be shared across threads, so it does not implement Sync.
+
+unsafe fn c_char_to_str(text: *const c_char) -> &'static str {
+ #[cfg(not(feature = "std"))]
+ {
+ // To be safe, we need to compute right now its length
+ let len = libc::strlen(text);
+ // Cast it to a slice
+ let slice = core::slice::from_raw_parts(text as *mut u8, len);
+ // And hope it's still text.
+ str::from_utf8(slice).expect("bad error message from zstd")
+ }
+
+ #[cfg(feature = "std")]
+ {
+ std::ffi::CStr::from_ptr(text)
+ .to_str()
+ .expect("bad error message from zstd")
+ }
+}
+
+/// Returns the error string associated with an error code.
+pub fn get_error_name(code: usize) -> &'static str {
+ unsafe {
+ // Safety: assumes ZSTD returns a well-formed utf8 string.
+ let name = zstd_sys::ZSTD_getErrorName(code);
+ c_char_to_str(name)
+ }
+}
+
+/// A Decompression Context.
+///
+/// The lifetime references the potential dictionary used for this context.
+///
+/// If no dictionary was used, it will most likely be `'static`.
+///
+/// Same as `DStream`.
+pub struct DCtx<'a>(NonNull<zstd_sys::ZSTD_DCtx>, PhantomData<&'a ()>);
+
+impl Default for DCtx<'_> {
+ fn default() -> Self {
+ DCtx::create()
+ }
+}
+
+impl<'a> DCtx<'a> {
+ /// Try to create a new decompression context.
+ ///
+ /// Returns `None` if the operation failed (for example, not enough memory).
+ pub fn try_create() -> Option<Self> {
+ Some(DCtx(
+ NonNull::new(unsafe { zstd_sys::ZSTD_createDCtx() })?,
+ PhantomData,
+ ))
+ }
+
+ /// Creates a new decoding context.
+ ///
+ /// # Panics
+ ///
+ /// If the context creation fails.
+ pub fn create() -> Self {
+ Self::try_create()
+ .expect("zstd returned null pointer when creating new context")
+ }
+
+ /// Fully decompress the given frame.
+ ///
+ /// This decompress an entire frame in-memory. If you can have enough memory to store both the
+ /// input and output buffer, then it may be faster that streaming decompression.
+ ///
+ /// Wraps the `ZSTD_decompressDCtx()` function.
+ pub fn decompress<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ ) -> SafeResult {
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_decompressDCtx(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ))
+ })
+ }
+ }
+
+ /// Fully decompress the given frame using a dictionary.
+ ///
+ /// Dictionary must be identical to the one used during compression.
+ ///
+ /// If you plan on using the same dictionary multiple times, it is faster to create a `DDict`
+ /// first and use `decompress_using_ddict`.
+ ///
+ /// Wraps `ZSTD_decompress_usingDict`
+ pub fn decompress_using_dict<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ dict: &[u8],
+ ) -> SafeResult {
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_decompress_usingDict(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ptr_void(dict),
+ dict.len(),
+ ))
+ })
+ }
+ }
+
+ /// Fully decompress the given frame using a dictionary.
+ ///
+ /// Dictionary must be identical to the one used during compression.
+ ///
+ /// Wraps the `ZSTD_decompress_usingDDict()` function.
+ pub fn decompress_using_ddict<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ ddict: &DDict<'_>,
+ ) -> SafeResult {
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_decompress_usingDDict(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ddict.0.as_ptr(),
+ ))
+ })
+ }
+ }
+
+ /// Initializes an existing `DStream` for decompression.
+ ///
+ /// This is equivalent to calling:
+ /// * `reset(SessionOnly)`
+ /// * `disable_dictionary()`
+ ///
+ /// Wraps the `ZSTD_initCStream()` function.
+ pub fn init(&mut self) -> SafeResult {
+ let code = unsafe { zstd_sys::ZSTD_initDStream(self.0.as_ptr()) };
+ parse_code(code)
+ }
+
+ /// Wraps the `ZSTD_initDStream_usingDict()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ #[deprecated]
+ pub fn init_using_dict(&mut self, dict: &[u8]) -> SafeResult {
+ let code = unsafe {
+ zstd_sys::ZSTD_initDStream_usingDict(
+ self.0.as_ptr(),
+ ptr_void(dict),
+ dict.len(),
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Wraps the `ZSTD_initDStream_usingDDict()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ #[deprecated]
+ pub fn init_using_ddict<'b>(&mut self, ddict: &DDict<'b>) -> SafeResult
+ where
+ 'b: 'a,
+ {
+ let code = unsafe {
+ zstd_sys::ZSTD_initDStream_usingDDict(
+ self.0.as_ptr(),
+ ddict.0.as_ptr(),
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Resets the state of the context.
+ ///
+ /// Depending on the reset mode, it can reset the session, the parameters, or both.
+ ///
+ /// Wraps the `ZSTD_DCtx_reset()` function.
+ pub fn reset(&mut self, reset: ResetDirective) -> SafeResult {
+ parse_code(unsafe {
+ zstd_sys::ZSTD_DCtx_reset(self.0.as_ptr(), reset.as_sys())
+ })
+ }
+
+ /// Loads a dictionary.
+ ///
+ /// This will let this context decompress frames that were compressed using this dictionary.
+ ///
+ /// The dictionary content will be copied internally and does not need to be kept alive after
+ /// calling this function.
+ ///
+ /// If you need to use the same dictionary for multiple contexts, it may be more efficient to
+ /// create a `DDict` first, then loads that.
+ ///
+ /// The dictionary will apply to all future frames, until a new dictionary is set.
+ pub fn load_dictionary(&mut self, dict: &[u8]) -> SafeResult {
+ parse_code(unsafe {
+ zstd_sys::ZSTD_DCtx_loadDictionary(
+ self.0.as_ptr(),
+ ptr_void(dict),
+ dict.len(),
+ )
+ })
+ }
+
+ /// Return to "no-dictionary" mode.
+ ///
+ /// This will disable any dictionary/prefix previously registered for future frames.
+ pub fn disable_dictionary(&mut self) -> SafeResult {
+ parse_code(unsafe {
+ zstd_sys::ZSTD_DCtx_loadDictionary(
+ self.0.as_ptr(),
+ core::ptr::null(),
+ 0,
+ )
+ })
+ }
+
+ /// References a dictionary.
+ ///
+ /// This will let this context decompress frames compressed with the same dictionary.
+ ///
+ /// It will apply to all frames decompressed by this context (until a new dictionary is set).
+ ///
+ /// Wraps the `ZSTD_DCtx_refDDict()` function.
+ pub fn ref_ddict<'b>(&mut self, ddict: &DDict<'b>) -> SafeResult
+ where
+ 'b: 'a,
+ {
+ parse_code(unsafe {
+ zstd_sys::ZSTD_DCtx_refDDict(self.0.as_ptr(), ddict.0.as_ptr())
+ })
+ }
+
+ /// Use some prefix as single-use dictionary for the next frame.
+ ///
+ /// Just like a dictionary, this only works if compression was done with the same prefix.
+ ///
+ /// But unlike a dictionary, this only applies to the next frame.
+ ///
+ /// Wraps the `ZSTD_DCtx_refPrefix()` function.
+ pub fn ref_prefix<'b>(&mut self, prefix: &'b [u8]) -> SafeResult
+ where
+ 'b: 'a,
+ {
+ parse_code(unsafe {
+ zstd_sys::ZSTD_DCtx_refPrefix(
+ self.0.as_ptr(),
+ ptr_void(prefix),
+ prefix.len(),
+ )
+ })
+ }
+
+ /// Sets a decompression parameter.
+ pub fn set_parameter(&mut self, param: DParameter) -> SafeResult {
+ #[cfg(feature = "experimental")]
+ use zstd_sys::ZSTD_dParameter::{
+ ZSTD_d_experimentalParam1 as ZSTD_d_format,
+ ZSTD_d_experimentalParam2 as ZSTD_d_stableOutBuffer,
+ ZSTD_d_experimentalParam3 as ZSTD_d_forceIgnoreChecksum,
+ ZSTD_d_experimentalParam4 as ZSTD_d_refMultipleDDicts,
+ };
+
+ use zstd_sys::ZSTD_dParameter::*;
+ use DParameter::*;
+
+ let (param, value) = match param {
+ #[cfg(feature = "experimental")]
+ Format(format) => (ZSTD_d_format, format as c_int),
+ #[cfg(feature = "experimental")]
+ StableOutBuffer(stable) => {
+ (ZSTD_d_stableOutBuffer, stable as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ ForceIgnoreChecksum(force) => {
+ (ZSTD_d_forceIgnoreChecksum, force as c_int)
+ }
+ #[cfg(feature = "experimental")]
+ RefMultipleDDicts(value) => {
+ (ZSTD_d_refMultipleDDicts, value as c_int)
+ }
+
+ WindowLogMax(value) => (ZSTD_d_windowLogMax, value as c_int),
+ };
+
+ parse_code(unsafe {
+ zstd_sys::ZSTD_DCtx_setParameter(self.0.as_ptr(), param, value)
+ })
+ }
+
+ /// Performs a step of a streaming decompression operation.
+ ///
+ /// This will read some data from `input` and/or write some data to `output`.
+ ///
+ /// # Returns
+ ///
+ /// * `Ok(0)` if the current frame just finished decompressing successfully.
+ /// * `Ok(hint)` with a hint for the "ideal" amount of input data to provide in the next call.
+ /// Can be safely ignored.
+ ///
+ /// Wraps the `ZSTD_decompressStream()` function.
+ pub fn decompress_stream<C: WriteBuf + ?Sized>(
+ &mut self,
+ output: &mut OutBuffer<'_, C>,
+ input: &mut InBuffer<'_>,
+ ) -> SafeResult {
+ let mut output = output.wrap();
+ let mut input = input.wrap();
+ let code = unsafe {
+ zstd_sys::ZSTD_decompressStream(
+ self.0.as_ptr(),
+ ptr_mut(&mut output),
+ ptr_mut(&mut input),
+ )
+ };
+ parse_code(code)
+ }
+
+ /// Wraps the `ZSTD_DStreamInSize()` function.
+ ///
+ /// Returns a hint for the recommended size of the input buffer for decompression.
+ pub fn in_size() -> usize {
+ unsafe { zstd_sys::ZSTD_DStreamInSize() }
+ }
+
+ /// Wraps the `ZSTD_DStreamOutSize()` function.
+ ///
+ /// Returns a hint for the recommended size of the output buffer for decompression.
+ pub fn out_size() -> usize {
+ unsafe { zstd_sys::ZSTD_DStreamOutSize() }
+ }
+
+ /// Wraps the `ZSTD_sizeof_DCtx()` function.
+ pub fn sizeof(&self) -> usize {
+ unsafe { zstd_sys::ZSTD_sizeof_DCtx(self.0.as_ptr()) }
+ }
+
+ /// Wraps the `ZSTD_decompressBlock()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn decompress_block<C: WriteBuf + ?Sized>(
+ &mut self,
+ dst: &mut C,
+ src: &[u8],
+ ) -> SafeResult {
+ unsafe {
+ dst.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZSTD_decompressBlock(
+ self.0.as_ptr(),
+ buffer,
+ capacity,
+ ptr_void(src),
+ src.len(),
+ ))
+ })
+ }
+ }
+
+ /// Wraps the `ZSTD_insertBlock()` function.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn insert_block(&mut self, block: &[u8]) -> usize {
+ unsafe {
+ zstd_sys::ZSTD_insertBlock(
+ self.0.as_ptr(),
+ ptr_void(block),
+ block.len(),
+ )
+ }
+ }
+
+ /// Creates a copy of this context.
+ ///
+ /// This only works before any data has been decompressed. An error will be
+ /// returned otherwise.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn try_clone(&self) -> Result<Self, ErrorCode> {
+ let context = NonNull::new(unsafe { zstd_sys::ZSTD_createDCtx() })
+ .ok_or(0usize)?;
+
+ unsafe { zstd_sys::ZSTD_copyDCtx(context.as_ptr(), self.0.as_ptr()) };
+
+ Ok(DCtx(context, self.1))
+ }
+}
+
+impl Drop for DCtx<'_> {
+ fn drop(&mut self) {
+ unsafe {
+ zstd_sys::ZSTD_freeDCtx(self.0.as_ptr());
+ }
+ }
+}
+
+unsafe impl Send for DCtx<'_> {}
+// DCtx can't be shared across threads, so it does not implement Sync.
+
+/// Compression dictionary.
+pub struct CDict<'a>(NonNull<zstd_sys::ZSTD_CDict>, PhantomData<&'a ()>);
+
+impl CDict<'static> {
+ /// Prepare a dictionary to compress data.
+ ///
+ /// This will make it easier for compression contexts to load this dictionary.
+ ///
+ /// The dictionary content will be copied internally, and does not need to be kept around.
+ ///
+ /// # Panics
+ ///
+ /// If loading this dictionary failed.
+ pub fn create(
+ dict_buffer: &[u8],
+ compression_level: CompressionLevel,
+ ) -> Self {
+ Self::try_create(dict_buffer, compression_level)
+ .expect("zstd returned null pointer when creating dict")
+ }
+
+ /// Prepare a dictionary to compress data.
+ ///
+ /// This will make it easier for compression contexts to load this dictionary.
+ ///
+ /// The dictionary content will be copied internally, and does not need to be kept around.
+ pub fn try_create(
+ dict_buffer: &[u8],
+ compression_level: CompressionLevel,
+ ) -> Option<Self> {
+ Some(CDict(
+ NonNull::new(unsafe {
+ zstd_sys::ZSTD_createCDict(
+ ptr_void(dict_buffer),
+ dict_buffer.len(),
+ compression_level,
+ )
+ })?,
+ PhantomData,
+ ))
+ }
+}
+
+impl<'a> CDict<'a> {
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn create_by_reference(
+ dict_buffer: &'a [u8],
+ compression_level: CompressionLevel,
+ ) -> Self {
+ CDict(
+ NonNull::new(unsafe {
+ zstd_sys::ZSTD_createCDict_byReference(
+ ptr_void(dict_buffer),
+ dict_buffer.len(),
+ compression_level,
+ )
+ })
+ .expect("zstd returned null pointer"),
+ PhantomData,
+ )
+ }
+
+ /// Returns the _current_ memory usage of this dictionary.
+ ///
+ /// Note that this may change over time.
+ pub fn sizeof(&self) -> usize {
+ unsafe { zstd_sys::ZSTD_sizeof_CDict(self.0.as_ptr()) }
+ }
+
+ /// Returns the dictionary ID for this dict.
+ ///
+ /// Returns `None` if this dictionary is empty or invalid.
+ pub fn get_dict_id(&self) -> Option<NonZeroU32> {
+ NonZeroU32::new(unsafe {
+ zstd_sys::ZSTD_getDictID_fromCDict(self.0.as_ptr()) as u32
+ })
+ }
+}
+
+/// Wraps the `ZSTD_createCDict()` function.
+pub fn create_cdict(
+ dict_buffer: &[u8],
+ compression_level: CompressionLevel,
+) -> CDict<'static> {
+ CDict::create(dict_buffer, compression_level)
+}
+
+impl<'a> Drop for CDict<'a> {
+ fn drop(&mut self) {
+ unsafe {
+ zstd_sys::ZSTD_freeCDict(self.0.as_ptr());
+ }
+ }
+}
+
+unsafe impl<'a> Send for CDict<'a> {}
+unsafe impl<'a> Sync for CDict<'a> {}
+
+/// Wraps the `ZSTD_compress_usingCDict()` function.
+pub fn compress_using_cdict(
+ cctx: &mut CCtx<'_>,
+ dst: &mut [u8],
+ src: &[u8],
+ cdict: &CDict<'_>,
+) -> SafeResult {
+ cctx.compress_using_cdict(dst, src, cdict)
+}
+
+/// A digested decompression dictionary.
+pub struct DDict<'a>(NonNull<zstd_sys::ZSTD_DDict>, PhantomData<&'a ()>);
+
+impl DDict<'static> {
+ pub fn create(dict_buffer: &[u8]) -> Self {
+ Self::try_create(dict_buffer)
+ .expect("zstd returned null pointer when creating dict")
+ }
+
+ pub fn try_create(dict_buffer: &[u8]) -> Option<Self> {
+ Some(DDict(
+ NonNull::new(unsafe {
+ zstd_sys::ZSTD_createDDict(
+ ptr_void(dict_buffer),
+ dict_buffer.len(),
+ )
+ })?,
+ PhantomData,
+ ))
+ }
+}
+
+impl<'a> DDict<'a> {
+ pub fn sizeof(&self) -> usize {
+ unsafe { zstd_sys::ZSTD_sizeof_DDict(self.0.as_ptr()) }
+ }
+
+ /// Wraps the `ZSTD_createDDict_byReference()` function.
+ ///
+ /// The dictionary will keep referencing `dict_buffer`.
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ pub fn create_by_reference(dict_buffer: &'a [u8]) -> Self {
+ DDict(
+ NonNull::new(unsafe {
+ zstd_sys::ZSTD_createDDict_byReference(
+ ptr_void(dict_buffer),
+ dict_buffer.len(),
+ )
+ })
+ .expect("zstd returned null pointer"),
+ PhantomData,
+ )
+ }
+
+ /// Returns the dictionary ID for this dict.
+ ///
+ /// Returns `None` if this dictionary is empty or invalid.
+ pub fn get_dict_id(&self) -> Option<NonZeroU32> {
+ NonZeroU32::new(unsafe {
+ zstd_sys::ZSTD_getDictID_fromDDict(self.0.as_ptr()) as u32
+ })
+ }
+}
+
+/// Wraps the `ZSTD_createDDict()` function.
+///
+/// It copies the dictionary internally, so the resulting `DDict` is `'static`.
+pub fn create_ddict(dict_buffer: &[u8]) -> DDict<'static> {
+ DDict::create(dict_buffer)
+}
+
+impl<'a> Drop for DDict<'a> {
+ fn drop(&mut self) {
+ unsafe {
+ zstd_sys::ZSTD_freeDDict(self.0.as_ptr());
+ }
+ }
+}
+
+unsafe impl<'a> Send for DDict<'a> {}
+unsafe impl<'a> Sync for DDict<'a> {}
+
+/// Wraps the `ZSTD_decompress_usingDDict()` function.
+pub fn decompress_using_ddict(
+ dctx: &mut DCtx<'_>,
+ dst: &mut [u8],
+ src: &[u8],
+ ddict: &DDict<'_>,
+) -> SafeResult {
+ dctx.decompress_using_ddict(dst, src, ddict)
+}
+
+/// Compression stream.
+///
+/// Same as `CCtx`.
+pub type CStream<'a> = CCtx<'a>;
+
+// CStream can't be shared across threads, so it does not implement Sync.
+
+/// Allocates a new `CStream`.
+pub fn create_cstream<'a>() -> CStream<'a> {
+ CCtx::create()
+}
+
+/// Prepares an existing `CStream` for compression at the given level.
+pub fn init_cstream(
+ zcs: &mut CStream<'_>,
+ compression_level: CompressionLevel,
+) -> SafeResult {
+ zcs.init(compression_level)
+}
+
+#[derive(Debug)]
+/// Wrapper around an input buffer.
+///
+/// Bytes will be read starting at `src[pos]`.
+///
+/// `pos` will be updated after reading.
+pub struct InBuffer<'a> {
+ pub src: &'a [u8],
+ pub pos: usize,
+}
+
+/// Describe a resizeable bytes container like `Vec<u8>`.
+///
+/// Represents a contiguous segment of memory, a prefix of which is initialized.
+///
+/// It allows starting from an uninitializes chunk of memory and writing to it.
+///
+/// The main implementors are:
+/// * `Vec<u8>` and similar structures. These can start empty with a non-zero capacity, and they
+/// will be resized to cover the data written.
+/// Any existing data will be overwritten.
+/// * `[u8]` and `[u8; N]`. These must start already-initialized, and will not be resized. It will
+/// be up to the caller to only use the part that was written.
+/// * `std::io::Cursor<T: WriteBuf>`. This will ignore data before the cursor's position, and
+/// append data after that.
+pub unsafe trait WriteBuf {
+ /// Returns the valid data part of this container. Should only cover initialized data.
+ fn as_slice(&self) -> &[u8];
+
+ /// Returns the full capacity of this container. May include uninitialized data.
+ fn capacity(&self) -> usize;
+
+ /// Returns a pointer to the start of the data.
+ fn as_mut_ptr(&mut self) -> *mut u8;
+
+ /// Indicates that the first `n` bytes of the container have been written.
+ ///
+ /// Safety: this should only be called if the `n` first bytes of this buffer have actually been
+ /// initialized.
+ unsafe fn filled_until(&mut self, n: usize);
+
+ /// Call the given closure using the pointer and capacity from `self`.
+ ///
+ /// Assumes the given function returns a parseable code, which if valid, represents how many
+ /// bytes were written to `self`.
+ ///
+ /// The given closure must treat its first argument as pointing to potentially uninitialized
+ /// memory, and should not read from it.
+ ///
+ /// In addition, it must have written at least `n` bytes contiguously from this pointer, where
+ /// `n` is the returned value.
+ unsafe fn write_from<F>(&mut self, f: F) -> SafeResult
+ where
+ F: FnOnce(*mut c_void, usize) -> SafeResult,
+ {
+ let res = f(ptr_mut_void(self), self.capacity());
+ if let Ok(n) = res {
+ self.filled_until(n);
+ }
+ res
+ }
+}
+
+#[cfg(feature = "std")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "std")))]
+unsafe impl<T> WriteBuf for std::io::Cursor<T>
+where
+ T: WriteBuf,
+{
+ fn as_slice(&self) -> &[u8] {
+ &self.get_ref().as_slice()[self.position() as usize..]
+ }
+
+ fn capacity(&self) -> usize {
+ self.get_ref()
+ .capacity()
+ .saturating_sub(self.position() as usize)
+ }
+
+ fn as_mut_ptr(&mut self) -> *mut u8 {
+ let start = self.position() as usize;
+ assert!(start <= self.get_ref().capacity());
+ // Safety: start is still in the same memory allocation
+ unsafe { self.get_mut().as_mut_ptr().add(start) }
+ }
+
+ unsafe fn filled_until(&mut self, n: usize) {
+ // Early exit: `n = 0` does not indicate anything.
+ if n == 0 {
+ return;
+ }
+
+ // Here we assume data _before_ self.position() was already initialized.
+ // Egh it's not actually guaranteed by Cursor? So let's guarantee it ourselves.
+ let position = self.position() as usize;
+ let initialized = self.get_ref().as_slice().len();
+ if let Some(uninitialized) = position.checked_sub(initialized) {
+ // Cursor's solution is to pad with zeroes
+ // From the end of valid data (as_slice().len()) to the position.
+
+ // Safety:
+ // * We know `n > 0`
+ // * This means `self.capacity() > 0` (promise by the caller)
+ // * This means `self.get_ref().capacity() > self.position`
+ // * This means that `position` is within the nested pointer's allocation.
+ // * Finally, `initialized + uninitialized = position`, so the entire byte
+ // range here is within the allocation
+ unsafe {
+ self.get_mut()
+ .as_mut_ptr()
+ .add(initialized)
+ .write_bytes(0u8, uninitialized)
+ };
+ }
+
+ let start = self.position() as usize;
+ assert!(start + n <= self.get_ref().capacity());
+ self.get_mut().filled_until(start + n);
+ }
+}
+
+#[cfg(feature = "std")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "std")))]
+unsafe impl<'a> WriteBuf for &'a mut std::vec::Vec<u8> {
+ fn as_slice(&self) -> &[u8] {
+ std::vec::Vec::as_slice(self)
+ }
+
+ fn capacity(&self) -> usize {
+ std::vec::Vec::capacity(self)
+ }
+
+ fn as_mut_ptr(&mut self) -> *mut u8 {
+ std::vec::Vec::as_mut_ptr(self)
+ }
+
+ unsafe fn filled_until(&mut self, n: usize) {
+ std::vec::Vec::set_len(self, n)
+ }
+}
+
+#[cfg(feature = "std")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "std")))]
+unsafe impl WriteBuf for std::vec::Vec<u8> {
+ fn as_slice(&self) -> &[u8] {
+ &self[..]
+ }
+ fn capacity(&self) -> usize {
+ self.capacity()
+ }
+ fn as_mut_ptr(&mut self) -> *mut u8 {
+ self.as_mut_ptr()
+ }
+ unsafe fn filled_until(&mut self, n: usize) {
+ self.set_len(n);
+ }
+}
+
+#[cfg(feature = "arrays")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "arrays")))]
+unsafe impl<const N: usize> WriteBuf for [u8; N] {
+ fn as_slice(&self) -> &[u8] {
+ self
+ }
+ fn capacity(&self) -> usize {
+ self.len()
+ }
+
+ fn as_mut_ptr(&mut self) -> *mut u8 {
+ (&mut self[..]).as_mut_ptr()
+ }
+
+ unsafe fn filled_until(&mut self, _n: usize) {
+ // Assume the slice is already initialized
+ }
+}
+
+unsafe impl WriteBuf for [u8] {
+ fn as_slice(&self) -> &[u8] {
+ self
+ }
+ fn capacity(&self) -> usize {
+ self.len()
+ }
+
+ fn as_mut_ptr(&mut self) -> *mut u8 {
+ self.as_mut_ptr()
+ }
+
+ unsafe fn filled_until(&mut self, _n: usize) {
+ // Assume the slice is already initialized
+ }
+}
+
+/*
+// This is possible, but... why?
+unsafe impl<'a> WriteBuf for OutBuffer<'a, [u8]> {
+ fn as_slice(&self) -> &[u8] {
+ self.dst
+ }
+ fn capacity(&self) -> usize {
+ self.dst.len()
+ }
+ fn as_mut_ptr(&mut self) -> *mut u8 {
+ self.dst.as_mut_ptr()
+ }
+ unsafe fn filled_until(&mut self, n: usize) {
+ self.pos = n;
+ }
+}
+*/
+
+#[derive(Debug)]
+/// Wrapper around an output buffer.
+///
+/// `C` is usually either `[u8]` or `Vec<u8>`.
+///
+/// Bytes will be written starting at `dst[pos]`.
+///
+/// `pos` will be updated after writing.
+///
+/// # Invariant
+///
+/// `pos <= dst.capacity()`
+pub struct OutBuffer<'a, C: WriteBuf + ?Sized> {
+ pub dst: &'a mut C,
+ pos: usize,
+}
+
+/// Convenience method to get a mut pointer from a mut ref.
+fn ptr_mut<B>(ptr_void: &mut B) -> *mut B {
+ ptr_void as *mut B
+}
+
+/// Interface between a C-level ZSTD_outBuffer and a rust-level `OutBuffer`.
+///
+/// Will update the parent buffer from the C buffer on drop.
+struct OutBufferWrapper<'a, 'b, C: WriteBuf + ?Sized> {
+ buf: zstd_sys::ZSTD_outBuffer,
+ parent: &'a mut OutBuffer<'b, C>,
+}
+
+impl<'a, 'b: 'a, C: WriteBuf + ?Sized> Deref for OutBufferWrapper<'a, 'b, C> {
+ type Target = zstd_sys::ZSTD_outBuffer;
+
+ fn deref(&self) -> &Self::Target {
+ &self.buf
+ }
+}
+
+impl<'a, 'b: 'a, C: WriteBuf + ?Sized> DerefMut
+ for OutBufferWrapper<'a, 'b, C>
+{
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.buf
+ }
+}
+
+impl<'a, C: WriteBuf + ?Sized> OutBuffer<'a, C> {
+ /// Returns a new `OutBuffer` around the given slice.
+ ///
+ /// Starts with `pos = 0`.
+ pub fn around(dst: &'a mut C) -> Self {
+ OutBuffer { dst, pos: 0 }
+ }
+
+ /// Returns a new `OutBuffer` around the given slice, starting at the given position.
+ ///
+ /// # Panics
+ ///
+ /// If `pos >= dst.capacity()`.
+ pub fn around_pos(dst: &'a mut C, pos: usize) -> Self {
+ if pos >= dst.capacity() {
+ panic!("Given position outside of the buffer bounds.");
+ }
+
+ OutBuffer { dst, pos }
+ }
+
+ /// Returns the current cursor position.
+ pub fn pos(&self) -> usize {
+ self.pos
+ }
+
+ /// Sets the new cursor position.
+ ///
+ /// # Panics
+ ///
+ /// If `pos > self.dst.capacity()`.
+ ///
+ /// # Safety
+ ///
+ /// Data up to `pos` must have actually been written to.
+ pub unsafe fn set_pos(&mut self, pos: usize) {
+ if pos > self.dst.capacity() {
+ panic!("Given position outside of the buffer bounds.");
+ }
+
+ self.dst.filled_until(pos);
+
+ self.pos = pos;
+ }
+
+ fn wrap<'b>(&'b mut self) -> OutBufferWrapper<'b, 'a, C> {
+ OutBufferWrapper {
+ buf: zstd_sys::ZSTD_outBuffer {
+ dst: ptr_mut_void(self.dst),
+ size: self.dst.capacity(),
+ pos: self.pos,
+ },
+ parent: self,
+ }
+ }
+
+ /// Returns the part of this buffer that was written to.
+ pub fn as_slice<'b>(&'b self) -> &'a [u8]
+ where
+ 'b: 'a,
+ {
+ let pos = self.pos;
+ &self.dst.as_slice()[..pos]
+ }
+}
+
+impl<'a, 'b, C: WriteBuf + ?Sized> Drop for OutBufferWrapper<'a, 'b, C> {
+ fn drop(&mut self) {
+ // Safe because we guarantee that data until `self.buf.pos` has been written.
+ unsafe { self.parent.set_pos(self.buf.pos) };
+ }
+}
+
+struct InBufferWrapper<'a, 'b> {
+ buf: zstd_sys::ZSTD_inBuffer,
+ parent: &'a mut InBuffer<'b>,
+}
+
+impl<'a, 'b: 'a> Deref for InBufferWrapper<'a, 'b> {
+ type Target = zstd_sys::ZSTD_inBuffer;
+
+ fn deref(&self) -> &Self::Target {
+ &self.buf
+ }
+}
+
+impl<'a, 'b: 'a> DerefMut for InBufferWrapper<'a, 'b> {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.buf
+ }
+}
+
+impl<'a> InBuffer<'a> {
+ /// Returns a new `InBuffer` around the given slice.
+ ///
+ /// Starts with `pos = 0`.
+ pub fn around(src: &'a [u8]) -> Self {
+ InBuffer { src, pos: 0 }
+ }
+
+ /// Returns the current cursor position.
+ pub fn pos(&self) -> usize {
+ self.pos
+ }
+
+ /// Sets the new cursor position.
+ ///
+ /// # Panics
+ ///
+ /// If `pos > self.src.len()`.
+ pub fn set_pos(&mut self, pos: usize) {
+ if pos > self.src.len() {
+ panic!("Given position outside of the buffer bounds.");
+ }
+ self.pos = pos;
+ }
+
+ fn wrap<'b>(&'b mut self) -> InBufferWrapper<'b, 'a> {
+ InBufferWrapper {
+ buf: zstd_sys::ZSTD_inBuffer {
+ src: ptr_void(self.src),
+ size: self.src.len(),
+ pos: self.pos,
+ },
+ parent: self,
+ }
+ }
+}
+
+impl<'a, 'b> Drop for InBufferWrapper<'a, 'b> {
+ fn drop(&mut self) {
+ self.parent.set_pos(self.buf.pos);
+ }
+}
+
+/// A Decompression stream.
+///
+/// Same as `DCtx`.
+pub type DStream<'a> = DCtx<'a>;
+
+// Some functions work on a "frame prefix".
+// TODO: Define `struct FramePrefix(&[u8]);` and move these functions to it?
+//
+// Some other functions work on a dictionary (not CDict or DDict).
+// Same thing?
+
+/// Wraps the `ZSTD_findFrameCompressedSize()` function.
+///
+/// `src` should contain at least an entire frame.
+pub fn find_frame_compressed_size(src: &[u8]) -> SafeResult {
+ let code = unsafe {
+ zstd_sys::ZSTD_findFrameCompressedSize(ptr_void(src), src.len())
+ };
+ parse_code(code)
+}
+
+/// Wraps the `ZSTD_getFrameContentSize()` function.
+///
+/// Args:
+/// * `src`: A prefix of the compressed frame. It should at least include the frame header.
+///
+/// Returns:
+/// * `Err(ContentSizeError)` if `src` is too small of a prefix, or if it appears corrupted.
+/// * `Ok(None)` if the frame does not include a content size.
+/// * `Ok(Some(content_size_in_bytes))` otherwise.
+pub fn get_frame_content_size(
+ src: &[u8],
+) -> Result<Option<u64>, ContentSizeError> {
+ parse_content_size(unsafe {
+ zstd_sys::ZSTD_getFrameContentSize(ptr_void(src), src.len())
+ })
+}
+
+/// Wraps the `ZSTD_findDecompressedSize()` function.
+///
+/// `src` should be exactly a sequence of ZSTD frames.
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+pub fn find_decompressed_size(
+ src: &[u8],
+) -> Result<Option<u64>, ContentSizeError> {
+ parse_content_size(unsafe {
+ zstd_sys::ZSTD_findDecompressedSize(ptr_void(src), src.len())
+ })
+}
+
+/// Wraps the `ZSTD_isFrame()` function.
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+pub fn is_frame(buffer: &[u8]) -> bool {
+ unsafe { zstd_sys::ZSTD_isFrame(ptr_void(buffer), buffer.len()) > 0 }
+}
+
+/// Wraps the `ZSTD_getDictID_fromDict()` function.
+///
+/// Returns `None` if the dictionary is not a valid zstd dictionary.
+pub fn get_dict_id_from_dict(dict: &[u8]) -> Option<NonZeroU32> {
+ NonZeroU32::new(unsafe {
+ zstd_sys::ZSTD_getDictID_fromDict(ptr_void(dict), dict.len()) as u32
+ })
+}
+
+/// Wraps the `ZSTD_getDictID_fromFrame()` function.
+///
+/// Returns `None` if the dictionary ID could not be decoded. This may happen if:
+/// * The frame was not encoded with a dictionary.
+/// * The frame intentionally did not include dicionary ID.
+/// * The dictionary was non-conformant.
+/// * `src` is too small and does not include the frame header.
+/// * `src` is not a valid zstd frame prefix.
+pub fn get_dict_id_from_frame(src: &[u8]) -> Option<NonZeroU32> {
+ NonZeroU32::new(unsafe {
+ zstd_sys::ZSTD_getDictID_fromFrame(ptr_void(src), src.len()) as u32
+ })
+}
+
+/// What kind of context reset should be applied.
+pub enum ResetDirective {
+ /// Only the session will be reset.
+ ///
+ /// All parameters will be preserved (including the dictionary).
+ /// But any frame being processed will be dropped.
+ ///
+ /// It can be useful to start re-using a context after an error or when an
+ /// ongoing compression is no longer needed.
+ SessionOnly,
+
+ /// Only reset parameters (including dictionary or referenced prefix).
+ ///
+ /// All parameters will be reset to default values.
+ ///
+ /// This can only be done between sessions - no compression or decompression must be ongoing.
+ Parameters,
+
+ /// Reset both the session and parameters.
+ ///
+ /// The result is similar to a newly created context.
+ SessionAndParameters,
+}
+
+impl ResetDirective {
+ fn as_sys(self) -> zstd_sys::ZSTD_ResetDirective {
+ match self {
+ ResetDirective::SessionOnly => zstd_sys::ZSTD_ResetDirective::ZSTD_reset_session_only,
+ ResetDirective::Parameters => zstd_sys::ZSTD_ResetDirective::ZSTD_reset_parameters,
+ ResetDirective::SessionAndParameters => zstd_sys::ZSTD_ResetDirective::ZSTD_reset_session_and_parameters,
+ }
+ }
+}
+
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[repr(u32)]
+pub enum FrameFormat {
+ /// Regular zstd format.
+ One = zstd_sys::ZSTD_format_e::ZSTD_f_zstd1 as u32,
+
+ /// Skip the 4 bytes identifying the content as zstd-compressed data.
+ Magicless = zstd_sys::ZSTD_format_e::ZSTD_f_zstd1_magicless as u32,
+}
+
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[repr(u32)]
+pub enum DictAttachPref {
+ DefaultAttach =
+ zstd_sys::ZSTD_dictAttachPref_e::ZSTD_dictDefaultAttach as u32,
+ ForceAttach = zstd_sys::ZSTD_dictAttachPref_e::ZSTD_dictForceAttach as u32,
+ ForceCopy = zstd_sys::ZSTD_dictAttachPref_e::ZSTD_dictForceCopy as u32,
+ ForceLoad = zstd_sys::ZSTD_dictAttachPref_e::ZSTD_dictForceLoad as u32,
+}
+
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[repr(u32)]
+pub enum ParamSwitch {
+ Auto = zstd_sys::ZSTD_paramSwitch_e::ZSTD_ps_auto as u32,
+ Enable = zstd_sys::ZSTD_paramSwitch_e::ZSTD_ps_enable as u32,
+ Disable = zstd_sys::ZSTD_paramSwitch_e::ZSTD_ps_disable as u32,
+}
+
+/// A compression parameter.
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum CParameter {
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ RSyncable(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ Format(FrameFormat),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ ForceMaxWindow(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ ForceAttachDict(DictAttachPref),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ LiteralCompressionMode(ParamSwitch),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ TargetCBlockSize(u32),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ SrcSizeHint(u32),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ EnableDedicatedDictSearch(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ StableInBuffer(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ StableOutBuffer(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ BlockDelimiters(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ ValidateSequences(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ UseBlockSplitter(ParamSwitch),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ UseRowMatchFinder(ParamSwitch),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ DeterministicRefPrefix(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ PrefetchCDictTables(ParamSwitch),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ EnableSeqProducerFallback(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ MaxBlockSize(u32),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ SearchForExternalRepcodes(ParamSwitch),
+
+ /// Compression level to use.
+ ///
+ /// Compression levels are global presets for the other compression parameters.
+ CompressionLevel(CompressionLevel),
+
+ /// Maximum allowed back-reference distance.
+ ///
+ /// The actual distance is 2 power "this value".
+ WindowLog(u32),
+
+ HashLog(u32),
+
+ ChainLog(u32),
+
+ SearchLog(u32),
+
+ MinMatch(u32),
+
+ TargetLength(u32),
+
+ Strategy(Strategy),
+
+ EnableLongDistanceMatching(bool),
+
+ LdmHashLog(u32),
+
+ LdmMinMatch(u32),
+
+ LdmBucketSizeLog(u32),
+
+ LdmHashRateLog(u32),
+
+ ContentSizeFlag(bool),
+
+ ChecksumFlag(bool),
+
+ DictIdFlag(bool),
+
+ /// How many threads will be spawned.
+ ///
+ /// With a default value of `0`, `compress_stream*` functions block until they complete.
+ ///
+ /// With any other value (including 1, a single compressing thread), these methods directly
+ /// return, and the actual compression is done in the background (until a flush is requested).
+ ///
+ /// Note: this will only work if the `zstdmt` feature is activated.
+ NbWorkers(u32),
+
+ /// Size in bytes of a compression job.
+ ///
+ /// Does not have any effect when `NbWorkers` is set to 0.
+ ///
+ /// The default value of 0 finds the best job size based on the compression parameters.
+ ///
+ /// Note: this will only work if the `zstdmt` feature is activated.
+ JobSize(u32),
+
+ /// Specifies how much overlap must be given to each worker.
+ ///
+ /// Possible values:
+ ///
+ /// * `0` (default value): automatic overlap based on compression strategy.
+ /// * `1`: No overlap
+ /// * `1 < n < 9`: Overlap a fraction of the window size, defined as `1/(2 ^ 9-n)`.
+ /// * `9`: Full overlap (as long as the window)
+ /// * `9 < m`: Will return an error.
+ ///
+ /// Note: this will only work if the `zstdmt` feature is activated.
+ OverlapSizeLog(u32),
+}
+
+/// A decompression parameter.
+pub enum DParameter {
+ WindowLogMax(u32),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ /// See `FrameFormat`.
+ Format(FrameFormat),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ StableOutBuffer(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ ForceIgnoreChecksum(bool),
+
+ #[cfg(feature = "experimental")]
+ #[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+ RefMultipleDDicts(bool),
+}
+
+/// Wraps the `ZDICT_trainFromBuffer()` function.
+#[cfg(feature = "zdict_builder")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "zdict_builder")))]
+pub fn train_from_buffer<C: WriteBuf + ?Sized>(
+ dict_buffer: &mut C,
+ samples_buffer: &[u8],
+ samples_sizes: &[usize],
+) -> SafeResult {
+ assert_eq!(samples_buffer.len(), samples_sizes.iter().sum());
+
+ unsafe {
+ dict_buffer.write_from(|buffer, capacity| {
+ parse_code(zstd_sys::ZDICT_trainFromBuffer(
+ buffer,
+ capacity,
+ ptr_void(samples_buffer),
+ samples_sizes.as_ptr(),
+ samples_sizes.len() as u32,
+ ))
+ })
+ }
+}
+
+/// Wraps the `ZDICT_getDictID()` function.
+#[cfg(feature = "zdict_builder")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "zdict_builder")))]
+pub fn get_dict_id(dict_buffer: &[u8]) -> Option<NonZeroU32> {
+ NonZeroU32::new(unsafe {
+ zstd_sys::ZDICT_getDictID(ptr_void(dict_buffer), dict_buffer.len())
+ })
+}
+
+/// Wraps the `ZSTD_getBlockSize()` function.
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+pub fn get_block_size(cctx: &CCtx) -> usize {
+ unsafe { zstd_sys::ZSTD_getBlockSize(cctx.0.as_ptr()) }
+}
+
+/// Wraps the `ZSTD_decompressBound` function
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+pub fn decompress_bound(data: &[u8]) -> Result<u64, ErrorCode> {
+ let bound =
+ unsafe { zstd_sys::ZSTD_decompressBound(ptr_void(data), data.len()) };
+ if is_error(bound as usize) {
+ Err(bound as usize)
+ } else {
+ Ok(bound)
+ }
+}
+
+/// Given a buffer of size `src_size`, returns the maximum number of sequences that can ge
+/// generated.
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+pub fn sequence_bound(src_size: usize) -> usize {
+ // Safety: Just FFI.
+ unsafe { zstd_sys::ZSTD_sequenceBound(src_size) }
+}
+
+/// Returns the minimum extra space when output and input buffer overlap.
+///
+/// When using in-place decompression, the output buffer must be at least this much bigger (in
+/// bytes) than the input buffer. The extra space must be at the front of the output buffer (the
+/// input buffer must be at the end of the output buffer).
+#[cfg(feature = "experimental")]
+#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "experimental")))]
+pub fn decompression_margin(
+ compressed_data: &[u8],
+) -> Result<usize, ErrorCode> {
+ parse_code(unsafe {
+ zstd_sys::ZSTD_decompressionMargin(
+ ptr_void(compressed_data),
+ compressed_data.len(),
+ )
+ })
+}
projects / platform / upstream / rust-zstd-safe.git / commitdiff