[face] Add hb_face_collect_nominal_glyph_mapping

Fixes https://github.com/harfbuzz/harfbuzz/issues/3973

docs/harfbuzz-sections.txt

@@ -354,6 +354,7 @@ hb_face_get_upem
 hb_face_reference_blob
 hb_face_reference_table
 hb_face_collect_unicodes
+hb_face_collect_nominal_glyph_mapping
 hb_face_collect_variation_selectors
 hb_face_collect_variation_unicodes
 hb_face_builder_create

src/hb-face.cc

@@ -580,7 +580,7 @@ hb_face_get_table_tags (const hb_face_t *face,
 /**
  * hb_face_collect_unicodes:
  * @face: A face object
- * @out: The set to add Unicode characters to
+ * @out: (out): The set to add Unicode characters to
  *
  * Collects all of the Unicode characters covered by @face and adds
  * them to the #hb_set_t set @out.
@@ -593,10 +593,31 @@ hb_face_collect_unicodes (hb_face_t *face,
 {
   face->table.cmap->collect_unicodes (out, face->get_num_glyphs ());
 }
+/**
+ * hb_face_collect_nominal_glyph_mapping:
+ * @face: A face object
+ * @mapping: (out): The map to add Unicode-to-glyph mapping to
+ * @unicodes: (nullable) (out): The set to add Unicode characters to, or %NULL
+ *
+ * Collects the mapping from Unicode characters to nominal glyphs of the @face,
+ * and optionall all of the Unicode characters covered by @face.
+ *
+ * Since: REPLACEME
+ */
+void
+hb_face_collect_nominal_glyph_mapping (hb_face_t *face,
+				       hb_map_t  *mapping,
+				       hb_set_t  *unicodes)
+{
+  hb_set_t static_unicodes;
+  if (!unicodes)
+    unicodes = &static_unicodes;
+  face->table.cmap->collect_mapping (unicodes, mapping, face->get_num_glyphs ());
+}
 /**
  * hb_face_collect_variation_selectors:
  * @face: A face object
- * @out: The set to add Variation Selector characters to
+ * @out: (out): The set to add Variation Selector characters to
  *
  * Collects all Unicode "Variation Selector" characters covered by @face and adds
  * them to the #hb_set_t set @out.
@@ -613,7 +634,7 @@ hb_face_collect_variation_selectors (hb_face_t *face,
  * hb_face_collect_variation_unicodes:
  * @face: A face object
  * @variation_selector: The Variation Selector to query
- * @out: The set to add Unicode characters to
+ * @out: (out): The set to add Unicode characters to
  *
  * Collects all Unicode characters for @variation_selector covered by @face and adds
  * them to the #hb_set_t set @out.

src/hb-face.h

@@ -33,6 +33,7 @@
 
 #include "hb-common.h"
 #include "hb-blob.h"
+#include "hb-map.h"
 #include "hb-set.h"
 
 HB_BEGIN_DECLS
@@ -149,6 +150,11 @@ HB_EXTERN void
 hb_face_collect_unicodes (hb_face_t *face,
 			  hb_set_t  *out);
 
+HB_EXTERN void
+hb_face_collect_nominal_glyph_mapping (hb_face_t *face,
+				       hb_map_t  *mapping,
+				       hb_set_t  *unicodes);
+
 HB_EXTERN void
 hb_face_collect_variation_selectors (hb_face_t *face,
 				     hb_set_t  *out);

test/api/test-collect-unicodes.c

@@ -97,20 +97,32 @@ test_collect_unicodes (void)
 {
   hb_face_t *face = hb_test_open_font_file ("fonts/Roboto-Regular.abc.ttf");
   hb_set_t *codepoints = hb_set_create();
+  hb_set_t *codepoints2 = hb_set_create();
+  hb_map_t *mapping = hb_map_create();
   hb_codepoint_t cp;
 
   hb_face_collect_unicodes (face, codepoints);
+  hb_face_collect_nominal_glyph_mapping (face, mapping, codepoints2);
+
+  g_assert (hb_set_is_equal (codepoints, codepoints2));
+  g_assert_cmpuint (hb_set_get_population (codepoints), ==, 3);
+  g_assert_cmpuint (hb_map_get_population (mapping), ==, 3);
 
   cp = HB_SET_VALUE_INVALID;
   g_assert (hb_set_next (codepoints, &cp));
+  g_assert (hb_map_has (mapping, cp));
   g_assert_cmpuint (0x61, ==, cp);
   g_assert (hb_set_next (codepoints, &cp));
+  g_assert (hb_map_has (mapping, cp));
   g_assert_cmpuint (0x62, ==, cp);
   g_assert (hb_set_next (codepoints, &cp));
+  g_assert (hb_map_has (mapping, cp));
   g_assert_cmpuint (0x63, ==, cp);
   g_assert (!hb_set_next (codepoints, &cp));
 
   hb_set_destroy (codepoints);
+  hb_set_destroy (codepoints2);
+  hb_map_destroy (mapping);
   hb_face_destroy (face);
 }