Skip to content

Compress

Lifetime Management

ZL_CCtx* ZL_CCtx_create(void);

void ZL_CCtx_free(ZL_CCtx* cctx);

CCtx Compression

size_t ZL_compressBound(size_t totalSrcSize);

Provides the upper bound for the compressed size needed to ensure that compressing totalSrcSize is successful. When compressing multiple inputs, totalSrcSize must be the sum of the size of each input.

Parameters:

  • totalSrcSize –

    The sum of all input sizes

Returns:

The upper bound of the compressed size

Note

This is a very large over-estimation, to be tightened later 

ZL_Report ZL_CCtx_compress(ZL_CCtx* cctx, void* dst, size_t dstCapacity,
                           const void* src, size_t srcSize);

A one-shot (blocking) compression function.

Parameters:

  • dst –

    The destination buffer to write the compressed data to

  • dstCapacity –

    The capacity of the destination buffer

  • src –

    The source buffer to compress

  • srcSize –

    The size of the source buffer

Returns:

The number of bytes written into dst, if successful. Otherwise, returns an error. 

ZL_Report ZL_CCtx_compressTypedRef(ZL_CCtx* cctx, void* dst, size_t dstCapacity,
                                   const ZL_TypedRef* input);

Compresses a single typed input presented as a ZL_TypedRef. See below for TypedRef* object creation.

Parameters:

  • dst –

    The destination buffer to write the compressed data to

  • dstCapacity –

    The capacity of the destination buffer

  • input –

    The input to compress

Returns:

The number of bytes written into dst, if successful. Otherwise, returns an error. 

ZL_Report ZL_CCtx_compressMultiTypedRef(ZL_CCtx* cctx, void* dst,
                                        size_t dstCapacity,
                                        const ZL_TypedRef* inputs,
                                        size_t nbInputs);

Compresses multiple typed inputs , presented as an array of ZL_TypedRef. See below for TypedRef* object creation.

Parameters:

  • dst –

    The destination buffer to write the compressed data to

  • dstCapacity –

    The capacity of the destination buffer

  • inputs –

    The inputs to compress

  • nbInputs –

    The number of inputs to compress

Returns:

The number of bytes written into dst, if successful. Otherwise, returns an error.

Note

These inputs will be regenerated together in the same order at decompression time.

Errors and Warnings

const char* ZL_CCtx_getErrorContextString(const ZL_CCtx* cctx,
                                          ZL_Report report);

Gets the error context for a given ZL_Report. This context is useful for debugging and for submitting bug reports to Zstrong developers.

Parameters:

  • report –

    The report to get the error context for

Returns:

A verbose error string containing context about the error that occurred.

Note

: This string is stored within the cctx and is only valid for the lifetime of the cctx. 

const char* ZL_CCtx_getErrorContextString_fromError(const ZL_CCtx* cctx,
                                                    ZL_Error error);

See ZL_CCtx_getErrorContextString()

Parameters:

  • error –

    The error to get the context for 

ZL_Error_Array ZL_CCtx_getWarnings(const ZL_CCtx* cctx);

Gets the warnings that were encountered during the lifetime of the most recent compression operation.

Returns:

The array of warnings encountered

Note

The array's and the errors' lifetimes are valid until the next compression operation.

Typed Inputs

ZL_TypedRef* ZL_TypedRef_createSerial(const void* src, size_t srcSize);

Creates a ZL_TypedRef that represents a regular buffer of bytes.

Parameters:

  • src –

    The reference buffer

  • srcSize –

    The size of the reference buffer

Returns:

A ZL_TypedRef* of type ZL_Type_serial. 

ZL_TypedRef* ZL_TypedRef_createStruct(const void* start, size_t structWidth,
                                      size_t structCount);

Creates a ZL_TypedRef that represents a concatenated list of fields of a fixed size of structWidth.

structWidth can be any size > 0. Even odd sizes (13, 17, etc.) are allowed. All fields are considered concatenated back to back. There is no alignment requirement.

Parameters:

  • start –

    The start of the reference buffer

  • structWidth –

    The width of each element in the reference buffer.

  • structCount –

    The number of elements in the input buffer. The total size will be structWidth * structCount.

Note

Struct in this case is just short-hand for fixed-size-fields. It's not limited to C-style structures. 

ZL_TypedRef* ZL_TypedRef_createNumeric(const void* start, size_t numWidth,
                                       size_t numCount);

Creates a ZL_TypedRef that references an array of numeric values, employing the local host's endianness. Supported widths are 1, 2, 4, and 8 and the input array must be properly aligned (in local ABI).

Parameters:

  • start –

    The start of the reference array

  • numWidth –

    The width of the numeric values

  • numCount –

    The number of elements in the input array. The total size will be numWidth * numCount. 

ZL_TypedRef* ZL_TypedRef_createString(const void* strBuffer, size_t bufferSize,
                                      const uint32_t* strLens,
                                      size_t nbStrings);

Creates a ZL_TypedRef referencing a "flat-strings" representation. All "strings" are concatenated into strBuffer and their lengths are stored in a strLens array.

Parameters:

  • strBuffer –

    The data buffer

  • bufferSize –

    The size of the data buffer

  • strLengths –

    The lengths array

  • nbStrings –

    The number of strings (i.e. the size of the lengths array)

Note

String is just short-hand for variable-size-fields. It's not limited to null-terminated ascii strings. A string can be any blob of bytes, including some containing 0-value bytes, because length is explicit. 

void ZL_TypedRef_free(ZL_TypedRef* tref);

Frees the given ZL_TypedRef.

Parameters:

  • tref –

    the object to free

Note

All ZL_TypedRef* objects of any type are released by the same method

Compression Parameters

ZL_Report ZL_CCtx_setParameter(ZL_CCtx* cctx, ZL_CParam gcparam, int value);

Sets a global compression parameter via the CCtx.

Parameters:

  • gcparam –

    The global compression parameter to set

  • value –

    The value to set the global compression parameter to

Returns:

A ZL_Report containing the result of the operation

Note

Parameters set via CCtx have higher priority than parameters set via CGraph.

Note

By default, parameters set via CCtx are reset at the end of the compression session. To preserve them across sessions, set stickyParameters=1. 

int ZL_CCtx_getParameter(const ZL_CCtx* cctx, ZL_CParam gcparam);

Reads a compression parameter's configured value from the CCtx.

Parameters:

  • gcparam –

    The global compression parameter to read

Returns:

The value set for the given parameter (0 if unset or does not exist) 

ZL_Report ZL_CCtx_resetParameters(ZL_CCtx* cctx);

Resets the parameters in the cctx to a blank state.

Note

Useful when unsure if ZL_CParam_stickyParameters is set to 1. 

ZL_Report ZL_CCtx_setDataArena(ZL_CCtx* cctx, ZL_DataArenaType sat);

Sets the Arena for Data* objects in the CCtx. This frees the previous Data Arena and creates a new one. This choice remains sticky, until set again. The default Data Arena is HeapArena.

Parameters:

  • sat –

    The Data Arena type to set

Note

This is an advanced (experimental) parameter. 

enum ZL_CParam

The list of global compression parameters. 

ZL_CParam_stickyParameters = 1

Only meaningful at CCtx level (ignored at CGraph level) By default, parameters are reset between compression sessions setting this parameter to 1 keep the parameters across compression sessions. 

ZL_CParam_compressionLevel = 2

Scale amplitude to determine. 

ZL_CParam_decompressionLevel = 3

Scale amplitude to determine. 

ZL_CParam_formatVersion = 4

Sets the format version number to use for encoding. See @ZL_getDefaultEncodingVersion for details. @default 0 means use format version ZL_getDefaultEncodingVersion(). 

ZL_CParam_permissiveCompression = 5

Select behavior when an internal compression stage fails. For example, when expecting an array of 32-bit integers, but the input size is not a clean multiple of 4. Strict mode stops at such stage and outputs an error. Permissive mode engages a generic backup compression mechanism, to successfully complete compression, at the cost of efficiency. At the time of this writing, backup is ZL_GRAPH_COMPRESS_GENERIC. Valid values for this parameter use the ZS2_cv3_* format. @default 0 currently means strict mode. This may change in the future. 

ZL_CParam_compressedChecksum = 6

Enable checksum of the compressed frame. This is useful to check for corruption that happens after compression. Valid values for this parameter use the ZS2_cv3_* format. @default 0 currently means checksum, might change in the future. 

ZL_CParam_contentChecksum = 7

Enable checksum of the uncompressed content contained in the frame. This is useful to check for corruption that happens after compression, or corruption introduced during (de)compression. However, it cannot distinguish the two alone. In order to determine whether it is corruption or a bug in the ZStrong library, you have to enable both compressed and content checksums. Valid values for this parameter use the ZS2_cv3_* format. @default 0 currently means checksum, might change in the future. 

ZL_CParam_minStreamSize = 11

Any time an internal data Stream becomes smaller than this size, it gets STORED immediately, without further processing. This reduces processing time, improves decompression speed, and reduce risks of data expansion. Note(@Cyan): follows convention that setting 0 means "default", aka ZL_MINSTREAMSIZE_DEFAULT. Therefore, in order to completely disable the "automatic store" feature, one must pass a negative threshold value.