Bug 1438687 - Document mozilla::intl::Locale. r=jfkthame,Pike
authorZibi Braniecki <zbraniecki@mozilla.com>
Thu, 26 Apr 2018 14:18:08 -0700
changeset 801194 56bf1eeea50a4dfb26864fc983ef32ea410d1147
parent 801193 09582e9a65939bc59f99596053575af85160db08
child 801195 38922a89e9d5d957a95e4344a369a5ef345c5a1c
push id111603
push usermozilla@kaply.com
push dateTue, 29 May 2018 22:12:07 +0000
reviewersjfkthame, Pike
bugs1438687
milestone62.0a1
Bug 1438687 - Document mozilla::intl::Locale. r=jfkthame,Pike MozReview-Commit-ID: BzGKIfzR63
intl/locale/MozLocale.h
intl/locale/tests/gtest/TestLocaleService.cpp
intl/locale/tests/gtest/TestMozLocale.cpp
--- a/intl/locale/MozLocale.h
+++ b/intl/locale/MozLocale.h
@@ -46,42 +46,100 @@ namespace intl {
  *     ASSERT_TRUE(loc.GetRegion().Equals("AT")); // canonicalized to upper case
  *
  *
  * Note: The file name is `MozLocale` to avoid compilation problems on case-insensitive
  * Windows. The class name is `Locale`.
  */
 class Locale {
   public:
+    /**
+     * The constructor expects the input to be a well-formed BCP47-style locale string.
+     *
+     * Two operations are performed on the well-formed language tags:
+     *
+     *  * Case normalization to conform with BCP47 (e.g. "eN-uS" -> "en-US")
+     *  * Underscore delimiters replaced with dashed (e.g. "en_US" -> "en-US")
+     *
+     * If the input language tag string is not well-formed, the Locale will be
+     * created with its flag `mValid` set to false which will make the Locale never match.
+     */
     explicit Locale(const nsACString& aLocale);
     explicit Locale(const char* aLocale)
       : Locale(nsDependentCString(aLocale))
       { };
 
     const nsACString& GetLanguage() const;
     const nsACString& GetScript() const;
     const nsACString& GetRegion() const;
     const nsTArray<nsCString>& GetVariants() const;
 
+    /**
+     * Returns a `true` if the locale is well-formed, such that the
+     * Locale object can validly be matched against others.
+     */
     bool IsValid() const {
       return mIsValid;
     }
 
+    /**
+     * Returns a canonicalized language tag string of the locale.
+     */
     const nsCString AsString() const;
 
+    /**
+     * Compares two locales optionally treating one or both of
+     * the locales as a range.
+     *
+     * In case one of the locales is treated as a range, its
+     * empty fields are considered to match all possible
+     * values of the same field on the other locale.
+     *
+     * Example:
+     *
+     * Locale("en").Matches(Locale("en-US"), false, false) // false
+     * Locale("en").Matches(Locale("en-US"), true, false)  // true
+     *
+     * The latter returns true because the region field on the "en"
+     * locale is being treated as a range and matches any region field
+     * value including "US" of the other locale.
+     */
     bool Matches(const Locale& aOther, bool aThisRange, bool aOtherRange) const;
+
+    /**
+     * This operation uses CLDR data to build a more specific version
+     * of a generic locale.
+     *
+     * Example:
+     *
+     * Locale("en").AddLikelySubtags().AsString(); // "en-Latn-US"
+     */
     bool AddLikelySubtags();
+
+    /**
+     * Clears the variants field of the Locale object.
+     */
     void ClearVariants();
+
+    /**
+     * Clears the region field of the Locale object.
+     */
     void ClearRegion();
 
-    // Mark the object as invalid, meaning we shouldn't use it any more.
+    /**
+     * Marks the locale as invalid which in turns makes
+     * it to be skipped by most LocaleService operations.
+     */
     void Invalidate() {
       mIsValid = false;
     }
 
+    /**
+     * Compares two locales expecting all fields to match each other.
+     */
     bool operator== (const Locale& aOther) {
       // Note: invalid Locale objects are never treated as equal to anything
       // (even other invalid ones).
       return IsValid() &&
              aOther.IsValid() &&
              mLanguage.Equals(aOther.mLanguage) &&
              mScript.Equals(aOther.mScript) &&
              mRegion.Equals(aOther.mRegion) &&
--- a/intl/locale/tests/gtest/TestLocaleService.cpp
+++ b/intl/locale/tests/gtest/TestLocaleService.cpp
@@ -6,16 +6,22 @@
 #include "gtest/gtest.h"
 #include "mozilla/intl/LocaleService.h"
 #include "mozilla/intl/MozLocale.h"
 #include "mozilla/Services.h"
 #include "nsIToolkitChromeRegistry.h"
 
 using namespace mozilla::intl;
 
+TEST(Intl_Locale_LocaleService, GetAppLocalesAsBCP47) {
+  nsTArray<nsCString> appLocales;
+  LocaleService::GetInstance()->GetAppLocalesAsBCP47(appLocales);
+
+  ASSERT_FALSE(appLocales.IsEmpty());
+}
 
 TEST(Intl_Locale_LocaleService, GetAppLocalesAsLangTags) {
   nsTArray<nsCString> appLocales;
   LocaleService::GetInstance()->GetAppLocalesAsLangTags(appLocales);
 
   ASSERT_FALSE(appLocales.IsEmpty());
 }
 
@@ -35,17 +41,16 @@ TEST(Intl_Locale_LocaleService, GetAppLo
   LocaleService::GetInstance()->GetAppLocalesAsLangTags(appLocales);
 
   nsAutoCString locale;
   LocaleService::GetInstance()->GetAppLocaleAsLangTag(locale);
 
   ASSERT_TRUE(appLocales[0] == locale);
 }
 
-
 TEST(Intl_Locale_LocaleService, GetRegionalPrefsLocales) {
   nsTArray<nsCString> rpLocales;
   LocaleService::GetInstance()->GetRegionalPrefsLocales(rpLocales);
 
   int32_t len = rpLocales.Length();
   ASSERT_TRUE(len > 0);
 }
 
--- a/intl/locale/tests/gtest/TestMozLocale.cpp
+++ b/intl/locale/tests/gtest/TestMozLocale.cpp
@@ -93,8 +93,28 @@ TEST(Intl_Locale_Locale, PrivateUse) {
 
   // Make sure that we canonicalize private use tags
   // and preserve their order.
   Locale loc3 = Locale("fr-x-foo-bAr-BaZ");
 
   ASSERT_TRUE(loc3.IsValid());
   ASSERT_TRUE(loc3.AsString().Equals("fr-x-foo-bar-baz"));
 }
+
+TEST(Intl_Locale_Locale, InvalidLocale) {
+  Locale loc = Locale("en-verylongsubtag");
+  ASSERT_FALSE(loc.IsValid());
+
+  Locale loc2 = Locale("p-te");
+  ASSERT_FALSE(loc2.IsValid());
+}
+
+TEST(Intl_Locale_Locale, ClearRegion) {
+  Locale loc = Locale("en-US");
+  loc.ClearRegion();
+  ASSERT_TRUE(loc.AsString().Equals("en"));
+}
+
+TEST(Intl_Locale_Locale, ClearVariants) {
+  Locale loc = Locale("en-US-mac");
+  loc.ClearVariants();
+  ASSERT_TRUE(loc.AsString().Equals("en-US"));
+}