1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
/*
* ZXC - High-performance lossless compression
*
* Copyright (c) 2025-2026 Bertrand Lebonnois and contributors.
* SPDX-License-Identifier: BSD-3-Clause
*/
/**
* @file zxc_buffer.h
* @brief Buffer-based (single-shot) compression and decompression API.
*
* This header exposes the simplest way to use ZXC: pass an entire input buffer
* and receive the result in a single output buffer. All functions in this
* header are single-threaded and blocking.
*
* @par Typical usage
* @code
* // Compress
* size_t bound = zxc_compress_bound(src_size);
* void *dst = malloc(bound);
* zxc_compress_opts_t opts = { .level = ZXC_LEVEL_DEFAULT, .checksum = 1 };
* int64_t csize = zxc_compress(src, src_size, dst, bound, &opts);
*
* // Decompress
* uint64_t orig = zxc_get_decompressed_size(dst, csize);
* void *out = malloc(orig);
* zxc_decompress_opts_t dopts = { .checksum = 1 };
* int64_t dsize = zxc_decompress(dst, csize, out, orig, &dopts);
* @endcode
*
* @see zxc_stream.h for the streaming (multi-threaded) API.
* @see zxc_sans_io.h for the low-level sans-I/O building blocks.
*/
#ifndef ZXC_BUFFER_H
#define ZXC_BUFFER_H
#include <stddef.h>
#include <stdint.h>
#include "zxc_export.h"
#include "zxc_stream.h" /* zxc_compress_opts_t, zxc_decompress_opts_t */
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup buffer_api Buffer API
* @brief Single-shot, buffer-based compression and decompression.
* @{
*/
/**
* @brief Calculates the maximum theoretical compressed size for a given input.
*
* Useful for allocating output buffers before compression.
* Accounts for file headers, block headers, and potential expansion
* of incompressible data.
*
* @param[in] input_size Size of the input data in bytes.
*
* @return Maximum required buffer size in bytes.
*/
ZXC_EXPORT uint64_t zxc_compress_bound(const size_t input_size);
/**
* @brief Compresses a data buffer using the ZXC algorithm.
*
* This version uses standard size_t types and void pointers.
* It executes in a single thread (blocking operation).
* It writes the ZXC file header followed by compressed blocks.
*
* @param[in] src Pointer to the source buffer.
* @param[in] src_size Size of the source data in bytes.
* @param[out] dst Pointer to the destination buffer.
* @param[in] dst_capacity Maximum capacity of the destination buffer.
* @param[in] opts Compression options (NULL uses all defaults).
* Only @c level, @c block_size, and @c checksum are used.
*
* @return The number of bytes written to dst (>0 on success),
* or a negative zxc_error_t code (e.g., ZXC_ERROR_DST_TOO_SMALL) on failure.
*/
ZXC_EXPORT int64_t zxc_compress(const void* src, const size_t src_size, void* dst,
const size_t dst_capacity, const zxc_compress_opts_t* opts);
/**
* @brief Decompresses a ZXC compressed buffer.
*
* This version uses standard size_t types and void pointers.
* It executes in a single thread (blocking operation).
* It expects a valid ZXC file header followed by compressed blocks.
*
* @param[in] src Pointer to the source buffer containing compressed data.
* @param[in] src_size Size of the compressed data in bytes.
* @param[out] dst Pointer to the destination buffer.
* @param[in] dst_capacity Capacity of the destination buffer.
* @param[in] opts Decompression options (NULL uses all defaults).
* Only @c checksum is used.
*
* @return The number of bytes written to dst (>0 on success),
* or a negative zxc_error_t code (e.g., ZXC_ERROR_CORRUPT_DATA) on failure.
*/
ZXC_EXPORT int64_t zxc_decompress(const void* src, const size_t src_size, void* dst,
const size_t dst_capacity, const zxc_decompress_opts_t* opts);
/**
* @brief Returns the decompressed size stored in a ZXC compressed buffer.
*
* This function reads the file footer to extract the original uncompressed size
* without performing any decompression. Useful for allocating output buffers.
*
* @param[in] src Pointer to the compressed data buffer.
* @param[in] src_size Size of the compressed data in bytes.
*
* @return The original uncompressed size in bytes, or 0 if the buffer is invalid
* or too small to contain a valid ZXC archive.
*/
ZXC_EXPORT uint64_t zxc_get_decompressed_size(const void* src, const size_t src_size);
/* ========================================================================= */
/* Reusable Context API (opaque, heap-allocated) */
/* ========================================================================= */
/**
* @defgroup context_api Reusable Context API
* @brief Opaque, reusable compression / decompression contexts.
*
* This API eliminates per-call allocation overhead by letting callers retain
* a context across multiple operations. The internal layout is hidden behind
* an opaque pointer.
*
* @{
*/
/* --- Compression context ------------------------------------------------- */
/** @brief Opaque compression context (forward-declared). */
typedef struct zxc_cctx_s zxc_cctx;
/**
* @brief Creates a new reusable compression context.
*
* When @p opts is non-NULL the context pre-allocates all internal buffers
* using the supplied level, block_size, and checksum_enabled settings.
* When @p opts is NULL, allocation is deferred to the first call to
* zxc_compress_cctx().
*
* The returned context must be freed with zxc_free_cctx().
*
* @param[in] opts Compression options for eager init, or NULL for lazy init.
* @return Pointer to the new context, or @c NULL on allocation failure.
*/
ZXC_EXPORT zxc_cctx* zxc_create_cctx(const zxc_compress_opts_t* opts);
/**
* @brief Frees a compression context and all associated resources.
*
* It is safe to pass @c NULL; the call is a no-op in that case.
*
* @param[in] cctx Context to free.
*/
ZXC_EXPORT void zxc_free_cctx(zxc_cctx* cctx);
/**
* @brief Compresses data using a reusable context.
*
* Identical to zxc_compress() but reuses the internal buffers from @p cctx,
* avoiding per-call malloc/free overhead. The context automatically
* re-initializes when block_size or level changes between calls.
*
* Options are **sticky**: settings passed via @p opts are remembered and
* reused on subsequent calls where @p opts is NULL. The initial sticky
* values come from the @p opts passed to zxc_create_cctx().
*
* @param[in,out] cctx Reusable compression context.
* @param[in] src Source data.
* @param[in] src_size Source data size in bytes.
* @param[out] dst Destination buffer.
* @param[in] dst_capacity Capacity of the destination buffer.
* @param[in] opts Compression options, or NULL to reuse
* settings from create / last call.
*
* @return Compressed size in bytes (> 0) on success,
* or a negative @ref zxc_error_t code on failure.
*/
ZXC_EXPORT int64_t zxc_compress_cctx(zxc_cctx* cctx, const void* src, size_t src_size, void* dst,
size_t dst_capacity, const zxc_compress_opts_t* opts);
/* --- Decompression context ----------------------------------------------- */
/** @brief Opaque decompression context (forward-declared). */
typedef struct zxc_dctx_s zxc_dctx;
/**
* @brief Creates a new reusable decompression context.
*
* @return Pointer to the new context, or @c NULL on allocation failure.
*/
ZXC_EXPORT zxc_dctx* zxc_create_dctx(void);
/**
* @brief Frees a decompression context and all associated resources.
*
* It is safe to pass @c NULL.
*
* @param[in] dctx Context to free.
*/
ZXC_EXPORT void zxc_free_dctx(zxc_dctx* dctx);
/**
* @brief Decompresses data using a reusable context.
*
* Identical to zxc_decompress() but reuses buffers from @p dctx.
*
* @param[in,out] dctx Reusable decompression context.
* @param[in] src Compressed data.
* @param[in] src_size Compressed data size in bytes.
* @param[out] dst Destination buffer.
* @param[in] dst_capacity Capacity of the destination buffer.
* @param[in] opts Decompression options (NULL for defaults).
*
* @return Decompressed size in bytes (> 0) on success,
* or a negative @ref zxc_error_t code on failure.
*/
ZXC_EXPORT int64_t zxc_decompress_dctx(zxc_dctx* dctx, const void* src, size_t src_size, void* dst,
size_t dst_capacity, const zxc_decompress_opts_t* opts);
/** @} */ /* end of context_api */
/** @} */ /* end of buffer_api */
#ifdef __cplusplus
}
#endif
#endif // ZXC_BUFFER_H
|
