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