From: Yann Collet Date: Thu, 4 Feb 2016 14:28:14 +0000 (+0100) Subject: minor comments refactoring X-Git-Tag: v0.5.0~1^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=953ce72f4a87ecfc053a6dec5115ef58a841c4c3;p=thirdparty%2Fzstd.git minor comments refactoring --- diff --git a/lib/zstd.h b/lib/zstd.h index 652609f36..837451ca2 100644 --- a/lib/zstd.h +++ b/lib/zstd.h @@ -1,7 +1,7 @@ /* 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) @@ -28,7 +28,6 @@ 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 @@ -37,13 +36,13 @@ extern "C" { #endif -/* ************************************* -* Includes +/*-************************************* +* Dependencies ***************************************/ #include /* size_t */ -/* *************************************************************** +/*-*************************************************************** * Export parameters *****************************************************************/ /*! @@ -70,43 +69,39 @@ ZSTDLIB_API unsigned ZSTD_versionNumber (void); /* ************************************* * 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); @@ -115,12 +110,12 @@ 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); @@ -128,9 +123,8 @@ ZSTDLIB_API size_t ZSTD_decompressDCtx(ZSTD_DCtx* ctx, void* dst, size_t dstCapa /*-*********************** * 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, @@ -138,9 +132,9 @@ ZSTDLIB_API size_t ZSTD_compress_usingDict(ZSTD_CCtx* ctx, 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, diff --git a/lib/zstd_compress.c b/lib/zstd_compress.c index f4ddb910f..47b55cfff 100644 --- a/lib/zstd_compress.c +++ b/lib/zstd_compress.c @@ -2154,7 +2154,7 @@ size_t ZSTD_compressBegin_advanced(ZSTD_CCtx* zc, 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) diff --git a/lib/zstd_decompress.c b/lib/zstd_decompress.c index f0c8c428c..1e8aa4c0c 100644 --- a/lib/zstd_decompress.c +++ b/lib/zstd_decompress.c @@ -51,11 +51,11 @@ /*-******************************************************* -* Includes +* Dependencies *********************************************************/ #include /* calloc */ #include /* memcpy, memmove */ -#include /* debug : printf */ +#include /* debug only : printf */ #include "mem.h" /* low level memory routines */ #include "zstd_internal.h" #include "fse_static.h" @@ -105,15 +105,15 @@ static void ZSTD_copy4(void* dst, const void* src) { memcpy(dst, src, 4); } ***************************************/ 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); } @@ -268,9 +268,9 @@ void ZSTD_copyDCtx(ZSTD_DCtx* dstDCtx, const ZSTD_DCtx* srcDCtx) */ -/** 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) { @@ -296,9 +296,9 @@ size_t ZSTD_getFrameParams(ZSTD_parameters* params, const void* src, size_t srcS 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) { @@ -340,7 +340,7 @@ static size_t ZSTD_copyRawBlock(void* dst, size_t maxDstSize, const void* src, s } -/*! 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 */ diff --git a/lib/zstd_internal.h b/lib/zstd_internal.h index d3f989cd2..20c626738 100644 --- a/lib/zstd_internal.h +++ b/lib/zstd_internal.h @@ -1,7 +1,7 @@ /* 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) @@ -28,7 +28,6 @@ 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 @@ -38,7 +37,7 @@ extern "C" { #endif /* ************************************* -* Includes +* Dependencies ***************************************/ #include "mem.h" #include "error_private.h" @@ -117,7 +116,8 @@ static void ZSTD_copy8(void* dst, const void* src) { memcpy(dst, src, 8); } #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; diff --git a/lib/zstd_static.h b/lib/zstd_static.h index 4a36f1e8a..ad81e25ca 100644 --- a/lib/zstd_static.h +++ b/lib/zstd_static.h @@ -1,7 +1,7 @@ /* 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) @@ -28,7 +28,6 @@ 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 @@ -42,14 +41,14 @@ extern "C" { #endif -/* ************************************* -* Includes +/*-************************************* +* Dependencies ***************************************/ #include "zstd.h" #include "mem.h" -/* ************************************* +/*-************************************* * Types ***************************************/ #define ZSTD_WINDOWLOG_MAX 26 @@ -85,16 +84,16 @@ typedef struct #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, @@ -102,10 +101,10 @@ ZSTDLIB_API size_t ZSTD_compress_advanced (ZSTD_CCtx* ctx, 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, @@ -114,10 +113,10 @@ ZSTDLIB_API size_t ZSTD_compress_usingPreparedCCtx( /*- 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, @@ -136,7 +135,7 @@ ZSTDLIB_API size_t ZSTD_copyCCtx(ZSTD_CCtx* cctx, const ZSTD_CCtx* preparedCCtx) 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. @@ -169,7 +168,7 @@ ZSTDLIB_API size_t ZSTD_getFrameParams(ZSTD_parameters* params, const void* src, 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. @@ -216,7 +215,7 @@ ZSTDLIB_API size_t ZSTD_decompressContinue(ZSTD_DCtx* dctx, void* dst, size_t ds + 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 !! */ @@ -229,8 +228,8 @@ size_t ZSTD_decompressBlock(ZSTD_DCtx* dctx, void* dst, size_t dstCapacity, cons * 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);