### Setup collisions test with limited RAM

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

When RAM is limited, use the --filter mode. This example plans for 16 GB for the filter, expecting to process approximately 1 billion candidates.

```bash
./collisionsTest --nbh=14G --filter NameOfHash
```

--------------------------------

### Build and Install xxHash using CMake

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/README.md

Use these commands to build and install xxHash from its source directory. This method is recommended for system-wide usage.

```bash
cd /path/to/xxHash
cmake -S build/cmake -B cmake_build
cmake --build cmake_build --parallel
cmake --install cmake_build
```

--------------------------------

### Install Targets and Package Configuration

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/CMakeLists.txt

Installs the xxhash library, headers, and the xxhsum executable. It also configures and installs CMake package files (Config.cmake, Targets.cmake) and pkg-config files for easier integration.

```cmake
if(NOT XXHASH_BUNDLED_MODE)
  include(GNUInstallDirs)

  install (TARGETS xxhash
    EXPORT xxHashTargets
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}")
  install (FILES "${XXHASH_DIR}/xxhash.h"
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
  install (FILES "${XXHASH_DIR}/xxh3.h"
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
  if(DISPATCH)
    install (FILES "${XXHASH_DIR}/xxh_x86dispatch.h"
      DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
  endif()
  if(XXHASH_BUILD_XXHSUM)
    install (TARGETS xxhsum
      EXPORT xxHashTargets
      RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}")
    install (FILES "${XXHSUM_DIR}/xxhsum.1"
      DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
  endif(XXHASH_BUILD_XXHSUM)

  include(CMakePackageConfigHelpers)

  set(xxHash_VERSION_CONFIG "${PROJECT_BINARY_DIR}/xxHashConfigVersion.cmake")
  set(xxHash_PROJECT_CONFIG "${PROJECT_BINARY_DIR}/xxHashConfig.cmake")
  set(xxHash_TARGETS_CONFIG "${PROJECT_BINARY_DIR}/xxHashTargets.cmake")
  set(xxHash_CONFIG_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}/cmake/xxHash/")
  write_basic_package_version_file(${xxHash_VERSION_CONFIG}
    VERSION ${XXHASH_VERSION_STRING}
    COMPATIBILITY AnyNewerVersion)
  configure_package_config_file(
    ${PROJECT_SOURCE_DIR}/xxHashConfig.cmake.in
    ${xxHash_PROJECT_CONFIG}
    INSTALL_DESTINATION ${xxHash_CONFIG_INSTALL_DIR})
    export(EXPORT xxHashTargets
      FILE ${xxHash_TARGETS_CONFIG}
      NAMESPACE ${PROJECT_NAME}::)

  install (FILES ${xxHash_PROJECT_CONFIG} ${xxHash_VERSION_CONFIG}
    DESTINATION ${xxHash_CONFIG_INSTALL_DIR})
  install (EXPORT xxHashTargets
    DESTINATION ${xxHash_CONFIG_INSTALL_DIR}
    NAMESPACE ${PROJECT_NAME}::)

  # configure and install pkg-config
  include(JoinPaths.cmake)
  set(PREFIX ${CMAKE_INSTALL_PREFIX})
  set(EXECPREFIX "\${prefix}")
  join_paths(INCLUDEDIR "\${prefix}" "${CMAKE_INSTALL_INCLUDEDIR}")
  join_paths(LIBDIR "\${prefix}" "${CMAKE_INSTALL_LIBDIR}")
  set(VERSION "${XXHASH_VERSION_STRING}")
  configure_file(${XXHASH_DIR}/libxxhash.pc.in ${CMAKE_BINARY_DIR}/libxxhash.pc @ONLY)

  install (FILES ${CMAKE_BINARY_DIR}/libxxhash.pc
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)

endif(NOT XXHASH_BUNDLED_MODE)
```

--------------------------------

### Find and Link xxHash in CMakeLists.txt

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/README.md

Add this to your CMakeLists.txt to find the installed xxHash package and link it to your target. Requires xxHash to be installed.

```cmake
find_package(xxHash 0.8 CONFIG REQUIRED)
target_link_libraries(YourTarget PRIVATE xxHash::xxhash)
```

--------------------------------

### Initialize Accumulators (xxHash)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Initializes the four internal accumulators with values derived from an optional seed. This is the starting point for processing larger inputs.

```c
  u64 acc1 = seed + PRIME64_1 + PRIME64_2;
  u64 acc2 = seed + PRIME64_2;
  u64 acc3 = seed + 0;
  u64 acc4 = seed - PRIME64_1;
```

--------------------------------

### Build Configuration Options for XXHash

Source: https://context7.com/cyan4973/xxhash/llms.txt

Control library behavior and optimize for specific use cases by defining preprocessor macros during compilation. Examples include inlining all functions, adding a namespace prefix, or disabling specific algorithms like XXH3 or 64-bit variants.

