/*

 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.

 * All rights reserved.

 *

 * This source code is licensed under both the BSD-style license (found in the

 * LICENSE file in the root directory of this source tree) and the GPLv2 (found

 * in the COPYING file in the root directory of this source tree).

 * You may select, at your option, one of the above-listed licenses.

 */

#if defined (__cplusplus)

extern "C" {

#endif

#ifndef ZSTD_H_235446

#define ZSTD_H_235446

/* ======   Dependency   ======*/

#include <stddef.h>   /* size_t */

/* =====   ZSTDLIB_API : control library symbols visibility   ===== */

#ifndef ZSTDLIB_VISIBILITY

#  if defined(__GNUC__) && (__GNUC__ >= 4)

#    define ZSTDLIB_VISIBILITY __attribute__ ((visibility ("default")))

#  else

#    define ZSTDLIB_VISIBILITY

#  endif

#endif

#if defined(ZSTD_DLL_EXPORT) && (ZSTD_DLL_EXPORT==1)

#  define ZSTDLIB_API __declspec(dllexport) ZSTDLIB_VISIBILITY

#elif defined(ZSTD_DLL_IMPORT) && (ZSTD_DLL_IMPORT==1)

#  define ZSTDLIB_API __declspec(dllimport) ZSTDLIB_VISIBILITY /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/

#else

#  define ZSTDLIB_API ZSTDLIB_VISIBILITY

#endif

/*******************************************************************************

  Introduction

  zstd, short for Zstandard, is a fast lossless compression algorithm, targeting

  real-time compression scenarios at zlib-level and better compression ratios.

  The zstd compression library provides in-memory compression and decompression

  functions.

  The library supports regular compression levels from 1 up to ZSTD_maxCLevel(),

  which is currently 22. Levels >= 20, labeled `--ultra`, should be used with

  caution, as they require more memory. The library also offers negative

  compression levels, which extend the range of speed vs. ratio preferences.

  The lower the level, the faster the speed (at the cost of compression).

  Compression can be done in:

    - a single step (described as Simple API)

    - a single step, reusing a context (described as Explicit context)

    - unbounded multiple steps (described as Streaming compression)

  The compression ratio achievable on small data can be highly improved using

  a dictionary. Dictionary compression can be performed in:

    - a single step (described as Simple dictionary API)

    - a single step, reusing a dictionary (described as Bulk-processing

      dictionary API)

  Advanced experimental functions can be accessed using

  `#define ZSTD_STATIC_LINKING_ONLY` before including zstd.h.

  Advanced experimental APIs should never be used with a dynamically-linked

  library. They are not "stable"; their definitions or signatures may change in

  the future. Only static linking is allowed.

*******************************************************************************/

/*------   Version   ------*/

#define ZSTD_VERSION_MAJOR    1

#define ZSTD_VERSION_NUMBER  (ZSTD_VERSION_MAJOR *100*100 + ZSTD_VERSION_MINOR *100 + ZSTD_VERSION_RELEASE)

ZSTDLIB_API unsigned ZSTD_versionNumber(void);   /**< to check runtime library version */

#define ZSTD_LIB_VERSION ZSTD_VERSION_MAJOR.ZSTD_VERSION_MINOR.ZSTD_VERSION_RELEASE

#define ZSTD_QUOTE(str) #str

#define ZSTD_EXPAND_AND_QUOTE(str) ZSTD_QUOTE(str)

#define ZSTD_VERSION_STRING ZSTD_EXPAND_AND_QUOTE(ZSTD_LIB_VERSION)

ZSTDLIB_API const char* ZSTD_versionString(void);   /* requires v1.3.0+ */

#ifndef ZSTD_CLEVEL_DEFAULT

#  define ZSTD_CLEVEL_DEFAULT 3

#endif

/***************************************

*  Simple API

***************************************/

/*! ZSTD_compress() :

 *  Compresses `src` content as a single zstd compressed frame into already allocated `dst`.

 *  Hint : compression runs faster if `dstCapacity` >=  `ZSTD_compressBound(srcSize)`.

 *  @return : compressed size written into `dst` (<= `dstCapacity),

 *            or an error code if it fails (which can be tested using ZSTD_isError()). */

ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity,

                            const void* src, size_t srcSize,

                                  int compressionLevel);

