Bug 473805 – Add API enumerating scripts for a language

2008-08-18  Behdad Esfahbod  <behdad@gnome.org>

        Bug 473805 – Add API enumerating scripts for a language

        * docs/Makefile.am:
        * docs/pango-sections.txt:
        * docs/tmpl/scripts.sgml:
        * docs/tmpl/text-attributes.sgml:
        * docs/tmpl/utils.sgml:
        * pango/pango-language.c (pango_language_get_scripts),
        (pango_language_includes_script),
        (pango_script_get_sample_language):
        * pango/pango-language.h:
        * pango/pango-script.c:
        * pango/pango.def:
        Add a minor new public API:

                pango_language_get_scripts()

        This is what pango_language_includes_script() has been using
        internally.  Previously one had to call that function over all
        possible script values to determine which scripts a language
        uses.  The new API makes that much easier.

svn path=/trunk/; revision=2693

10 files changed, 250 insertions, 120 deletions

diff --git a/ChangeLog b/ChangeLog
index fccb715c..7b8c076c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,29 @@
 2008-08-18  Behdad Esfahbod  <behdad@gnome.org>
 
+	Bug 473805 – Add API enumerating scripts for a language
+
+	* docs/Makefile.am:
+	* docs/pango-sections.txt:
+	* docs/tmpl/scripts.sgml:
+	* docs/tmpl/text-attributes.sgml:
+	* docs/tmpl/utils.sgml:
+	* pango/pango-language.c (pango_language_get_scripts),
+	(pango_language_includes_script),
+	(pango_script_get_sample_language):
+	* pango/pango-language.h:
+	* pango/pango-script.c:
+	* pango/pango.def:
+	Add a minor new public API:
+
+		pango_language_get_scripts()
+	
+	This is what pango_language_includes_script() has been using
+	internally.  Previously one had to call that function over all
+	possible script values to determine which scripts a language
+	uses.  The new API makes that much easier.
+
+2008-08-18  Behdad Esfahbod  <behdad@gnome.org>
+
 	* pango/pango-language.h:
 	* pango/pango-script.h:
 	Fix cyclic header ordering and move pango_language_* to
diff --git a/docs/Makefile.am b/docs/Makefile.am
index b32cb757..3b5d901b 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -40,7 +40,8 @@ IGNORE_HFILES=			\
 	pangoatsui-private.h	\
 	pangox-private.h	\
 	pangoxft-private.h	\
-	pango-ot-private.h
+	pango-ot-private.h	\
+	pango-script-lang-table.h
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
 # if $(DOC_MODULE).types is non-empty.
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 772e70c5..c5b47c67 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -374,11 +374,6 @@ pango_color_parse
 pango_color_copy
 pango_color_free
 pango_color_to_string
-PangoLanguage
-PANGO_TYPE_LANGUAGE
-pango_language_from_string
-pango_language_to_string
-pango_language_matches
 <SUBSECTION>
 PangoAttrList
 PANGO_TYPE_ATTR_LIST
@@ -406,7 +401,6 @@ pango_attr_type_get_type
 pango_attr_list_get_type
 pango_underline_get_type
 pango_color_get_type
-pango_language_get_type
 </SECTION>
 
 <SECTION>
@@ -557,21 +551,29 @@ pango_ellipsize_mode_get_type
 </SECTION>
 
 <SECTION>
-<TITLE>Scripts</TITLE>
+<TITLE>Scripts and Languages</TITLE>
 <FILE>scripts</FILE>
-PangoScriptIter
 PangoScript
 PANGO_TYPE_SCRIPT
+PangoScriptIter
 pango_script_for_unichar
 pango_script_get_sample_language
-pango_language_includes_script
 pango_script_iter_new
 pango_script_iter_get_range
 pango_script_iter_next
 pango_script_iter_free
+PangoLanguage
+PANGO_TYPE_LANGUAGE
+pango_language_from_string
+pango_language_to_string
+pango_language_matches
+pango_language_includes_script
+pango_language_get_scripts
+pango_language_get_default
+pango_language_get_sample_string
 <SUBSECTION Private>
 pango_script_get_type
-PangoScriptForLang
+pango_language_get_type
 </SECTION>
 
 <SECTION>
