Zstd for V
V bindings for
zstd
This package uses the version 1.5.5 of
zstd
Synopsis
import prantlf.zstd
src := 'A text to compress.'.bytes()
dst := zstd.compress(src)!
Installation
You can install this package either from
VPM
v install prantlf.zstd
v install --git https://github.com/prantlf/v-zstd
API
The API corresponds with the
zstd
Once
If you want to compress or decompress once, use the following convenience functions:
compress(src []u8) ![]u8
compress_with_level(src []u8, compression_level int) ![]u8
decompress(src []u8) ![]u8
If you want to reuse the destination buffer for more compressions or decompressions, make sure to check the returned number of bytes written to it:
compress_to(mut dst []u8, src []u8) !int
compress_with_level_to(mut dst []u8, src []u8, compression_level int) !int
decompress_to(mut dst []u8, src []u8) !int
Finally, you can have the full controll over the memory pointers by using the unsafe functions:
compress_at(mut dst &u8, dst_len int, src &u8, src_len int) !int
compress_with_level_at(mut dst &u8, dst_len int, src &u8, src_len int, compression_level int) !int
decompress_at(mut dst &u8, dst_len int, src &u8, src_len int) !int
Repeatedly
If you want to compress or decompress multiple times, you can gain better performance by creating a compression or decompression context and reuse it. You will be able to set compression and decompression parameters too:
cctx := zstd.new_compress_context()
defer { cctx.free() }
cctx.set_param(zstd.CompressParam.compression_level, zstd.max_compress_level)!
src := 'A text to compress.'.bytes()
dst := cctx.compress(src)!
cctx.reset(zstd.ResetDir.session_only)
src2 := 'Anoter text to compress.'.bytes()
dst2 := cctx.compress(src2)!
Compression
enum ResetDir {
session_only
parameters
session_and_parameters
}
new_compress_context() !&CompressContext
(c &CompressContext) free()
(c &CompressContext) reset(reset ResetDir)
const (
strategy_fast
strategy_dfast
strategy_greedy
strategy_lazy
strategy_lazy2
strategy_btlazy2
strategy_btopt
strategy_btultra
strategy_btultra2
)
enum CompressParam {
compression_level
window_log
hash_log
chain_log
search_log
min_match
target_length
strategy
enable_long_distance_matching
ldm_hash_log
ldm_min_match
ldm_bucket_size_log
ldm_hash_rate_log
content_size_flag
checksum_flag
dict_id_flag
nb_workers
job_size
overlap_log
rsyncable
format
force_max_window
force_attach_dict
literal_compression_mode
target_c_block_size
src_size_hint
enable_dedicated_dict_search
stable_in_buffer
stable_out_buffer
block_delimiters
validate_sequences
use_block_splitter
use_row_match_finder
prefetch_c_dict_tables
enable_seq_producer_fallback
max_block_size
}
compress_param_bounds(param CompressParam) !(int, int)
(c &CompressContext) set_param(param CompressParam, value int) !
(c &CompressContext) get_param(param CompressParam) !int
(c &CompressContext) set_pledged_src_size(pledged_src_size int) !
(c &CompressContext) compress(src []u8) ![]u8
(c &CompressContext) compress_to(mut dst []u8, src []u8) !int
(c &CompressContext) compress_at(mut dst &u8, dst_len int, src &u8, src_len int) !int
Decompression
enum ResetDir {
session_only
parameters
session_and_parameters
}
new_decompress_context() !&DecompressContext
(d &DecompressContext) free()
(d &DecompressContext) reset(reset ResetDir)
enum DecompressParam {
window_log_max
format
stable_out_buffer
force_ignore_checksum
ref_multiple_d_dicts
}
decompress_param_bounds(param DecompressParam) !(int, int)
(d &DecompressContext) set_param(param DecompressParam, value int) !
(d &DecompressContext) get_param(param DecompressParam) !int
(d &DecompressContext) set_max_window_size(max_window_size int) !
(d &DecompressContext) decompress(src []u8) ![]u8
(d &DecompressContext) decompress_to(mut dst []u8, src []u8) !int
(d &DecompressContext) decompress_at(mut dst &u8, dst_len int, src &u8, src_len int) !int
Streaming
If you want to compress or decompress large data, or if the data comes chunk after chunk, you can use chunked compression or decompression functions:
cctx := zstd.new_compress_context()!
defer { cctx.free() }
cctx.set_param(zstd.CompressParam.checksum_flag, 1)!
mut dst := []u8{cap: zstd.compress_bound(src.len)}
mut dst_ref := &dst
drain := fn [dst_ref] (buf &u8, len int) ! {
unsafe { dst_ref.push_many(buf, len) }
}
mut sctx := new_compress_stream_context(drain)
cctx.compress_chunk(mut sctx, src, false)!
...
unsafe { cctx.compress_chunk(mut sctx, data, len, true)! }
...
cctx.compress_end(mut sctx)!
Compression
new_compress_stream_context(drain fn (buf &u8, len int) !) &StreamContext
(c &CompressContext) compress_chunk(mut sctx StreamContext, src []u8, last bool) !
(c &CompressContext) compress_chunk_at(mut sctx StreamContext, src &u8, src_len int, last bool) !
Decompression
new_decompress_stream_context(drain fn (buf &u8, len int) !) &StreamContext
(d &DecompressContext) decompress_chunk(mut sctx StreamContext, src []u8, last bool) !
(d &DecompressContext) decompress_chunk_at(mut sctx StreamContext, src &u8, src_len int, last bool) !
Errors
THe following error codes can be checked by calling the
code
IError
const (
err_no_error
err_generic
err_prefix_unknown
err_version_unsupported
err_frame_parameter_unsupported
err_frame_parameter_window_too_large
err_corruption_detected
err_checksum_wrong
err_literals_header_wrong
err_dictionary_corrupted
err_dictionary_wrong
err_dictionary_creation_failed
err_parameter_unsupported
err_parameter_combination_unsupported
err_parameter_out_of_bound
err_table_log_too_large
err_max_symbol_value_too_large
err_max_symbol_value_too_small
err_stability_condition_not_respected
err_stage_wrong
err_init_missing
err_memory_allocation
err_work_space_too_small
err_dst_size_too_small
err_src_size_wrong
err_dst_buffer_null
err_no_forward_progress_dest_full
err_no_forward_progress_input_empty
err_frame_index_too_large
err_seekable_io
err_dst_buffer_wrong
err_src_buffer_wrong
err_sequence_producer_failed
err_external_sequences_invalid
err_max_code
)
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.
License
Copyright (c) 2023 Ferdinand Prantl
Licensed under the MIT license.