/*! ZSTD_decompress() :

 *  `compressedSize` : must be the _exact_ size of some number of compressed and/or skippable frames.

 *  `dstCapacity` is an upper bound of originalSize to regenerate.

 *  If user cannot imply a maximum upper bound, it's better to use streaming mode to decompress data.

 *  @return : the number of bytes decompressed into `dst` (<= `dstCapacity`),

 *            or an errorCode if it fails (which can be tested using ZSTD_isError()). */

ZSTDLIB_API size_t ZSTD_decompress( void* dst, size_t dstCapacity,

                              const void* src, size_t compressedSize);

/*! ZSTD_getFrameContentSize() : requires v1.3.0+

 *  `src` should point to the start of a ZSTD encoded frame.

 *  `srcSize` must be at least as large as the frame header.

 *            hint : any size >= `ZSTD_frameHeaderSize_max` is large enough.

 *  @return : - decompressed size of `src` frame content, if known

 *            - ZSTD_CONTENTSIZE_UNKNOWN if the size cannot be determined

 *            - ZSTD_CONTENTSIZE_ERROR if an error occurred (e.g. invalid magic number, srcSize too small)

 *   note 1 : a 0 return value means the frame is valid but "empty".

 *   note 2 : decompressed size is an optional field, it may not be present, typically in streaming mode.

 *            When `return==ZSTD_CONTENTSIZE_UNKNOWN`, data to decompress could be any size.

 *            In which case, it's necessary to use streaming mode to decompress data.

 *            Optionally, application can rely on some implicit limit,

 *            as ZSTD_decompress() only needs an upper bound of decompressed size.

 *            (For example, data could be necessarily cut into blocks <= 16 KB).

 *   note 3 : decompressed size is always present when compression is completed using single-pass functions,

 *            such as ZSTD_compress(), ZSTD_compressCCtx() ZSTD_compress_usingDict() or ZSTD_compress_usingCDict().

 *   note 4 : decompressed size can be very large (64-bits value),

 *            potentially larger than what local system can handle as a single memory segment.

 *            In which case, it's necessary to use streaming mode to decompress data.

 *   note 5 : If source is untrusted, decompressed size could be wrong or intentionally modified.

 *            Always ensure return value fits within application's authorized limits.

 *            Each application can set its own limits.

 *   note 6 : This function replaces ZSTD_getDecompressedSize() */

#define ZSTD_CONTENTSIZE_UNKNOWN (0ULL - 1)

#define ZSTD_CONTENTSIZE_ERROR   (0ULL - 2)

ZSTDLIB_API unsigned long long ZSTD_getFrameContentSize(const void *src, size_t srcSize);

/*! ZSTD_getDecompressedSize() :

 *  NOTE: This function is now obsolete, in favor of ZSTD_getFrameContentSize().

 *  Both functions work the same way, but ZSTD_getDecompressedSize() blends

 *  "empty", "unknown" and "error" results to the same return value (0),

 *  while ZSTD_getFrameContentSize() gives them separate return values.

 * @return : decompressed size of `src` frame content _if known and not empty_, 0 otherwise. */

ZSTDLIB_API unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);

/*======  Helper functions  ======*/

#define ZSTD_COMPRESSBOUND(srcSize)   ((srcSize) + ((srcSize)>>8) + (((srcSize) < (128<<10)) ? (((128<<10) - (srcSize)) >> 11) /* margin, from 64 to 0 */ : 0))  /* this formula ensures that bound(A) + bound(B) <= bound(A+B) as long as A and B >= 128 KB */

ZSTDLIB_API size_t      ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size in worst case single-pass scenario */

ZSTDLIB_API unsigned    ZSTD_isError(size_t code);          /*!< tells if a `size_t` function result is an error code */

ZSTDLIB_API const char* ZSTD_getErrorName(size_t code);     /*!< provides readable string from an error code */

ZSTDLIB_API int         ZSTD_maxCLevel(void);               /*!< maximum compression level available */

/***************************************

*  Explicit context

***************************************/

/*= Compression context

 *  When compressing many times,

 *  This will make workload friendlier for system's memory.

typedef struct ZSTD_CCtx_s ZSTD_CCtx;

ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);

ZSTDLIB_API size_t     ZSTD_freeCCtx(ZSTD_CCtx* cctx);

/*! ZSTD_compressCCtx() :

 *  Same as ZSTD_compress(), using an explicit ZSTD_CCtx

 *  The function will compress at requested compression level,

 *  ignoring any other parameter */

ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* cctx,

                                     void* dst, size_t dstCapacity,

                               const void* src, size_t srcSize,

                                     int compressionLevel);

