sal/inc/rtl/locale.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: locale.hxx,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _RTL_LOCALE_HXX_
  32 #define _RTL_LOCALE_HXX_
  33
  34 #include <rtl/locale.h>
  35 #include <rtl/ustring.hxx>
  36
  37 #ifdef __cplusplus
  38
  39 namespace rtl
  40 {
  41
  42 /**
  43     A <code>OLocale</code> object represents a specific geographical, political,
  44     or cultural region. An operation that requires a <code>OLocale</code> to perform
  45     its task is called <em>locale-sensitive</em> and uses the <code>OLocale</code>
  46     to tailor information for the user. For example, displaying a number
  47     is a locale-sensitive operation--the number should be formatted
  48     according to the customs/conventions of the user's native country,
  49     region, or culture.
  50
  51     <P>
  52     You create a <code>OLocale</code> object using one of the two constructors in
  53     this class:
  54     <blockquote>
  55     <pre>
  56     OLocale(String language, String country)
  57     OLocale(String language, String country, String variant)
  58     </pre>
  59     </blockquote>
  60     The first argument to both constructors is a valid <STRONG>ISO
  61     Language Code.</STRONG> These codes are the lower-case two-letter
  62     codes as defined by ISO-639.
  63     You can find a full list of these codes at a number of sites, such as:
  64     <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
  65     <code>http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</code></a>
  66
  67     <P>
  68     The second argument to both constructors is a valid <STRONG>ISO Country
  69     Code.</STRONG> These codes are the upper-case two-letter codes
  70     as defined by ISO-3166.
  71     You can find a full list of these codes at a number of sites, such as:
  72     <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">
  73     <code>http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</code></a>
  74
  75     <P>
  76     The second constructor requires a third argument--the <STRONG>Variant.</STRONG>
  77     The Variant codes are vendor and browser-specific.
  78     For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
  79     Where there are two variants, separate them with an underscore, and
  80     put the most important one first. For
  81     example, a Traditional Spanish collation might be referenced, with
  82     "ES", "ES", "Traditional_WIN".
  83
  84     <P>
  85     Because a <code>OLocale</code> object is just an identifier for a region,
  86     no validity check is performed when you construct a <code>OLocale</code>.
  87     If you want to see whether particular resources are available for the
  88     <code>OLocale</code> you construct, you must query those resources. For
  89     example, ask the <code>NumberFormat</code> for the locales it supports
  90     using its <code>getAvailableLocales</code> method.
  91     <BR><STRONG>Note:</STRONG> When you ask for a resource for a particular
  92     locale, you get back the best available match, not necessarily
  93     precisely what you asked for. For more information, look at
  94     <a href="java.util.ResourceBundle.html"><code>ResourceBundle</code></a>.
  95
  96     <P>
  97     The <code>OLocale</code> class provides a number of convenient constants
  98     that you can use to create <code>OLocale</code> objects for commonly used
  99     locales. For example, the following creates a <code>OLocale</code> object
 100     for the United States:
 101     <blockquote>
 102     <pre>
 103     OLocale.US
 104     </pre>
 105     </blockquote>
 106
 107     <P>
 108     Once you've created a <code>OLocale</code> you can query it for information about
 109     itself. Use <code>getCountry</code> to get the ISO Country Code and
 110     <code>getLanguage</code> to get the ISO Language Code. You can
 111     use <code>getDisplayCountry</code> to get the
 112     name of the country suitable for displaying to the user. Similarly,
 113     you can use <code>getDisplayLanguage</code> to get the name of
 114     the language suitable for displaying to the user. Interestingly,
 115     the <code>getDisplayXXX</code> methods are themselves locale-sensitive
 116     and have two versions: one that uses the default locale and one
 117     that uses the locale specified as an argument.
 118
 119     <P>
 120     The JDK provides a number of classes that perform locale-sensitive
 121     operations. For example, the <code>NumberFormat</code> class formats
 122     numbers, currency, or percentages in a locale-sensitive manner. Classes
 123     such as <code>NumberFormat</code> have a number of convenience methods
 124     for creating a default object of that type. For example, the
 125     <code>NumberFormat</code> class provides these three convenience methods
 126     for creating a default <code>NumberFormat</code> object:
 127     <blockquote>
 128     <pre>
 129     NumberFormat.getInstance()
 130     NumberFormat.getCurrencyInstance()
 131     NumberFormat.getPercentInstance()
 132     </pre>
 133     </blockquote>
 134     These methods have two variants; one with an explicit locale
 135     and one without; the latter using the default locale.
 136     <blockquote>
 137     <pre>
 138     NumberFormat.getInstance(myLocale)
 139     NumberFormat.getCurrencyInstance(myLocale)
 140     NumberFormat.getPercentInstance(myLocale)
 141     </pre>
 142     </blockquote>
 143     A <code>OLocale</code> is the mechanism for identifying the kind of object
 144     (<code>NumberFormat</code>) that you would like to get. The locale is
 145     <STRONG>just</STRONG> a mechanism for identifying objects,
 146     <STRONG>not</STRONG> a container for the objects themselves.
 147
 148     <P>
 149     Each class that performs locale-sensitive operations allows you
 150     to get all the available objects of that type. You can sift
 151     through these objects by language, country, or variant,
 152     and use the display names to present a menu to the user.
 153     For example, you can create a menu of all the collation objects
 154     suitable for a given language. Such classes must implement these
 155     three class methods:
 156     <blockquote>
 157     <pre>
 158     public static OLocale[] getAvailableLocales()
 159     public static String getDisplayName(OLocale objectLocale,
 160                                        OLocale displayLocale)
 161     public static final String getDisplayName(OLocale objectLocale)
 162        // getDisplayName will throw MissingResourceException if the locale
 163        // is not one of the available locales.
 164     </pre>
 165     </blockquote>
 166  */
 167 class OLocale
 168 {
 169 public:
 170     OLocale( rtl_Locale * locale )
 171         : pData( locale ) {}
 172
 173     OLocale( const OLocale & obj)
 174         : pData(obj.pData) {}
 175
 176     OLocale & operator = ( const OLocale & obj)
 177         {
 178             pData = obj.pData;
 179             return *this;
 180         }
 181
 182     /**
 183          Construct a locale from language, country, variant.
 184         @param language lowercase two-letter ISO-639 code.
 185         @param country uppercase two-letter ISO-3166 code.
 186         @param variant vendor and browser specific code. See class description.
 187      */
 188     static OLocale registerLocale( const OUString & language, const OUString & country,
 189                             const OUString & variant )
 190     {
 191         return rtl_locale_register( language, country, variant );
 192     }
 193
 194     /**
 195          Construct a locale from language, country.
 196         @param language lowercase two-letter ISO-639 code.
 197         @param country uppercase two-letter ISO-3166 code.
 198      */
 199     static OLocale registerLocale( const OUString & language, const OUString & country )
 200     {
 201         return rtl_locale_register( language, country, NULL );
 202     }
 203
 204     /** @deprecated
 205      */
 206     static OLocale getDefault()  { return rtl_locale_getDefault(); }
 207
 208     /** @deprecated
 209      */
 210     static void setDefault( const OUString & language, const OUString & country,
 211                             const OUString & variant )
 212              { rtl_locale_setDefault(language, country, variant); }
 213
 214     /**
 215          Getter for programmatic name of field,
 216          an lowercased two-letter ISO-639 code.
 217      */
 218     OUString getLanguage() const { return pData->Language; }
 219
 220     /**
 221          Getter for programmatic name of field,
 222          an uppercased two-letter ISO-3166 code.
 223      */
 224     OUString getCountry() const { return pData->Country; }
 225
 226     /**
 227          Getter for programmatic name of field.
 228      */
 229     OUString getVariant() const { return pData->Variant; }
 230
 231
 232     /**
 233          Returns the hash code of the locale This.
 234      */
 235     sal_Int32 hashCode() const { return pData->HashCode; }
 236
 237     sal_Bool operator == (const OLocale & obj ) const
 238     {
 239         return pData == obj.pData;
 240     }
 241
 242     rtl_Locale *        getData() const { return pData; }
 243
 244 private:
 245     /**
 246          Must be the first member in this class. OUString access this member with
 247          *(rtl_Locale **)&locale.
 248      */
 249     rtl_Locale *        pData;
 250
 251     OLocale()
 252         : pData(rtl_locale_getDefault()) {}
 253 /*
 254     OLocale( const OLocale & obj)
 255         : pData(obj.pData) {}
 256
 257     OLocale & operator = ( const OLocale & obj)
 258         { pData = obj.pData;
 259           return *this;
 260         }
 261 */
 262 };
 263
 264 }
 265
 266 #endif /* __cplusplus */
 267 #endif /* _RTL_LOCALE_HXX_ */
 268
 269