```c
// Compile with specific options:

// 1. Inline all functions for maximum speed (header-only mode)
// gcc -DXXH_INLINE_ALL myapp.c -o myapp
#define XXH_INLINE_ALL

// 2. Namespace prefix to avoid symbol collisions
// gcc -DXXH_NAMESPACE=MyApp_ myapp.c xxhash.c -o myapp
#define XXH_NAMESPACE MyApp_

// 3. Disable XXH3 to reduce binary size
// gcc -DXXH_NO_XXH3 myapp.c xxhash.c -o myapp
#define XXH_NO_XXH3

// 4. Disable 64-bit variants (XXH64 and XXH3) for 32-bit only builds
// gcc -DXXH_NO_LONG_LONG myapp.c xxhash.c -o myapp
#define XXH_NO_LONG_LONG

// 5. Disable streaming API for smaller binary
// gcc -DXXH_NO_STREAM myapp.c xxhash.c -o myapp
#define XXH_NO_STREAM

// 6. Force specific SIMD instruction set for XXH3
// gcc -DXXH_VECTOR=XXH_AVX2 -mavx2 myapp.c xxhash.c -o myapp
#define XXH_VECTOR XXH_AVX2  // Options: XXH_SCALAR, XXH_SSE2, XXH_AVX2, XXH_AVX512, XXH_NEON

// 7. Disable stdlib (no malloc/free) for embedded systems
// gcc -DXXH_NO_STDLIB myapp.c xxhash.c -o myapp
#define XXH_NO_STDLIB  // createState() will return NULL, use static allocation

#include "xxhash.h"

```

--------------------------------

### Enable CPack Packaging

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/CMakeLists.txt

Includes the CPack module to enable packaging of the project, typically for creating installers or archives.

```cmake
include(CPack)
```

--------------------------------

### XXH64 hash collision test results

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

Example results for XXH64 hash algorithm with different input lengths and hash counts, showing the number of collisions against the expected value.

```none
| __XXH64__  | 255 | 100 Gi | 312.5 | 294 |  |
```

```none
| __XXH64__  |   8 | 100 Gi | 312.5 | __0__ | `XXH64` is bijective for `len==8` |
```

--------------------------------

### xxhsum CLI Tool Usage Examples

Source: https://context7.com/cyan4973/xxhash/llms.txt

The 'xxhsum' command-line utility computes and verifies xxHash checksums. It supports different hash algorithms (XXH64, XXH32, XXH128, XXH3) and output formats (default, BSD style). Checksums can be saved to a file and verified later using the '-c' option.

```bash
# Generate XXH64 hash (default) for files
xxhsum file1.txt file2.txt

# Generate XXH32 hash
xxhsum -H0 file.txt
xxh32sum file.txt  # Equivalent shortcut

# Generate XXH128 hash
xxhsum -H2 file.txt
xxh128sum file.txt  # Equivalent shortcut

# Generate XXH3 64-bit hash (GNU format)
xxhsum -H3 file.txt
xxh3sum file.txt  # Equivalent shortcut

# Output in BSD style format
xxhsum --tag file.txt

# Save checksums to file and verify later
xxhsum -H1 *.c > checksums.xxh64
xxhsum -c checksums.xxh64

# Quiet mode - only show failures
xxhsum -c --quiet checksums.xxh64

```

--------------------------------

### XXH3 hash collision test results

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

Example results for XXH3 hash algorithm with different input lengths and hash counts, showing the number of collisions against the expected value.

```none
| __XXH3__   | 255 | 100 Gi | 312.5 | 326 |  |
```

```none
| __XXH3__   |   8 | 100 Gi | 312.5 | __0__ | `XXH3` is also bijective for `len==8` |
```

```none
| __XXH3__   |  16 | 100 Gi | 312.5 | 332 |  |
```

```none
| __XXH3__   |  32 |  14 Gi |   6.1 |   3 |  |
```

--------------------------------

### XXH128 hash collision test results

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

Example results for XXH128 hash algorithm, including low64 and high64 variants, with different input lengths and hash counts, showing collisions.

```none
| __XXH128__ low64 | 512 | 100 Gi | 312.5 | 321 |  |
```

```none
| __XXH128__ high64| 512 | 100 Gi | 312.5 | 325 |  |
```

```none
| __XXH128__ | 255 | 100 Gi |   0.0 |   0 | a 128-bit hash is expected to generate 0 collisions |
```

```none
| __XXH128__ |  16 |  25 Gi |   0.0 |   0 | test range 9-16 |
```

```none
| __XXH128__ |  32 |  25 Gi |   0.0 |   0 | test range 17-128 |
```

```none
| __XXH128__ | 100 |  13 Gi |   0.0 |   0 | test range 17-128 |
```

```none
| __XXH128__ | 200 |  13 Gi |   0.0 |   0 | test range 129-240 |
```

--------------------------------

### XXH3-64 Input Processing for 17-128 Bytes

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes input data between 17 and 128 bytes for XXH3-64. It iterates through pairs of chunks from the start and end of the input, mixing them with the seed and accumulating the result.

```c
// the loop variable `i` should be signed to avoid underflow in implementation
processInput_XXH3_64_17to128():
  u64 numRounds = ((inputLength - 1) >> 5) + 1;
  for (i = numRounds - 1; i >= 0; i--) {
    size offsetStart = i*16;
    size offsetEnd = inputLength - i*16 - 16;
    acc += mixStep(input[offsetStart:offsetStart+16], i*32, seed);
    acc += mixStep(input[offsetEnd:offsetEnd+16], i*32+16, seed);
  }
```

--------------------------------

### Build with Different Compiler Flags

Source: https://github.com/cyan4973/xxhash/blob/dev/build/make/README.md

Build your project with various compiler flags to create different configurations. New flag sets will generate objects in new cache directories. Switching back to a previous configuration will only require relinking if objects are unchanged.

```sh
# Release with GCC
make CFLAGS="-O3"
```

```sh
# Debug with Clang + AddressSanitizer (new cache dir)
make CC=clang CFLAGS="-g -O0 -fsanitize=address"
```

```sh
# Switch back to GCC release (objects still valid, relink only)
make CFLAGS="-O3"
```

--------------------------------

### Add xxHash as a Subdirectory in CMake

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/README.md

Bundle xxHash directly into your project by adding its build directory as a subdirectory. This method avoids system-wide installation.

```cmake
# Optional: Configure xxHash before adding
set(XXHASH_BUILD_XXHSUM OFF)        # Don't build command line tool
option(BUILD_SHARED_LIBS OFF)       # Build static library

# Add xxHash to your project
add_subdirectory(path/to/xxHash/build/cmake xxhash_build EXCLUDE_FROM_ALL)

# Link to your target
target_link_libraries(YourTarget PRIVATE xxHash::xxhash)
```

--------------------------------

### Configure xxhsum Executable

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/CMakeLists.txt

Builds the xxhsum command-line executable, including dispatch mode sources if enabled. It links against the xxhash library and sets include directories.

```cmake
if(XXHASH_BUILD_XXHSUM)
  set(XXHSUM_DIR "${XXHASH_DIR}/cli")
  # xxhsum
  set(XXHSUM_SOURCES)
  if (XXHSUM_DISPATCH)
    list(APPEND XXHSUM_SOURCES "${XXHASH_DIR}/xxh_x86dispatch.c")
  endif()
  list(APPEND XXHSUM_SOURCES "${XXHSUM_DIR}/xxhsum.c"
                             "${XXHSUM_DIR}/xsum_arch.c"
                             "${XXHSUM_DIR}/xsum_os_specific.c"
                             "${XXHSUM_DIR}/xsum_output.c"
                             "${XXHSUM_DIR}/xsum_sanity_check.c"
                             "${XXHSUM_DIR}/xsum_bench.c"
      )
  add_executable(xxhsum ${XXHSUM_SOURCES})
  add_executable(${PROJECT_NAME}::xxhsum ALIAS xxhsum)

  target_link_libraries(xxhsum PRIVATE xxhash)
  target_include_directories(xxhsum PRIVATE "${XXHASH_DIR}")
endif(XXHASH_BUILD_XXHSUM)
```

--------------------------------

### XXH3 9-16 Bytes Input Initialization

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Reads the first and last 8 bytes of input for XXH3 hashing when the input size is between 9 and 16 bytes.

```c
u64 inputFirst = input[0:8];
u64 inputLast = input[inputLength-8:inputLength];
```

--------------------------------

### Run collisionsTest with custom parameters

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

Execute the collisionsTest tool, specifying the hash name and optional parameters like --nbh for the number of hashes, --filter to enable memory reduction, --threadlog for thread count, and --len for input length.

```bash
./collisionsTest [hashName] [opt]
```

```bash
./collisionsTest --nbh=NB
```

```bash
./collisionsTest --filter
```

```bash
./collisionsTest --threadlog=NB
```

```bash
./collisionsTest --len=NB
```

--------------------------------

### Simplified Accumulator Initialization (xxHash)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Used when the input is less than 32 bytes. A single accumulator is initialized, bypassing parallel processing.

```c
  u64 acc  = seed + PRIME64_5;
```

--------------------------------

### XXH3-128 Input Processing for 17-128 Bytes

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes input data between 17 and 128 bytes for XXH3-128. It pairs chunks from the start and end of the input, mixing them using `mixTwoChunks` and accumulating results.

```c
processInput_XXH3_128_17to128():
  u64 numRounds = ((inputLength - 1) >> 5) + 1;
  for (i = numRounds - 1; i >= 0; i--) {
    size offsetStart = i*16;
    size offsetEnd = inputLength - i*16 - 16;
    mixTwoChunks(input[offsetStart:offsetStart+16], input[offsetEnd:offsetEnd+16], i*32, seed);
  }
```

--------------------------------

### Configure Library and Binary Options

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/CMakeLists.txt

This CMake code sets up options for building shared or static libraries and an optional xxhsum binary. It also handles bundled mode, where xxHash is included as part of another project, influencing library build types.

```cmake
option(BUILD_SHARED_LIBS "Build shared library" ON)
option(XXHASH_BUILD_XXHSUM "Build the xxhsum binary" ON)

# If XXHASH is being bundled in another project, we don't want to
# install anything.  However, we want to let people override this, so
# we'll use the XXHASH_BUNDLED_MODE variable to let them do that; just
# set it to OFF in your project before you add_subdirectory(xxhash/cmake_unofficial).
if(NOT DEFINED XXHASH_BUNDLED_MODE)
  if("${PROJECT_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
    set(XXHASH_BUNDLED_MODE OFF)
  else()
    set(XXHASH_BUNDLED_MODE ON)
  endif()
endif()
set(XXHASH_BUNDLED_MODE ${XXHASH_BUNDLED_MODE} CACHE BOOL "" FORCE)
mark_as_advanced(XXHASH_BUNDLED_MODE)

# Allow people to choose whether to build shared or static libraries
# via the BUILD_SHARED_LIBS option unless we are in bundled mode,
# in which case we always use static libraries.
include(CMakeDependentOption)
CMAKE_DEPENDENT_OPTION(BUILD_SHARED_LIBS "Build shared libraries" ON "NOT XXHASH_BUNDLED_MODE" OFF)
```

--------------------------------

### XXH3-64 Accumulator Initialization (Medium Inputs)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Initializes the internal accumulator for XXH3-64 hashing with medium input sizes (17-240 bytes).

```c
// For XXH3-64
u64 acc = inputLength * PRIME64_1;
```

--------------------------------

### Include multiconf.make in Makefile

Source: https://github.com/cyan4973/xxhash/blob/dev/build/make/README.md

Include the multiconf.make file in your root Makefile to enable its functionality.

```makefile
include multiconf.make
```

--------------------------------

### XXH3 4-8 Bytes Input Initialization

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Reads the first and last 4 bytes of input and calculates a modified seed for XXH3 hashing when input is between 4 and 8 bytes.

```c
u32 inputFirst = input[0:4];
u32 inputLast = input[inputLength-4:inputLength];
u64 modifiedSeed = seed xor ((u64)bswap32((u32)lowerHalf(seed)) << 32);
```

--------------------------------

### Build the collisionsTest tool

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

Compile the collisionsTest tool using make. Note that the code is a mix of C99 and C++14, requiring a compatible compiler.

```bash
make
```

--------------------------------

### XXH32 Simplified Initialization

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

For inputs less than 16 bytes, XXH32 uses a simplified initialization with a single accumulator.

```c
  u32 acc  = seed + PRIME32_5;
```

--------------------------------

### One-Shot xxHash 64-bit Hash Calculation

Source: https://github.com/cyan4973/xxhash/blob/dev/README.md

Use this for a simple, single-buffer hash. Ensure xxhash.h is included.

```C
#include "xxhash.h"

    (...) 
    XXH64_hash_t hash = XXH64(buffer, size, seed);
}
```

--------------------------------

### XXH3 64-bit Streaming Hash for Files

Source: https://context7.com/cyan4973/xxhash/llms.txt

Implements a 64-bit hash for files using the XXH3 streaming API. Asserts on memory allocation failure.

```c
#include "xxhash.h"
#include <stdio.h>
#include <assert.h>

XXH64_hash_t hash_file_xxh3(FILE* file) {
    // Create state (properly aligned, don't use malloc directly)
    XXH3_state_t* state = XXH3_createState();
    assert(state != NULL && "Out of memory!");

    // Reset for default (unseeded) mode
    XXH3_64bits_reset(state);

    // Process file in chunks
    char buffer[4096];
    size_t count;
    while ((count = fread(buffer, 1, sizeof(buffer), file)) != 0) {
        XXH3_64bits_update(state, buffer, count);
    }

    // Get 64-bit digest
    XXH64_hash_t result = XXH3_64bits_digest(state);

    XXH3_freeState(state);
    return result;
}

// Example with seeded streaming
XXH64_hash_t hash_with_seed_streaming(const void* data, size_t len, XXH64_hash_t seed) {
    XXH3_state_t* state = XXH3_createState();

    // Reset with seed
    XXH3_64bits_reset_withSeed(state, seed);
    XXH3_64bits_update(state, data, len);

    XXH64_hash_t hash = XXH3_64bits_digest(state);
    XXH3_freeState(state);
    return hash;
}

int main(void) {
    FILE* file = fopen("data.bin", "rb");
    if (file) {
        XXH64_hash_t hash = hash_file_xxh3(file);
        printf("File XXH3_64: %016llx\n", (unsigned long long)hash);
        fclose(file);
    }
    return 0;
}
```

--------------------------------

### XXH3-128 Accumulator Initialization (Medium Inputs)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Initializes the internal accumulators for XXH3-128 hashing with medium input sizes (17-240 bytes).

```c
// For XXH3-128
u64 acc[2] = {inputLength * PRIME64_1, 0};
```

--------------------------------

### XXH3 Initialization of Accumulators for Large Inputs

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Initializes the 8 internal 64-bit accumulators with fixed prime constants for processing inputs larger than 240 bytes.

```c
u64 acc[8] = {
  PRIME32_3, PRIME64_1, PRIME64_2, PRIME64_3,
  PRIME64_4, PRIME32_2, PRIME64_5, PRIME32_1};

```

--------------------------------

### Static Allocation with XXH_STATIC_LINKING_ONLY

Source: https://context7.com/cyan4973/xxhash/llms.txt

Allocate XXH32, XXH64, and XXH3 states on the stack instead of the heap for performance-critical code. Ensure XXH3_state_t is properly aligned using XXH_ALIGN(64).

```c
#define XXH_STATIC_LINKING_ONLY
#include "xxhash.h"
#include <stdio.h>
#include <string.h>

int main(void) {
    // Stack-allocated XXH32 state
    XXH32_state_t state32;
    XXH32_reset(&state32, 0);
    XXH32_update(&state32, "Hello", 5);
    XXH32_update(&state32, " World", 6);
    printf("XXH32: %08x\n", XXH32_digest(&state32));

    // Stack-allocated XXH64 state
    XXH64_state_t state64;
    XXH64_reset(&state64, 0);
    XXH64_update(&state64, "Hello World", 11);
    printf("XXH64: %016llx\n", (unsigned long long)XXH64_digest(&state64));

    // Stack-allocated XXH3 state (requires special initialization)
    // Note: XXH3_state_t has 64-byte alignment requirement
    XXH_ALIGN(64) XXH3_state_t state3;
    XXH3_INITSTATE(&state3);  // Required for stack allocation with seeded reset
    XXH3_64bits_reset_withSeed(&state3, 12345);
    XXH3_64bits_update(&state3, "Hello World", 11);
    printf("XXH3_64: %016llx\n", (unsigned long long)XXH3_64bits_digest(&state3));

    return 0;
}

```

--------------------------------

### Benchmark xxHash Algorithm

Source: https://github.com/cyan4973/xxhash/blob/dev/cli/xxhsum.1.md

Benchmarks the xxHash algorithm on a synthetic sample. By default, it uses a 100 KB sample and benchmarks main variants, printing throughput in hashes per second and megabytes per second.

```bash
$ xxhsum -b
```

```bash
$ xxhsum -b1,2,3 -i10 -B16384
```

--------------------------------

### Define Source Directories in Makefile

Source: https://github.com/cyan4973/xxhash/blob/dev/build/make/README.md

Specify directories containing C and C++ source files. Ensure these directories exist in your project structure.

```makefile
C_SRCDIRS   := src src/cdeps    # all .c are in these directories
CXX_SRCDIRS := src src/cxxdeps  # all .cpp are in these directories
```

--------------------------------

### Consume Remaining Input (8-byte chunks) (xxHash)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes remaining input data in 8-byte chunks, updating the accumulator using XOR and multiplication operations. Continues as long as at least 8 bytes remain.

```pseudocode
  while (remainingLength >= 8) {
      lane = read_64bit_little_endian(input_ptr);
      acc = acc xor round(0, lane);
      acc = (acc <<< 27) * PRIME64_1;
      acc = acc + PRIME64_4;
      input_ptr += 8; remainingLength -= 8;
  }
```

--------------------------------

### XXH32 Accumulator Initialization

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Initializes the four internal accumulators for the XXH32 algorithm using a seed value and predefined prime constants. The seed is optional and can be 0.

```c
u32 acc1 = seed + PRIME32_1 + PRIME32_2;
u32 acc2 = seed + PRIME32_2;
u32 acc3 = seed + 0;
u32 acc4 = seed - PRIME32_1;
```

--------------------------------

### Declare Program and Library Targets

Source: https://github.com/cyan4973/xxhash/blob/dev/build/make/README.md

Use multiconf.make macros to define targets for C programs, C++ programs, static libraries, and dynamic libraries. Each macro takes the target name and its object files as arguments.

```makefile
app:
$(eval $(call c_program,app,app.o cdeps/obj.o))
```

```makefile
test:
$(eval $(call cxx_program,test, test.o cxxdeps/objcxx.o))
```

```makefile
lib.a:
$(eval $(call static_library,lib.a, lib.o cdeps/obj.o))
```

```makefile
lib.so:
$(eval $(call c_dynamic_library,lib.so, lib.o cdeps/obj.o))
```

--------------------------------

### XXH32 Streaming Hash for Files

Source: https://context7.com/cyan4973/xxhash/llms.txt

Processes a file incrementally to compute its XXH32 hash. Ensure the file is opened in binary read mode.

```c
#include "xxhash.h"
#include <stdio.h>
#include <stdlib.h>

XXH32_hash_t hash_file_xxh32(FILE* file) {
    // Create state
    XXH32_state_t* state = XXH32_createState();
    if (state == NULL) {
        return 0;
    }

    // Initialize with seed
    if (XXH32_reset(state, 0) == XXH_ERROR) {
        XXH32_freeState(state);
        return 0;
    }

    // Process file in chunks
    char buffer[4096];
    size_t bytes_read;
    while ((bytes_read = fread(buffer, 1, sizeof(buffer), file)) > 0) {
        if (XXH32_update(state, buffer, bytes_read) == XXH_ERROR) {
            XXH32_freeState(state);
            return 0;
        }
    }

    // Get final hash
    XXH32_hash_t hash = XXH32_digest(state);

    // Cleanup
    XXH32_freeState(state);

    return hash;
}

int main(void) {
    FILE* file = fopen("example.txt", "rb");
    if (file) {
        XXH32_hash_t hash = hash_file_xxh32(file);
        printf("File XXH32: %08x\n", hash);
        fclose(file);
    }
    return 0;
}
```

--------------------------------

### Build collisionsTest with custom options

Source: https://github.com/cyan4973/xxhash/blob/dev/tests/collisions/README.md

Modify the build process using flags like SLAB5 for an alternative pattern generator or POOL_MT=0 to disable multi-threading.

```bash
make SLAB5=1
```

```bash
make POOL_MT=0
```

--------------------------------

### Enable Inline Mode for xxHash Performance

Source: https://context7.com/cyan4973/xxhash/llms.txt

Define XXH_INLINE_ALL before including 'xxhash.h' to enable inline mode, which can significantly improve performance, especially for small inputs with known lengths at compile time. This mode avoids the need to link the xxhash.c file.

```c
// Define before including xxhash.h for inline mode
#define XXH_INLINE_ALL
#include "xxhash.h"

#include <stdio.h>
#include <string.h>

// Compile-time known length enables aggressive inlining
static inline XXH64_hash_t hash_fixed_8bytes(const void* data) {
    return XXH3_64bits(data, 8);  // Compiler can optimize for length=8
}

int main(void) {
    // When using XXH_INLINE_ALL, no need to link xxhash.c
    // All functions are inlined directly

    const char* data = "TestData";
    XXH64_hash_t hash = hash_fixed_8bytes(data);
    printf("Inline hash: %016llx\n", (unsigned long long)hash);

    // Standard usage also works
    const char* variable_data = "Variable length string";
    XXH64_hash_t hash2 = XXH3_64bits(variable_data, strlen(variable_data));
    printf("Standard hash: %016llx\n", (unsigned long long)hash2);

    return 0;
}

```

--------------------------------

### Configure xxHash Library

Source: https://github.com/cyan4973/xxhash/blob/dev/build/cmake/CMakeLists.txt

Configures the xxhash library, conditionally enabling dispatch mode for x86_64 platforms. It sets up include directories and export definitions for shared libraries.

```cmake
if((DEFINED DISPATCH) AND (DEFINED PLATFORM))
  # Only support DISPATCH option on x86_64.
  if(("${PLATFORM}" STREQUAL "x86_64") OR ("${PLATFORM}" STREQUAL "AMD64"))
    set(XXHSUM_DISPATCH ON)
    message(STATUS "Enable xxHash dispatch mode")
    add_library(xxhash "${XXHASH_DIR}/xxh_x86dispatch.c"
                       "${XXHASH_DIR}/xxhash.c"
               )
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DXXHSUM_DISPATCH=1")
  else()
    add_library(xxhash "${XXHASH_DIR}/xxhash.c")
  endif()
else()
  add_library(xxhash "${XXHASH_DIR}/xxhash.c")
endif()
add_library(${PROJECT_NAME}::xxhash ALIAS xxhash)

target_include_directories(xxhash
  PUBLIC
    $<BUILD_INTERFACE:${XXHASH_DIR}>
    $<INSTALL_INTERFACE:include/>)
if (BUILD_SHARED_LIBS)
  target_compile_definitions(xxhash PUBLIC XXH_EXPORT)
endif ()
set_target_properties(xxhash PROPERTIES
  SOVERSION "${XXHASH_LIB_SOVERSION}"
  VERSION "${XXHASH_VERSION_STRING}")
```

--------------------------------

### XXH32 Consume Remaining Input (>= 4 bytes)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes remaining input bytes in chunks of 4 bytes for the XXH32 algorithm.

```c
  while (remainingLength >= 4) {
      lane = read_32bit_little_endian(input_ptr);
      acc = acc + lane * PRIME32_3;
      acc = (acc <<< 17) * PRIME32_4;
      input_ptr += 4; remainingLength -= 4;
  }
```

--------------------------------

### Accumulator Convergence (xxHash)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Merges the four parallel accumulators into a single accumulator. This involves bitwise rotations and repeated calls to `mergeAccumulator`.

```pseudocode
  acc = (acc1 <<< 1) + (acc2 <<< 7) + (acc3 <<< 12) + (acc4 <<< 18);
  acc = mergeAccumulator(acc, acc1);
  acc = mergeAccumulator(acc, acc2);
  acc = mergeAccumulator(acc, acc3);
  acc = mergeAccumulator(acc, acc4);
```

--------------------------------

### Benchmark XXHash Variants

Source: https://context7.com/cyan4973/xxhash/llms.txt

Benchmark all XXHash variants using '-b'. For specific variants, iterations, and block sizes, use options like '-b1,2,3 -i10 -B16384'.

```bash
xxhsum -b
```

```bash
xxhsum -b1,2,3 -i10 -B16384
```

--------------------------------

### Generate Hashes from File List

Source: https://context7.com/cyan4973/xxhash/llms.txt

Use this command to generate XXHash sums for a list of files found by the 'find' command. The '--files-from -' option reads file paths from standard input.

```bash
find . -name "*.c" | xxhsum --files-from -
```

--------------------------------

### Consume Remaining Input (4-byte chunks) (xxHash)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes remaining input data in 4-byte chunks if available after 8-byte processing. Updates the accumulator with specific bitwise and arithmetic operations.