/*= Decompression context

 *  When decompressing many times,

 *  it is recommended to allocate a context only once,

 *  and re-use it for each successive compression operation.

 *  This will make workload friendlier for system's memory.

 *  Use one context per thread for parallel execution. */

typedef struct ZSTD_DCtx_s ZSTD_DCtx;

ZSTDLIB_API ZSTD_DCtx* ZSTD_createDCtx(void);

ZSTDLIB_API size_t     ZSTD_freeDCtx(ZSTD_DCtx* dctx);

/*! ZSTD_decompressDCtx() :

 *  Same as ZSTD_decompress(),

 *  requires an allocated ZSTD_DCtx.

 *  Compatible with sticky parameters.

 */

ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* dctx,

                                       void* dst, size_t dstCapacity,

                                 const void* src, size_t srcSize);

/***************************************

*  Advanced compression API

***************************************/

/* API design :

 *   Parameters are pushed one by one into an existing context,

 *   using ZSTD_CCtx_set*() functions.

 *   Pushed parameters are sticky : they are valid for next compressed frame, and any subsequent frame.

 *   "sticky" parameters are applicable to `ZSTD_compress2()` and `ZSTD_compressStream*()` !

 *   They do not apply to "simple" one-shot variants such as ZSTD_compressCCtx()

 *

 *   It's possible to reset all parameters to "default" using ZSTD_CCtx_reset().

 *

 *   This API supercedes all other "advanced" API entry points in the experimental section.

 *   In the future, we expect to remove from experimental API entry points which are redundant with this API.

 */

/* Compression strategies, listed from fastest to strongest */

typedef enum { ZSTD_fast=1,

               ZSTD_dfast=2,

               ZSTD_greedy=3,

               ZSTD_lazy=4,

               ZSTD_lazy2=5,

               ZSTD_btlazy2=6,

               ZSTD_btopt=7,

               ZSTD_btultra=8,

               ZSTD_btultra2=9

               /* note : new strategies _might_ be added in the future.

                         Only the order (from fast to strong) is guaranteed */

} ZSTD_strategy;

