Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing doxygen style comments to XXH3 family #856

Merged
merged 2 commits into from
Jul 12, 2023
Merged

Add missing doxygen style comments to XXH3 family #856

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
58d6f48
Add doxygen comments to XXH3_64bits_ family
t-mat Jul 10, 2023
c4d049b
Add doxygen comments to XXH3_128bits_ family
t-mat Jul 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 156 additions & 8 deletions xxhash.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1022,20 +1022,50 @@ XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSecret(XXH_NOESCAPE const
typedef struct XXH3_state_s XXH3_state_t;
XXH_PUBLIC_API XXH_MALLOCF XXH3_state_t* XXH3_createState(void);
XXH_PUBLIC_API XXH_errorcode XXH3_freeState(XXH3_state_t* statePtr);

/*!
* @brief Copies one @ref XXH3_state_t to another.
*
* @param dst_state The state to copy to.
* @param src_state The state to copy from.
* @pre
* @p dst_state and @p src_state must not be `NULL` and must not overlap.
*/
XXH_PUBLIC_API void XXH3_copyState(XXH_NOESCAPE XXH3_state_t* dst_state, XXH_NOESCAPE const XXH3_state_t* src_state);

/*
* XXH3_64bits_reset():
* Initialize with default parameters.
* digest will be equivalent to `XXH3_64bits()`.
/*!
* @brief Resets an @ref XXH3_state_t to begin a new hash.
*
* This function resets `statePtr` and generate a secret with default parameters. Call it before @ref XXH3_64bits_update().
* Digest will be equivalent to `XXH3_64bits()`.
*
* @param statePtr The state struct to reset.
*
* @pre
* @p statePtr must not be `NULL`.
*
* @return @ref XXH_OK on success, @ref XXH_ERROR on failure.
*
*/
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset(XXH_NOESCAPE XXH3_state_t* statePtr);
/*
* XXH3_64bits_reset_withSeed():
* Generate a custom secret from `seed`, and store it into `statePtr`.
* digest will be equivalent to `XXH3_64bits_withSeed()`.

/*!
* @brief Resets an @ref XXH3_state_t with 64-bit seed to begin a new hash.
*
* This function resets `statePtr` and generate a secret from `seed`. Call it before @ref XXH3_64bits_update().
* Digest will be equivalent to `XXH3_64bits_withSeed()`.
*
* @param statePtr The state struct to reset.
* @param seed The 64-bit seed to alter the state.
*
* @pre
* @p statePtr must not be `NULL`.
*
* @return @ref XXH_OK on success, @ref XXH_ERROR on failure.
*
*/
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSeed(XXH_NOESCAPE XXH3_state_t* statePtr, XXH64_hash_t seed);

/*!
* XXH3_64bits_reset_withSecret():
* `secret` is referenced, it _must outlive_ the hash streaming session.
Expand All @@ -1047,7 +1077,40 @@ XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSeed(XXH_NOESCAPE XXH3_state_
*/
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSecret(XXH_NOESCAPE XXH3_state_t* statePtr, XXH_NOESCAPE const void* secret, size_t secretSize);

/*!
* @brief Consumes a block of @p input to an @ref XXH3_state_t.
*
* Call this to incrementally consume blocks of data.
*
* @param statePtr The state struct to update.
* @param input The block of data to be hashed, at least @p length bytes in size.
* @param length The length of @p input, in bytes.
*
* @pre
* @p statePtr must not be `NULL`.
* @pre
* The memory between @p input and @p input + @p length must be valid,
* readable, contiguous memory. However, if @p length is `0`, @p input may be
* `NULL`. In C++, this also must be *TriviallyCopyable*.
*
* @return @ref XXH_OK on success, @ref XXH_ERROR on failure.
*/
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_update (XXH_NOESCAPE XXH3_state_t* statePtr, XXH_NOESCAPE const void* input, size_t length);

/*!
* @brief Returns the calculated XXH3 64-bit hash value from an @ref XXH3_state_t.
*
* @note
* Calling XXH3_64bits_digest() will not affect @p statePtr, so you can update,
* digest, and update again.
*
* @param statePtr The state struct to calculate the hash from.
*
* @pre
* @p statePtr must not be `NULL`.
*
* @return The calculated XXH3 64-bit hash value from that state.
*/
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_digest (XXH_NOESCAPE const XXH3_state_t* statePtr);
#endif /* !XXH_NO_STREAM */

Expand Down Expand Up @@ -1107,12 +1170,75 @@ XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSecret(XXH_NOESCAPE cons
* All reset and streaming functions have same meaning as their 64-bit counterpart.
*/

/*!
* @brief Resets an @ref XXH3_state_t to begin a new hash.
*
* This function resets `statePtr` and generate a secret with default parameters. Call it before @ref XXH3_128bits_update().
* Digest will be equivalent to `XXH3_128bits()`.
*
* @param statePtr The state struct to reset.
*
* @pre
* @p statePtr must not be `NULL`.
*
* @return @ref XXH_OK on success, @ref XXH_ERROR on failure.
*
*/
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset(XXH_NOESCAPE XXH3_state_t* statePtr);

/*!
* @brief Resets an @ref XXH3_state_t with 64-bit seed to begin a new hash.
*
* This function resets `statePtr` and generate a secret from `seed`. Call it before @ref XXH3_128bits_update().
* Digest will be equivalent to `XXH3_128bits_withSeed()`.
*
* @param statePtr The state struct to reset.
* @param seed The 64-bit seed to alter the state.
*
* @pre
* @p statePtr must not be `NULL`.
*
* @return @ref XXH_OK on success, @ref XXH_ERROR on failure.
*
*/
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSeed(XXH_NOESCAPE XXH3_state_t* statePtr, XXH64_hash_t seed);
/*! @brief Custom secret 128-bit variant of XXH3. @see XXH_64bits_reset_withSecret(). */
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSecret(XXH_NOESCAPE XXH3_state_t* statePtr, XXH_NOESCAPE const void* secret, size_t secretSize);

/*!
* @brief Consumes a block of @p input to an @ref XXH3_state_t.
*
* Call this to incrementally consume blocks of data.
*
* @param statePtr The state struct to update.
* @param input The block of data to be hashed, at least @p length bytes in size.
* @param length The length of @p input, in bytes.
*
* @pre
* @p statePtr must not be `NULL`.
* @pre
* The memory between @p input and @p input + @p length must be valid,
* readable, contiguous memory. However, if @p length is `0`, @p input may be
* `NULL`. In C++, this also must be *TriviallyCopyable*.
*
* @return @ref XXH_OK on success, @ref XXH_ERROR on failure.
*/
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_update (XXH_NOESCAPE XXH3_state_t* statePtr, XXH_NOESCAPE const void* input, size_t length);

/*!
* @brief Returns the calculated XXH3 128-bit hash value from an @ref XXH3_state_t.
*
* @note
* Calling XXH3_128bits_digest() will not affect @p statePtr, so you can update,
* digest, and update again.
*
* @param statePtr The state struct to calculate the hash from.
*
* @pre
* @p statePtr must not be `NULL`.
*
* @return The calculated XXH3 128-bit hash value from that state.
*/
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_digest (XXH_NOESCAPE const XXH3_state_t* statePtr);
#endif /* !XXH_NO_STREAM */

Expand All @@ -1139,7 +1265,29 @@ XXH_PUBLIC_API XXH_PUREF int XXH128_cmp(XXH_NOESCAPE const void* h128_1, XXH_NOE

/******* Canonical representation *******/
typedef struct { unsigned char digest[sizeof(XXH128_hash_t)]; } XXH128_canonical_t;


/*!
* @brief Converts an @ref XXH128_hash_t to a big endian @ref XXH128_canonical_t.
*
* @param dst The @ref XXH128_canonical_t pointer to be stored to.
* @param hash The @ref XXH128_hash_t to be converted.
*
* @pre
* @p dst must not be `NULL`.
*/
XXH_PUBLIC_API void XXH128_canonicalFromHash(XXH_NOESCAPE XXH128_canonical_t* dst, XXH128_hash_t hash);

/*!
* @brief Converts an @ref XXH128_canonical_t to a native @ref XXH128_hash_t.
*
* @param src The @ref XXH128_canonical_t to convert.
*
* @pre
* @p src must not be `NULL`.
*
* @return The converted hash.
*/
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH128_hashFromCanonical(XXH_NOESCAPE const XXH128_canonical_t* src);


Expand Down