Bug 1438687 - Document mozilla::intl::Locale. r?jfkthame
MozReview-Commit-ID: BzGKIfzR63
--- 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"));
+}