Merge pull request #938 from Cyan4973/v083

Update version number to v0.8.3

cli/xsum_bench.c

@@ -340,9 +340,13 @@ static char* XSUM_strcatDup(const char* s1, const char* s2)
 
 /*!
  * XSUM_benchMem():
- * buffer: Must be 16-byte aligned.
- * The real allocated size of buffer is supposed to be >= (bufferSize+3).
- * returns: 0 on success, 1 if error (invalid mode selected)
+ * Benchmark provided content up to twice per function:
+ * - once at provided aligned memory address (%16)
+ * - second time at unaligned memory address (+3)
+ * Enabled functions and modes are provided via @g_hashesToBench global variable.
+ * @buffer: Must be 16-byte aligned.
+ * The allocated size of underlying @buffer must be >= (@bufferSize+3).
+ * This function also fills @g_benchSecretBuf, to bench XXH3's _withSecret() variants.
  */
 static void XSUM_benchMem(const void* buffer, size_t bufferSize)
 {

cli/xxhsum.1

@@ -1,5 +1,5 @@
 .
-.TH "XXHSUM" "1" "July 2023" "xxhsum 0.8.2" "User Commands"
+.TH "XXHSUM" "1" "May 2024" "xxhsum 0.8.3" "User Commands"
 .
 .SH "NAME"
 \fBxxhsum\fR \- print or check xxHash non\-cryptographic checksums

xxhash.h

@@ -547,7 +547,7 @@ extern "C" {
 ***************************************/
 #define XXH_VERSION_MAJOR    0
 #define XXH_VERSION_MINOR    8
-#define XXH_VERSION_RELEASE  2
+#define XXH_VERSION_RELEASE  3
 /*! @brief Version number, encoded as two digits each */
 #define XXH_VERSION_NUMBER  (XXH_VERSION_MAJOR *100*100 + XXH_VERSION_MINOR *100 + XXH_VERSION_RELEASE)
 
@@ -1932,9 +1932,9 @@ XXH_PUBLIC_API void XXH3_generateSecret_fromSeed(XXH_NOESCAPE void* secretBuffer
  * @param secretSize The length of @p secret, in bytes.
  * @param seed       The 64-bit seed to alter the hash result predictably.
  *
- * These variants generate hash values using either
- * @p seed for "short" keys (< @ref XXH3_MIDSIZE_MAX = 240 bytes)
- * or @p secret for "large" keys (>= @ref XXH3_MIDSIZE_MAX).
+ * These variants generate hash values using either:
+ * - @p seed for "short" keys (< @ref XXH3_MIDSIZE_MAX = 240 bytes)
+ * - @p secret for "large" keys (>= @ref XXH3_MIDSIZE_MAX).
  *
  * This generally benefits speed, compared to `_withSeed()` or `_withSecret()`.
  * `_withSeed()` has to generate the secret on the fly for "large" keys.
@@ -1961,24 +1961,26 @@ XXH_PUBLIC_API XXH_PUREF XXH64_hash_t
 XXH3_64bits_withSecretandSeed(XXH_NOESCAPE const void* data, size_t len,
                               XXH_NOESCAPE const void* secret, size_t secretSize,
                               XXH64_hash_t seed);
+
 /*!
  * @brief Calculates 128-bit seeded variant of XXH3 hash of @p data.
  *
- * @param input      The block of data to be hashed, at least @p len bytes in size.
+ * @param data       The memory segment to be hashed, at least @p len bytes in size.
  * @param length     The length of @p data, in bytes.
- * @param secret     The secret data.
- * @param secretSize The length of @p secret, in bytes.
+ * @param secret     The secret used to alter hash result predictably.
+ * @param secretSize The length of @p secret, in bytes (must be >= XXH3_SECRET_SIZE_MIN)
  * @param seed64     The 64-bit seed to alter the hash result predictably.
  *
  * @return @ref XXH_OK on success.
  * @return @ref XXH_ERROR on failure.
  *
- * @see XXH3_64bits_withSecretandSeed()
+ * @see XXH3_64bits_withSecretandSeed(): contract is the same.
  */
 XXH_PUBLIC_API XXH_PUREF XXH128_hash_t
 XXH3_128bits_withSecretandSeed(XXH_NOESCAPE const void* input, size_t length,
                                XXH_NOESCAPE const void* secret, size_t secretSize,
                                XXH64_hash_t seed64);
+
 #ifndef XXH_NO_STREAM
 /*!
  * @brief Resets an @ref XXH3_state_t with secret data to begin a new hash.
@@ -1991,12 +1993,13 @@ XXH3_128bits_withSecretandSeed(XXH_NOESCAPE const void* input, size_t length,
  * @return @ref XXH_OK on success.
  * @return @ref XXH_ERROR on failure.
  *
- * @see XXH3_64bits_withSecretandSeed()
+ * @see XXH3_64bits_withSecretandSeed(). Contract is identical.
  */
 XXH_PUBLIC_API XXH_errorcode
 XXH3_64bits_reset_withSecretandSeed(XXH_NOESCAPE XXH3_state_t* statePtr,
                                     XXH_NOESCAPE const void* secret, size_t secretSize,
                                     XXH64_hash_t seed64);
+
 /*!
  * @brief Resets an @ref XXH3_state_t with secret data to begin a new hash.
  *
@@ -2008,12 +2011,21 @@ XXH3_64bits_reset_withSecretandSeed(XXH_NOESCAPE XXH3_state_t* statePtr,
  * @return @ref XXH_OK on success.
  * @return @ref XXH_ERROR on failure.
  *
- * @see XXH3_64bits_withSecretandSeed()
+ * @see XXH3_64bits_withSecretandSeed(). Contract is identical.
+ *
+ * Note: there was a bug in an earlier version of this function (<= v0.8.2)
+ * that would make it generate an incorrect hash value
+ * when @p seed == 0 and @p length < XXH3_MIDSIZE_MAX
+ * and @p secret is different from XXH3_generateSecret_fromSeed().
+ * As stated in the contract, the correct hash result must be
+ * the same as XXH3_128bits_withSeed() when @p length <= XXH3_MIDSIZE_MAX.
+ * Results generated by this older version are wrong, hence not comparable.
  */
 XXH_PUBLIC_API XXH_errorcode
 XXH3_128bits_reset_withSecretandSeed(XXH_NOESCAPE XXH3_state_t* statePtr,
                                      XXH_NOESCAPE const void* secret, size_t secretSize,
                                      XXH64_hash_t seed64);
+
 #endif /* !XXH_NO_STREAM */
 
 #endif  /* !XXH_NO_XXH3 */