From 3a9eb9b49716aad15156180da6e8018241b80cf8 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 25 Aug 2013 12:17:46 +0000 Subject: doxygen docs for ghash/edgehash --- source/blender/blenlib/intern/BLI_ghash.c | 185 ++++++++++++++++++++++++------ 1 file changed, 152 insertions(+), 33 deletions(-) (limited to 'source/blender/blenlib/intern/BLI_ghash.c') diff --git a/source/blender/blenlib/intern/BLI_ghash.c b/source/blender/blenlib/intern/BLI_ghash.c index 918fc55df72..21326227794 100644 --- a/source/blender/blenlib/intern/BLI_ghash.c +++ b/source/blender/blenlib/intern/BLI_ghash.c @@ -84,18 +84,29 @@ struct GHash { /* -------------------------------------------------------------------- */ /* GHash API */ -/* internal utility API */ +/** \name Internal Utility API + * \{ */ +/** + * Check if the number of items in the GHash is large enough to require more buckets. + */ BLI_INLINE bool ghash_test_expand_buckets(const unsigned int nentries, const unsigned int nbuckets) { return (nentries > nbuckets * 3); } +/** + * Get the hash for a key. + */ BLI_INLINE unsigned int ghash_keyhash(GHash *gh, const void *key) { return gh->hashfp(key) % gh->nbuckets; } +/** + * Internal lookup function. + * Takes a hash argument to avoid calling #ghash_keyhash multiple times. + */ BLI_INLINE Entry *ghash_lookup_entry_ex(GHash *gh, const void *key, const unsigned int hash) { @@ -109,12 +120,19 @@ BLI_INLINE Entry *ghash_lookup_entry_ex(GHash *gh, const void *key, return NULL; } +/** + * Internal lookup function. Only wraps #ghash_lookup_entry_ex + */ BLI_INLINE Entry *ghash_lookup_entry(GHash *gh, const void *key) { const unsigned int hash = ghash_keyhash(gh, key); return ghash_lookup_entry_ex(gh, key, hash); } +/** + * Internal insert function. + * Takes a hash argument to avoid calling #ghash_keyhash multiple times. + */ static void ghash_insert_ex(GHash *gh, void *key, void *val, unsigned int hash) { @@ -148,10 +166,22 @@ static void ghash_insert_ex(GHash *gh, void *key, void *val, MEM_freeN(old); } } +/** \} */ -/* Public API */ +/** \name Public API + * \{ */ +/** + * Creates a new, empty GHash. + * + * \param hashfp Hash callback. + * \param cmpfp Comparison callback. + * \param info Identifier string for the GHash. + * \param nentries_reserve Optionally reserve the number of members that the hash will hold. + * Use this to avoid resizing buckets if the size is known or can be closely approximated. + * \return An empty GHash. + */ GHash *BLI_ghash_new_ex(GHashHashFP hashfp, GHashCmpFP cmpfp, const char *info, const unsigned int nentries_reserve) { @@ -178,16 +208,29 @@ GHash *BLI_ghash_new_ex(GHashHashFP hashfp, GHashCmpFP cmpfp, const char *info, return gh; } +/** + * Wraps #BLI_ghash_new_ex with zero entries reserved. + */ GHash *BLI_ghash_new(GHashHashFP hashfp, GHashCmpFP cmpfp, const char *info) { return BLI_ghash_new_ex(hashfp, cmpfp, info, 0); } +/** + * \return size of the GHash. + */ int BLI_ghash_size(GHash *gh) { return (int)gh->nentries; } +/** + * Insert a key/value pair into the \a gh. + * + * \note Duplicates are not checked, + * the caller is expected to ensure elements are unique unless + * GHASH_FLAG_ALLOW_DUPES flag is set. + */ void BLI_ghash_insert(GHash *gh, void *key, void *val) { const unsigned int hash = ghash_keyhash(gh, key); @@ -195,7 +238,8 @@ void BLI_ghash_insert(GHash *gh, void *key, void *val) } /** - * Assign a new value to a key that may already be in ghash. + * Inserts a new value to a key that may already be in ghash. + * * Avoids #BLI_ghash_remove, #BLI_ghash_insert calls (double lookups) */ void BLI_ghash_reinsert(GHash *gh, void *key, void *val, GHashKeyFreeFP keyfreefp, GHashValFreeFP valfreefp) @@ -214,18 +258,45 @@ void BLI_ghash_reinsert(GHash *gh, void *key, void *val, GHashKeyFreeFP keyfreef } } +/** + * Lookup the value of \a key in \a gh. + * + * \param key The key to lookup. + * \returns the value for \a key or NULL. + * + * \note When NULL is a valid value, use #BLI_ghash_lookup_p to differentiate a missing key + * from a key with a NULL value. (Avoids calling #BLI_ghash_haskey before #BLI_ghash_lookup) + */ void *BLI_ghash_lookup(GHash *gh, const void *key) { Entry *e = ghash_lookup_entry(gh, key); return e ? e->val : NULL; } +/** + * Lookup a pointer to the value of \a key in \a gh. + * + * \param key The key to lookup. + * \returns the pointer to value for \a key or NULL. + * + * \note This has 2 main benifits over #BLI_ghash_lookup. + * - A NULL return always means that \a key isn't in \a gh. + * - The value can be modified in-place without further function calls (faster). + */ void **BLI_ghash_lookup_p(GHash *gh, const void *key) { Entry *e = ghash_lookup_entry(gh, key); return e ? &e->val : NULL; } +/** + * Remove \a key from \a gh, or return false if the key wasn't found. + * + * \param key The key to remove. + * \param keyfreefp Optional callback to free the key. + * \param valfreefp Optional callback to free the value. + * \return true if \a key was removed from \a gh. + */ bool BLI_ghash_remove(GHash *gh, void *key, GHashKeyFreeFP keyfreefp, GHashValFreeFP valfreefp) { const unsigned int hash = ghash_keyhash(gh, key); @@ -256,6 +327,13 @@ bool BLI_ghash_remove(GHash *gh, void *key, GHashKeyFreeFP keyfreefp, GHashValFr /* same as above but return the value, * no free value argument since it will be returned */ +/** + * Remove \a key from \a gh, returning the value or NULL if the key wasn't found. + * + * \param key The key to remove. + * \param keyfreefp Optional callback to free the key. + * \return the value of \a key int \a gh or NULL. + */ void *BLI_ghash_pop(GHash *gh, void *key, GHashKeyFreeFP keyfreefp) { const unsigned int hash = ghash_keyhash(gh, key); @@ -284,11 +362,20 @@ void *BLI_ghash_pop(GHash *gh, void *key, GHashKeyFreeFP keyfreefp) return NULL; } +/** + * \return true if the \a key is in \a gh. + */ bool BLI_ghash_haskey(GHash *gh, const void *key) { return (ghash_lookup_entry(gh, key) != NULL); } +/** + * Reset \a gh clearing all entries. + * + * \param keyfreefp Optional callback to free the key. + * \param valfreefp Optional callback to free the value. + */ void BLI_ghash_clear(GHash *gh, GHashKeyFreeFP keyfreefp, GHashValFreeFP valfreefp) { unsigned int i; @@ -316,6 +403,13 @@ void BLI_ghash_clear(GHash *gh, GHashKeyFreeFP keyfreefp, GHashValFreeFP valfree gh->buckets = MEM_callocN(gh->nbuckets * sizeof(*gh->buckets), "buckets"); } +/** + * Frees the GHash and its members. + * + * \param gh The GHash to free. + * \param keyfreefp Optional callback to free the key. + * \param valfreefp Optional callback to free the value. + */ void BLI_ghash_free(GHash *gh, GHashKeyFreeFP keyfreefp, GHashValFreeFP valfreefp) { unsigned int i; @@ -343,20 +437,31 @@ void BLI_ghash_free(GHash *gh, GHashKeyFreeFP keyfreefp, GHashValFreeFP valfreef MEM_freeN(gh); } +/** + * Sets a GHash flag. + */ void BLI_ghash_flag_set(GHash *gh, unsigned int flag) { gh->flag |= flag; } +/** + * Clear a GHash flag. + */ void BLI_ghash_flag_clear(GHash *gh, unsigned int flag) { gh->flag &= ~flag; } +/** \} */ + /* -------------------------------------------------------------------- */ /* GHash Iterator API */ +/** \name Iterator API + * \{ */ + GHashIterator *BLI_ghashIterator_new(GHash *gh) { GHashIterator *ghi = MEM_mallocN(sizeof(*ghi), "ghash iterator"); @@ -406,6 +511,12 @@ bool BLI_ghashIterator_done(GHashIterator *ghi) return ghi->curEntry == NULL; } +/** \} */ + + +/** \name Generic Key Hash & Comparison Functions + * \{ */ + /***/ #if 0 @@ -480,6 +591,43 @@ int BLI_ghashutil_strcmp(const void *a, const void *b) return strcmp(a, b); } +GHashPair *BLI_ghashutil_pairalloc(const void *first, const void *second) +{ + GHashPair *pair = MEM_mallocN(sizeof(GHashPair), "GHashPair"); + pair->first = first; + pair->second = second; + return pair; +} + +unsigned int BLI_ghashutil_pairhash(const void *ptr) +{ + const GHashPair *pair = ptr; + unsigned int hash = BLI_ghashutil_ptrhash(pair->first); + return hash ^ BLI_ghashutil_ptrhash(pair->second); +} + +int BLI_ghashutil_paircmp(const void *a, const void *b) +{ + const GHashPair *A = a; + const GHashPair *B = b; + + int cmp = BLI_ghashutil_ptrcmp(A->first, B->first); + if (cmp == 0) + return BLI_ghashutil_ptrcmp(A->second, B->second); + return cmp; +} + +void BLI_ghashutil_pairfree(void *ptr) +{ + MEM_freeN(ptr); +} + +/** \} */ + + +/** \name Convenience Creation Functions + * \{ */ + GHash *BLI_ghash_ptr_new_ex(const char *info, const unsigned int nentries_reserve) { @@ -524,33 +672,4 @@ GHash *BLI_ghash_pair_new(const char *info) return BLI_ghash_pair_new_ex(info, 0); } -GHashPair *BLI_ghashutil_pairalloc(const void *first, const void *second) -{ - GHashPair *pair = MEM_mallocN(sizeof(GHashPair), "GHashPair"); - pair->first = first; - pair->second = second; - return pair; -} - -unsigned int BLI_ghashutil_pairhash(const void *ptr) -{ - const GHashPair *pair = ptr; - unsigned int hash = BLI_ghashutil_ptrhash(pair->first); - return hash ^ BLI_ghashutil_ptrhash(pair->second); -} - -int BLI_ghashutil_paircmp(const void *a, const void *b) -{ - const GHashPair *A = a; - const GHashPair *B = b; - - int cmp = BLI_ghashutil_ptrcmp(A->first, B->first); - if (cmp == 0) - return BLI_ghashutil_ptrcmp(A->second, B->second); - return cmp; -} - -void BLI_ghashutil_pairfree(void *ptr) -{ - MEM_freeN(ptr); -} +/** \} */ -- cgit v1.2.3