/*
zstd - standard compression library
Header File
- Copyright (C) 2014-2015, Yann Collet.
+ Copyright (C) 2014-2016, Yann Collet.
BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
You can contact the author at :
- zstd source repository : https://github.com/Cyan4973/zstd
- - ztsd public forum : https://groups.google.com/forum/#!forum/lz4c
*/
#ifndef ZSTD_H
#define ZSTD_H
extern "C" {
#endif
-/* *************************************
-* Includes
+/*-*************************************
+* Dependencies
***************************************/
#include <stddef.h> /* size_t */
-/* ***************************************************************
+/*-***************************************************************
* Export parameters
*****************************************************************/
/*!
/* *************************************
* Simple functions
***************************************/
+/*! ZSTD_compress() :
+ Compresses `srcSize` bytes from buffer `src` into buffer `dst` of size `dstCapacity`.
+ Destination buffer must be already allocated.
+ Compression runs faster if `dstCapacity` >= `ZSTD_compressBound(srcSize)`.
+ @return : the number of bytes written into `dst`,
+ 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` : is the _exact_ size of the compressed blob, otherwise decompression will fail.
+ `dstCapacity` must be large enough, equal or larger than originalSize.
+ @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_compress() :
- Compresses @srcSize bytes from buffer @src into buffer @dst of size @dstCapacity.
- Destination buffer must be already allocated.
- Compression runs faster if @dstCapacity >= ZSTD_compressBound(srcSize).
- @return : the number of bytes written into @dst
- or an error code if it fails (which can be tested using ZSTD_isError())
-
-ZSTD_decompress() :
- @compressedSize : is the _exact_ size of the compressed blob (or decompression will fail)
- @dst must be large enough, equal or larger than originalSize.
- @return : the number of bytes decompressed into @dst (<= @dstCapacity)
- or an errorCode if it fails (which can be tested using ZSTD_isError())
-*/
-
/* *************************************
-* Tool functions
+* Helper functions
***************************************/
-ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /** maximum compressed size (worst case scenario) */
+ZSTDLIB_API size_t ZSTD_compressBound(size_t srcSize); /*!< maximum compressed size (worst case scenario) */
/* Error Management */
-ZSTDLIB_API unsigned ZSTD_isError(size_t code); /** tells if a return value is an error code */
-ZSTDLIB_API const char* ZSTD_getErrorName(size_t code); /** provides error code string */
+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 for an error code */
/* *************************************
* Explicit memory management
***************************************/
-/** Compression context management */
+/** Compression context */
typedef struct ZSTD_CCtx_s ZSTD_CCtx; /* incomplete type */
ZSTDLIB_API ZSTD_CCtx* ZSTD_createCCtx(void);
ZSTDLIB_API size_t ZSTD_freeCCtx(ZSTD_CCtx* cctx);
Same as ZSTD_compress(), but requires an already allocated ZSTD_CCtx (see ZSTD_createCCtx()) */
ZSTDLIB_API size_t ZSTD_compressCCtx(ZSTD_CCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize, int compressionLevel);
-/** Decompression context management */
+/** Decompression context */
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
+/** ZSTD_decompressDCtx() :
* Same as ZSTD_decompress(), but requires an already allocated ZSTD_DCtx (see ZSTD_createDCtx()) */
ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
/*-***********************
* Dictionary API
*************************/
-
-/*! ZSTD_compress_usingDict
-* Compression using a pre-defined Dictionary content (see dictBuilder)
+/*! ZSTD_compress_usingDict() :
+* Compression using a pre-defined Dictionary content (see dictBuilder).
* Note : dict can be NULL, in which case, it's equivalent to ZSTD_compressCCtx() */
ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx,
void* dst, size_t dstCapacity,
const void* dict,size_t dictSize,
int compressionLevel);
-/*! ZSTD_decompress_usingDict
-* Decompression using a pre-defined Dictionary content (see dictBuilder)
-* Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted
+/*! ZSTD_decompress_usingDict() :
+* Decompression using a pre-defined Dictionary content (see dictBuilder).
+* Dictionary must be identical to the one used during compression, otherwise regenerated data will be corrupted.
* Note : dict can be NULL, in which case, it's equivalent to ZSTD_decompressDCtx() */
ZSTDLIB_API size_t ZSTD_decompress_usingDict(ZSTD_DCtx* dctx,
void* dst, size_t dstCapacity,
size_t ZSTD_compressBegin_usingDict(ZSTD_CCtx* zc, const void* dict, size_t dictSize, int compressionLevel)
{
- return ZSTD_compressBegin_advanced(zc, dict, dictSize, ZSTD_getParams(compressionLevel, 128 KB));
+ return ZSTD_compressBegin_advanced(zc, dict, dictSize, ZSTD_getParams(compressionLevel, MAX(128 KB, dictSize)));
}
size_t ZSTD_compressBegin(ZSTD_CCtx* zc, int compressionLevel)
/*-*******************************************************
-* Includes
+* Dependencies
*********************************************************/
#include <stdlib.h> /* calloc */
#include <string.h> /* memcpy, memmove */
-#include <stdio.h> /* debug : printf */
+#include <stdio.h> /* debug only : printf */
#include "mem.h" /* low level memory routines */
#include "zstd_internal.h"
#include "fse_static.h"
***************************************/
unsigned ZSTD_versionNumber (void) { return ZSTD_VERSION_NUMBER; }
-/*! ZSTD_isError
+/*! ZSTD_isError() :
* tells if a return value is an error code */
unsigned ZSTD_isError(size_t code) { return ERR_isError(code); }
-/*! ZSTD_getError
+/*! ZSTD_getError() :
* convert a `size_t` function result into a proper ZSTD_errorCode enum */
ZSTD_errorCode ZSTD_getError(size_t code) { return ERR_getError(code); }
-/*! ZSTD_getErrorName
+/*! ZSTD_getErrorName() :
* provides error code string (useful for debugging) */
const char* ZSTD_getErrorName(size_t code) { return ERR_getErrorName(code); }
*/
-/** ZSTD_decodeFrameHeader_Part1
+/** ZSTD_decodeFrameHeader_Part1() :
* decode the 1st part of the Frame Header, which tells Frame Header size.
-* srcSize must be == ZSTD_frameHeaderSize_min
+* srcSize must be == ZSTD_frameHeaderSize_min.
* @return : the full size of the Frame Header */
static size_t ZSTD_decodeFrameHeader_Part1(ZSTD_DCtx* zc, const void* src, size_t srcSize)
{
return 0;
}
-/** ZSTD_decodeFrameHeader_Part2
-* decode the full Frame Header
-* srcSize must be the size provided by ZSTD_decodeFrameHeader_Part1
+/** ZSTD_decodeFrameHeader_Part2() :
+* decode the full Frame Header.
+* srcSize must be the size provided by ZSTD_decodeFrameHeader_Part1().
* @return : 0, or an error code, which can be tested using ZSTD_isError() */
static size_t ZSTD_decodeFrameHeader_Part2(ZSTD_DCtx* zc, const void* src, size_t srcSize)
{
}
-/*! ZSTD_decodeLiteralsBlock
+/*! ZSTD_decodeLiteralsBlock() :
@return : nb of bytes read from src (< srcSize ) */
size_t ZSTD_decodeLiteralsBlock(ZSTD_DCtx* dctx,
const void* src, size_t srcSize) /* note : srcSize < BLOCKSIZE */
/*
zstd_internal - common functions to include
Header File for include
- Copyright (C) 2014-2015, Yann Collet.
+ Copyright (C) 2014-2016, Yann Collet.
BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
You can contact the author at :
- zstd source repository : https://github.com/Cyan4973/zstd
- - ztsd public forum : https://groups.google.com/forum/#!forum/lz4c
*/
#ifndef ZSTD_CCOMMON_H_MODULE
#define ZSTD_CCOMMON_H_MODULE
#endif
/* *************************************
-* Includes
+* Dependencies
***************************************/
#include "mem.h"
#include "error_private.h"
#define COPY8(d,s) { ZSTD_copy8(d,s); d+=8; s+=8; }
-/*! ZSTD_wildcopy : custom version of memcpy(), can copy up to 7 bytes too many (8 bytes if length==0) */
+/*! ZSTD_wildcopy() :
+* custom version of memcpy(), can copy up to 7 bytes too many (8 bytes if length==0) */
MEM_STATIC void ZSTD_wildcopy(void* dst, const void* src, size_t length)
{
const BYTE* ip = (const BYTE*)src;
/*
zstd - standard compression library
Header File for static linking only
- Copyright (C) 2014-2015, Yann Collet.
+ Copyright (C) 2014-2016, Yann Collet.
BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
You can contact the author at :
- zstd source repository : https://github.com/Cyan4973/zstd
- - ztsd public forum : https://groups.google.com/forum/#!forum/lz4c
*/
#ifndef ZSTD_STATIC_H
#define ZSTD_STATIC_H
extern "C" {
#endif
-/* *************************************
-* Includes
+/*-*************************************
+* Dependencies
***************************************/
#include "zstd.h"
#include "mem.h"
-/* *************************************
+/*-*************************************
* Types
***************************************/
#define ZSTD_WINDOWLOG_MAX 26
#define ZSTD_MAX_CLEVEL 20
ZSTDLIB_API unsigned ZSTD_maxCLevel (void);
-/*! ZSTD_getParams
+/*! ZSTD_getParams() :
* @return ZSTD_parameters structure for a selected compression level and srcSize.
-* @srcSizeHint value is optional, select 0 if not known */
+* `srcSizeHint` value is optional, select 0 if not known */
ZSTDLIB_API ZSTD_parameters ZSTD_getParams(int compressionLevel, U64 srcSizeHint);
-/*! ZSTD_validateParams
+/*! ZSTD_validateParams() :
* correct params value to remain within authorized range */
ZSTDLIB_API void ZSTD_validateParams(ZSTD_parameters* params);
-/*! ZSTD_compress_advanced
+/*! ZSTD_compress_advanced() :
* Same as ZSTD_compress_usingDict(), with fine-tune control of each compression parameter */
ZSTDLIB_API size_t ZSTD_compress_advanced (ZSTD_CCtx* ctx,
void* dst, size_t dstCapacity,
const void* dict,size_t dictSize,
ZSTD_parameters params);
-/*! ZSTD_compress_usingPreparedDCtx
-* Same as ZSTD_compress_usingDict, but using a reference context preparedCCtx, where dictionary has been loaded.
+/*! ZSTD_compress_usingPreparedDCtx() :
+* Same as ZSTD_compress_usingDict, but using a reference context `preparedCCtx`, where dictionary has been loaded.
* It avoids reloading the dictionary each time.
-* preparedCCtx must have been properly initialized using ZSTD_compressBegin_usingDict() or ZSTD_compressBegin_advanced()
+* `preparedCCtx` must have been properly initialized using ZSTD_compressBegin_usingDict() or ZSTD_compressBegin_advanced().
* Requires 2 contexts : 1 for reference, which will not be modified, and 1 to run the compression operation */
ZSTDLIB_API size_t ZSTD_compress_usingPreparedCCtx(
ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx,
/*- Advanced Decompression functions -*/
-/*! ZSTD_decompress_usingPreparedDCtx
-* Same as ZSTD_decompress_usingDict, but using a reference context preparedDCtx, where dictionary has been loaded.
+/*! ZSTD_decompress_usingPreparedDCtx() :
+* Same as ZSTD_decompress_usingDict, but using a reference context `preparedDCtx`, where dictionary has been loaded.
* It avoids reloading the dictionary each time.
-* preparedDCtx must have been properly initialized using ZSTD_decompressBegin_usingDict().
+* `preparedDCtx` must have been properly initialized using ZSTD_decompressBegin_usingDict().
* Requires 2 contexts : 1 for reference, which will not be modified, and 1 to run the decompression operation */
ZSTDLIB_API size_t ZSTD_decompress_usingPreparedDCtx(
ZSTD_DCtx* dctx, const ZSTD_DCtx* preparedDCtx,
ZSTDLIB_API size_t ZSTD_compressContinue(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
ZSTDLIB_API size_t ZSTD_compressEnd(ZSTD_CCtx* cctx, void* dst, size_t dstCapacity);
-/**
+/*
Streaming compression, synchronous mode (bufferless)
A ZSTD_CCtx object is required to track streaming operations.
ZSTDLIB_API size_t ZSTD_nextSrcSizeToDecompress(ZSTD_DCtx* dctx);
ZSTDLIB_API size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, const void* src, size_t srcSize);
-/**
+/*
Streaming decompression, direct mode (bufferless)
A ZSTD_DCtx object is required to track streaming operations.
+ variants _usingDict() are also allowed
+ copyCCtx() and copyDCtx() work too
- When a block is considered not compressible enough, ZSTD_compressBlock() result will be zero.
- In which case, nothing is produced into @dst.
+ In which case, nothing is produced into `dst`.
+ User must test for such outcome and deal directly with uncompressed data
+ ZSTD_decompressBlock() doesn't accept uncompressed data as input !!
*/
* Error management
***************************************/
#include "error_public.h"
-/*! ZSTD_getErrorCode
- transform a function result using `size_t` into a `ZSTD_error_code` enum type
+/*! ZSTD_getErrorCode() :
+ convert a `size_t` function result into a `ZSTD_error_code` enum type,
which can be used to compare directly with enum list within "error_public.h" */
ZSTD_errorCode ZSTD_getError(size_t code);
projects / thirdparty / zstd.git / commitdiff