@@ -1057,8 +1059,6 @@ pango_parse_stretch
 pango_get_sysconf_subdirectory
 pango_get_lib_subdirectory
 pango_log2vis_get_embedding_levels
-pango_language_get_default
-pango_language_get_sample_string
 pango_is_zero_width
 pango_quantize_line_geometry
 </SECTION>
diff --git a/docs/tmpl/scripts.sgml b/docs/tmpl/scripts.sgml
index aa500c90..17aa595e 100644
--- a/docs/tmpl/scripts.sgml
+++ b/docs/tmpl/scripts.sgml
@@ -19,12 +19,6 @@ and of ranges within a larger text string.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### STRUCT PangoScriptIter ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### ENUM PangoScript ##### -->
 <para>
 The #PangoScript enumeration identifies different writing
@@ -125,30 +119,26 @@ The #GObject type for #PangoScript
 
 
 
-<!-- ##### FUNCTION pango_script_for_unichar ##### -->
+<!-- ##### STRUCT PangoScriptIter ##### -->
 <para>
 
 </para>
 
-@ch: 
-@Returns: 
-
 
-<!-- ##### FUNCTION pango_script_get_sample_language ##### -->
+<!-- ##### FUNCTION pango_script_for_unichar ##### -->
 <para>
 
 </para>
 
-@script: 
+@ch: 
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_language_includes_script ##### -->
+<!-- ##### FUNCTION pango_script_get_sample_language ##### -->
 <para>
 
 </para>
 
-@language: 
 @script: 
 @Returns: 
 
@@ -191,3 +181,86 @@ The #GObject type for #PangoScript
 @iter: 
 
 
+<!-- ##### STRUCT PangoLanguage ##### -->
+<para>
+The #PangoLanguage structure is used to
+represent a language.
+</para>
+<para>
+#PangoLanguage pointers can be efficiently 
+copied and compared with each other.
+</para>
+
+
+<!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### -->
+<para>
+The #GObject type for #PangoLanguage. 
+</para>
+
+
+
+<!-- ##### FUNCTION pango_language_from_string ##### -->
+<para>
+
+</para>
+
+@language: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_language_to_string ##### -->
+<para>
+
+</para>
+
+@language: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_language_matches ##### -->
+<para>
+
+</para>
+
+@language: 
+@range_list: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_language_includes_script ##### -->
+<para>
+
+</para>
+
+@language: 
+@script: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_language_get_scripts ##### -->
+<para>
+
+</para>
+
+@language: 
+@num_scripts: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_language_get_default ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_language_get_sample_string ##### -->
+<para>
+
+</para>
+
+@language: 
+@Returns: 
+
+
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index bbbb5c83..edf2922d 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -605,52 +605,6 @@ The #GObject type for #PangoColor.
 @Returns: 
 
 
-<!-- ##### STRUCT PangoLanguage ##### -->
-<para>
-The #PangoLanguage structure is used to
-represent a language.
-</para>
-<para>
-#PangoLanguage pointers can be efficiently 
-copied and compared with each other.
-</para>
-
-
-<!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### -->
-<para>
-The #GObject type for #PangoLanguage. 
-</para>
-
-
-
-<!-- ##### FUNCTION pango_language_from_string ##### -->
-<para>
-
-</para>
-
-@language: 
-@Returns: 
-
-
-<!-- ##### FUNCTION pango_language_to_string ##### -->
-<para>
-
-</para>
-
-@language: 
-@Returns: 
-
-
-<!-- ##### FUNCTION pango_language_matches ##### -->
-<para>
-
-</para>
-
-@language: 
-@range_list: 
-@Returns: 
-
-
 <!-- ##### STRUCT PangoAttrList ##### -->
 <para>
 The #PangoAttrList structure represents a list of attributes
diff --git a/docs/tmpl/utils.sgml b/docs/tmpl/utils.sgml
index f53c776f..6ac6a66f 100644
--- a/docs/tmpl/utils.sgml
+++ b/docs/tmpl/utils.sgml
@@ -188,23 +188,6 @@ backends and modules, but may be useful for other purposes too.
 @Returns: 
 
 
-<!-- ##### FUNCTION pango_language_get_default ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION pango_language_get_sample_string ##### -->
-<para>
-
-</para>
-
-@language: 
-@Returns: 
-
-
 <!-- ##### FUNCTION pango_is_zero_width ##### -->
 <para>
 
