Annotate hb-set a bit; add HB_SET_VALUE_INVALID

src/hb-set-private.hh

@@ -171,7 +171,7 @@ struct hb_set_t
   inline void add (hb_codepoint_t g)
   {
     if (unlikely (in_error)) return;
-    if (unlikely (g == SENTINEL)) return;
+    if (unlikely (g == INVALID)) return;
     if (unlikely (g > MAX_G)) return;
     elt (g) |= mask (g);
   }
@@ -256,19 +256,22 @@ struct hb_set_t
   }
   inline bool next (hb_codepoint_t *codepoint) const
   {
-    if (unlikely (*codepoint == SENTINEL)) {
+    if (unlikely (*codepoint == INVALID)) {
       hb_codepoint_t i = get_min ();
-      if (i != SENTINEL) {
+      if (i != INVALID) {
         *codepoint = i;
 	return true;
-      } else
+      } else {
+	*codepoint = INVALID;
         return false;
+      }
     }
     for (hb_codepoint_t i = *codepoint + 1; i < MAX_G + 1; i++)
       if (has (i)) {
         *codepoint = i;
 	return true;
       }
+    *codepoint = INVALID;
     return false;
   }
   inline bool next_range (hb_codepoint_t *first, hb_codepoint_t *last) const
@@ -277,7 +280,10 @@ struct hb_set_t
 
     i = *last;
     if (!next (&i))
+    {
+      *last = *first = INVALID;
       return false;
+    }
 
     *last = *first = i;
     while (next (&i) && i == *last + 1)
@@ -300,7 +306,7 @@ struct hb_set_t
 	for (unsigned int j = 0; j < BITS; j++)
 	  if (elts[i] & (1 << j))
 	    return i * BITS + j;
-    return SENTINEL;
+    return INVALID;
   }
   inline hb_codepoint_t get_max (void) const
   {
@@ -309,7 +315,7 @@ struct hb_set_t
 	for (unsigned int j = BITS; j; j--)
 	  if (elts[i - 1] & (1 << (j - 1)))
 	    return (i - 1) * BITS + (j - 1);
-    return SENTINEL;
+    return INVALID;
   }
 
   typedef uint32_t elt_t;
@@ -318,7 +324,7 @@ struct hb_set_t
   static const unsigned int BITS = (1 << SHIFT);
   static const unsigned int MASK = BITS - 1;
   static const unsigned int ELTS = (MAX_G + 1 + (BITS - 1)) / BITS;
-  static  const hb_codepoint_t SENTINEL = (hb_codepoint_t) -1;
+  static  const hb_codepoint_t INVALID = HB_SET_VALUE_INVALID;
 
   elt_t &elt (hb_codepoint_t g) { return elts[g >> SHIFT]; }
   elt_t elt (hb_codepoint_t g) const { return elts[g >> SHIFT]; }

src/hb-set.cc

@@ -30,6 +30,13 @@
 /* Public API */
 
 
