1565d668cSAndrew Rist /************************************************************** 2cdf0e10cSrcweir * 3565d668cSAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 4565d668cSAndrew Rist * or more contributor license agreements. See the NOTICE file 5565d668cSAndrew Rist * distributed with this work for additional information 6565d668cSAndrew Rist * regarding copyright ownership. The ASF licenses this file 7565d668cSAndrew Rist * to you under the Apache License, Version 2.0 (the 8565d668cSAndrew Rist * "License"); you may not use this file except in compliance 9565d668cSAndrew Rist * with the License. You may obtain a copy of the License at 10565d668cSAndrew Rist * 11565d668cSAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 12565d668cSAndrew Rist * 13565d668cSAndrew Rist * Unless required by applicable law or agreed to in writing, 14565d668cSAndrew Rist * software distributed under the License is distributed on an 15565d668cSAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16565d668cSAndrew Rist * KIND, either express or implied. See the License for the 17565d668cSAndrew Rist * specific language governing permissions and limitations 18565d668cSAndrew Rist * under the License. 19565d668cSAndrew Rist * 20565d668cSAndrew Rist *************************************************************/ 21565d668cSAndrew Rist 22565d668cSAndrew Rist 23cdf0e10cSrcweir 24cdf0e10cSrcweir #ifndef _RTL_LOCALE_HXX_ 25cdf0e10cSrcweir #define _RTL_LOCALE_HXX_ 26cdf0e10cSrcweir 27cdf0e10cSrcweir #include <rtl/locale.h> 28cdf0e10cSrcweir #include <rtl/ustring.hxx> 29cdf0e10cSrcweir 30cdf0e10cSrcweir #ifdef __cplusplus 31cdf0e10cSrcweir 32cdf0e10cSrcweir namespace rtl 33cdf0e10cSrcweir { 34cdf0e10cSrcweir 35cdf0e10cSrcweir /** 36cdf0e10cSrcweir A <code>OLocale</code> object represents a specific geographical, political, 37cdf0e10cSrcweir or cultural region. An operation that requires a <code>OLocale</code> to perform 38cdf0e10cSrcweir its task is called <em>locale-sensitive</em> and uses the <code>OLocale</code> 39cdf0e10cSrcweir to tailor information for the user. For example, displaying a number 40cdf0e10cSrcweir is a locale-sensitive operation--the number should be formatted 41cdf0e10cSrcweir according to the customs/conventions of the user's native country, 42cdf0e10cSrcweir region, or culture. 43cdf0e10cSrcweir 44cdf0e10cSrcweir <P> 45cdf0e10cSrcweir You create a <code>OLocale</code> object using one of the two constructors in 46cdf0e10cSrcweir this class: 47cdf0e10cSrcweir <blockquote> 48cdf0e10cSrcweir <pre> 49cdf0e10cSrcweir OLocale(String language, String country) 50cdf0e10cSrcweir OLocale(String language, String country, String variant) 51cdf0e10cSrcweir </pre> 52cdf0e10cSrcweir </blockquote> 53cdf0e10cSrcweir The first argument to both constructors is a valid <STRONG>ISO 54cdf0e10cSrcweir Language Code.</STRONG> These codes are the lower-case two-letter 55cdf0e10cSrcweir codes as defined by ISO-639. 56cdf0e10cSrcweir You can find a full list of these codes at a number of sites, such as: 57cdf0e10cSrcweir <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"> 58cdf0e10cSrcweir <code>http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</code></a> 59cdf0e10cSrcweir 60cdf0e10cSrcweir <P> 61cdf0e10cSrcweir The second argument to both constructors is a valid <STRONG>ISO Country 62cdf0e10cSrcweir Code.</STRONG> These codes are the upper-case two-letter codes 63cdf0e10cSrcweir as defined by ISO-3166. 64cdf0e10cSrcweir You can find a full list of these codes at a number of sites, such as: 65cdf0e10cSrcweir <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html"> 66cdf0e10cSrcweir <code>http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</code></a> 67cdf0e10cSrcweir 68cdf0e10cSrcweir <P> 69cdf0e10cSrcweir The second constructor requires a third argument--the <STRONG>Variant.</STRONG> 70cdf0e10cSrcweir The Variant codes are vendor and browser-specific. 71cdf0e10cSrcweir For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. 72cdf0e10cSrcweir Where there are two variants, separate them with an underscore, and 73cdf0e10cSrcweir put the most important one first. For 74cdf0e10cSrcweir example, a Traditional Spanish collation might be referenced, with 75cdf0e10cSrcweir "ES", "ES", "Traditional_WIN". 76cdf0e10cSrcweir 77cdf0e10cSrcweir <P> 78cdf0e10cSrcweir Because a <code>OLocale</code> object is just an identifier for a region, 79cdf0e10cSrcweir no validity check is performed when you construct a <code>OLocale</code>. 80cdf0e10cSrcweir If you want to see whether particular resources are available for the 81cdf0e10cSrcweir <code>OLocale</code> you construct, you must query those resources. For 82cdf0e10cSrcweir example, ask the <code>NumberFormat</code> for the locales it supports 83cdf0e10cSrcweir using its <code>getAvailableLocales</code> method. 84cdf0e10cSrcweir <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular 85cdf0e10cSrcweir locale, you get back the best available match, not necessarily 86cdf0e10cSrcweir precisely what you asked for. For more information, look at 87cdf0e10cSrcweir <a href="java.util.ResourceBundle.html"><code>ResourceBundle</code></a>. 88cdf0e10cSrcweir 89cdf0e10cSrcweir <P> 90cdf0e10cSrcweir The <code>OLocale</code> class provides a number of convenient constants 91cdf0e10cSrcweir that you can use to create <code>OLocale</code> objects for commonly used 92cdf0e10cSrcweir locales. For example, the following creates a <code>OLocale</code> object 93cdf0e10cSrcweir for the United States: 94cdf0e10cSrcweir <blockquote> 95cdf0e10cSrcweir <pre> 96cdf0e10cSrcweir OLocale.US 97cdf0e10cSrcweir </pre> 98cdf0e10cSrcweir </blockquote> 99cdf0e10cSrcweir 100cdf0e10cSrcweir <P> 101cdf0e10cSrcweir Once you've created a <code>OLocale</code> you can query it for information about 102cdf0e10cSrcweir itself. Use <code>getCountry</code> to get the ISO Country Code and 103cdf0e10cSrcweir <code>getLanguage</code> to get the ISO Language Code. You can 104cdf0e10cSrcweir use <code>getDisplayCountry</code> to get the 105cdf0e10cSrcweir name of the country suitable for displaying to the user. Similarly, 106cdf0e10cSrcweir you can use <code>getDisplayLanguage</code> to get the name of 107cdf0e10cSrcweir the language suitable for displaying to the user. Interestingly, 108cdf0e10cSrcweir the <code>getDisplayXXX</code> methods are themselves locale-sensitive 109cdf0e10cSrcweir and have two versions: one that uses the default locale and one 110cdf0e10cSrcweir that uses the locale specified as an argument. 111cdf0e10cSrcweir 112cdf0e10cSrcweir <P> 113cdf0e10cSrcweir The JDK provides a number of classes that perform locale-sensitive 114cdf0e10cSrcweir operations. For example, the <code>NumberFormat</code> class formats 115cdf0e10cSrcweir numbers, currency, or percentages in a locale-sensitive manner. Classes 116cdf0e10cSrcweir such as <code>NumberFormat</code> have a number of convenience methods 117cdf0e10cSrcweir for creating a default object of that type. For example, the 118cdf0e10cSrcweir <code>NumberFormat</code> class provides these three convenience methods 119cdf0e10cSrcweir for creating a default <code>NumberFormat</code> object: 120cdf0e10cSrcweir <blockquote> 121cdf0e10cSrcweir <pre> 122cdf0e10cSrcweir NumberFormat.getInstance() 123cdf0e10cSrcweir NumberFormat.getCurrencyInstance() 124cdf0e10cSrcweir NumberFormat.getPercentInstance() 125cdf0e10cSrcweir </pre> 126cdf0e10cSrcweir </blockquote> 127cdf0e10cSrcweir These methods have two variants; one with an explicit locale 128cdf0e10cSrcweir and one without; the latter using the default locale. 129cdf0e10cSrcweir <blockquote> 130cdf0e10cSrcweir <pre> 131cdf0e10cSrcweir NumberFormat.getInstance(myLocale) 132cdf0e10cSrcweir NumberFormat.getCurrencyInstance(myLocale) 133cdf0e10cSrcweir NumberFormat.getPercentInstance(myLocale) 134cdf0e10cSrcweir </pre> 135cdf0e10cSrcweir </blockquote> 136cdf0e10cSrcweir A <code>OLocale</code> is the mechanism for identifying the kind of object 137cdf0e10cSrcweir (<code>NumberFormat</code>) that you would like to get. The locale is 138cdf0e10cSrcweir <STRONG>just</STRONG> a mechanism for identifying objects, 139cdf0e10cSrcweir <STRONG>not</STRONG> a container for the objects themselves. 140cdf0e10cSrcweir 141cdf0e10cSrcweir <P> 142cdf0e10cSrcweir Each class that performs locale-sensitive operations allows you 143cdf0e10cSrcweir to get all the available objects of that type. You can sift 144cdf0e10cSrcweir through these objects by language, country, or variant, 145cdf0e10cSrcweir and use the display names to present a menu to the user. 146cdf0e10cSrcweir For example, you can create a menu of all the collation objects 147cdf0e10cSrcweir suitable for a given language. Such classes must implement these 148cdf0e10cSrcweir three class methods: 149cdf0e10cSrcweir <blockquote> 150cdf0e10cSrcweir <pre> 151cdf0e10cSrcweir public static OLocale[] getAvailableLocales() 152cdf0e10cSrcweir public static String getDisplayName(OLocale objectLocale, 153cdf0e10cSrcweir OLocale displayLocale) 154cdf0e10cSrcweir public static final String getDisplayName(OLocale objectLocale) 155cdf0e10cSrcweir // getDisplayName will throw MissingResourceException if the locale 156cdf0e10cSrcweir // is not one of the available locales. 157cdf0e10cSrcweir </pre> 158cdf0e10cSrcweir </blockquote> 159cdf0e10cSrcweir */ 160cdf0e10cSrcweir class OLocale 161cdf0e10cSrcweir { 162cdf0e10cSrcweir public: OLocale(rtl_Locale * locale)163cdf0e10cSrcweir OLocale( rtl_Locale * locale ) 164cdf0e10cSrcweir : pData( locale ) {} 165cdf0e10cSrcweir OLocale(const OLocale & obj)166cdf0e10cSrcweir OLocale( const OLocale & obj) 167cdf0e10cSrcweir : pData(obj.pData) {} 168cdf0e10cSrcweir operator =(const OLocale & obj)169cdf0e10cSrcweir OLocale & operator = ( const OLocale & obj) 170cdf0e10cSrcweir { 171cdf0e10cSrcweir pData = obj.pData; 172cdf0e10cSrcweir return *this; 173cdf0e10cSrcweir } 174cdf0e10cSrcweir 175cdf0e10cSrcweir /** 176cdf0e10cSrcweir Construct a locale from language, country, variant. 177cdf0e10cSrcweir @param language lowercase two-letter ISO-639 code. 178cdf0e10cSrcweir @param country uppercase two-letter ISO-3166 code. 179cdf0e10cSrcweir @param variant vendor and browser specific code. See class description. 180cdf0e10cSrcweir */ registerLocale(const OUString & language,const OUString & country,const OUString & variant)181cdf0e10cSrcweir static OLocale registerLocale( const OUString & language, const OUString & country, 182cdf0e10cSrcweir const OUString & variant ) 183cdf0e10cSrcweir { 184*24c56ab9SHerbert Dürr return rtl_locale_register( language.getStr(), country.getStr(), variant.getStr() ); 185cdf0e10cSrcweir } 186cdf0e10cSrcweir 187cdf0e10cSrcweir /** 188cdf0e10cSrcweir Construct a locale from language, country. 189cdf0e10cSrcweir @param language lowercase two-letter ISO-639 code. 190cdf0e10cSrcweir @param country uppercase two-letter ISO-3166 code. 191cdf0e10cSrcweir */ registerLocale(const OUString & language,const OUString & country)192cdf0e10cSrcweir static OLocale registerLocale( const OUString & language, const OUString & country ) 193cdf0e10cSrcweir { 194*24c56ab9SHerbert Dürr return rtl_locale_register( language.getStr(), country.getStr(), NULL ); 195cdf0e10cSrcweir } 196cdf0e10cSrcweir 197cdf0e10cSrcweir /** @deprecated 198cdf0e10cSrcweir */ getDefault()199cdf0e10cSrcweir static OLocale getDefault() { return rtl_locale_getDefault(); } 200cdf0e10cSrcweir 201cdf0e10cSrcweir /** @deprecated 202cdf0e10cSrcweir */ setDefault(const OUString & language,const OUString & country,const OUString & variant)203cdf0e10cSrcweir static void setDefault( const OUString & language, const OUString & country, 204cdf0e10cSrcweir const OUString & variant ) 205*24c56ab9SHerbert Dürr { rtl_locale_setDefault( language.getStr(), country.getStr(), variant.getStr()); } 206cdf0e10cSrcweir 207cdf0e10cSrcweir /** 208cdf0e10cSrcweir Getter for programmatic name of field, 209cdf0e10cSrcweir an lowercased two-letter ISO-639 code. 210cdf0e10cSrcweir */ getLanguage() const211cdf0e10cSrcweir OUString getLanguage() const { return pData->Language; } 212cdf0e10cSrcweir 213cdf0e10cSrcweir /** 214cdf0e10cSrcweir Getter for programmatic name of field, 215cdf0e10cSrcweir an uppercased two-letter ISO-3166 code. 216cdf0e10cSrcweir */ getCountry() const217cdf0e10cSrcweir OUString getCountry() const { return pData->Country; } 218cdf0e10cSrcweir 219cdf0e10cSrcweir /** 220cdf0e10cSrcweir Getter for programmatic name of field. 221cdf0e10cSrcweir */ getVariant() const222cdf0e10cSrcweir OUString getVariant() const { return pData->Variant; } 223cdf0e10cSrcweir 224cdf0e10cSrcweir 225cdf0e10cSrcweir /** 226cdf0e10cSrcweir Returns the hash code of the locale This. 227cdf0e10cSrcweir */ hashCode() const228cdf0e10cSrcweir sal_Int32 hashCode() const { return pData->HashCode; } 229cdf0e10cSrcweir operator ==(const OLocale & obj) const230cdf0e10cSrcweir sal_Bool operator == (const OLocale & obj ) const 231cdf0e10cSrcweir { 232cdf0e10cSrcweir return pData == obj.pData; 233cdf0e10cSrcweir } 234cdf0e10cSrcweir getData() const235cdf0e10cSrcweir rtl_Locale * getData() const { return pData; } 236cdf0e10cSrcweir 237cdf0e10cSrcweir private: 238cdf0e10cSrcweir /** 239cdf0e10cSrcweir Must be the first member in this class. OUString access this member with 240cdf0e10cSrcweir *(rtl_Locale **)&locale. 241cdf0e10cSrcweir */ 242cdf0e10cSrcweir rtl_Locale * pData; 243cdf0e10cSrcweir OLocale()244cdf0e10cSrcweir OLocale() 245cdf0e10cSrcweir : pData(rtl_locale_getDefault()) {} 246cdf0e10cSrcweir /* 247cdf0e10cSrcweir OLocale( const OLocale & obj) 248cdf0e10cSrcweir : pData(obj.pData) {} 249cdf0e10cSrcweir 250cdf0e10cSrcweir OLocale & operator = ( const OLocale & obj) 251cdf0e10cSrcweir { pData = obj.pData; 252cdf0e10cSrcweir return *this; 253cdf0e10cSrcweir } 254cdf0e10cSrcweir */ 255cdf0e10cSrcweir }; 256cdf0e10cSrcweir 257cdf0e10cSrcweir } 258cdf0e10cSrcweir 259cdf0e10cSrcweir #endif /* __cplusplus */ 260cdf0e10cSrcweir #endif /* _RTL_LOCALE_HXX_ */ 261cdf0e10cSrcweir 262cdf0e10cSrcweir 263