tag: add function to check whether a string is a valid language code

API: gst_tag_check_language_code()

5 files changed, 38 insertions, 4 deletions

diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt
index 3f60d565e..5640d2173 100644
--- a/docs/libs/gst-plugins-base-libs-sections.txt
+++ b/docs/libs/gst-plugins-base-libs-sections.txt
@@ -1971,6 +1971,7 @@ gst_tag_get_language_code
 gst_tag_get_language_code_iso_639_1
 gst_tag_get_language_code_iso_639_2B
 gst_tag_get_language_code_iso_639_2T
+gst_tag_check_language_code
 </SECTION>
 
 <SECTION>
diff --git a/gst-libs/gst/tag/lang.c b/gst-libs/gst/tag/lang.c
index a0838fe1e..c37366e08 100644
--- a/gst-libs/gst/tag/lang.c
+++ b/gst-libs/gst/tag/lang.c
@@ -30,8 +30,6 @@
  * </refsect2>
  */
 
-/* FIXME 0.11: maybe switch to ISO-639-2 everywhere incl. GST_TAG_LANGUAGE? */
-
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -311,8 +309,8 @@ gst_tag_get_language_codes (void)
  * gst_tag_get_language_name:
  * @language_code: two or three-letter ISO-639 language code
  *
- * Returns the name of the language given an ISO-639 language code, such
- * as often found in a GST_TAG_LANGUAGE tag. The name will be translated
+ * Returns the name of the language given an ISO-639 language code as
+ * found in a GST_TAG_LANGUAGE_CODE tag. The name will be translated
  * according to the current locale (if the library was built against the
  * iso-codes package, otherwise the English name will be returned).
  *
@@ -492,3 +490,25 @@ gst_tag_get_language_code_iso_639_2B (const gchar * lang_code)
 
   return c;
 }
+
+/**
+ * gst_tag_check_language_code:
+ * @lang_code: ISO-639 language code (e.g. "deu" or "ger" or "de")
+ *
+ * Check if a given string contains a known ISO 639 language code.
+ *
+ * This is useful in situations where it's not clear whether a given
+ * string is a language code (which should be put into a #GST_TAG_LANGUAGE_CODE
+ * tag) or a free-form language name descriptor (which should be put into a
+ * #GST_TAG_LANGUAGE_NAME tag instead).
+ *
+ * Returns: TRUE if the two- or three-letter language code in @lang_code
+ *     is a valid ISO-639 language code.
+ *
+ * Since: 0.10.37
+ */
+gboolean
+gst_tag_check_language_code (const gchar * lang_code)
+{
+  return (gst_tag_get_language_code_iso_639_1 (lang_code) != NULL);
+}
diff --git a/gst-libs/gst/tag/tag.h b/gst-libs/gst/tag/tag.h
index 057378c2e..074f81e3b 100644
--- a/gst-libs/gst/tag/tag.h
+++ b/gst-libs/gst/tag/tag.h
@@ -551,6 +551,8 @@ const gchar *  gst_tag_get_language_code_iso_639_2B (const gchar * lang_code);
 
 const gchar *  gst_tag_get_language_code_iso_639_2T (const gchar * lang_code);
 
+gboolean       gst_tag_check_language_code          (const gchar * lang_code);
+
 /**
  * gst_tag_get_language_code:
  * @lang_code: ISO-639 language code (e.g. "deu" or "ger" or "de")
diff --git a/tests/check/libs/tag.c b/tests/check/libs/tag.c
index 634cc3fe4..58748e007 100644
--- a/tests/check/libs/tag.c
+++ b/tests/check/libs/tag.c
@@ -748,6 +748,16 @@ GST_START_TEST (test_language_utils)
   ASSERT_STRINGS_EQUAL (gst_tag_get_language_code_iso_639_2B ("de"), "ger");
   ASSERT_STRINGS_EQUAL (gst_tag_get_language_code_iso_639_2B ("deu"), "ger");
   ASSERT_STRINGS_EQUAL (gst_tag_get_language_code_iso_639_2B ("ger"), "ger");
+
+  fail_unless (gst_tag_check_language_code ("de"));
+  fail_unless (gst_tag_check_language_code ("deu"));
+  fail_unless (gst_tag_check_language_code ("ger"));
+  fail_if (gst_tag_check_language_code ("xxx"));
+  fail_if (gst_tag_check_language_code ("und"));
+  fail_if (gst_tag_check_language_code ("un"));
+  fail_if (gst_tag_check_language_code (""));
+  fail_if (gst_tag_check_language_code ("\377"));
+  fail_if (gst_tag_check_language_code ("deutsch"));
 }
 
 GST_END_TEST;
diff --git a/win32/common/libgsttag.def b/win32/common/libgsttag.def
index 8fa522c52..4af90e3ee 100644
--- a/win32/common/libgsttag.def
+++ b/win32/common/libgsttag.def
@@ -1,4 +1,5 @@
 EXPORTS
+	gst_tag_check_language_code
 	gst_tag_demux_get_type
 	gst_tag_demux_result_get_type
 	gst_tag_freeform_string_to_utf8