typedef enum {

    ZSTD_c_compressionLevel=100, /* Update all compression parameters according to pre-defined cLevel table

                              * Default level is ZSTD_CLEVEL_DEFAULT==3.

                              * Special: value 0 means default, which is controlled by ZSTD_CLEVEL_DEFAULT.

                              * Note 1 : it's possible to pass a negative compression level.

                              * Note 2 : setting a level sets all default values of other compression parameters */

    ZSTD_c_windowLog=101,    /* Maximum allowed back-reference distance, expressed as power of 2.

                              * Must be clamped between ZSTD_WINDOWLOG_MIN and ZSTD_WINDOWLOG_MAX.

                              * Special: value 0 means "use default windowLog".

                              * Note: Using a windowLog greater than ZSTD_WINDOWLOG_LIMIT_DEFAULT

                              *       requires explicitly allowing such window size at decompression stage if using streaming. */

    ZSTD_c_hashLog=102,      /* Size of the initial probe table, as a power of 2.

                              * Resulting memory usage is (1 << (hashLog+2)).

                              * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX.

                              * Larger tables improve compression ratio of strategies <= dFast,

                              * and improve speed of strategies > dFast.

                              * Special: value 0 means "use default hashLog". */

    ZSTD_c_chainLog=103,     /* Size of the multi-probe search table, as a power of 2.

                              * Resulting memory usage is (1 << (chainLog+2)).

                              * Must be clamped between ZSTD_CHAINLOG_MIN and ZSTD_CHAINLOG_MAX.

                              * Larger tables result in better and slower compression.

                              * This parameter is useless when using "fast" strategy.

                              * It's still useful when using "dfast" strategy,

                              * in which case it defines a secondary probe table.

                              * Special: value 0 means "use default chainLog". */

    ZSTD_c_searchLog=104,    /* Number of search attempts, as a power of 2.

                              * More attempts result in better and slower compression.

                              * This parameter is useless when using "fast" and "dFast" strategies.

                              * Special: value 0 means "use default searchLog". */

    ZSTD_c_minMatch=105,     /* Minimum size of searched matches.

                              * Note that Zstandard can still find matches of smaller size,

                              * it just tweaks its search algorithm to look for this size and larger.

                              * Larger values increase compression and decompression speed, but decrease ratio.

                              * Must be clamped between ZSTD_MINMATCH_MIN and ZSTD_MINMATCH_MAX.

                              * Note that currently, for all strategies < btopt, effective minimum is 4.

                              *                    , for all strategies > fast, effective maximum is 6.

                              * Special: value 0 means "use default minMatchLength". */

    ZSTD_c_targetLength=106, /* Impact of this field depends on strategy.

                              * For strategies btopt, btultra & btultra2:

                              *     Length of Match considered "good enough" to stop search.

                              *     Larger values make compression stronger, and slower.

                              * For strategy fast:

                              *     Distance between match sampling.

                              *     Larger values make compression faster, and weaker.

                              * Special: value 0 means "use default targetLength". */

    ZSTD_c_strategy=107,     /* See ZSTD_strategy enum definition.

                              * The higher the value of selected strategy, the more complex it is,

                              * resulting in stronger and slower compression.

                              * Special: value 0 means "use default strategy". */

    /* LDM mode parameters */

    ZSTD_c_enableLongDistanceMatching=160, /* Enable long distance matching.

                                     * This parameter is designed to improve compression ratio

                                     * for large inputs, by finding large matches at long distance.

                                     * It increases memory usage and window size.

                                     * Note: enabling this parameter increases default ZSTD_c_windowLog to 128 MB

                                     * except when expressly set to a different value. */

    ZSTD_c_ldmHashLog=161,   /* Size of the table for long distance matching, as a power of 2.

                              * Larger values increase memory usage and compression ratio,

                              * but decrease compression speed.

                              * Must be clamped between ZSTD_HASHLOG_MIN and ZSTD_HASHLOG_MAX

                              * default: windowlog - 7.

                              * Special: value 0 means "automatically determine hashlog". */

    ZSTD_c_ldmMinMatch=162,  /* Minimum match size for long distance matcher.

                              * Larger/too small values usually decrease compression ratio.

                              * Must be clamped between ZSTD_LDM_MINMATCH_MIN and ZSTD_LDM_MINMATCH_MAX.

                              * Special: value 0 means "use default value" (default: 64). */

    ZSTD_c_ldmBucketSizeLog=163, /* Log size of each bucket in the LDM hash table for collision resolution.

                              * Larger values improve collision resolution but decrease compression speed.

                              * The maximum value is ZSTD_LDM_BUCKETSIZELOG_MAX.

                              * Special: value 0 means "use default value" (default: 3). */

    ZSTD_c_ldmHashRateLog=164, /* Frequency of inserting/looking up entries into the LDM hash table.

                              * Must be clamped between 0 and (ZSTD_WINDOWLOG_MAX - ZSTD_HASHLOG_MIN).

                              * Default is MAX(0, (windowLog - ldmHashLog)), optimizing hash table usage.

                              * Larger values improve compression speed.

                              * Deviating far from default value will likely result in a compression ratio decrease.

                              * Special: value 0 means "automatically determine hashRateLog". */

    /* frame parameters */

    ZSTD_c_contentSizeFlag=200, /* Content size will be written into frame header _whenever known_ (default:1)

                              * Content size must be known at the beginning of compression.

                              * This is automatically the case when using ZSTD_compress2(),

                              * For streaming variants, content size must be provided with ZSTD_CCtx_setPledgedSrcSize() */

    ZSTD_c_checksumFlag=201, /* A 32-bits checksum of content is written at end of frame (default:0) */

    ZSTD_c_dictIDFlag=202,   /* When applicable, dictionary's ID is written into frame header (default:1) */

    /* multi-threading parameters */

    /* These parameters are only useful if multi-threading is enabled (compiled with build macro ZSTD_MULTITHREAD).

     * They return an error otherwise. */

    ZSTD_c_nbWorkers=400,    /* Select how many threads will be spawned to compress in parallel.

                              * When nbWorkers >= 1, triggers asynchronous mode when used with ZSTD_compressStream*() :

                              * ZSTD_compressStream*() consumes input and flush output if possible, but immediately gives back control to caller,

                              * while compression work is performed in parallel, within worker threads.

                              * (note : a strong exception to this rule is when first invocation of ZSTD_compressStream2() sets ZSTD_e_end :

                              *  in which case, ZSTD_compressStream2() delegates to ZSTD_compress2(), which is always a blocking call).

                              * More workers improve speed, but also increase memory usage.

                              * Default value is `0`, aka "single-threaded mode" : no worker is spawned, compression is performed inside Caller's thread, all invocations are blocking */

    ZSTD_c_jobSize=401,      /* Size of a compression job. This value is enforced only when nbWorkers >= 1.

                              * Each compression job is completed in parallel, so this value can indirectly impact the nb of active threads.

                              * 0 means default, which is dynamically determined based on compression parameters.

                              * Job size must be a minimum of overlap size, or 1 MB, whichever is largest.

                              * The minimum size is automatically and transparently enforced */

    ZSTD_c_overlapLog=402,   /* Control the overlap size, as a fraction of window size.

                              * The overlap size is an amount of data reloaded from previous job at the beginning of a new job.

                              * It helps preserve compression ratio, while each job is compressed in parallel.

                              * This value is enforced only when nbWorkers >= 1.

                              * Larger values increase compression ratio, but decrease speed.

                              * Possible values range from 0 to 9 :

                              * - 0 means "default" : value will be determined by the library, depending on strategy

                              * - 1 means "no overlap"

                              * - 9 means "full overlap", using a full window size.

                              * Each intermediate rank increases/decreases load size by a factor 2 :

                              * 9: full window;  8: w/2;  7: w/4;  6: w/8;  5:w/16;  4: w/32;  3:w/64;  2:w/128;  1:no overlap;  0:default

                              * default value varies between 6 and 9, depending on strategy */

    /* note : additional experimental parameters are also available

     * within the experimental section of the API.

     * At the time of this writing, they include :

     * ZSTD_c_rsyncable

     * ZSTD_c_format

     * ZSTD_c_forceMaxWindow

     * ZSTD_c_forceAttachDict

     * Because they are not stable, it's necessary to define ZSTD_STATIC_LINKING_ONLY to access them.

     * note : never ever use experimentalParam? names directly;

     *        also, the enums values themselves are unstable and can still change.

     */

     ZSTD_c_experimentalParam1=500,

     ZSTD_c_experimentalParam2=10,

     ZSTD_c_experimentalParam3=1000,

} ZSTD_cParameter;

