-spec close(Ctx :: context()) -> ok.

Close a context/0, releasing all referenced resources. After a context/0 is closed it is no longer possible to use it.

A context/0 is automatically closed when GC:ed, so the only reason to call this function is to make the resources attached to the context be released before the next GC.

-spec compress(iodata()) -> iodata().

Equivalent to compress(Data, #{}).

-spec compress(Data :: iodata(), Options :: compress_parameters()) -> iodata();
              (Data :: iodata(), Ctx :: context()) -> iodata().

Compress Data using the given compress_parameters/0 or the context/0.

Example:

> zstd:compress("abc").
> zstd:compress("abc", #{ compressionLevel => 20 }).

-spec context(compress | decompress) -> {ok, context()}.

Equivalent to context(Mode, #{}).

-spec context(compress, Options :: compress_parameters()) -> {ok, context()};
             (decompress, Options :: decompress_parameters()) -> {ok, context()}.

Create a compression or decompression context.

A context can be used to do streaming compression/decompression and allows re-using parameters for multiple compressions/decompressions.

-spec decompress(iodata()) -> iodata().

Equivalent to decompress(Data, #{}).

-spec decompress(Data :: iodata(), Options :: decompress_parameters()) -> iodata();
                (Data :: iodata(), Ctx :: context()) -> iodata().

Decompress Data using the given compress_parameters/0 or the context/0.

Example:

> Compressed = zstd:compress("abc").
> zstd:decompress(Compressed).
[~"abc"]

-spec dict(Mode :: compress | decompress, Dict :: binary()) -> {ok, dict()}.

Equivalent to dict(Mode, Dict, #{}).

-spec dict(compress, Dict :: binary(), #{compressionLevel => compressionLevel()}) -> {ok, dict()};
          (decompress, Dict :: binary(), #{}) -> {ok, dict()}.

Create a compression or decompression dictionary.

A compression dictionary can be used as a compress_parameters/0 to use a dictionary for compression. Dictionaries allow good compression ratios even for small amounts of data.

A decompression dictionary can be used as a decompress_parameters/0 to use a dictionary for decompression. The same dictionary has to be used for compression as decompression. To verify that the same dictionary is used you can use get_dict_id/1 on the dictionary and compressed data, or just try to decompress as decompression will raise and exception if an incorrect dictionary is given.

The compressionLevel set on a dictionary will override the compressionLevel set in the context/0.

Example:

> {ok, CDict} = zstd:dict(compress, Dict).
> Data = lists:duplicate(100, 1).
[1, 1, 1 | _]
> iolist_size(zstd:compress(Data)).
17
> iolist_size(zstd:compress(Data, #{ dictionary => CDict, dictIDFlag => false })).
16

As loading a dictionary can be a heavy operations, it is possible to create only a single dict/0 and provide it to multiple context/0.

There is no API exposed in zstd to create a dictionary, instead use the zstd command line tool.

-spec finish(Ctx :: context(), Data :: iodata()) -> Result when Result :: {done, erlang:iovec()}.

Finish compressing/decompressing data.

This flushes all output buffers and resets the context/0 so that it can be used for compressing/decompressing again.

Example:

> {ok, DCtx} = zstd:context(decompress).
> {continue, D1} = zstd:stream(DCtx, <<40,181,47,253,32>>).
> {done, D2} = zstd:finish(DCtx, <<2,17,0,0,97,98>>).
> iolist_to_binary([D1,D2]).
<<"ab">>

-spec get_dict_id(DictOrFrame :: dict() | binary()) -> non_neg_integer().

Get the dictionary ID of a dictionary or a frame.

The dictionary ID 0 represents no dictionary.

Example:

> {ok, CDict} = zstd:dict(compress, Dict).
> zstd:get_dict_id(CDict).
1850243626
> zstd:get_dict_id(zstd:compress("abc")).
0

-spec get_frame_header(Frame :: iodata()) ->
                          {ok,
                           #{blockSizeMax => non_neg_integer(),
                             checksumFlag => boolean(),
                             dictID => non_neg_integer(),
                             frameContentSize => non_neg_integer(),
                             frameType => 'ZSTD_frame' | 'ZSTD_skippableFrame',
                             headerSize => non_neg_integer(),
                             windowSize => non_neg_integer()}} |
                          {error, unicode:chardata()}.

Get header of a Zstandard compressed frame.

A compressed Zstandard stream can consist of multiple frames. This function will read metadata from the first frame. This information can be useful when debugging corrupted Zstandard streams.

Example:

> Compressed = zstd:compress(~"abc").
> zstd:get_frame_header(Compressed).
{ok,#{frameContentSize => 3,windowSize => 3,blockSizeMax => 3,
      frameType => 'ZSTD_frame',headerSize => 6,
      dictID => 0, checksumFlag => false}}

-spec get_parameter(Ctx :: context(), Key :: term()) -> Value :: term().

Get a parameter from a context/0.

See compress_parameters/0 and decompress_parameters/0 for details on which parameters are available and what each parameter does.

Note that it is not possible to get the dictionary and pledgedSrcSize parameters using this API. Instead you can use get_dict_id/1 on the context/0 to get the id of the dictionary used. There is no way to get the pledgedSrcSize.

Returns ok on success, raises an error on failure.

Example:

> {ok, CCtx} = zstd:context(compress).
{ok, _}
> zstd:get_parameter(CCtx, compressionLevel).
3
> zstd:set_parameter(CCtx, compressionLevel, 15).
ok
> zstd:get_parameter(CCtx, compressionLevel).
15

-spec reset(Ctx :: context()) -> ok.

Reset a context while streaming data, returning it to its original state but keeping all parameters set.

By resetting the state, the context can be re-used for other operations even if it is in the middle of a (de)compression stream.

Example:

> {ok, CCtx} = zstd:context(compress).
> zstd:stream(CCtx, "a").
{continue, _}
> zstd:reset(CCtx).
ok
> {done, Compressed} = zstd:finish(CCtx, "b").
> zstd:decompress(Compressed).
[~"b"]

-spec set_parameter(Ctx :: context(), Key :: term(), Value :: term()) -> ok.

Set a parameter on a context/0.

See compress_parameters/0 and decompress_parameters/0 for details on which parameters are available and what each parameter does.

Returns ok on success, raises an error on failure.

Example:

> {ok, CCtx} = zstd:context(compress).
{ok, _}
> ok = zstd:set_parameter(CCtx, compressionLevel, 15).
ok
> zstd:stream(CCtx, "abc").
{continue, _}
> catch zstd:set_parameter(CCtx, dictionary, "abc").
{'EXIT', {{zstd_error, <<"Operation not authorized at current processing stage">>}, _}}

-spec stream(Ctx :: context(), Data :: iodata()) -> Result
                when
                    Result ::
                        {continue, Remainder :: erlang:iovec(), Output :: binary()} |
                        {continue, Output :: binary()}.

Compress or decompress a stream of data. The last stream of data should be called with finish/2 to complete the compression/decompression.

Example:

> {ok, CCtx} = zstd:context(compress).
> {continue, C1} = zstd:stream(CCtx, ~"a").
> {done, C2} = zstd:finish(CCtx, ~"b").
> Compressed = iolist_to_binary([C1, C2]).
<<40,181,47,253,0,88,17,0,0,97,98>>
> zstd:decompress(Compressed).
[<<"ab">>]