[pango/preferred-languages: 7/8] Add pango_language_get_preferred

[Matthias Clasen <matthiasc src gnome org>]

commit d1444c3e5f20daf987faa0447bcdff95d6897985
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Sep 8 10:44:20 2020 -0400

    Add pango_language_get_preferred
    
    This returns the list of preferred languages, as
    determined from the PANGO_LANGUAGES or LANGUAGES
    environment variables.

 docs/pango-sections.txt |  1 +
 pango/pango-language.c  | 36 ++++++++++++++++++++++++++++++++----
 pango/pango-language.h  |  3 +++
 3 files changed, 36 insertions(+), 4 deletions(-)
---
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 04b6b442..56ca9ecf 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -644,6 +644,7 @@ pango_language_matches
 pango_language_includes_script
 pango_language_get_scripts
 pango_language_get_default
+pango_language_get_preferred
 pango_language_get_sample_string
 
 <SUBSECTION Private>
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 410ca0bf..04c3e0ca 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -791,13 +791,14 @@ parse_default_languages (void)
   return (PangoLanguage **) g_array_free (langs, FALSE);
 }
 
+G_LOCK_DEFINE_STATIC (languages);
+static gboolean initialized = FALSE; /* MT-safe */
+static PangoLanguage * const * languages = NULL; /* MT-safe */
+static GHashTable *hash = NULL; /* MT-safe */
+
 static PangoLanguage *
 _pango_script_get_default_language (PangoScript script)
 {
-  G_LOCK_DEFINE_STATIC (languages);
-  static gboolean initialized = FALSE; /* MT-safe */
-  static PangoLanguage * const * languages = NULL; /* MT-safe */
-  static GHashTable *hash = NULL; /* MT-safe */
   PangoLanguage *result, * const * p;
 
   G_LOCK (languages);
@@ -834,6 +835,33 @@ out:
   return result;
 }
 
+/**
+ * pango_language_get_preferred:
+ *
+ * Returns the list of languages that the user prefers, as specified
+ * by the PANGO_LANGUAGE or LANGUAGE environment variables, in order
+ * of preference. Note that this list does not necessarily include
+ * the language returned by pango_language_get_default().
+ *
+ * When choosing language-specific resources, such as the sample
+ * text returned by pango_language_get_sample_string(), you should
+ * first try the default language, followed by the languages returned
+ * by this function.
+ *
+ * Returns: (transfer none) (nullable): a %NULL-terminated array of
+ *    PangoLanguage*
+ *
+ * Since: 1.48
+ */
+PangoLanguage **
+pango_language_get_preferred (void)
+{
+  /* We call this just for its side-effect of initializing languages */
+  _pango_script_get_default_language (PANGO_SCRIPT_COMMON);
+
+  return languages;
+}
+
 /**
  * pango_script_get_sample_language:
  * @script: a #PangoScript
diff --git a/pango/pango-language.h b/pango/pango-language.h
index 2ab07bc0..16e6512c 100644
--- a/pango/pango-language.h
+++ b/pango/pango-language.h
@@ -53,6 +53,9 @@ const char    *pango_language_get_sample_string (PangoLanguage *language) G_GNUC
 PANGO_AVAILABLE_IN_1_16
 PangoLanguage *pango_language_get_default (void) G_GNUC_CONST;
 
+PANGO_AVAILABLE_IN_1_48
+PangoLanguage **pango_language_get_preferred (void) G_GNUC_CONST;
+
 PANGO_AVAILABLE_IN_ALL
 gboolean      pango_language_matches  (PangoLanguage *language,
                                       const char *range_list) G_GNUC_PURE;