[subset] change glyph mapping api to return a mutable map.

Maintains consistency with our other set based api methods.
diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt
index ce35281..9a740c6 100644
--- a/docs/harfbuzz-sections.txt
+++ b/docs/harfbuzz-sections.txt
@@ -874,9 +874,9 @@
 hb_subset_input_get_flags
 hb_subset_input_unicode_set
 hb_subset_input_glyph_set
+hb_subset_input_old_to_new_glyph_mapping
 hb_subset_input_pin_axis_location
 hb_subset_input_pin_axis_to_default
-hb_subset_input_set_old_to_new_glyph_mapping
 hb_subset_or_fail
 hb_subset_plan_create_or_fail
 hb_subset_plan_reference
diff --git a/src/hb-subset-input.cc b/src/hb-subset-input.cc
index 49fe7df..4eba5e2 100644
--- a/src/hb-subset-input.cc
+++ b/src/hb-subset-input.cc
@@ -525,34 +525,29 @@
  * @input: a #hb_subset_input_t object.
  * @mapping: a mapping from original glyphs to new ids.
  *
- * Provide a mapping from glyph ids in the original font to the desired
- * new glyph ids. The mappings must be unique, that is no two original
- * glyph ids can be mapped to the same new id.
+ * Returns a map which specifies an explicit mapping from old to new glyph
+ * id's in the produced subset. The caller should populate the map as desired.
+ * If this map is left empty then glyph ids will be automatically mapped to new
+ * values by the subsetter. If populated, the mapping must be unique, that
+ * is no two original glyph ids can be mapped to the same new id.
+ * Additionally, if a mapping is provided then the retain gids option cannot
+ * be enabled.
  *
  * Any glyphs that are retained in the subset which are not specified
  * in this mapping will be assigned glyph ids after the highest glyph
  * id in the mapping.
  *
- * Note: if a glyph mapping is set with this function, then the retain gids
- * setting will be ignored.
- *
  * Note: this will accept and apply non-monotonic mappings, however this
  * may result in unsorted Coverage tables. Such fonts may not work for all
- * use cases (for example ots will reject such coverage tables). So it's
+ * use cases (for example ots will reject unsorted coverage tables). So it's
  * recommended, if possible, to supply a monotonic mapping.
  *
  * Since: REPLACEME
  **/
-HB_EXTERN void
-hb_subset_input_set_old_to_new_glyph_mapping (hb_subset_input_t *input,
-                                              const hb_map_t* mapping)
+HB_EXTERN hb_map_t*
+hb_subset_input_old_to_new_glyph_mapping (hb_subset_input_t *input)
 {
-  hb_set_t new_gids(mapping->values());
-  if (new_gids.get_population() != mapping->get_population())
-    // Mapping cannot map multiple old gids to the same new gid.
-    return;
-
-  input->glyph_map = *mapping;
+  return &input->glyph_map;
 }
 
 #ifdef HB_EXPERIMENTAL_API
diff --git a/src/hb-subset-plan.cc b/src/hb-subset-plan.cc
index 1e152d3..111ff72 100644
--- a/src/hb-subset-plan.cc
+++ b/src/hb-subset-plan.cc
@@ -767,7 +767,7 @@
   ;
 }
 
-static void
+static bool
 _create_old_gid_to_new_gid_map (const hb_face_t *face,
 				bool		 retain_gids,
 				const hb_set_t	*all_gids_to_retain,
@@ -782,6 +782,20 @@
 
   if (*requested_glyph_map)
   {
+    hb_set_t new_gids(requested_glyph_map->values());
+    if (new_gids.get_population() != requested_glyph_map->get_population())
+    {
+      DEBUG_MSG (SUBSET, nullptr, "The provided custom glyph mapping is not unique.");
+      return false;
+    }
+
+    if (retain_gids)
+    {
+      DEBUG_MSG (SUBSET, nullptr, 
+        "HB_SUBSET_FLAGS_RETAIN_GIDS cannot be set if "
+        "a custom glyph mapping has been provided.");
+      return false;
+    }
   
     hb_codepoint_t max_glyph = 0;
     hb_set_t remaining;
@@ -839,6 +853,8 @@
   | hb_map (&hb_pair_t<hb_codepoint_t, hb_codepoint_t>::reverse)
   | hb_sink (glyph_map)
   ;
+
+  return true;
 }
 
 #ifndef HB_NO_VAR
@@ -1042,13 +1058,16 @@
   if (unlikely (in_error ()))
     return;
 
-  _create_old_gid_to_new_gid_map (face,
-                                  input->flags & HB_SUBSET_FLAGS_RETAIN_GIDS,
-				  &_glyphset,
-                                  &input->glyph_map,
-				  glyph_map,
-				  reverse_glyph_map,
-				  &_num_output_glyphs);
+  if (!check_success(_create_old_gid_to_new_gid_map(
+          face,
+          input->flags & HB_SUBSET_FLAGS_RETAIN_GIDS,
+          &_glyphset,
+          &input->glyph_map,
+          glyph_map,
+          reverse_glyph_map,
+          &_num_output_glyphs))) {
+    return;
+  }
 
   _create_glyph_map_gsub (
       &_glyphset_gsub,
diff --git a/src/hb-subset.h b/src/hb-subset.h
index a790128..078dc5a 100644
--- a/src/hb-subset.h
+++ b/src/hb-subset.h
@@ -172,10 +172,8 @@
 				   hb_tag_t            axis_tag,
 				   float               axis_value);
 
-HB_EXTERN void
-hb_subset_input_set_old_to_new_glyph_mapping (hb_subset_input_t *input,
-                                              const hb_map_t* mapping);
-
+HB_EXTERN hb_map_t*
+hb_subset_input_old_to_new_glyph_mapping (hb_subset_input_t *input);
 
 #ifdef HB_EXPERIMENTAL_API
 HB_EXTERN hb_bool_t
diff --git a/util/hb-subset.cc b/util/hb-subset.cc
index 82ec02b..599c7dc 100644
--- a/util/hb-subset.cc
+++ b/util/hb-subset.cc
@@ -753,7 +753,6 @@
   // <entry> = <old gid>:<new gid>
   subset_main_t *subset_main = (subset_main_t *) data;
   hb_subset_input_t* input = subset_main->input;
-  hb_map_t *mapping = hb_map_create ();
   hb_set_t *glyphs = hb_subset_input_glyph_set(input);
 
   char *s = (char *) arg;
@@ -792,12 +791,11 @@
     }
 
     hb_set_add(glyphs, start_code);
-    hb_map_set (mapping, start_code, end_code);
+    hb_map_set (hb_subset_input_old_to_new_glyph_mapping (input), start_code, end_code);
 
     s = p;
   }
 
-  hb_subset_input_set_old_to_new_glyph_mapping(input, mapping);
   return true;
 }