+/**
+ * hb_set_create: (constructor)
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_set_t *
 hb_set_create (void)
 {
@@ -43,6 +50,13 @@ hb_set_create (void)
   return set;
 }
 
+/**
+ * hb_set_get_empty:
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 hb_set_t *
 hb_set_get_empty (void)
 {
@@ -56,12 +70,26 @@ hb_set_get_empty (void)
   return const_cast<hb_set_t *> (&_hb_set_nil);
 }
 
+/**
+ * hb_set_reference: (skip)
+ * @set: a set.
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_set_t *
 hb_set_reference (hb_set_t *set)
 {
   return hb_object_reference (set);
 }
 
+/**
+ * hb_set_destroy: (skip)
+ * @set: a set.
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_destroy (hb_set_t *set)
 {
@@ -72,6 +100,18 @@ hb_set_destroy (hb_set_t *set)
   free (set);
 }
 
+/**
+ * hb_set_set_user_data: (skip)
+ * @set: a set.
+ * @key:
+ * @data:
+ * @destroy (closure data):
+ * @replace:
+ *
+ * Return value:
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_set_user_data (hb_set_t           *set,
 		      hb_user_data_key_t *key,
@@ -82,6 +122,15 @@ hb_set_set_user_data (hb_set_t           *set,
   return hb_object_set_user_data (set, key, data, destroy, replace);
 }
 
+/**
+ * hb_set_get_user_data: (skip)
+ * @set: a set.
+ * @key:
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 void *
 hb_set_get_user_data (hb_set_t           *set,
 		      hb_user_data_key_t *key)
@@ -90,24 +139,63 @@ hb_set_get_user_data (hb_set_t           *set,
 }
 
 
+/**
+ * hb_set_allocation_successful:
+ * @set: a set.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_allocation_successful (const hb_set_t  *set HB_UNUSED)
 {
   return !set->in_error;
 }
 
+/**
+ * hb_set_clear:
+ * @set: a set.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_clear (hb_set_t *set)
 {
   set->clear ();
 }
 
+/**
+ * hb_set_is_empty:
+ * @set: a set.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_is_empty (const hb_set_t *set)
 {
   return set->is_empty ();
 }
 
+/**
+ * hb_set_has:
+ * @set: a set.
+ * @codepoint: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_has (const hb_set_t *set,
 	    hb_codepoint_t  codepoint)
@@ -115,6 +203,15 @@ hb_set_has (const hb_set_t *set,
   return set->has (codepoint);
 }
 
+/**
+ * hb_set_add:
+ * @set: a set.
+ * @codepoint: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_add (hb_set_t       *set,
 	    hb_codepoint_t  codepoint)
@@ -122,6 +219,16 @@ hb_set_add (hb_set_t       *set,
   set->add (codepoint);
 }
 
+/**
+ * hb_set_add_range:
+ * @set: a set.
+ * @first: 
+ * @last: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_add_range (hb_set_t       *set,
 		  hb_codepoint_t  first,
@@ -130,6 +237,15 @@ hb_set_add_range (hb_set_t       *set,
   set->add_range (first, last);
 }
 
+/**
+ * hb_set_del:
+ * @set: a set.
+ * @codepoint: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_del (hb_set_t       *set,
 	    hb_codepoint_t  codepoint)
@@ -137,6 +253,16 @@ hb_set_del (hb_set_t       *set,
   set->del (codepoint);
 }
 
+/**
+ * hb_set_del_range:
+ * @set: a set.
+ * @first: 
+ * @last: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_del_range (hb_set_t       *set,
 		  hb_codepoint_t  first,
@@ -145,6 +271,17 @@ hb_set_del_range (hb_set_t       *set,
   set->del_range (first, last);
 }
 
+/**
+ * hb_set_is_equal:
+ * @set: a set.
+ * @other: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_is_equal (const hb_set_t *set,
 		 const hb_set_t *other)
@@ -152,6 +289,15 @@ hb_set_is_equal (const hb_set_t *set,
   return set->is_equal (other);
 }
 
+/**
+ * hb_set_set:
+ * @set: a set.
+ * @other: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_set (hb_set_t       *set,
 	    const hb_set_t *other)
@@ -159,6 +305,15 @@ hb_set_set (hb_set_t       *set,
   set->set (other);
 }
 
+/**
+ * hb_set_union:
+ * @set: a set.
+ * @other: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_union (hb_set_t       *set,
 	      const hb_set_t *other)
@@ -166,6 +321,15 @@ hb_set_union (hb_set_t       *set,
   set->union_ (other);
 }
 
+/**
+ * hb_set_intersect:
+ * @set: a set.
+ * @other: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_intersect (hb_set_t       *set,
 		  const hb_set_t *other)
@@ -173,6 +337,15 @@ hb_set_intersect (hb_set_t       *set,
   set->intersect (other);
 }
 
+/**
+ * hb_set_subtract:
+ * @set: a set.
+ * @other: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_subtract (hb_set_t       *set,
 		 const hb_set_t *other)
@@ -180,6 +353,15 @@ hb_set_subtract (hb_set_t       *set,
   set->subtract (other);
 }
 
+/**
+ * hb_set_symmetric_difference:
+ * @set: a set.
+ * @other: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_symmetric_difference (hb_set_t       *set,
 			     const hb_set_t *other)
@@ -187,30 +369,79 @@ hb_set_symmetric_difference (hb_set_t       *set,
   set->symmetric_difference (other);
 }
 
+/**
+ * hb_set_invert:
+ * @set: a set.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_set_invert (hb_set_t *set)
 {
   set->invert ();
 }
 
+/**
+ * hb_set_get_population:
+ * @set: a set.
+ *
+ * Returns the number of numbers in the set.
+ *
+ * Return value: set population.
+ *
+ * Since: 1.0
+ **/
 unsigned int
 hb_set_get_population (const hb_set_t *set)
 {
   return set->get_population ();
 }
 
+/**
+ * hb_set_get_min:
+ * @set: a set.
+ *
+ * Finds the minimum number in the set.
+ *
+ * Return value: minimum of the set, or %HB_SET_VALUE_INVALID if set is empty.
+ *
+ * Since: 1.0
+ **/
 hb_codepoint_t
 hb_set_get_min (const hb_set_t *set)
 {
   return set->get_min ();
 }
 
+/**
+ * hb_set_get_max:
+ * @set: a set.
+ *
+ * Finds the maximum number in the set.
+ *
+ * Return value: minimum of the set, or %HB_SET_VALUE_INVALID if set is empty.
+ *
+ * Since: 1.0
+ **/
 hb_codepoint_t
 hb_set_get_max (const hb_set_t *set)
 {
   return set->get_max ();
 }
 
