include/i18nlangtag/languagetag.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  */
   9
  10 #ifndef INCLUDED_I18NLANGTAG_LANGUAGETAG_HXX
  11 #define INCLUDED_I18NLANGTAG_LANGUAGETAG_HXX
  12
  13 #include <sal/config.h>
  14 #include <rtl/ustring.hxx>
  15 #include <com/sun/star/lang/Locale.hpp>
  16 #include <i18nlangtag/i18nlangtagdllapi.h>
  17 #include <i18nlangtag/lang.h>
  18
  19 #include <vector>
  20
  21 typedef struct _rtl_Locale rtl_Locale;  // as in rtl/locale.h
  22
  23
  24 /** Wrapper for liblangtag BCP 47 language tags, MS-LangIDs, locales and
  25     conversions in between.
  26
  27     Note that member variables are mutable and may change their values even in
  28     const methods. Getter methods return either the original value or matching
  29     converted values.
  30  */
  31 class I18NLANGTAG_DLLPUBLIC LanguageTag
  32 {
  33 public:
  34
  35     /** Init LanguageTag with existing BCP 47 language tag string.
  36
  37         @param bCanonicalize
  38             If TRUE, canonicalize tag and reparse, the resulting tag string may
  39             be different.
  40             IF FALSE, the tag is simply stored and can be retrieved with
  41             getBcp47().
  42
  43         Note that conversions to ISO codes, locales or LanguageType or
  44         obtaining language or script will canonicalize the tag string anyway,
  45         so specifying bCanonicalize=false is not a guarantee that the tag will
  46         stay identical to what was passed.
  47      */
  48     explicit LanguageTag( const OUString & rBcp47LanguageTag, bool bCanonicalize = false );
  49
  50     /** Init LanguageTag with Locale. */
  51     explicit LanguageTag( const com::sun::star::lang::Locale & rLocale );
  52
  53     /** Init LanguageTag with LanguageType MS-LangID. */
  54     explicit LanguageTag( LanguageType nLanguage );
  55
  56     /** Init LanguageTag with language and country strings.
  57
  58         This is a convenience ctor for places that so far use only language and
  59         country to replace the MsLangId::convert...IsoNames...() calls. Avoid
  60         use in new code.
  61      */
  62     explicit LanguageTag( const OUString& rLanguage, const OUString& rCountry );
  63
  64     /** Init LanguageTag with rtl_Locale.
  65
  66         This is a convenience ctor.
  67      */
  68     explicit LanguageTag( const rtl_Locale & rLocale );
  69
  70     LanguageTag( const LanguageTag & rLanguageTag );
  71     ~LanguageTag();
  72     LanguageTag& operator=( const LanguageTag & rLanguageTag );
  73
  74     /** Obtain BCP 47 language tag.
  75
  76         @param bResolveSystem
  77                If TRUE, resolve an empty language tag denoting the system
  78                locale to the real locale used.
  79                If FALSE, return an empty OUString for such a tag.
  80      */
  81     const OUString &                getBcp47( bool bResolveSystem = true ) const;
  82
  83     /** Obtain language tag as Locale.
  84
  85         As a convention, language tags that can not be expressed as "pure"
  86         com::sun::star::lang::Locale content using Language and Country fields
  87         store "qlt" (ISO 639 reserved for local use) in the Language field and
  88         the entire BCP 47 language tag in the Variant field. The Country field
  89         contains the corresponding ISO 3166 country code _if_ there is one, or
  90         otherwise is empty.
  91
  92         @param bResolveSystem
  93                If TRUE, resolve an empty language tag denoting the system
  94                locale to the real locale used.
  95                If FALSE, return an empty Locale for such a tag.
  96      */
  97     const com::sun::star::lang::Locale &    getLocale( bool bResolveSystem = true ) const;
  98
  99     /** Obtain mapping to MS-LangID.
 100
 101         @param bResolveSystem
 102                If TRUE, resolve an empty language tag denoting the system
 103                locale to the real locale used.
 104                If FALSE, return LANGUAGE_SYSTEM for such a tag.
 105      */
 106     LanguageType                    getLanguageType( bool bResolveSystem = true ) const;
 107
 108     /** Obtain ISO strings for language and country.
 109
 110         This is a convenience method for places that so far use only language and
 111         country to replace the MsLangId::convert...IsoNames...() calls. Avoid
 112         use in new code.
 113
 114         ATTENTION! May return empty strings if the language tag is not
 115         expressable in valid ISO codes!
 116
 117         @see isIsoLocale()
 118
 119         Always resolves an empty tag to the system locale.
 120      */
 121     void                            getIsoLanguageCountry( OUString& rLanguage, OUString& rCountry ) const;
 122
 123     /** Get ISO 639 language code, or BCP 47 language.
 124
 125         Always resolves an empty tag to the system locale.
 126      */
 127     OUString                        getLanguage() const;
 128
 129     /** Get ISO 15924 script code, if not the default script according to
 130         BCP 47. For default script an empty string is returned.
 131
 132         @see hasScript()
 133
 134         Always resolves an empty tag to the system locale.
 135      */
 136     OUString                        getScript() const;
 137
 138     /** Get combined language and script code, separated by '-' if
 139         non-default script, if default script only language.
 140
 141         @see hasScript()
 142
 143         Always resolves an empty tag to the system locale.
 144      */
 145     OUString                        getLanguageAndScript() const;
 146
 147     /** Get ISO 3166 country alpha code. Empty if the BCP 47 tags denote a
 148         region not expressable as 2 character country code.
 149
 150         Always resolves an empty tag to the system locale.
 151      */
 152     OUString                        getCountry() const;
 153
 154     /** Get BCP 47 region tag, which may be an ISO 3166 country alpha code or
 155         any other BCP 47 region tag.
 156
 157         Always resolves an empty tag to the system locale.
 158      */
 159     OUString                        getRegion() const;
 160
 161     /** Get a GLIBC locale string.
 162
 163         Always resolves an empty tag to the system locale.
 164
 165         @param  rEncoding
 166                 An encoding to be appended to language_country, for example
 167                 ".UTF-8" including the dot.
 168
 169         @return The resulting GLIBC locale string if it could be constructed,
 170                 if not an empty string is returned.
 171      */
 172     OUString                        getGlibcLocaleString( const OUString & rEncoding ) const;
 173
 174     /** If language tag has a non-default script specified.
 175      */
 176     bool                            hasScript() const;
 177
 178     /** If language tag is a locale that can be expressed using only ISO 639
 179         language codes and ISO 3166 country codes, thus is convertible to a
 180         conforming Locale struct without using extension mechanisms.
 181
 182         Note that an empty language tag or empty Locale::Language field or
 183         LanguageType LANGUAGE_SYSTEM could be treated as a valid ISO locale in
 184         some context, but here is not. If you want that ask for
 185         aTag.isSystemLocale() || aTag.isIsoLocale()
 186
 187         Always resolves an empty tag to the system locale.
 188      */
 189     bool                            isIsoLocale() const;
 190
 191     /** If language tag is a locale that can be expressed using only ISO 639
 192         language codes and ISO 15924 script codes and ISO 3166 country codes,
 193         thus can be stored in an ODF document using only fo:language, fo:script
 194         and fo:country attributes. If this is FALSE, the locale must be stored
 195         as a <*:rfc-language-tag> element.
 196
 197         Always resolves an empty tag to the system locale.
 198      */
 199     bool                            isIsoODF() const;
 200
 201     /** If this is a valid BCP 47 language tag.
 202
 203         Always resolves an empty tag to the system locale.
 204      */
 205     bool                            isValidBcp47() const;
 206
 207     /** If this tag was contructed as an empty tag denoting the system locale.
 208       */
 209     bool                            isSystemLocale() const;
 210
 211
 212     /** Reset with existing BCP 47 language tag string. See ctor. */
 213     void                            reset( const OUString & rBcp47LanguageTag, bool bCanonicalize = false );
 214
 215     /** Reset with Locale. */
 216     void                            reset( const com::sun::star::lang::Locale & rLocale );
 217
 218     /** Reset with LanguageType MS-LangID. */
 219     void                            reset( LanguageType nLanguage );
 220
 221     /** Reset with rtl_Locale. */
 222     void                            reset( const rtl_Locale & rLocale );
 223
 224
 225     /** Fall back to a known locale.
 226
 227         If the current tag does not represent a known (by us) locale, fall back
 228         to the most likely locale possible known.
 229         If the current tag is known, no change occurs.
 230      */
 231     LanguageTag &                   makeFallback();
 232
 233     /** Return a vector of fall-back strings.
 234
 235         In order:
 236         full BCP 47 tag, same as getBcp47()
 237         lll-Ssss-CC
 238         lll-Ssss
 239         lll-CC
 240         lll
 241
 242         Only strings that differ from a higher order are included, for example
 243         if there is no script the elements will be bcp47, lll-CC, lll; if the
 244         bcp47 string is identical to lll-CC then only lll-CC, lll.
 245
 246         Note that lll is only ISO 639-1/2 alpha code and CC is only ISO 3166
 247         alpha code. If the region can not be expressed as ISO 3166 then no -CC
 248         tags are included.
 249      */
 250     ::std::vector< OUString >       getFallbackStrings() const;
 251
 252
 253     /** @short  search for an equal or at least for a similar locale in a list
 254                 of possible ones.
 255
 256         @descr  First search for a locale that is equal to the reference
 257                 locale. (means: same BCP47 string)
 258
 259                 If the reference locale could not be located, check for
 260                 "similar" locales, in the same order as obtained by
 261                 getFallbackStrings().
 262
 263                 If no similar locale could be located, we search for a locale
 264                 "en-US" inside the given locale list.
 265
 266                 If "en-US" could not be located, we search for a locale "en"
 267                 inside the given list.
 268
 269                 If no "same" nor any "similar" locale could be found, we try
 270                 "x-default" and "x-no-translate" explicitly. Sometimes
 271                 variables don't use real localization. For example, in case the
 272                 localized value is a fix product name.
 273
 274                 If no locale matched until then, we use any other locale that
 275                 exists inside the set of given ones, namely the first
 276                 encountered!
 277
 278         @param  rList
 279                 the vector of possible locales as BCP47 strings.
 280
 281         @param  rReference
 282                 the reference locale, BCP47 string.
 283
 284         @return An iterator that points to the found element inside the given
 285                 locale list. If no matching locale could be found it points to
 286                 the end of the list.
 287      */
 288     static ::std::vector< OUString >::const_iterator getFallback( const ::std::vector< OUString > & rList,
 289                                                                   const OUString & rReference );
 290
 291
 292     /** Test equality of two LanguageTag, possibly resolving system locale.
 293
 294         @param bResolveSystem
 295                If TRUE, resolve empty language tags denoting the system
 296                locale to the real locale used before comparing.
 297                If FALSE, the behavior is identical to operator==(), system
 298                locales are not resolved first.
 299       */
 300     bool                            equals( const LanguageTag & rLanguageTag, bool bResolveSystem = false ) const;
 301
 302     /** Test equality of two LanguageTag.
 303
 304         Does NOT resolve system, i.e. if the system locale is en-US
 305         LanguageTag("")==LanguageTag("en-US") returns false! Use
 306         equals(...,true) instead if system locales shall be resolved.
 307      */
 308     bool    operator==( const LanguageTag & rLanguageTag ) const;
 309
 310     /** Test inequality of two LanguageTag.
 311
 312         Does NOT resolve system, i.e. if the system locale is en-US
 313         LanguageTag("")!=LanguageTag("en-US") returns true! Use
 314         !equals(,...true) instead if system locales shall be resolved.
 315      */
 316     bool    operator!=( const LanguageTag & rLanguageTag ) const;
 317
 318 private:
 319
 320     enum Decision
 321     {
 322         DECISION_DONTKNOW,
 323         DECISION_NO,
 324         DECISION_YES
 325     };
 326
 327     mutable com::sun::star::lang::Locale    maLocale;
 328     mutable OUString                        maBcp47;
 329     mutable OUString                        maCachedLanguage;   ///< cache getLanguage()
 330     mutable OUString                        maCachedScript;     ///< cache getScript()
 331     mutable OUString                        maCachedCountry;    ///< cache getCountry()
 332     mutable void*                           mpImplLangtag;      ///< actually lt_tag_t pointer, encapsulated
 333     mutable LanguageType                    mnLangID;
 334     mutable Decision                        meIsValid;
 335     mutable Decision                        meIsIsoLocale;
 336     mutable Decision                        meIsIsoODF;
 337     mutable Decision                        meIsLiblangtagNeeded;   ///< whether processing with liblangtag needed
 338             bool                            mbSystemLocale      : 1;
 339     mutable bool                            mbInitializedBcp47  : 1;
 340     mutable bool                            mbInitializedLocale : 1;
 341     mutable bool                            mbInitializedLangID : 1;
 342     mutable bool                            mbCachedLanguage    : 1;
 343     mutable bool                            mbCachedScript      : 1;
 344     mutable bool                            mbCachedCountry     : 1;
 345             bool                            mbIsFallback        : 1;
 346
 347     void    convertLocaleToBcp47();
 348     void    convertLocaleToLang();
 349     void    convertBcp47ToLocale();
 350     void    convertBcp47ToLang();
 351     void    convertLangToLocale();
 352     void    convertLangToBcp47();
 353
 354     void    convertFromRtlLocale();
 355
 356     bool    canonicalize();
 357
 358     OUString    getLanguageFromLangtag();
 359     OUString    getScriptFromLangtag();
 360     OUString    getRegionFromLangtag();
 361
 362     void            resetVars();
 363
 364     /** Obtain Language, Script and Country via simpleExtract() and assign them
 365         to the cached variables if successful.
 366
 367         @return return of simpleExtract()
 368      */
 369     bool            cacheSimpleLSC();
 370
 371     static bool     isIsoLanguage( const OUString& rLanguage );
 372     static bool     isIsoScript( const OUString& rScript );
 373     static bool     isIsoCountry( const OUString& rRegion );
 374
 375     enum Extraction
 376     {
 377         EXTRACTED_NONE,
 378         EXTRACTED_LSC,
 379         EXTRACTED_X,
 380         EXTRACTED_X_JOKER
 381     };
 382
 383     /** Of a simple language tag of the form lll[-Ssss][-CC] (i.e. one that
 384         would fulfill the isIsoODF() condition) extract the portions.
 385
 386         Does not check case or content!
 387
 388         @return EXTRACTED_LSC if simple tag was detected, EXTRACTED_X if x-...
 389         privateuse tag was detected, EXTRACTED_X_JOKER if "*" joker was
 390         detected, else EXTRACTED_NONE.
 391      */
 392     static Extraction   simpleExtract( const OUString& rBcp47,
 393                                        OUString& rLanguage,
 394                                        OUString& rScript,
 395                                        OUString& rCountry );
 396
 397 };
 398
 399 #endif  // INCLUDED_I18NLANGTAG_LANGUAGETAG_HXX
 400
 401 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */