Cleanup: group BLI_ghash_utils.c API in BLU_ghash.h

1 files changed, 139 insertions, 100 deletions

diff --git a/source/blender/blenlib/BLI_ghash.h b/source/blender/blenlib/BLI_ghash.h
index 7a2d9924904..ec591c6bb48 100644
--- a/source/blender/blenlib/BLI_ghash.h
+++ b/source/blender/blenlib/BLI_ghash.h
@@ -81,7 +81,10 @@ enum {
 #endif
 };
 
-/* *** */
+/** \name GHash API
+ *
+ * Defined in ``BLI_ghash.c``
+ * \{ */
 
 GHash *BLI_ghash_new_ex(
         GHashHashFP hashfp, GHashCmpFP cmpfp, const char *info,
@@ -114,7 +117,10 @@ unsigned int BLI_ghash_len(GHash *gh) ATTR_WARN_UNUSED_RESULT;
 void   BLI_ghash_flag_set(GHash *gh, unsigned int flag);
 void   BLI_ghash_flag_clear(GHash *gh, unsigned int flag);
 
-/* *** */
+/** \} */
+
+/** \name GHash Iterator
+ * \{ */
 
 GHashIterator *BLI_ghashIterator_new(GHash *gh) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
 
@@ -149,94 +155,15 @@ BLI_INLINE bool   BLI_ghashIterator_done(GHashIterator *ghi)       { return !ghi
 	     BLI_ghashIterator_done(&gh_iter_) == false; \
 	     BLI_ghashIterator_step(&gh_iter_), i_++)
 
-/** \name Callbacks for GHash
- *
- * \note '_p' suffix denotes void pointer arg,
- * so we can have functions that take correctly typed args too.
- * \{ */
-
-unsigned int    BLI_ghashutil_ptrhash(const void *key);
-bool            BLI_ghashutil_ptrcmp(const void *a, const void *b);
-
-unsigned int    BLI_ghashutil_strhash_n(const char *key, size_t n);
-#define         BLI_ghashutil_strhash(key) ( \
-                CHECK_TYPE_ANY(key, char *, const char *, const char * const), \
-                BLI_ghashutil_strhash_p(key))
-unsigned int    BLI_ghashutil_strhash_p(const void *key);
-unsigned int    BLI_ghashutil_strhash_p_murmur(const void *key);
-bool            BLI_ghashutil_strcmp(const void *a, const void *b);
-
-#define         BLI_ghashutil_inthash(key) ( \
-                CHECK_TYPE_ANY(&(key), int *, const int *), \
-                BLI_ghashutil_uinthash((unsigned int)key))
-unsigned int    BLI_ghashutil_uinthash(unsigned int key);
-unsigned int    BLI_ghashutil_inthash_p(const void *ptr);
-unsigned int    BLI_ghashutil_inthash_p_murmur(const void *ptr);
-unsigned int    BLI_ghashutil_inthash_p_simple(const void *ptr);
-bool            BLI_ghashutil_intcmp(const void *a, const void *b);
-
-size_t          BLI_ghashutil_combine_hash(size_t hash_a, size_t hash_b);
-
-
-unsigned int    BLI_ghashutil_uinthash_v4(const unsigned int key[4]);
-#define         BLI_ghashutil_inthash_v4(key) ( \
-                CHECK_TYPE_ANY(key, int *, const int *), \
-                BLI_ghashutil_uinthash_v4((const unsigned int *)key))
-#define         BLI_ghashutil_inthash_v4_p \
-   ((GSetHashFP)BLI_ghashutil_uinthash_v4)
-#define         BLI_ghashutil_uinthash_v4_p \
-   ((GSetHashFP)BLI_ghashutil_uinthash_v4)
-unsigned int    BLI_ghashutil_uinthash_v4_murmur(const unsigned int key[4]);
-#define         BLI_ghashutil_inthash_v4_murmur(key) ( \
-                CHECK_TYPE_ANY(key, int *, const int *), \
-                BLI_ghashutil_uinthash_v4_murmur((const unsigned int *)key))
-#define         BLI_ghashutil_inthash_v4_p_murmur \
-   ((GSetHashFP)BLI_ghashutil_uinthash_v4_murmur)
-#define         BLI_ghashutil_uinthash_v4_p_murmur \
-   ((GSetHashFP)BLI_ghashutil_uinthash_v4_murmur)
-bool            BLI_ghashutil_uinthash_v4_cmp(const void *a, const void *b);
-#define         BLI_ghashutil_inthash_v4_cmp \
-                BLI_ghashutil_uinthash_v4_cmp
-
 /** \} */
 
