zstd-cr

C binding to libzstd (Zstandard compression library) written in Crystal

Status:

Installation

This shard requires libzstd version >= 1.4.0 (oldest known to work)

1. Install libzstd:

sudo apt update
sudo apt install libzstd1

If you get an error "unable to locate package..." it means you need to build libzstd from source

2. Add the dependency to your shard.yml:

dependencies:
  zstd-cr:
    github: BlackHabanero/zstd-cr

3. Run shards install

Usage

Module consists of three classes in Crystal-default manner: Writer, Reader & Error. Their behaviour was inspired by Zlib module from Crystal standard library.

1. See requiring files

require "zstd-cr"

2. Example use of Writer class:

# Reads a file to a slice
size = File.size("./file")
slice = Slice(UInt8).new(size)
File.open("./file") do |file|
  file.read_fully(slice)
end

# Compresses slice and writes compressed data into compressedfile
# with default compression level - 3.
# Recommended compression level range is 1-19,
# although max and min levels are different (see Docs)
#
# Writing checksum at compressedfile's end is turned on by default.
# You can change it using #set_parameter
Zstd::Writer.open("compressedfile") do |writr|
  writr.write(slice)
end

# For other IO types than files you can specify if
# both Writer/Reader and wrapped IO
# (e.g. some_io of type IO::Memory) will be closed synchronously.
#
# In built-in solution for (de)compressing files sync_close is set to true and it cannot be changed
some_io = IO::Memory.new "hello"
Zstd::Writer.open(some_io, sync_close: true) do |writr|
  writr.write(slice)
end

3. Example use of Reader class:

# Decompresses compressed.zst file into slice.
# Reader only returns amount of data equal to slice size.
# In this example Reader#get_decompressed_size function is used
# to read whole decompressed content
#
# #read trims decompressed data to fit slice size
Zstd::Reader.open("./compressed.zst") do |reader|
  size = reader.get_decompressed_size
  slice = Bytes.new(size)
  reader.read(slice)
end
# Reader can also close underlying IO synchronously with itself just like Writer does

4. For more information check docs

Contributing

1. Fork it (https://github.com/BlackHabanero/zstd-cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• BlackHabanero - creator and maintainer