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. Helpful tips are provided in README.md file here

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)
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
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
#
# NOTE Reader.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 also can close underlying IO synchronously with itself.
# You can specify it just like with Writer

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