diff --git a/pango/pango-language.c b/pango/pango-language.c
index dc1647ec..6b482dee 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -421,6 +421,14 @@ pango_language_get_sample_string (PangoLanguage *language)
   return result;
 }
 
+
+
+
+/*
+ * From language to script
+ */
+
+
 #include "pango-script-lang-table.h"
 
 static int
@@ -434,41 +442,47 @@ script_for_lang_compare (gconstpointer key,
 }
 
 /**
- * pango_language_includes_script:
+ * pango_language_get_scripts:
  * @language: a #PangoLanguage, or %NULL
- * @script: a #PangoScript
+ * @num_scripts: location to return number of scripts, or %NULL
  *
- * Determines if @script is one of the scripts used to
- * write @language. The returned value is conservative;
- * if nothing is known about the language tag @language,
- * %TRUE will be returned, since, as far as Pango knows,
- * @script might be used to write @language.
+ * Determines the scripts used to to write @language.
+ * If nothing is known about the language tag @language,
+ * or if @language is %NULL, then %NULL is returned.
+ * The list of scripts returned starts with the script that the
+ * language uses most and continues to the one it uses least.
  *
- * This routine is used in Pango's itemization process when
- * determining if a supplied language tag is relevant to
- * a particular section of text. It probably is not useful for
- * applications in most circumstances.
+ * The value @num_script points at will be set to the number
+ * of scripts in the returned array (or zero if %NULL is returned).
  *
- * Return value: %TRUE if @script is one of the scripts used
- * to write @language or if nothing is known about @language
- * (including the case that @language is %NULL),
- * %FALSE otherwise.
+ * Most languages use only one script for writing, but there are
+ * some that use two (Latin and Cyrillic for example), and a few
+ * use three (Japanese for example).  Applications should not make
+ * any assumptions on the maximum number of scripts returned
+ * though, except that it is a small number.
+ *
+ * The pango_language_includes_script() uses this function
+ * internally.
+ *
+ * Return value: An array of #PangoScript values, with the
+ * number of entries in the array stored in @num_scripts, or
+ * %NULL if Pango does not have any information about this
+ * particular language tag (also the case if @language is %NULL).
+ * The returned array is owned by Pango and should not be modified
+ * or freed.
  
- * Since: 1.4
+ * Since: 1.22
  **/
-gboolean
-pango_language_includes_script (PangoLanguage *language,
-				PangoScript    script)
+G_CONST_RETURN PangoScript *
+pango_language_get_scripts (PangoLanguage *language,
+			    int           *num_scripts)
 {
   PangoScriptForLang *script_for_lang;
   unsigned int j;
   const char *lang_str;
 
-#define REAL_SCRIPT(script) \
-  ((script) > PANGO_SCRIPT_INHERITED)
-
-  if (language == NULL || !REAL_SCRIPT (script))
-    return TRUE;
+  if (language == NULL)
+    goto NOT_FOUND;
 
   lang_str = pango_language_to_string (language);
 
@@ -482,7 +496,7 @@ pango_language_includes_script (PangoLanguage *language,
 			     sizeof (PangoScriptForLang),
 			     script_for_lang_compare);
   if (!script_for_lang)
-    return TRUE;
+    goto NOT_FOUND;
   else
     {
       gboolean found = FALSE;
@@ -508,16 +522,90 @@ pango_language_includes_script (PangoLanguage *language,
 	}
 
       if (!found)
-        return TRUE;
+        goto NOT_FOUND;
     }
 
-  for (j = 0; j < G_N_ELEMENTS (script_for_lang->scripts); j++)
-    if (script_for_lang->scripts[j] == script)
+  if (num_scripts)
+    {
+      for (j = 0; j < G_N_ELEMENTS (script_for_lang->scripts); j++)
+	if (script_for_lang->scripts[j] == 0)
+	  break;
+
+      g_assert (j > 0);
+
+      *num_scripts = j;
+    }
+
+  return script_for_lang->scripts;
+
+ NOT_FOUND:
+
+  if (num_scripts)
+    *num_scripts = 0;
+
+  return NULL;
+}
+
+/**
+ * pango_language_includes_script:
+ * @language: a #PangoLanguage, or %NULL
+ * @script: a #PangoScript
+ *
+ * Determines if @script is one of the scripts used to
+ * write @language. The returned value is conservative;
+ * if nothing is known about the language tag @language,
+ * %TRUE will be returned, since, as far as Pango knows,
+ * @script might be used to write @language.
+ *
+ * This routine is used in Pango's itemization process when
+ * determining if a supplied language tag is relevant to
+ * a particular section of text. It probably is not useful for
+ * applications in most circumstances.
+ *
+ * This function uses pango_language_get_scripts() internally.
+ *
+ * Return value: %TRUE if @script is one of the scripts used
+ * to write @language or if nothing is known about @language
+ * (including the case that @language is %NULL),
+ * %FALSE otherwise.
+ 
+ * Since: 1.4
+ **/
+gboolean
+pango_language_includes_script (PangoLanguage *language,
+				PangoScript    script)
+{
+  const PangoScript *scripts;
+  int num_scripts, j;
+
+/* copied from the one in pango-script.c */
+#define REAL_SCRIPT(script) \
+  ((script) > PANGO_SCRIPT_INHERITED && (script) != PANGO_SCRIPT_UNKNOWN)
+
+  if (!REAL_SCRIPT (script))
+    return TRUE;
+
+#undef REAL_SCRIPT
+
+  scripts = pango_language_get_scripts (language, &num_scripts);
+  if (!scripts)
+    return TRUE;
+
+  for (j = 0; j < num_scripts; j++)
+    if (scripts[j] == script)
       return TRUE;
 
   return FALSE;
 }
 
