From: Yann Collet <yann.collet.73@gmail.com>
Date: Mon, 1 Aug 2016 00:26:20 +0000 (+0200)
Subject: updated doc (#269)
X-Git-Tag: v0.8.0^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ca750372d43da3f90017c8ee6b04f0743ab6782;p=thirdparty%2Fzstd.git

updated doc (#269)
---

diff --git a/NEWS b/NEWS
index 16a4fb8ff..56c46fef1 100644
--- a/NEWS
+++ b/NEWS
@@ -4,7 +4,7 @@ New : Build on FreeBSD and DragonFly, thanks to JrMarino
 Changed : modified API : ZSTD_compressEnd()
 Fixed : legacy mode with ZSTD_HEAPMODE=0, by Christopher Bergqvist
 Fixed : premature end of frame when zero-sized raw block, reported by Eric Biggers
-Fixed : statistics for large dictionaries (> 256 KB), reported by Ilona Papava
+Fixed : large dictionaries (> 384 KB), reported by Ilona Papava
 Fixed : checksum correctly checked in single-pass mode
 Fixed : combined --test amd --rm, reported by Andreas M. Nilsson
 Modified : minor compression level adaptations
diff --git a/images/Cspeed4.png b/images/Cspeed4.png
index d5219d726..f0ca0ffba 100644
Binary files a/images/Cspeed4.png and b/images/Cspeed4.png differ
diff --git a/lib/dictBuilder/zdict.c b/lib/dictBuilder/zdict.c
index e1bece3a7..6c2277be8 100644
--- a/lib/dictBuilder/zdict.c
+++ b/lib/dictBuilder/zdict.c
@@ -879,7 +879,7 @@ size_t ZDICT_trainFromBuffer_unsafe(
     U32 const dictListSize = MAX(MAX(DICTLISTSIZE, nbSamples), (U32)(maxDictSize/16));
     dictItem* const dictList = (dictItem*)malloc(dictListSize * sizeof(*dictList));
     unsigned const selectivity = params.selectivityLevel == 0 ? g_selectivity_default : params.selectivityLevel;
-    unsigned const minRep = (selectivity > 30) ? 1 : nbSamples >> selectivity;
+    unsigned const minRep = (selectivity > 30) ? MINRATIO : nbSamples >> selectivity;
     size_t const targetDictSize = maxDictSize;
     size_t const samplesBuffSize = ZDICT_totalSampleSize(samplesSizes, nbSamples);
     size_t dictSize = 0;
diff --git a/lib/zstd.h b/lib/zstd.h
index 6b9ed463d..cb33b5588 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -79,20 +79,28 @@ ZSTDLIB_API size_t ZSTD_compress( void* dst, size_t dstCapacity,
                                   int compressionLevel);
 
 /*! ZSTD_getDecompressedSize() :
-*   @return : decompressed size if known, 0 otherwise.
-*      note 1 : decompressed size could be wrong or intentionally modified !
-*               Always ensure result fits within application's authorized limits !
-*               Each application can set its own limit, depending on local restrictions.
-*               For extended interoperability, it is recommended to support at least 8 MB.
-*      note 2 : when `0`, if precise failure cause is needed, use ZSTD_getFrameParams() to know more.
-*      note 3 : when `0`, and if no external guarantee about maximum possible decompressed size,
-*               it's necessary to use "streaming mode" to decompress data. */
+*   @return : decompressed size as a 64-bits value _if known_, 0 otherwise.
+*    note 1 : 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 2 : decompressed size is an optional field, that may not be present.
+*             When `return==0`, consider data to decompress could have any size.
+*             In which case, it's necessary to use streaming mode to decompress data,
+*             or rely on application's implied limits.
+*             (For example, it may know that its own data is necessarily cut into blocks <= 16 KB).
+*    note 3 : decompressed size could be wrong or intentionally modified !
+*             Always ensure result fits within application's authorized limits !
+*             Each application can have its own set of conditions.
+*             If the intention is to decompress public data compressed by zstd command line utility,
+*             it is recommended to support at least 8 MB for extended compatibility.
+*    note 4 : when `return==0`, if precise failure cause is needed, use ZSTD_getFrameParams() to know more. */
 unsigned long long ZSTD_getDecompressedSize(const void* src, size_t srcSize);
 
 /*! ZSTD_decompress() :
     `compressedSize` : must be the _exact_ size of compressed input, otherwise decompression will fail.
     `dstCapacity` must be equal or larger than originalSize (see ZSTD_getDecompressedSize() ).
-    If maximum possible content size is unknown, use streaming mode to decompress data.
+    If originalSize is unknown, and if there is no implied application-specific limitations,
+    it's necessary 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,