1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef _COMPHELPER_LOCALE_HXX_ 25 #define _COMPHELPER_LOCALE_HXX_ 26 27 //_______________________________________________ 28 // includes 29 30 #include <vector> 31 #include <rtl/ustring.hxx> 32 #include "comphelper/comphelperdllapi.h" 33 34 // These are specified by i386 ABI suppl. but 35 // only affect Solaris i386/illumos so far. 36 37 #if !defined(_XPG4_2) || defined(__EXTENSIONS__) 38 #undef CS 39 #undef ES 40 #endif 41 42 //_______________________________________________ 43 // namespace 44 45 namespace comphelper{ 46 47 //_______________________________________________ 48 // definitions 49 50 /** @short A Locale object represents a specific geographical, political, or cultural region. 51 52 @descr This Locale class can be used to: 53 - provide the different parts of a Locale (Language, Country, Variant) 54 - converting it from/to ISO formatted string values (like e.g. "en-US") 55 - provide some predefined (static) Locale objects 56 */ 57 class COMPHELPER_DLLPUBLIC Locale 58 { 59 //------------------------------------------- 60 // const 61 62 public: 63 64 /** @short separates LANGUAGE and COUNTRY part of an ISO formatted Locale. */ 65 static const sal_Unicode SEPERATOR_LC; 66 67 /** @short separates COUNTRY and VARIANT part of an ISO formatted Locale. */ 68 static const sal_Unicode SEPERATOR_CV; 69 70 /** @short separates COUNTRY and VARIANT part of an ISO formatted Locale. 71 @descr Its true for some linux derivatives only :-( */ 72 static const sal_Unicode SEPERATOR_CV_LINUX; 73 74 /** @short some predefined Locale objects. */ 75 static const Locale& EN_US(); 76 static const Locale& EN(); 77 static const Locale& DE_DE(); 78 static const Locale& DE_CH(); 79 static const Locale& DE_AT(); 80 static const Locale& AR(); 81 static const Locale& CA(); 82 static const Locale& CS(); 83 static const Locale& DA(); 84 static const Locale& EL(); 85 static const Locale& ES(); 86 static const Locale& FI(); 87 static const Locale& FR(); 88 static const Locale& HE(); 89 static const Locale& HI_IN(); 90 static const Locale& HU(); 91 static const Locale& IT(); 92 static const Locale& JA(); 93 static const Locale& KO(); 94 static const Locale& NL(); 95 static const Locale& PL(); 96 static const Locale& PT(); 97 static const Locale& PT_BR(); 98 static const Locale& RU(); 99 static const Locale& SK(); 100 static const Locale& SL(); 101 static const Locale& SV(); 102 static const Locale& TH(); 103 static const Locale& TR(); 104 static const Locale& X_DEFAULT(); 105 static const Locale& X_COMMENT(); 106 static const Locale& X_TRANSLATE(); 107 static const Locale& X_NOTRANSLATE(); 108 static const Locale& ZH_CN(); 109 static const Locale& ZH_TW(); 110 111 //------------------------------------------- 112 // types 113 114 public: 115 116 /** @short will be throw during conversion, if a Locale can't be interpreted. */ 117 struct MalFormedLocaleException 118 { 119 public: 120 ::rtl::OUString Message; 121 MalFormedLocaleExceptioncomphelper::Locale::MalFormedLocaleException122 MalFormedLocaleException() 123 {} 124 MalFormedLocaleExceptioncomphelper::Locale::MalFormedLocaleException125 MalFormedLocaleException(const ::rtl::OUString& sMessage) 126 : Message(sMessage) 127 {} 128 }; 129 130 //------------------------------------------- 131 // member 132 133 private : 134 135 //--------------------------------------- 136 /** @short must be a valid ISO Language Code. 137 138 @descr These codes are the lower-case two-letter codes as defined by ISO-639. 139 You can find a full list of these codes at a number of sites, such as: 140 <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"> 141 http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</a> 142 */ 143 ::rtl::OUString m_sLanguage; 144 145 //--------------------------------------- 146 /** @short must be a valid ISO Country Code. 147 @descr These codes are the upper-case two-letter codes as defined by ISO-3166. 148 You can find a full list of these codes at a number of sites, such as: 149 <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html"> 150 http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</a> 151 */ 152 ::rtl::OUString m_sCountry; 153 154 //--------------------------------------- 155 /** @short Variant codes are vendor and browser-specific. 156 @descr For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. 157 Where there are two variants, separate them with an underscore, and 158 put the most important one first. For example, a Traditional Spanish collation 159 might be referenced, with "ES", "ES", "Traditional_WIN". 160 */ 161 ::rtl::OUString m_sVariant; 162 163 //------------------------------------------- 164 // interface 165 166 public : 167 168 //--------------------------------------- 169 /** @short needed by outside users! 170 171 @descr Otherwise it wouldn't be possible to use 172 any instance of such Locale static ... 173 */ 174 Locale(); 175 176 //--------------------------------------- 177 /** @short construct a Locale from an ISO formatted string value. 178 179 @seealso fromISO() 180 181 @param sISO 182 an ISO formatted string value, which can be parsed and 183 tokenized into a Language, Country and Variant part. 184 185 @throw MalFormedLocaleException 186 if conversion failed. 187 */ 188 Locale(const ::rtl::OUString& sISO); 189 190 //--------------------------------------- 191 /** @short construct a Locale from language, country and variant. 192 193 @seealso setLanguage() 194 @seealso setCountry() 195 @seealso setVariant() 196 197 @param sLanguage 198 lowercase two-letter ISO-639 code. 199 200 @param sCountry 201 uppercase two-letter ISO-3166 code. 202 203 @param sVariant 204 vendor and browser specific code. 205 */ 206 Locale(const ::rtl::OUString& sLanguage , 207 const ::rtl::OUString& sCountry , 208 const ::rtl::OUString& sVariant = ::rtl::OUString()); 209 210 //--------------------------------------- 211 /** @short copy constructor. 212 213 @param aCopy 214 the copy object. 215 */ 216 Locale(const Locale& aCopy); 217 218 //--------------------------------------- 219 /** @short returns the language code for this locale. 220 221 @descr That will either be the empty string or 222 a lowercase ISO 639 code. 223 224 @return [string] 225 the language code. 226 */ 227 ::rtl::OUString getLanguage() const; 228 229 //--------------------------------------- 230 /** @short returns the country/region code for this locale. 231 232 @descr That will either be the empty string or an 233 uppercase ISO 3166 2-letter code. 234 235 @return [string] 236 the country code. 237 */ 238 ::rtl::OUString getCountry() const; 239 240 //--------------------------------------- 241 /** @short returns the variant code for this locale. 242 243 @return [string] 244 the variant code. 245 */ 246 ::rtl::OUString getVariant() const; 247 248 //--------------------------------------- 249 /** @short set the new language code for this locale. 250 251 @descr That will either be the empty string or 252 a lowercase ISO 639 code. 253 254 @param sLanguage 255 the language code. 256 */ 257 void setLanguage(const ::rtl::OUString& sLanguage); 258 259 //--------------------------------------- 260 /** @short set the new country/region code for this locale. 261 262 @descr That will either be the empty string or an 263 uppercase ISO 3166 2-letter code. 264 265 @param sCountry 266 the country code. 267 */ 268 void setCountry(const ::rtl::OUString& sCountry); 269 270 //--------------------------------------- 271 /** @short set the new variant code for this locale. 272 273 @param sVariant 274 the variant code. 275 */ 276 void setVariant(const ::rtl::OUString& sVariant); 277 278 //--------------------------------------- 279 /** @short take over new Locale informations. 280 281 @seealso Locale(const ::rtl::OUString& sISO) 282 283 @param sISO 284 an ISO formatted string value, which can be parsed and 285 tokenized into a Language, Country and Variant part. 286 e.g. "en-US" or "en-US_WIN" 287 288 @throw MalFormedLocaleException 289 if conversion failed. 290 */ 291 void fromISO(const ::rtl::OUString& sISO); 292 293 //--------------------------------------- 294 /** @short converts this Locale to an ISO formatted string value. 295 296 @descr The different parts of this Locale will be assembled 297 e.g. to "en-US" or "en-US_WIN" 298 299 @return [string] 300 the ISO formatted string. 301 */ 302 ::rtl::OUString toISO() const; 303 304 //--------------------------------------- 305 /** @short check, if two Locale objects are equals. 306 307 @descr All parts of a Locale (means Language, Country and Variant) 308 will be checked. 309 310 @param aComparable 311 the Locale object for compare. 312 313 @return [boolean] 314 TRUE if both objects uses the same values for 315 Language, Country and Variant. 316 */ 317 sal_Bool equals(const Locale& aComparable) const; 318 319 //--------------------------------------- 320 /** @short check, if two Locale objects 321 uses the same language. 322 323 @descr The Country and Variant parts of a Locale 324 won't be checked here. 325 326 @return [boolean] 327 TRUE if both objects uses the same 328 Language value. 329 */ 330 sal_Bool similar(const Locale& aComparable) const; 331 332 //--------------------------------------- 333 /** @short search for an equal or at least for a similar 334 Locale in a list of possible ones. 335 336 @descr First it searches for a Locale, which is equals 337 to the reference Locale. 338 (means: same Language, Country, Variant) 339 340 If the reference Locale couldn't be located, it will be 341 tried again - but we are checking for "similar" Locales then. 342 (means: same Language) 343 344 If no similar Locale could be located, we search 345 for a Locale "en-US" inside the given Locale list. 346 347 If "en-US" could not be located, we search for 348 a Locale "en" inside the given list. 349 350 If no "same" nor any "similar" locale could be found, 351 we try "x-default" and "x-notranslate" explicitly. 352 Sometimes localized variables are optimized and don't use 353 localization really. E.g. in case the localized value is a fix 354 product name. 355 356 If no locale match till now, we use any other existing 357 locale, which exists inside the set of given ones! 358 359 @seealso equals() 360 @seealso similar() 361 362 @param lISOList 363 the list of possible Locales 364 (as formatted ISO strings). 365 366 @param sReferenceISO 367 the reference Locale, which should be searched 368 if it's equal or similar to any Locale inside 369 the provided Locale list. 370 371 @return An iterator, which points to the found element 372 inside the given Locale list. 373 If no matching Locale could be found, it points 374 to the end of the list. 375 376 @throw [MalFormedLocaleException] 377 if at least one ISO formatted string couldn't 378 be converted to a valid Locale Object. 379 */ 380 static ::std::vector< ::rtl::OUString >::const_iterator getFallback(const ::std::vector< ::rtl::OUString >& lISOList , 381 const ::rtl::OUString& sReferenceISO); 382 383 //--------------------------------------- 384 /** @short search for the next possible fallback locale. 385 386 @descr Instead of getFallback(vector<>, string) this method 387 uses the given locale and decide by using an algorithm 388 which locale can be the next possible one. 389 390 Algorithm: 391 - if locale has country return language only 392 - if locale different "en-US" return "en-US" 393 - if locale "en-US" return "en" 394 395 @param aLocale [in/out]! 396 the incoming value will be used to start 397 search for a possible fallback ... 398 and in case such fallback was found this parameter 399 will be used for return too. 400 401 @return TRUE if the parameter aLocale contains a new fallback value; 402 FALSE otherwise. 403 */ 404 static sal_Bool getFallback(Locale& aLocale); 405 406 //--------------------------------------- 407 /** @short assign elements of another locale 408 to this instance. 409 410 @param rCopy 411 another locale object. 412 */ 413 void operator=(const Locale& rCopy); 414 415 //--------------------------------------- 416 /** @short check if two Locale objects are equals. 417 418 @seealso equals() 419 420 @param aComparable 421 the Locale object for compare. 422 423 @return [boolean] 424 TRUE if both objects uses the same values for 425 Language, Country and Variant. 426 */ 427 sal_Bool operator==(const Locale& aComparable) const; 428 429 //--------------------------------------- 430 /** @short check if two Locale objects are different. 431 432 @param aComparable 433 the Locale object for compare. 434 435 @return [boolean] 436 TRUE if at least one part of such Locale 437 isn't the same. 438 */ 439 sal_Bool operator!=(const Locale& aComparable) const; 440 }; 441 442 } // namespace salhelper 443 444 #endif // _COMPHELPER_LOCALE_HXX_ 445