diff options
Diffstat (limited to 'libparc/parc/algol/parc_Hash.h')
| -rwxr-xr-x | libparc/parc/algol/parc_Hash.h | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_Hash.h b/libparc/parc/algol/parc_Hash.h new file mode 100755 index 00000000..92227041 --- /dev/null +++ b/libparc/parc/algol/parc_Hash.h @@ -0,0 +1,341 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file parc_Hash.h + * @ingroup datastructures + * @brief Implements the FNV-1a 64-bit and 32-bit hashes. + * + * These are some basic hashing functions for blocks of data and integers. They + * generate 64 and 32 bit hashes (They are currently using the FNV-1a algorithm.) + * There is also a cumulative version of the hashes that can be used if intermediary + * hashes are required/useful. + * + */ +#ifndef libparc_parc_Hash_h +#define libparc_parc_Hash_h + +#include <stdint.h> +#include <stdlib.h> + + +struct parc_hash_32bits; +/** + * @typedef PARCHash32Bits + * @brief An accumulator + */ + +typedef struct parc_hash_32bits PARCHash32Bits; + +/** + * Create a 32 bit hash generator + * + * @return A pointer to a `PARCHash32Bits` instance + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +PARCHash32Bits *parcHash32Bits_Create(void); + +/** + * Generate a 32 bit hash from a memory block starting with a previous hash + * + * This is a typed version of {@link parcHash32_Data_Cumulative} + * + * @param [in] hash the value of the last cumulative hash calculated + * @param [in] data pointer to a memory block. + * @param [in] length length of the memory pointed to by data + * + * @return pointer to a {@link PARCHash32Bits} with the cumulative hash + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +PARCHash32Bits *parcHash32Bits_Update(PARCHash32Bits *hash, const void *data, size_t length); + +/** + * Generate a 32 bit hash from a uint32 starting with a previous hash + * Update the cumulative state of the given {@link PARCHash32Bits} + * + * @param [in] hash the value of the last cumulative hash calculated + * @param [in] value The `uint32` to be hashed + * + * @return pointer to a `PARCHash32Bits` with the cumulative hash + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +PARCHash32Bits *parcHash32Bits_UpdateUint32(PARCHash32Bits *hash, uint32_t value); + +/** + * Get the current value of the cummulative state of the given {@link PARCHash32Bits}. + * + * @param [in] hash the value of the last cumulative hash calculated + * + * @return The hash value as an unsigned 32 bit integer + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +uint32_t parcHash32Bits_Hash(PARCHash32Bits *hash); + +/** + * Acquire a new reference to the given {@link PARCHash32Bits} instance. + * + * The reference count to the instance is incremented. + * + * @param [in] hash The instance of `PARCHash32Bits` to which to refer. + * + * @return The same value as the input parameter @p hash + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +PARCHash32Bits *parcHash32Bits_Acquire(const PARCHash32Bits *hash); + +/** + * Release a reference to the given {@link PARCHash32Bits} instance. + * + * Only the last invocation where the reference count is decremented to zero, + * will actually destroy the `PARCHash32Bits`. + * + * @param [in,out] hash is a pointer to the `PARCHash32Bits` reference. + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + */ +void parcHash32Bits_Release(PARCHash32Bits **hash); + +/** + * Generate a 64 bit hash from a memory block + * + * This function will generate a 64bit hash from a block of memory. The memory block + * is not modified in any way. + * + * The output of this function can be used as input for the cumulative version of + * this function + * + * @param [in] data A pointer to a memory block. + * @param [in] len The length of the memory pointed to by data + * + * @return hash_64bit A 64 bit hash of the memory block. + * + * Example: + * @code + * + * char * data = "Hello world of hashing"; + * uint64_t myhash = parcHash64_Data(data,strlen(data)); + * + * @endcode + * + * @see {@link parcHash64_Data_Cumulative} + */ +uint64_t parcHash64_Data(const void *data, size_t len); + +/** + * Generate a 64 bit hash from a memory block starting with a previous hash + * + * This function will generate a 64 bit hash from a block of memory and an initial + * hash. This is used to cumulatively calculate a hash of larger block. So, + * one could generate the hash of the first part of the data (A), then calculate the + * hash including the next part of the data (AB) and then the hash of the next + * part (ABC). This is useful for not having to recalculate the hash of the parts + * you have already hashed. + * + * A cumulative hash should have the same value as a full hash of the complete data. + * So cumulative_hash(B,len(B),hash(A)) is equal to hash(AB,len(AB)). + * + * @param [in] data pointer to a memory block. + * @param [in] len length of the memory pointed to by data + * @param [in] lastValue the vale of the last cumulative hash calculated + * + * @return cumulative_hash64 A 64 bit hash of the data _and_ the data that was + * hashed before (represented by lastValue). + * + * Example: + * @code + * + * char * data1 = "1234567890"; + * uint64_t myhash1 = parcHash64_Data(data1,10); + * char * data2 = "abcdefghij"; + * uint64_t myhash2 = parcHash64_Data_Cumulative(data2,10,myhash1); + * char * data3 = "1234567890abcdefghij"; + * uint64_t myhash3 = parcHash64_Data(data3,20); + * // myhash3 will be equal to myhash2 + * + * @endcode + * + * @see {@link parcHash64_Data} + */ +uint64_t parcHash64_Data_Cumulative(const void *data, size_t len, uint64_t lastValue); + +/** + * Generate a 64 bit hash from a 64 bit Integer + * + * This function hashes a 64 bit integer into a 64 bit hash + * + * @param [in] int64 A 64 bit integer + * + * @return hash64 A 64 bit hash of the 64 bit integer + * + * Example: + * @code + * uint64_t id64 = 1234567890123456; + * uint64_t hash64 = parcHash64_Int64(id64); + * @endcode + * + */ +uint64_t parcHash64_Int64(uint64_t int64); + +/** + * Generate a 64 bit hash from a 32 bit Integer + * + * This function hashes a 32 bit integer into a 64 bit hash + * + * @param [in] int32 A 32 bit integer + * + * @return hash64 A 64 bit hash of the 32 bit integer + * + * Example: + * @code + * uint32_t id32 = 70; + * uint64_t hash64 = parcHash64_Int32(id32); + * @endcode + * + */ +uint64_t parcHash64_Int32(uint32_t int32); + +/** + * Generate a 32 bit hash from a memory block + * + * This function will generate a 32bit hash from a block of memory. The memory block + * is not modified in any way. + * The output of this function can be used as input for the cumulative version of + * this function. + * + * @param [in] data pointer to a memory block. + * @param [in] len length of the memory pointed to by data + * + * @return hash_32bit A 32 bit hash of the memory block. + * + * Example: + * @code + * + * char * data = "Hello world of hashing"; + * uint32_t myhash = parcHash32_Data(data,strlen(data)); + * + * @endcode + * + * @see {@link parcHash32_Data_Cumulative} + */ +uint32_t parcHash32_Data(const void *data, size_t len); + +/** + * Generate a 32 bit hash from a memory block starting with a previous hash + * + * This function will generate a 32 bit hash from a block of memory and an initial + * hash. This is used to cumulatively calculate a hash of larger block. So, + * one could generate the hash of the first part of the data (A), then calculate the + * hash including the next part of the data (AB) and then the hash of the next + * part (ABC). This is useful for not having to recalculate the hash of the parts + * you have already hashed. + * + * A cumulative hash should have the same value as a full hash of the complete data. + * So cumulative_hash(B,len(B),hash(A)) is equal to hash(AB,len(AB)). + * + * @param [in] data pointer to a memory block. + * @param [in] len length of the memory pointed to by data + * @param [in] lastValue the vale of the last cumulative hash calculated + * + * @return cumulative_hash32 A 32 bit hash of the data _and_ the data that was + * hashed before (represented by lastValue). + * + * Example: + * @code + * + * char * data1 = "1234567890"; + * uint32_t myhash1 = parcHash32_Data(data1,10); + * char * data2 = "abcdefghij"; + * uint32_t myhash2 = parcHash32_Data_Cumulative(data2,10,myhash1); + * char * data3 = "1234567890abcdefghij"; + * uint32_t myhash3 = parcHash32_Data(data3,20); + * // myhash3 will be equal to myhash2 + * + * @endcode + * + * @see {@link parcHash32_Data} + */ +uint32_t parcHash32_Data_Cumulative(const void *data, size_t len, uint32_t lastValue); + +/** + * Generate a 32 bit hash from a 64 bit Integer + * + * This function hashes a 64 bit integer into a 32 bit hash + * + * @param [in] int64 A 64 bit integer + * + * @return hash32 A 32 bit hash of the 64 bit integer + * + * Example: + * @code + * uint64_t id64 = 1234567890123456; + * uint32_t hash32 = parcHash32_Int64(id64); + * @endcode + * + */ +uint32_t parcHash32_Int64(uint64_t int64); + +/** + * Generate a 32 bit hash from a 32 bit Integer + * + * This function hashes a 32 bit integer into a 32 bit hash + * + * @param [in] int32 A 32 bit integer + * + * @return hash32 A 32 bit hash of the 32 bit integer + * + * Example: + * @code + * uint32_t id32 = 1234567890123456; + * uint32_t hash32 = parcHash32_Int32(id32); + * @endcode + * + */ +uint32_t parcHash32_Int32(uint32_t int32); +#endif // libparc_parc_Hash_h |