+/**
+ * hb_set_next:
+ * @set: a set.
+ * @codepoint: (inout):
+ *
+ * 
+ *
+ * Return value: whether there was a next value.
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_next (const hb_set_t *set,
 	     hb_codepoint_t *codepoint)
@@ -218,6 +449,19 @@ hb_set_next (const hb_set_t *set,
   return set->next (codepoint);
 }
 
+/**
+ * hb_set_next_range:
+ * @set: a set.
+ * @first: (out): output first codepoint in the range.
+ * @last: (inout): input current last and output last codepoint in the range.
+ *
+ * Gets the next consecutive range of numbers in @set that
+ * are greater than current value of @last.
+ *
+ * Return value: whether there was a next range.
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_set_next_range (const hb_set_t *set,
 		   hb_codepoint_t *first,

src/hb-set.h

@@ -36,6 +36,8 @@
 HB_BEGIN_DECLS
 
 
+#define HB_SET_VALUE_INVALID ((hb_codepoint_t) -1)
+
 typedef struct hb_set_t hb_set_t;
 
 

src/hb-version.h.in

@@ -56,7 +56,7 @@ HB_BEGIN_DECLS
  * Returns library version as three integer components.
  *
  * Since: 1.0
- */
+ **/
 void
 hb_version (unsigned int *major,
 	    unsigned int *minor,
@@ -67,8 +67,10 @@ hb_version (unsigned int *major,
  *
  * Returns library version as a string with three components.
  *
+ * Return value: library version string.
+ *
  * Since: 1.0
- */
+ **/
 const char *
 hb_version_string (void);
 

test/api/test-set.c

@@ -32,24 +32,24 @@
 static void
 test_empty (hb_set_t *s)
 {
-  hb_codepoint_t next = (hb_codepoint_t) -1;
+  hb_codepoint_t next = HB_SET_VALUE_INVALID;
   g_assert_cmpint (hb_set_get_population (s), ==, 0);
-  g_assert_cmpint (hb_set_get_min (s), ==, (hb_codepoint_t) -1);
-  g_assert_cmpint (hb_set_get_max (s), ==, (hb_codepoint_t) -1);
+  g_assert_cmpint (hb_set_get_min (s), ==, HB_SET_VALUE_INVALID);
+  g_assert_cmpint (hb_set_get_max (s), ==, HB_SET_VALUE_INVALID);
   g_assert (!hb_set_has (s, 13));
   g_assert (!hb_set_next (s, &next));
-  g_assert_cmpint (next, ==, (hb_codepoint_t) -1);
+  g_assert_cmpint (next, ==, HB_SET_VALUE_INVALID);
 }
 
 static void
 test_not_empty (hb_set_t *s)
 {
-  hb_codepoint_t next = (hb_codepoint_t) -1;
+  hb_codepoint_t next = HB_SET_VALUE_INVALID;
   g_assert_cmpint (hb_set_get_population (s), !=, 0);
-  g_assert_cmpint (hb_set_get_min (s), !=, (hb_codepoint_t) -1);
-  g_assert_cmpint (hb_set_get_max (s), !=, (hb_codepoint_t) -1);
+  g_assert_cmpint (hb_set_get_min (s), !=, HB_SET_VALUE_INVALID);
+  g_assert_cmpint (hb_set_get_max (s), !=, HB_SET_VALUE_INVALID);
   g_assert (hb_set_next (s, &next));
-  g_assert_cmpint (next, !=, (hb_codepoint_t) -1);
+  g_assert_cmpint (next, !=, HB_SET_VALUE_INVALID);
 }
 
 static void
@@ -166,7 +166,7 @@ test_set_iter (void)
 
   test_not_empty (s);
 
-  next = (hb_codepoint_t) -1;
+  next = HB_SET_VALUE_INVALID;
   g_assert (hb_set_next (s, &next));
   g_assert_cmpint (next, ==, 6);
   g_assert (hb_set_next (s, &next));
@@ -181,9 +181,9 @@ test_set_iter (void)
   g_assert (hb_set_next (s, &next));
   g_assert_cmpint (next, ==, 20005);
   g_assert (!hb_set_next (s, &next));
-  g_assert_cmpint (next, ==, 20005);
+  g_assert_cmpint (next, ==, HB_SET_VALUE_INVALID);
 
-  first = last = (hb_codepoint_t) -1;
+  first = last = HB_SET_VALUE_INVALID;
   g_assert (hb_set_next_range (s, &first, &last));
   g_assert_cmpint (first, ==, 6);
   g_assert_cmpint (last,  ==, 6);
@@ -194,8 +194,8 @@ test_set_iter (void)
   g_assert_cmpint (first, ==, 20005);
   g_assert_cmpint (last,  ==, 20005);
   g_assert (!hb_set_next_range (s, &first, &last));
-  g_assert_cmpint (first, ==, 20005);
-  g_assert_cmpint (last,  ==, 20005);
+  g_assert_cmpint (first, ==, HB_SET_VALUE_INVALID);
+  g_assert_cmpint (last,  ==, HB_SET_VALUE_INVALID);
 }
 
 static void