[pango/get_face] family: Clarify and improve pango_font_family_get_face()

[Benjamin Otte <otte src gnome org>]

commit 5e07328675aa49d9b84b3ab4405ff94b92835e9c
Author: Benjamin Otte <otte redhat com>
Date:   Sun Dec 8 03:33:02 2019 +0100

    family: Clarify and improve pango_font_family_get_face()
    
    - Clarify that the function can return NULL
    - Fix annotations
    - Allow passing NULL as name to get a guaranteed default face.
    - Map the default name to "Regular" in the FC backend

 pango/fonts.c           | 22 ++++++++++++++++------
 pango/pangofc-fontmap.c |  3 +++
 2 files changed, 19 insertions(+), 6 deletions(-)
---
diff --git a/pango/fonts.c b/pango/fonts.c
index 736c9c20..f4244911 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -2295,12 +2295,19 @@ pango_font_family_real_get_face (PangoFontFamily *family,
   pango_font_family_list_faces (family, &faces, &n_faces);
 
   face = NULL;
-  for (i = 0; i < n_faces; i++)
+  if (name == NULL)
     {
-      if (strcmp (name, pango_font_face_get_face_name (faces[i])) == 0)
+      face = faces[0];
+    }
+  else
+    {
+      for (i = 0; i < n_faces; i++)
         {
-          face = faces[i];
-          break;
+          if (strcmp (name, pango_font_face_get_face_name (faces[i])) == 0)
+            {
+              face = faces[i];
+              break;
+            }
         }
     }
 
@@ -2312,11 +2319,14 @@ pango_font_family_real_get_face (PangoFontFamily *family,
 /**
  * pango_font_family_get_face:
  * @family: a #PangoFontFamily
- * @name: the name of a face
+ * @name: (optional): the name of a face. If the name is %NULL,
+ *     the family's default face (fontconfig calls it "Regular")
+ *     will be returned.
  *
  * Gets the #PangoFontFace of @family with the given name.
  *
- * Returns: (transfer none): the #PangoFontFace
+ * Returns: (transfer none) (nullable): the #PangoFontFace,
+ *     or %NULL if no face with the given name exists.
  *
  * Since: 1.46
  */
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 49040b24..9ecea09b 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -2861,6 +2861,9 @@ pango_fc_family_get_face (PangoFontFamily *family,
 
   ensure_faces (fcfamily);
 
+  if (name == NULL)
+    name = "Regular"; /* This name always exists in fontconfig */
+
   for (i = 0; i < fcfamily->n_faces; i++)
     {
       PangoFontFace *face = PANGO_FONT_FACE (fcfamily->faces[i]);