From: Yann Collet <cyan@fb.com>
Date: Mon, 16 Dec 2024 20:54:52 +0000 (-0800)
Subject: updated documentation on validateSequence
X-Git-Tag: v1.5.7^2~48^2~25
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d2d0fdac4288fed2d63b4d3e0e41f4b4768f8b60;p=thirdparty%2Fzstd.git

updated documentation on validateSequence
---

diff --git a/lib/compress/zstd_compress.c b/lib/compress/zstd_compress.c
index 6ff27056f..dc084830e 100644
--- a/lib/compress/zstd_compress.c
+++ b/lib/compress/zstd_compress.c
@@ -6585,11 +6585,11 @@ size_t ZSTD_compress2(ZSTD_CCtx* cctx,
 }
 
 /* ZSTD_validateSequence() :
- * @offCode : is presumed to follow format required by ZSTD_storeSeq()
+ * @offBase : must use the format required by ZSTD_storeSeq()
  * @returns a ZSTD error code if sequence is not valid
  */
 static size_t
-ZSTD_validateSequence(U32 offCode, U32 matchLength, U32 minMatch,
+ZSTD_validateSequence(U32 offBase, U32 matchLength, U32 minMatch,
                       size_t posInSrc, U32 windowLog, size_t dictSize, int useSequenceProducer)
 {
     U32 const windowSize = 1u << windowLog;
@@ -6600,7 +6600,7 @@ ZSTD_validateSequence(U32 offCode, U32 matchLength, U32 minMatch,
      */
     size_t const offsetBound = posInSrc > windowSize ? (size_t)windowSize : posInSrc + (size_t)dictSize;
     size_t const matchLenLowerBound = (minMatch == 3 || useSequenceProducer) ? 3 : 4;
-    RETURN_ERROR_IF(offCode > OFFSET_TO_OFFBASE(offsetBound), externalSequences_invalid, "Offset too large!");
+    RETURN_ERROR_IF(offBase > OFFSET_TO_OFFBASE(offsetBound), externalSequences_invalid, "Offset too large!");
     /* Validate maxNbSeq is large enough for the given matchLength and minMatch */
     RETURN_ERROR_IF(matchLength < matchLenLowerBound, externalSequences_invalid, "Matchlength too small for the minMatch");
     return 0;
diff --git a/lib/zstd.h b/lib/zstd.h
index 6218a5d0c..7f1d8c483 100644
--- a/lib/zstd.h
+++ b/lib/zstd.h
@@ -1635,11 +1635,11 @@ ZSTDLIB_STATIC_API size_t ZSTD_mergeBlockDelimiters(ZSTD_Sequence* sequences, si
  *    the block size derived from the cctx, and sequences may be split. This is the default setting.
  *
  *    If ZSTD_c_blockDelimiters == ZSTD_sf_explicitBlockDelimiters, the array of ZSTD_Sequence is expected to contain
- *    block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
+ *    valid block delimiters (defined in ZSTD_Sequence). Behavior is undefined if no block delimiters are provided.
  *
- *    If ZSTD_c_validateSequences == 0, this function will blindly accept the sequences provided. Invalid sequences cause undefined
- *    behavior. If ZSTD_c_validateSequences == 1, then if sequence is invalid (see doc/zstd_compression_format.md for
- *    specifics regarding offset/matchlength requirements) then the function will bail out and return an error.
+ *    If ZSTD_c_validateSequences == 0, this function blindly accepts the Sequences provided. Invalid Sequences cause undefined
+ *    behavior. If ZSTD_c_validateSequences == 1, then the function will detect invalid Sequences (see doc/zstd_compression_format.md for
+ *    specifics regarding offset/matchlength requirements) and then bail out and return an error.
  *
  *    In addition to the two adjustable experimental params, there are other important cctx params.
  *    - ZSTD_c_minMatch MUST be set as less than or equal to the smallest match generated by the match finder. It has a minimum value of ZSTD_MINMATCH_MIN.
@@ -1662,10 +1662,10 @@ ZSTD_compressSequences(ZSTD_CCtx* cctx,
 /*! ZSTD_compressSequencesAndLiterals() :
  * This is a variant of ZSTD_compressSequences() which,
  * instead of receiving (src,srcSize) as input parameter, receives (literals,litSize),
- * aka all literals already extracted and laid out into a single continuous buffer.
+ * aka all the literals, already extracted and laid out into a single continuous buffer.
  * This can be useful if the process generating the sequences also happens to generate the buffer of literals,
  * thus skipping an extraction + caching stage.
- * It's merely a speed optimization when the right conditions are met,
+ * It's a speed optimization, useful when the right conditions are met,
  * but it also features the following limitations:
  * - Only supports explicit delimiter mode
  * - Supports 1 block only (max input 128 KB)
@@ -2172,17 +2172,17 @@ ZSTDLIB_STATIC_API size_t ZSTD_CCtx_refPrefix_advanced(ZSTD_CCtx* cctx, const vo
 /* ZSTD_c_validateSequences
  * Default is 0 == disabled. Set to 1 to enable sequence validation.
  *
- * For use with sequence compression API: ZSTD_compressSequences().
- * Designates whether or not we validate sequences provided to ZSTD_compressSequences()
+ * For use with sequence compression API: ZSTD_compressSequences*().
+ * Designates whether or not provided sequences are validated within ZSTD_compressSequences*()
  * during function execution.
  *
- * Without validation, providing a sequence that does not conform to the zstd spec will cause
- * undefined behavior, and may produce a corrupted block.
+ * When Sequence validation is disabled (default), Sequences are compressed as-is,
+ * so they must correct, otherwise it would result in a corruption error.
  *
- * With validation enabled, if sequence is invalid (see doc/zstd_compression_format.md for
+ * Sequence validation adds some protection, by ensuring that all values respect boundary conditions.
+ * If a Sequence is detected invalid (see doc/zstd_compression_format.md for
  * specifics regarding offset/matchlength requirements) then the function will bail out and
  * return an error.
- *
  */
 #define ZSTD_c_validateSequences ZSTD_c_experimentalParam12