-GHash *BLI_ghash_ptr_new_ex(
-        const char *info,
-        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_ptr_new(
-        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_str_new_ex(
-        const char *info,
-        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_str_new(
-        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_int_new_ex(
-        const char *info,
-        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_int_new(
-        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_pair_new_ex(
-        const char *info,
-        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GHash *BLI_ghash_pair_new(
-        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-
-typedef struct GHashPair {
-	const void *first;
-	const void *second;
-} GHashPair;
-
-GHashPair      *BLI_ghashutil_pairalloc(const void *first, const void *second);
-unsigned int    BLI_ghashutil_pairhash(const void *ptr);
-bool            BLI_ghashutil_paircmp(const void *a, const void *b);
-void            BLI_ghashutil_pairfree(void *ptr);
-
-/**
- * GSet is a 'set' implementation (unordered collection of unique elements).
+/** \name GSet API
+ * A 'set' implementation (unordered collection of unique elements).
  *
  * Internally this is a 'GHash' without any keys,
  * which is why this API's are in the same header & source file.
- */
+ *
+ * \{ */
 
 typedef struct GSet GSet;
 
@@ -247,15 +174,6 @@ typedef GHashKeyCopyFP GSetKeyCopyFP;
 
 typedef GHashIterState GSetIterState;
 
-/* so we can cast but compiler sees as different */
-typedef struct GSetIterator {
-	GHashIterator _ghi
-#ifdef __GNUC__
-	__attribute__ ((deprecated))
-#endif
-	;
-} GSetIterator;
-
 GSet  *BLI_gset_new_ex(
         GSetHashFP hashfp, GSetCmpFP cmpfp, const char *info,
         const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
@@ -281,14 +199,20 @@ void   BLI_gset_clear(GSet *gs, GSetKeyFreeFP keyfreefp);
 void  *BLI_gset_lookup(GSet *gh, const void *key) ATTR_WARN_UNUSED_RESULT;
 void  *BLI_gset_pop_key(GSet *gs, const void *key) ATTR_WARN_UNUSED_RESULT;
 
-GSet *BLI_gset_ptr_new_ex(const char *info, const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GSet *BLI_gset_ptr_new(const char *info);
-GSet *BLI_gset_str_new_ex(const char *info, const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GSet *BLI_gset_str_new(const char *info);
-GSet *BLI_gset_pair_new_ex(const char *info, const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
-GSet *BLI_gset_pair_new(const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+/** \name GSet Iterator
+ * \{ */
 
 /* rely on inline api for now */
+
+/* so we can cast but compiler sees as different */
+typedef struct GSetIterator {
+	GHashIterator _ghi
+#ifdef __GNUC__
+	__attribute__ ((deprecated))
+#endif
+	;
+} GSetIterator;
+
 BLI_INLINE GSetIterator *BLI_gsetIterator_new(GSet *gs) { return (GSetIterator *)BLI_ghashIterator_new((GHash *)gs); }
 BLI_INLINE void BLI_gsetIterator_init(GSetIterator *gsi, GSet *gs) { BLI_ghashIterator_init((GHashIterator *)gsi, (GHash *)gs); }
 BLI_INLINE void BLI_gsetIterator_free(GSetIterator *gsi) { BLI_ghashIterator_free((GHashIterator *)gsi); }
@@ -306,6 +230,10 @@ BLI_INLINE bool BLI_gsetIterator_done(GSetIterator *gsi) { return BLI_ghashItera
 	     BLI_gsetIterator_done(&gs_iter_) == false; \
 	     BLI_gsetIterator_step(&gs_iter_), i_++)
 
+/** \} */
+
+/** \name GHash/GSet Debugging API's
+ * \{ */
 
 /* For testing, debugging only */
 #ifdef GHASH_INTERNAL_API
@@ -321,6 +249,10 @@ double BLI_gset_calc_quality_ex(
 double BLI_ghash_calc_quality(GHash *gh);
 double BLI_gset_calc_quality(GSet *gs);
 #endif  /* GHASH_INTERNAL_API */
+/** \} */
+
+/** \name GHash/GSet Macros
+ * \{ */
 
 #define GHASH_FOREACH_BEGIN(type, var, what) \
 	do { \
@@ -342,6 +274,113 @@ double BLI_gset_calc_quality(GSet *gs);
 		} \
 	} while(0)
 
+/** \} */
+
+/** \name GHash/GSet Utils
+ *
+ * Defined in ``BLI_ghash_utils.c``
+ * \{ */
+
+/**
+ * Callbacks for GHash (``BLI_ghashutil_``)
+ *
+ * \note '_p' suffix denotes void pointer arg,
+ * so we can have functions that take correctly typed args too.
+ * \{ */
+
+unsigned int    BLI_ghashutil_ptrhash(const void *key);
+bool            BLI_ghashutil_ptrcmp(const void *a, const void *b);
+
+unsigned int    BLI_ghashutil_strhash_n(const char *key, size_t n);
+#define         BLI_ghashutil_strhash(key) ( \
+                CHECK_TYPE_ANY(key, char *, const char *, const char * const), \
+                BLI_ghashutil_strhash_p(key))
+unsigned int    BLI_ghashutil_strhash_p(const void *key);
+unsigned int    BLI_ghashutil_strhash_p_murmur(const void *key);
+bool            BLI_ghashutil_strcmp(const void *a, const void *b);
+
+#define         BLI_ghashutil_inthash(key) ( \
+                CHECK_TYPE_ANY(&(key), int *, const int *), \
+                BLI_ghashutil_uinthash((unsigned int)key))
+unsigned int    BLI_ghashutil_uinthash(unsigned int key);
+unsigned int    BLI_ghashutil_inthash_p(const void *ptr);
+unsigned int    BLI_ghashutil_inthash_p_murmur(const void *ptr);
+unsigned int    BLI_ghashutil_inthash_p_simple(const void *ptr);
+bool            BLI_ghashutil_intcmp(const void *a, const void *b);
+
+size_t          BLI_ghashutil_combine_hash(size_t hash_a, size_t hash_b);
+
+
+unsigned int    BLI_ghashutil_uinthash_v4(const unsigned int key[4]);
+#define         BLI_ghashutil_inthash_v4(key) ( \
+                CHECK_TYPE_ANY(key, int *, const int *), \
+                BLI_ghashutil_uinthash_v4((const unsigned int *)key))
+#define         BLI_ghashutil_inthash_v4_p \
+   ((GSetHashFP)BLI_ghashutil_uinthash_v4)
+#define         BLI_ghashutil_uinthash_v4_p \
+   ((GSetHashFP)BLI_ghashutil_uinthash_v4)
+unsigned int    BLI_ghashutil_uinthash_v4_murmur(const unsigned int key[4]);
+#define         BLI_ghashutil_inthash_v4_murmur(key) ( \
+                CHECK_TYPE_ANY(key, int *, const int *), \
+                BLI_ghashutil_uinthash_v4_murmur((const unsigned int *)key))
+#define         BLI_ghashutil_inthash_v4_p_murmur \
+   ((GSetHashFP)BLI_ghashutil_uinthash_v4_murmur)
+#define         BLI_ghashutil_uinthash_v4_p_murmur \
+   ((GSetHashFP)BLI_ghashutil_uinthash_v4_murmur)
+bool            BLI_ghashutil_uinthash_v4_cmp(const void *a, const void *b);
+#define         BLI_ghashutil_inthash_v4_cmp \
+                BLI_ghashutil_uinthash_v4_cmp
+
+typedef struct GHashPair {
+	const void *first;
+	const void *second;
+} GHashPair;
+
+GHashPair      *BLI_ghashutil_pairalloc(const void *first, const void *second);
+unsigned int    BLI_ghashutil_pairhash(const void *ptr);
+bool            BLI_ghashutil_paircmp(const void *a, const void *b);
+void            BLI_ghashutil_pairfree(void *ptr);
+
+/**
+ * Wrapper GHash Creation Functions
+ */
+
+GHash *BLI_ghash_ptr_new_ex(
+        const char *info,
+        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_ptr_new(
+        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_str_new_ex(
+        const char *info,
+        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_str_new(
+        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_int_new_ex(
+        const char *info,
+        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_int_new(
+        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_pair_new_ex(
+        const char *info,
+        const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GHash *BLI_ghash_pair_new(
+        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+
+GSet *BLI_gset_ptr_new_ex(
+        const char *info, const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GSet *BLI_gset_ptr_new(
+        const char *info);
+GSet *BLI_gset_str_new_ex(
+        const char *info, const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GSet *BLI_gset_str_new(
+        const char *info);
+GSet *BLI_gset_pair_new_ex(
+        const char *info, const unsigned int nentries_reserve) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+GSet *BLI_gset_pair_new(
+        const char *info) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
+
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif