Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/libdeflate.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 /*
2 * libdeflate.h - public header for libdeflate
3 */
4
5 #ifndef LIBDEFLATE_H
6 #define LIBDEFLATE_H
7
8 #include <stddef.h>
9 #include <stdint.h>
10
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14
15 #define LIBDEFLATE_VERSION_MAJOR 1
16 #define LIBDEFLATE_VERSION_MINOR 17
17 #define LIBDEFLATE_VERSION_STRING "1.17"
18
19 /*
20 * Users of libdeflate.dll on Windows can define LIBDEFLATE_DLL to cause
21 * __declspec(dllimport) to be used. This should be done when it's easy to do.
22 * Otherwise it's fine to skip it, since it is a very minor performance
23 * optimization that is irrelevant for most use cases of libdeflate.
24 */
25 #ifndef LIBDEFLATEAPI
26 # if defined(LIBDEFLATE_DLL) && (defined(_WIN32) || defined(__CYGWIN__))
27 # define LIBDEFLATEAPI __declspec(dllimport)
28 # else
29 # define LIBDEFLATEAPI
30 # endif
31 #endif
32
33 /* ========================================================================== */
34 /* Compression */
35 /* ========================================================================== */
36
37 struct libdeflate_compressor;
38
39 /*
40 * libdeflate_alloc_compressor() allocates a new compressor that supports
41 * DEFLATE, zlib, and gzip compression. 'compression_level' is the compression
42 * level on a zlib-like scale but with a higher maximum value (1 = fastest, 6 =
43 * medium/default, 9 = slow, 12 = slowest). Level 0 is also supported and means
44 * "no compression", specifically "create a valid stream, but only emit
45 * uncompressed blocks" (this will expand the data slightly).
46 *
47 * The return value is a pointer to the new compressor, or NULL if out of memory
48 * or if the compression level is invalid (i.e. outside the range [0, 12]).
49 *
50 * Note: for compression, the sliding window size is defined at compilation time
51 * to 32768, the largest size permissible in the DEFLATE format. It cannot be
52 * changed at runtime.
53 *
54 * A single compressor is not safe to use by multiple threads concurrently.
55 * However, different threads may use different compressors concurrently.
56 */
57 LIBDEFLATEAPI struct libdeflate_compressor *
58 libdeflate_alloc_compressor(int compression_level);
59
60 /*
61 * libdeflate_deflate_compress() performs raw DEFLATE compression on a buffer of
62 * data. It attempts to compress 'in_nbytes' bytes of data located at 'in' and
63 * write the result to 'out', which has space for 'out_nbytes_avail' bytes. The
64 * return value is the compressed size in bytes, or 0 if the data could not be
65 * compressed to 'out_nbytes_avail' bytes or fewer (but see note below).
66 *
67 * If compression is successful, then the output data is guaranteed to be a
68 * valid DEFLATE stream that decompresses to the input data. No other
69 * guarantees are made about the output data. Notably, different versions of
70 * libdeflate can produce different compressed data for the same uncompressed
71 * data, even at the same compression level. Do ***NOT*** do things like
72 * writing tests that compare compressed data to a golden output, as this can
73 * break when libdeflate is updated. (This property isn't specific to
74 * libdeflate; the same is true for zlib and other compression libraries too.)
75 *
76 * Note: due to a performance optimization, libdeflate_deflate_compress()
77 * currently needs a small amount of slack space at the end of the output
78 * buffer. As a result, it can't actually report compressed sizes very close to
79 * 'out_nbytes_avail'. This doesn't matter in real-world use cases, and
80 * libdeflate_deflate_compress_bound() already includes the slack space.
81 * However, it does mean that testing code that redundantly compresses data
82 * using an exact-sized output buffer won't work as might be expected:
83 *
84 * out_nbytes = libdeflate_deflate_compress(c, in, in_nbytes, out,
85 * libdeflate_deflate_compress_bound(in_nbytes));
86 * // The following assertion will fail.
87 * assert(libdeflate_deflate_compress(c, in, in_nbytes, out, out_nbytes) != 0);
88 *
89 * To avoid this, either don't write tests like the above, or make sure to
90 * include at least 9 bytes of slack space in 'out_nbytes_avail'.
91 */
92 LIBDEFLATEAPI size_t
93 libdeflate_deflate_compress(struct libdeflate_compressor *compressor,
94 const void *in, size_t in_nbytes,
95 void *out, size_t out_nbytes_avail);
96
97 /*
98 * libdeflate_deflate_compress_bound() returns a worst-case upper bound on the
99 * number of bytes of compressed data that may be produced by compressing any
100 * buffer of length less than or equal to 'in_nbytes' using
101 * libdeflate_deflate_compress() with the specified compressor. This bound will
102 * necessarily be a number greater than or equal to 'in_nbytes'. It may be an
103 * overestimate of the true upper bound. The return value is guaranteed to be
104 * the same for all invocations with the same compressor and same 'in_nbytes'.
105 *
106 * As a special case, 'compressor' may be NULL. This causes the bound to be
107 * taken across *any* libdeflate_compressor that could ever be allocated with
108 * this build of the library, with any options.
109 *
110 * Note that this function is not necessary in many applications. With
111 * block-based compression, it is usually preferable to separately store the
112 * uncompressed size of each block and to store any blocks that did not compress
113 * to less than their original size uncompressed. In that scenario, there is no
114 * need to know the worst-case compressed size, since the maximum number of
115 * bytes of compressed data that may be used would always be one less than the
116 * input length. You can just pass a buffer of that size to
117 * libdeflate_deflate_compress() and store the data uncompressed if
118 * libdeflate_deflate_compress() returns 0, indicating that the compressed data
119 * did not fit into the provided output buffer.
120 */
121 LIBDEFLATEAPI size_t
122 libdeflate_deflate_compress_bound(struct libdeflate_compressor *compressor,
123 size_t in_nbytes);
124
125 /*
126 * Like libdeflate_deflate_compress(), but uses the zlib wrapper format instead
127 * of raw DEFLATE.
128 */
129 LIBDEFLATEAPI size_t
130 libdeflate_zlib_compress(struct libdeflate_compressor *compressor,
131 const void *in, size_t in_nbytes,
132 void *out, size_t out_nbytes_avail);
133
134 /*
135 * Like libdeflate_deflate_compress_bound(), but assumes the data will be
136 * compressed with libdeflate_zlib_compress() rather than with
137 * libdeflate_deflate_compress().
138 */
139 LIBDEFLATEAPI size_t
140 libdeflate_zlib_compress_bound(struct libdeflate_compressor *compressor,
141 size_t in_nbytes);
142
143 /*
144 * Like libdeflate_deflate_compress(), but uses the gzip wrapper format instead
145 * of raw DEFLATE.
146 */
147 LIBDEFLATEAPI size_t
148 libdeflate_gzip_compress(struct libdeflate_compressor *compressor,
149 const void *in, size_t in_nbytes,
150 void *out, size_t out_nbytes_avail);
151
152 /*
153 * Like libdeflate_deflate_compress_bound(), but assumes the data will be
154 * compressed with libdeflate_gzip_compress() rather than with
155 * libdeflate_deflate_compress().
156 */
157 LIBDEFLATEAPI size_t
158 libdeflate_gzip_compress_bound(struct libdeflate_compressor *compressor,
159 size_t in_nbytes);
160
161 /*
162 * libdeflate_free_compressor() frees a compressor that was allocated with
163 * libdeflate_alloc_compressor(). If a NULL pointer is passed in, no action is
164 * taken.
165 */
166 LIBDEFLATEAPI void
167 libdeflate_free_compressor(struct libdeflate_compressor *compressor);
168
169 /* ========================================================================== */
170 /* Decompression */
171 /* ========================================================================== */
172
173 struct libdeflate_decompressor;
174
175 /*
176 * libdeflate_alloc_decompressor() allocates a new decompressor that can be used
177 * for DEFLATE, zlib, and gzip decompression. The return value is a pointer to
178 * the new decompressor, or NULL if out of memory.
179 *
180 * This function takes no parameters, and the returned decompressor is valid for
181 * decompressing data that was compressed at any compression level and with any
182 * sliding window size.
183 *
184 * A single decompressor is not safe to use by multiple threads concurrently.
185 * However, different threads may use different decompressors concurrently.
186 */
187 LIBDEFLATEAPI struct libdeflate_decompressor *
188 libdeflate_alloc_decompressor(void);
189
190 /*
191 * Result of a call to libdeflate_deflate_decompress(),
192 * libdeflate_zlib_decompress(), or libdeflate_gzip_decompress().
193 */
194 enum libdeflate_result {
195 /* Decompression was successful. */
196 LIBDEFLATE_SUCCESS = 0,
197
198 /* Decompression failed because the compressed data was invalid,
199 * corrupt, or otherwise unsupported. */
200 LIBDEFLATE_BAD_DATA = 1,
201
202 /* A NULL 'actual_out_nbytes_ret' was provided, but the data would have
203 * decompressed to fewer than 'out_nbytes_avail' bytes. */
204 LIBDEFLATE_SHORT_OUTPUT = 2,
205
206 /* The data would have decompressed to more than 'out_nbytes_avail'
207 * bytes. */
208 LIBDEFLATE_INSUFFICIENT_SPACE = 3,
209 };
210
211 /*
212 * libdeflate_deflate_decompress() decompresses a DEFLATE stream from the buffer
213 * 'in' with compressed size up to 'in_nbytes' bytes. The uncompressed data is
214 * written to 'out', a buffer with size 'out_nbytes_avail' bytes. If
215 * decompression succeeds, then 0 (LIBDEFLATE_SUCCESS) is returned. Otherwise,
216 * a nonzero result code such as LIBDEFLATE_BAD_DATA is returned, and the
217 * contents of the output buffer are undefined.
218 *
219 * Decompression stops at the end of the DEFLATE stream (as indicated by the
220 * BFINAL flag), even if it is actually shorter than 'in_nbytes' bytes.
221 *
222 * libdeflate_deflate_decompress() can be used in cases where the actual
223 * uncompressed size is known (recommended) or unknown (not recommended):
224 *
225 * - If the actual uncompressed size is known, then pass the actual
226 * uncompressed size as 'out_nbytes_avail' and pass NULL for
227 * 'actual_out_nbytes_ret'. This makes libdeflate_deflate_decompress() fail
228 * with LIBDEFLATE_SHORT_OUTPUT if the data decompressed to fewer than the
229 * specified number of bytes.
230 *
231 * - If the actual uncompressed size is unknown, then provide a non-NULL
232 * 'actual_out_nbytes_ret' and provide a buffer with some size
233 * 'out_nbytes_avail' that you think is large enough to hold all the
234 * uncompressed data. In this case, if the data decompresses to less than
235 * or equal to 'out_nbytes_avail' bytes, then
236 * libdeflate_deflate_decompress() will write the actual uncompressed size
237 * to *actual_out_nbytes_ret and return 0 (LIBDEFLATE_SUCCESS). Otherwise,
238 * it will return LIBDEFLATE_INSUFFICIENT_SPACE if the provided buffer was
239 * not large enough but no other problems were encountered, or another
240 * nonzero result code if decompression failed for another reason.
241 */
242 LIBDEFLATEAPI enum libdeflate_result
243 libdeflate_deflate_decompress(struct libdeflate_decompressor *decompressor,
244 const void *in, size_t in_nbytes,
245 void *out, size_t out_nbytes_avail,
246 size_t *actual_out_nbytes_ret);
247
248 /*
249 * Like libdeflate_deflate_decompress(), but adds the 'actual_in_nbytes_ret'
250 * argument. If decompression succeeds and 'actual_in_nbytes_ret' is not NULL,
251 * then the actual compressed size of the DEFLATE stream (aligned to the next
252 * byte boundary) is written to *actual_in_nbytes_ret.
253 */
254 LIBDEFLATEAPI enum libdeflate_result
255 libdeflate_deflate_decompress_ex(struct libdeflate_decompressor *decompressor,
256 const void *in, size_t in_nbytes,
257 void *out, size_t out_nbytes_avail,
258 size_t *actual_in_nbytes_ret,
259 size_t *actual_out_nbytes_ret);
260
261 /*
262 * Like libdeflate_deflate_decompress(), but assumes the zlib wrapper format
263 * instead of raw DEFLATE.
264 *
265 * Decompression will stop at the end of the zlib stream, even if it is shorter
266 * than 'in_nbytes'. If you need to know exactly where the zlib stream ended,
267 * use libdeflate_zlib_decompress_ex().
268 */
269 LIBDEFLATEAPI enum libdeflate_result
270 libdeflate_zlib_decompress(struct libdeflate_decompressor *decompressor,
271 const void *in, size_t in_nbytes,
272 void *out, size_t out_nbytes_avail,
273 size_t *actual_out_nbytes_ret);
274
275 /*
276 * Like libdeflate_zlib_decompress(), but adds the 'actual_in_nbytes_ret'
277 * argument. If 'actual_in_nbytes_ret' is not NULL and the decompression
278 * succeeds (indicating that the first zlib-compressed stream in the input
279 * buffer was decompressed), then the actual number of input bytes consumed is
280 * written to *actual_in_nbytes_ret.
281 */
282 LIBDEFLATEAPI enum libdeflate_result
283 libdeflate_zlib_decompress_ex(struct libdeflate_decompressor *decompressor,
284 const void *in, size_t in_nbytes,
285 void *out, size_t out_nbytes_avail,
286 size_t *actual_in_nbytes_ret,
287 size_t *actual_out_nbytes_ret);
288
289 /*
290 * Like libdeflate_deflate_decompress(), but assumes the gzip wrapper format
291 * instead of raw DEFLATE.
292 *
293 * If multiple gzip-compressed members are concatenated, then only the first
294 * will be decompressed. Use libdeflate_gzip_decompress_ex() if you need
295 * multi-member support.
296 */
297 LIBDEFLATEAPI enum libdeflate_result
298 libdeflate_gzip_decompress(struct libdeflate_decompressor *decompressor,
299 const void *in, size_t in_nbytes,
300 void *out, size_t out_nbytes_avail,
301 size_t *actual_out_nbytes_ret);
302
303 /*
304 * Like libdeflate_gzip_decompress(), but adds the 'actual_in_nbytes_ret'
305 * argument. If 'actual_in_nbytes_ret' is not NULL and the decompression
306 * succeeds (indicating that the first gzip-compressed member in the input
307 * buffer was decompressed), then the actual number of input bytes consumed is
308 * written to *actual_in_nbytes_ret.
309 */
310 LIBDEFLATEAPI enum libdeflate_result
311 libdeflate_gzip_decompress_ex(struct libdeflate_decompressor *decompressor,
312 const void *in, size_t in_nbytes,
313 void *out, size_t out_nbytes_avail,
314 size_t *actual_in_nbytes_ret,
315 size_t *actual_out_nbytes_ret);
316
317 /*
318 * libdeflate_free_decompressor() frees a decompressor that was allocated with
319 * libdeflate_alloc_decompressor(). If a NULL pointer is passed in, no action
320 * is taken.
321 */
322 LIBDEFLATEAPI void
323 libdeflate_free_decompressor(struct libdeflate_decompressor *decompressor);
324
325 /* ========================================================================== */
326 /* Checksums */
327 /* ========================================================================== */
328
329 /*
330 * libdeflate_adler32() updates a running Adler-32 checksum with 'len' bytes of
331 * data and returns the updated checksum. When starting a new checksum, the
332 * required initial value for 'adler' is 1. This value is also returned when
333 * 'buffer' is specified as NULL.
334 */
335 LIBDEFLATEAPI uint32_t
336 libdeflate_adler32(uint32_t adler, const void *buffer, size_t len);
337
338
339 /*
340 * libdeflate_crc32() updates a running CRC-32 checksum with 'len' bytes of data
341 * and returns the updated checksum. When starting a new checksum, the required
342 * initial value for 'crc' is 0. This value is also returned when 'buffer' is
343 * specified as NULL.
344 */
345 LIBDEFLATEAPI uint32_t
346 libdeflate_crc32(uint32_t crc, const void *buffer, size_t len);
347
348 /* ========================================================================== */
349 /* Custom memory allocator */
350 /* ========================================================================== */
351
352 /*
353 * Install a custom memory allocator which libdeflate will use for all memory
354 * allocations. 'malloc_func' is a function that must behave like malloc(), and
355 * 'free_func' is a function that must behave like free().
356 *
357 * There must not be any libdeflate_compressor or libdeflate_decompressor
358 * structures in existence when calling this function.
359 */
360 LIBDEFLATEAPI void
361 libdeflate_set_memory_allocator(void *(*malloc_func)(size_t),
362 void (*free_func)(void *));
363
364 #ifdef __cplusplus
365 }
366 #endif
367
368 #endif /* LIBDEFLATE_H */