xbmc/utils/Locale.h

   1 /*
   2  *  Copyright (C) 2015-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include <set>
  12 #include <string>
  13 #include <unordered_map>
  14
  15 /*!
  16  \brief Class representing a full locale of the form `[language[_territory][.codeset][@modifier]]`.
  17  */
  18 class CLocale
  19 {
  20 public:
  21   CLocale();
  22   explicit CLocale(const std::string& language);
  23   CLocale(const std::string& language, const std::string& territory);
  24   CLocale(const std::string& language, const std::string& territory, const std::string& codeset);
  25   CLocale(const std::string& language, const std::string& territory, const std::string& codeset, const std::string& modifier);
  26   ~CLocale();
  27
  28   /*!
  29    \brief Empty (and invalid) CLocale instance.
  30    */
  31   static const CLocale Empty;
  32
  33   /*!
  34    \brief Parses the given string representation and turns it into a locale.
  35
  36    \param locale String representation of a locale
  37    */
  38   static CLocale FromString(const std::string& locale);
  39
  40   bool operator==(const CLocale& other) const;
  41   inline bool operator!=(const CLocale& other) const { return !(*this == other); }
  42
  43   /*!
  44    \brief Whether the locale is valid or not.
  45
  46    \details A locale is considered valid if at least the language code is set.
  47    */
  48   bool IsValid() const { return m_valid; }
  49
  50   /*!
  51    \brief Returns the (lower-case) ISO 639-1 language code of the locale.
  52    */
  53   const std::string& GetLanguageCode() const { return m_language; }
  54   /*!
  55    \brief Returns the (upper-case) ISO 3166-1 Alpha-2 territory code of the locale.
  56    */
  57   const std::string& GetTerritoryCode() const { return m_territory; }
  58   /*!
  59    \brief Returns the codeset of the locale.
  60    */
  61   const std::string& GetCodeset() const { return m_codeset; }
  62   /*!
  63    \brief Returns the modifier of the locale.
  64    */
  65   const std::string& GetModifier() const { return m_modifier; }
  66
  67   /*!
  68    \brief Returns the full string representation of the locale.
  69
  70    \details The format of the string representation is
  71    `[language[_territory][.codeset][@modifier]]` where the language is
  72    represented as a (lower-case) two character ISO 639-1 code and the territory
  73    is represented as a (upper-case) two character ISO 3166-1 Alpha-2 code.
  74    */
  75   std::string ToString() const;
  76   /*!
  77    \brief Returns the full string representation of the locale in lowercase.
  78
  79    \details The format of the string representation is
  80    `language[_territory][.codeset][@modifier]]` where the language is
  81    represented as a two character ISO 639-1 code and the territory is
  82    represented as a two character ISO 3166-1 Alpha-2 code.
  83    */
  84   std::string ToStringLC() const;
  85   /*!
  86    \brief Returns the short string representation of the locale.
  87
  88    \details The format of the short string representation is
  89    `[language[_territory]` where the language is represented as a (lower-case)
  90    two character ISO 639-1 code and the territory is represented as a
  91    (upper-case) two character ISO 3166-1 Alpha-2 code.
  92    */
  93   std::string ToShortString() const;
  94   /*!
  95    \brief Returns the short string representation of the locale in lowercase.
  96
  97    \details The format of the short string representation is
  98    `[language[_territory]` where the language is represented as a two character
  99    ISO 639-1 code and the territory is represented as a two character
 100    ISO 3166-1 Alpha-2 code.
 101    */
 102   std::string ToShortStringLC() const;
 103
 104   /*!
 105    \brief Checks if the given string representation of a locale exactly matches
 106           the locale.
 107
 108    \param locale String representation of a locale
 109    \return True if the string representation matches the locale, false otherwise.
 110    */
 111   bool Equals(const std::string& locale) const;
 112
 113   /*!
 114    \brief Checks if the given string representation of a locale partly matches
 115           the locale.
 116
 117    \details Partial matching means that every available locale part needs to
 118    match the same locale part of the other locale if present.
 119
 120    \param locale String representation of a locale
 121    \return True if the string representation matches the locale, false otherwise.
 122   */
 123   bool Matches(const std::string& locale) const;
 124
 125   /*!
 126   \brief Tries to find the locale in the given list that matches this locale
 127          best.
 128
 129   \param locales List of string representations of locales
 130   \return Best matching locale from the given list or empty string.
 131   */
 132   std::string FindBestMatch(const std::set<std::string>& locales) const;
 133
 134   /*!
 135   \brief Tries to find the locale in the given list that matches this locale
 136          best.
 137
 138   \param locales Map list of string representations of locales with first as
 139                  locale identifier
 140   \return Best matching locale from the given list or empty string.
 141
 142   \remark Used from \ref CAddonInfo::GetTranslatedText to prevent copy from map
 143           to set.
 144   */
 145   std::string FindBestMatch(const std::unordered_map<std::string, std::string>& locales) const;
 146
 147 private:
 148   static bool CheckValidity(const std::string& language, const std::string& territory, const std::string& codeset, const std::string& modifier);
 149   static bool ParseLocale(const std::string &locale, std::string &language, std::string &territory, std::string &codeset, std::string &modifier);
 150
 151   void Initialize();
 152
 153   int GetMatchRank(const std::string& locale) const;
 154
 155   bool m_valid = false;
 156   std::string m_language;
 157   std::string m_territory;
 158   std::string m_codeset;
 159   std::string m_modifier;
 160 };
 161