+
+
+
+/*
+ * From script to language
+ */
+
+
 static PangoLanguage **
 parse_default_languages (void)
 {
@@ -645,6 +733,8 @@ pango_script_get_sample_language (PangoScript script)
    * to include the script, so alternate orthographies
    * (Shavian for English, Osmanya for Somali, etc), typically
    * have no sample language
+   *
+   * XXX Add a test to check the above invariant.
    */
   static const char sample_languages[][4] = {
     "",    /* PANGO_SCRIPT_COMMON */
diff --git a/pango/pango-language.h b/pango/pango-language.h
index b807c4c0..37cdc164 100644
--- a/pango/pango-language.h
+++ b/pango/pango-language.h
@@ -35,6 +35,7 @@ GType          pango_language_get_type    (void) G_GNUC_CONST;
 PangoLanguage *pango_language_from_string (const char *language);
 
 G_CONST_RETURN char *pango_language_to_string   (PangoLanguage *language) G_GNUC_CONST;
+/* For back compat.  Will have to keep indefinitely. */
 #define pango_language_to_string(language) ((const char *)language)
 
 G_CONST_RETURN char *pango_language_get_sample_string (PangoLanguage *language) G_GNUC_CONST;
@@ -45,8 +46,10 @@ gboolean      pango_language_matches  (PangoLanguage *language,
 
 #include <pango/pango-script.h>
 
-gboolean       pango_language_includes_script   (PangoLanguage *language,
-						 PangoScript    script) G_GNUC_PURE;
+gboolean		    pango_language_includes_script (PangoLanguage *language,
+							    PangoScript    script) G_GNUC_PURE;
+G_CONST_RETURN PangoScript *pango_language_get_scripts	   (PangoLanguage *language,
+							    int           *num_scripts);
 
 G_END_DECLS
 
diff --git a/pango/pango-script.c b/pango/pango-script.c
index d147f1f1..862c8475 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -228,6 +228,7 @@ get_pair_index (gunichar ch)
   return -1;
 }
 
+/* duplicated in pango-language.c */
 #define REAL_SCRIPT(script) \
   ((script) > PANGO_SCRIPT_INHERITED && (script) != PANGO_SCRIPT_UNKNOWN)
 
diff --git a/pango/pango.def b/pango/pango.def
index 791af071..39ab42bc 100644
--- a/pango/pango.def
+++ b/pango/pango.def
@@ -219,6 +219,7 @@ EXPORTS
 	pango_language_from_string
 	pango_language_get_default
 	pango_language_get_sample_string
+	pango_language_get_scripts
 	pango_language_get_type
 	pango_language_includes_script
 	pango_language_matches