diff options
Diffstat (limited to 'libparc/parc/algol/parc_HashCodeTable.h')
| -rw-r--r-- | libparc/parc/algol/parc_HashCodeTable.h | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_HashCodeTable.h b/libparc/parc/algol/parc_HashCodeTable.h new file mode 100644 index 00000000..58b3d016 --- /dev/null +++ b/libparc/parc/algol/parc_HashCodeTable.h @@ -0,0 +1,168 @@ +/* + * 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_HashCodeTable.h + * @ingroup datastructures + * + * A hashcode table requires the user to specify their own hash function + * to operate on the object type being inserted. + * + */ +#ifndef libparc_parc_HashCodeTable_h +#define libparc_parc_HashCodeTable_h + +#include <stdint.h> +#include <stdlib.h> +#include <stdbool.h> + +#include <parc/algol/parc_HashCode.h> + +struct parc_hashcode_table; +typedef struct parc_hashcode_table PARCHashCodeTable; + +typedef PARCHashCode HashCodeType; + + +/** + * @typedef PARCHashCodeTable_KeyEqualsFunc + * @brief Are two keys equal? + * + */ + +typedef bool (*PARCHashCodeTable_KeyEqualsFunc)(const void *keyA, const void *keyB); + +/** + * @typedef PARCHashCodeTable_HashCodeFunc + */ + +typedef HashCodeType (*PARCHashCodeTable_HashCodeFunc)(const void *keyA); + +/** + * @typedef PARCHashCodeTable_Destroyer + */ + +typedef void (*PARCHashCodeTable_Destroyer)(void **keyOrDataPtr); + +/** + * Create a Hash Table based on hash codes. + * + * @param [in] keyEqualsFunc Tests keys for equality. + * @param [in] keyHashCodeFunc Returns the hash code of a key + * @param [in] keyDestroyer Called on Remove or Destroy to free stored keys, may be NULL. + * @param [in] dataDestroyer Called on Remove or Destroy to free stored data, may be NULL. + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCHashCodeTable *parcHashCodeTable_Create(PARCHashCodeTable_KeyEqualsFunc keyEqualsFunc, + PARCHashCodeTable_HashCodeFunc keyHashCodeFunc, + PARCHashCodeTable_Destroyer keyDestroyer, + PARCHashCodeTable_Destroyer dataDestroyer); + + +/** + * Create a Hash Table based on hash codes. + * + * @param [in] keyEqualsFunc Tests keys for equality. + * @param [in] keyHashCodeFunc Returns the hash code of a key + * @param [in] keyDestroyer Called on Remove or Destroy to free stored keys, may be NULL. + * @param [in] dataDestroyer Called on Remove or Destroy to free stored data, may be NULL. + * @param [in] minimumSize The minimum size of the table + * + * Example: + * @code + * <#example#> + * @endcode + */ +PARCHashCodeTable *parcHashCodeTable_Create_Size(PARCHashCodeTable_KeyEqualsFunc keyEqualsFunc, + PARCHashCodeTable_HashCodeFunc keyHashCodeFunc, + PARCHashCodeTable_Destroyer keyDestroyer, + PARCHashCodeTable_Destroyer dataDestroyer, + size_t minimumSize); + +/** + * Destroy the table and free all saved objects + * + * @param [in,out] tablePtr is a pointer to the `PARCHashCodeTable` reference. + * + * + * Example: + * @code + * <#example#> + * @endcode + */ +void parcHashCodeTable_Destroy(PARCHashCodeTable **tablePtr); + +/** + * Add an element to the hash table. + * @param [in,out] table The key, must be usable with the {@link PARCHashCodeTable_KeyEqualsFunc} and {@link PARCHashCodeTable_HashCodeFunc}. + * @param [in] key The key, must be usable with the `keyEqualsFunc` and `keyHashCodeFunc`. + * @param [in] data The value, must not be NULL + * + * @return true if key did not exist and data was added. Returns false if key exists or error. + * + * Example: + * @code + * <#example#> + * @endcode + */ +bool parcHashCodeTable_Add(PARCHashCodeTable *table, void *key, void *data); + +/** + * Removes a key from an instance of `PARCHashCodeTable`, freeing key and data memory. Does nothing if key does not + * exist in the table. + * + * @param [in,out] table The instance of `PARCHashCodeTable` from which the key will be removed. + * @param [in] key The key, must be usable with the {@link PARCHashCodeTable_KeyEqualsFunc} and {@link PARCHashCodeTable_HashCodeFunc}. + * + * Example: + * @code + * <#example#> + * @endcode + */ +void parcHashCodeTable_Del(PARCHashCodeTable *table, const void *key); + +/** + * Returns the key value, or NULL if the key does not exist + * + * @param [in] table The instance of `PARCHashCodeTable` from which the the value will be retrieved. + * @param [in] key The key to identify the desired value. + * + * @return A pointer to the value of the specified key. + * + * Example: + * @code + * <#example#> + * @endcode + */ +void *parcHashCodeTable_Get(PARCHashCodeTable *table, const void *key); + +/** + * Returns the number of entries in the table + * + * + * @param [in] table The specified `PARCHashCodeTable` instance. + * @return The number of entries in @p table. + * + * Example: + * @code + * <#example#> + * @endcode + */ +size_t parcHashCodeTable_Length(const PARCHashCodeTable *table); +#endif // libparc_parc_HashCodeTable_h |