```pseudocode
  if (remainingLength >= 4) {
      lane = read_32bit_little_endian(input_ptr);
      acc = acc xor (lane * PRIME64_1);
      acc = (acc <<< 23) * PRIME64_2;
      acc = acc + PRIME64_3;
      input_ptr += 4; remainingLength -= 4;
  }
```

--------------------------------

### Generate xxHash Checksums for Files

Source: https://github.com/cyan4973/xxhash/blob/dev/cli/xxhsum.1.md

Outputs xxHash (64-bit) checksum values for specified files to standard output. Use -H1 for 64-bit and -H0 for 32-bit.

```bash
$ xxhsum -H1 foo bar baz
```

```bash
$ xxhsum -H0 foo bar baz > xyz.xxh32
$ xxhsum -H1 foo bar baz > qux.xxh64
```

--------------------------------

### XXH3 Prime Constants (C)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Defines the 64-bit prime number constants used in XXH3 and XXH64 algorithms. These are essential for the hashing calculations.

```c
static const u64 PRIME32_1 = 0x9E3779B1U;  // 0b10011110001101110111100110110001
  static const u64 PRIME32_2 = 0x85EBCA77U;  // 0b10000101111010111100101001110111
  static const u64 PRIME32_3 = 0xC2B2AE3DU;  // 0b11000010101100101010111000111101
  static const u64 PRIME64_1 = 0x9E3779B185EBCA87ULL;  // 0b1001111000110111011110011011000110000101111010111100101010000111
  static const u64 PRIME64_2 = 0xC2B2AE3D27D4EB4FULL;  // 0b1100001010110010101011100011110100100111110101001110101101001111
  static const u64 PRIME64_3 = 0x165667B19E3779F9ULL;  // 0b0001011001010110011001111011000110011110001101110111100111111001
  static const u64 PRIME64_4 = 0x85EBCA77C2B2AE63ULL;  // 0b1000010111101011110010100111011111000010101100101010111001100011
  static const u64 PRIME64_5 = 0x27D4EB2F165667C5ULL;  // 0b0010011111010100111010110010111100010110010101100110011111000101
  static const u64 PRIME_MX1 = 0x165667919E3779F9ULL;  // 0b0001011001010110011001111001000110011110001101110111100111111001
  static const u64 PRIME_MX2 = 0x9FB21C651E98DF25ULL;  // 0b1001111110110010000111000110010100011110100110001101111100100101
```

--------------------------------

### Calculate XXH64 One-Shot Hash

Source: https://context7.com/cyan4973/xxhash/llms.txt

Utilize XXH64 for 64-bit hashing, optimized for 64-bit systems, offering a larger hash space and reduced collision probability. A seed can be provided for keyed hashing.

```c
#include "xxhash.h"
#include <stdio.h>
#include <string.h>

int main(void) {
    const char* data = "Hello, xxHash!";
    size_t length = strlen(data);
    XXH64_hash_t seed = 0;

    // Calculate 64-bit hash
    XXH64_hash_t hash = XXH64(data, length, seed);

    printf("XXH64 hash: %016llx\n", (unsigned long long)hash);
    // Output: XXH64 hash: a1b2c3d4e5f67890

    // Hash with custom seed for keyed hashing
    XXH64_hash_t hash_keyed = XXH64(data, length, 0xDEADBEEF);
    printf("XXH64 hash (keyed): %016llx\n", (unsigned long long)hash_keyed);

    return 0;
}
```

--------------------------------

### XXH3 1-3 Bytes Input Combination (XXH3-64)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Combines input bytes and length into a 32-bit value for XXH3-64 hashing. Used when input is between 1 and 3 bytes.

```c
u32 combined = (u32)input[inputLength-1] | ((u32)inputLength << 8) |
               ((u32)input[0] << 16) | ((u32)input[inputLength>>1] << 24);
// LSB          8       16           24                    MSB
//  | last byte | length | first byte | middle-or-last byte |
```

--------------------------------

### XXH3 128-bit Streaming Hash for Files

Source: https://context7.com/cyan4973/xxhash/llms.txt

Generates a 128-bit hash for a file using the XXH3 streaming API. Handles potential allocation errors by returning a zeroed hash.

```c
#include "xxhash.h"
#include <stdio.h>

XXH128_hash_t hash_file_xxh128(FILE* file) {
    // XXH3_128bits uses the same state type as XXH3_64bits
    XXH3_state_t* state = XXH3_createState();
    if (state == NULL) return (XXH128_hash_t){0, 0};

    // Reset for 128-bit mode
    XXH3_128bits_reset(state);

    char buffer[4096];
    size_t count;
    while ((count = fread(buffer, 1, sizeof(buffer), file)) != 0) {
        XXH3_128bits_update(state, buffer, count);
    }

    // Get 128-bit digest
    XXH128_hash_t result = XXH3_128bits_digest(state);

    XXH3_freeState(state);
    return result;
}

int main(void) {
    FILE* file = fopen("secure_data.bin", "rb");
    if (file) {
        XXH128_hash_t hash = hash_file_xxh128(file);
        printf("File XXH128: %016llx%016llx\n",
               (unsigned long long)hash.high64,
               (unsigned long long)hash.low64);
        fclose(file);
    }
    return 0;
}
```