typedef struct {

    size_t error;

    int lowerBound;

    int upperBound;

} ZSTD_bounds;

/*! ZSTD_cParam_getBounds() :

 *  All parameters must belong to an interval with lower and upper bounds,

 *  otherwise they will either trigger an error or be automatically clamped.

 * @return : a structure, ZSTD_bounds, which contains

 *         - an error status field, which must be tested using ZSTD_isError()

 *         - lower and upper bounds, both inclusive

 */

ZSTDLIB_API ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter cParam);

/*! ZSTD_CCtx_setParameter() :

 *  Set one compression parameter, selected by enum ZSTD_cParameter.

 *  All parameters have valid bounds. Bounds can be queried using ZSTD_cParam_getBounds().

 *  Providing a value beyond bound will either clamp it, or trigger an error (depending on parameter).

 *  Setting a parameter is generally only possible during frame initialization (before starting compression).

 *  Exception : when using multi-threading mode (nbWorkers >= 1),

 *              the following parameters can be updated _during_ compression (within same frame):

 *              => compressionLevel, hashLog, chainLog, searchLog, minMatch, targetLength and strategy.

 *              new parameters will be active for next job only (after a flush()).

 * @return : an error code (which can be tested using ZSTD_isError()).

 */

ZSTDLIB_API size_t ZSTD_CCtx_setParameter(ZSTD_CCtx* cctx, ZSTD_cParameter param, int value);

/*! ZSTD_CCtx_setPledgedSrcSize() :

 *  Total input data size to be compressed as a single frame.

 *  Value will be written in frame header, unless if explicitly forbidden using ZSTD_c_contentSizeFlag.

 *  This value will also be controlled at end of frame, and trigger an error if not respected.

 * @result : 0, or an error code (which can be tested with ZSTD_isError()).

 *  Note 1 : pledgedSrcSize==0 actually means zero, aka an empty frame.

 *           In order to mean "unknown content size", pass constant ZSTD_CONTENTSIZE_UNKNOWN.

 *           ZSTD_CONTENTSIZE_UNKNOWN is default value for any new frame.

 *  Note 2 : pledgedSrcSize is only valid once, for the next frame.

 *           It's discarded at the end of the frame, and replaced by ZSTD_CONTENTSIZE_UNKNOWN.

 *  Note 3 : Whenever all input data is provided and consumed in a single round,

 *           for example with ZSTD_compress2(),

 *           or invoking immediately ZSTD_compressStream2(,,,ZSTD_e_end),

 */

ZSTDLIB_API size_t ZSTD_CCtx_setPledgedSrcSize(ZSTD_CCtx* cctx, unsigned long long pledgedSrcSize);