intl/locale/MozLocale.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode:nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef mozilla_intl_MozLocale_h__
   7 #define mozilla_intl_MozLocale_h__
   8
   9 #include "nsString.h"
  10 #include "nsTArray.h"
  11
  12 namespace mozilla {
  13 namespace intl {
  14
  15 /**
  16  * Locale class is a core representation of a single locale.
  17  *
  18  * A locale is a data object representing a combination of language, script,
  19  * region, variant and a set of regional extension preferences that may further specify
  20  * particular user choices like calendar, numbering system, etc.
  21  *
  22  * A locale can be expressed as a language tag string, like a simple "fr" for French,
  23  * or a more specific "sr-Cyrl-RS-u-hc-h12" for Serbian in Russia with a Cyrylic script,
  24  * and hour cycle selected to be `h12`.
  25  *
  26  * The format of the language tag follows BCP47 standard and implements a subset of it.
  27  * In the future we expect to extend this class to cover more subtags and extensions.
  28  *
  29  * BCP47: https://tools.ietf.org/html/bcp47
  30  *
  31  * The aim of this class it aid in validation, parsing and canonicalization of the
  32  * string.
  33  *
  34  * It allows the user to input any well-formed BCP47 language tag and operate
  35  * on its subtags in a canonicalized form.
  36  *
  37  * It should be used for all operations on language tags, and together with
  38  * LocaleService::NegotiateLanguages for language negotiation.
  39  *
  40  * Example:
  41  *
  42  *     Locale loc = Locale("de-at");
  43  *
  44  *     ASSERT_TRUE(loc.GetLanguage().Equals("de"));
  45  *     ASSERT_TRUE(loc.GetScript().IsEmpty());
  46  *     ASSERT_TRUE(loc.GetRegion().Equals("AT")); // canonicalized to upper case
  47  *
  48  *
  49  * Note: The file name is `MozLocale` to avoid compilation problems on case-insensitive
  50  * Windows. The class name is `Locale`.
  51  */
  52 class Locale {
  53   public:
  54     explicit Locale(const nsACString& aLocale);
  55     explicit Locale(const char* aLocale)
  56       : Locale(nsDependentCString(aLocale))
  57       { };
  58
  59     const nsACString& GetLanguage() const;
  60     const nsACString& GetScript() const;
  61     const nsACString& GetRegion() const;
  62     const nsTArray<nsCString>& GetVariants() const;
  63
  64     bool IsValid() const {
  65       return mIsValid;
  66     }
  67
  68     const nsCString AsString() const;
  69
  70     bool Matches(const Locale& aOther, bool aThisRange, bool aOtherRange) const;
  71     bool AddLikelySubtags();
  72     void ClearVariants();
  73     void ClearRegion();
  74
  75     // Mark the object as invalid, meaning we shouldn't use it any more.
  76     void Invalidate() {
  77       mIsValid = false;
  78     }
  79
  80     bool operator== (const Locale& aOther) {
  81       // Note: invalid Locale objects are never treated as equal to anything
  82       // (even other invalid ones).
  83       return IsValid() &&
  84              aOther.IsValid() &&
  85              mLanguage.Equals(aOther.mLanguage) &&
  86              mScript.Equals(aOther.mScript) &&
  87              mRegion.Equals(aOther.mRegion) &&
  88              mVariants == aOther.mVariants &&
  89              mPrivateUse == aOther.mPrivateUse;
  90     }
  91
  92   private:
  93     nsAutoCStringN<3> mLanguage;
  94     nsAutoCStringN<4> mScript;
  95     nsAutoCStringN<2> mRegion;
  96     nsTArray<nsCString> mVariants;
  97     nsTArray<nsCString> mPrivateUse;
  98     bool mIsValid = true;
  99 };
 100
 101 } // intl
 102 } // namespace mozilla
 103
 104 DECLARE_USE_COPY_CONSTRUCTORS(mozilla::intl::Locale)
 105
 106 #endif /* mozilla_intl_MozLocale_h__ */