Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_zip_create (3DAX)

Name

dax_zip_create - create a codec from symbols

Synopsis

cc [ flag... ] file... -ldax [ library...]

#include <dax.h>

dax_status_t
dax_zip_create(dax_context_t *ctx, uint16_t nsyms, uint8_t widths[],
    void *syms, dax_zip_t **codec);

Description

This function creates a zip encoder/decoder for use in libdax functions that zip and unzip data and returns it in codec. The number of symbols in the codec is nsyms, which may be any value from 1 to 1024 symbols. The code word width is the same for all symbols, and has ceil(log2(nsyms)) bits.

Each code word from 0 to 1023 represents a symbol with a width ranging from 1 to 8 bytes. The symbol for code word i is hereafter referred to as symbol i. It reads the bytes of all symbols from syms, starting with the bytes of symbol 0 from its leftmost to rightmost bytes, followed by the bytes of symbol 1, and so on, with no padding or termination in between.

widths is a vector of 4-bit values with 2 values packed per byte. Its element number increases from high to low nibble within each byte, and from low to high address across bytes. The ith element of widths gives the width in bytes of symbol i. The size of widths is ceil(nsyms/2) bytes. If nsyms is odd, the last nibble must be 0.

The widths have the following constraints:

  • Each width must be a value from 1 to 8 bytes.

  • In libdax version 1, for i from 0 to 255, width(i) + width(i+256) + width(i+512) + width(i+768) <= 14. If an index exceeds nsyms - 1, the corresponding term is 0.

  • In libdax version 2, 2 + (nsyms + 1) / 2 + sum(syms widths) <= 8192

The libdax library only checks these conditions if the DAX_DEBUG_EXTRA debug option is set. If violation of the conditions occur and are not checked, you will get undefined results.

On return, the caller can change or free the data in widths and syms without affecting the returned codec.

Return Values

DAX_SUCCESS

Operation completed successfully

DAX_EINVAL

Invalid argument

DAX_ENOMEM

Memory resources are unavailable

DAX_ETHREAD

The calling thread did not create ctx

Usage

This function is useful for applications that need to derive their own encoding schemes, with different space and time requirements and compression ratios than those provided by the dax_encode() function.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library
Interface Stability
Committed

See Also

dax_zip_free(3DAX), dax_zip_create_contig(3DAX), dax_zip(3DAX), dax_encode(3DAX), libdax(3LIB)