--------------------------------

### XXH32 Consume Remaining Input (1-3 bytes)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes the final remaining bytes (1 to 3) for the XXH32 algorithm.

```c
  while (remainingLength >= 1) {
      lane = read_byte(input_ptr);
      acc = acc + lane * PRIME32_5;
      acc = (acc <<< 11) * PRIME32_1;
      input_ptr += 1; remainingLength -= 1;
  }
```

--------------------------------

### Consume Remaining Input (1-byte chunks) (xxHash)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes the final remaining bytes (less than 4) one by one. Each byte is used to update the accumulator with specific bitwise and arithmetic operations.

```pseudocode
  while (remainingLength >= 1) {
      lane = read_byte(input_ptr);
      acc = acc xor (lane * PRIME64_5);
      acc = (acc <<< 11) * PRIME64_1;
      input_ptr += 1; remainingLength -= 1;
  }
```

--------------------------------

### Calculate XXH3 64-bit Hashes

Source: https://context7.com/cyan4973/xxhash/llms.txt

Employ XXH3_64bits for the fastest 64-bit hashing, leveraging SIMD acceleration. It supports unseeded, seeded, and secret-based hashing for various security and performance needs.

```c
#include "xxhash.h"
#include <stdio.h>
#include <string.h>

int main(void) {
    const char* data = "Hello, xxHash!";
    size_t length = strlen(data);

    // Unseeded variant (fastest)
    XXH64_hash_t hash = XXH3_64bits(data, length);
    printf("XXH3_64 hash: %016llx\n", (unsigned long long)hash);

    // Seeded variant - generates custom secret from seed
    XXH64_hash_t hash_seeded = XXH3_64bits_withSeed(data, length, 12345);
    printf("XXH3_64 hash (seeded): %016llx\n", (unsigned long long)hash_seeded);

    // With custom secret for higher protection against collision attacks
    unsigned char secret[XXH3_SECRET_SIZE_MIN];
    XXH3_generateSecret(secret, sizeof(secret), "my_custom_key", 13);
    XXH64_hash_t hash_secret = XXH3_64bits_withSecret(data, length, secret, sizeof(secret));
    printf("XXH3_64 hash (secret): %016llx\n", (unsigned long long)hash_secret);

    return 0;
}
```

--------------------------------

### XXH3 1-3 Bytes Input Hash Calculation (XXH3-64)

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Calculates the XXH3-64 hash for inputs between 1 and 3 bytes. It uses a secret, seed, and the combined input value.

```c
XXH3_64_1to3():
  u32 secretWords[2] = secret[0:8];
  u64 value = ((u64)(secretWords[0] xor secretWords[1]) + seed) xor (u64)combined;
  return avalanche_XXH64(value);
```

--------------------------------

### XXH32 Accumulator Convergence

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Merges the four lane accumulators into a single 32-bit accumulator in the XXH32 algorithm.

```c
  acc = (acc1 <<< 1) + (acc2 <<< 7) + (acc3 <<< 12) + (acc4 <<< 18);
```

--------------------------------

### XXH3-64 Input Processing for 129-240 Bytes

Source: https://github.com/cyan4973/xxhash/blob/dev/doc/xxhash_spec.md

Processes input data between 129 and 240 bytes for XXH3-64. It first mixes the initial 128 bytes, applies an avalanche operation, processes remaining full chunks, and finally mixes the last 16 bytes.

```c
processInput_XXH3_64_129to240():
  u64 numChunks = inputLength >> 4;
  for (i = 0; i < 8; i++) {
    acc += mixStep(input[i*16:i*16+16], i*16, seed);
  }
  acc = avalanche(acc);
  for (i = 8; i < numChunks; i++) {
    acc += mixStep(input[i*16:i*16+16], (i-8)*16 + 3, seed);
  }
  acc += mixStep(input[inputLength-16:inputLength], 119, seed);
```

--------------------------------

### XXH64 Streaming Hash for Files

Source: https://context7.com/cyan4973/xxhash/llms.txt

Computes the XXH64 hash of a file by processing it in chunks. Uses a larger buffer for potentially better performance on large files.

```c
#include "xxhash.h"
#include <stdio.h>
#include <stdlib.h>

XXH64_hash_t hash_file_xxh64(FILE* file) {
    XXH64_state_t* state = XXH64_createState();
    if (state == NULL) return 0;

    // Initialize with seed
    XXH64_reset(state, 0);

    // Process file in chunks
    char buffer[8192];
    size_t bytes_read;
    while ((bytes_read = fread(buffer, 1, sizeof(buffer), file)) > 0) {
        XXH64_update(state, buffer, bytes_read);
    }

    // Get final hash (doesn't affect state - can continue updating)
    XXH64_hash_t hash = XXH64_digest(state);

    XXH64_freeState(state);
    return hash;
}

int main(void) {
    FILE* file = fopen("largefile.bin", "rb");
    if (file) {
        XXH64_hash_t hash = hash_file_xxh64(file);
        printf("File XXH64: %016llx\n", (unsigned long long)hash);
        fclose(file);
    }
    return 0;
}
```