text: //=========================================================================
  // Copyright (C) 2012 The Elastos Open Source Project
  //
  // Licensed under the Apache License, Version 2.0 (the "License");
  // you may not use this file except in compliance with the License.
  // You may obtain a copy of the License at
  //
  //      http://www.apache.org/licenses/LICENSE-2.0
  //
  // Unless required by applicable law or agreed to in writing, software
  // distributed under the License is distributed on an "AS IS" BASIS,
  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  // See the License for the specific language governing permissions and
  // limitations under the License.
  //=========================================================================
  
  #ifndef __ELASTOS_UTILITY_CLOCALE_H__
  #define __ELASTOS_UTILITY_CLOCALE_H__
  
  #include "_Elastos_Utility_CLocale.h"
  #include <elastos/utility/Locale.h>
  
  namespace Elastos {
  namespace Utility {
  
  /**
   * {@code Locale} represents a language/country/variant combination. Locales are used to
   * alter the presentation of information such as numbers or dates to suit the conventions
   * in the region they describe.
   *
   * <p>The language codes are two-letter lowercase ISO language codes (such as "en") as defined by
   * <a href="http://en.wikipedia.org/wiki/ISO_639-1">ISO 639-1</a>.
   * The country codes are two-letter uppercase ISO country codes (such as "US") as defined by
   * <a href="http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO 3166-1</a>.
   * The variant codes are unspecified.
   *
   * <p>Note that Java uses several deprecated two-letter codes. The Hebrew ("he") language
   * code is rewritten as "iw", Indonesian ("id") as "in", and Yiddish ("yi") as "ji". This
   * rewriting happens even if you construct your own {@code Locale} object, not just for
   * instances returned by the various lookup methods.
   *
   * <a name="available_locales"><h3>Available locales</h3></a>
   * <p>This class' constructors do no error checking. You can create a {@code Locale} for languages
   * and countries that don't exist, and you can create instances for combinations that don't
   * exist (such as "de_US" for "German as spoken in the US").
   *
   * <p>Note that locale data is not necessarily available for any of the locales pre-defined as
   * constants in this class except for en_US, which is the only locale Java guarantees is always
   * available.
   *
   * <p>It is also a mistake to assume that all devices have the same locales available.
   * A device sold in the US will almost certainly support en_US and es_US, but not necessarily
   * any locales with the same language but different countries (such as en_GB or es_ES),
   * nor any locales for other languages (such as de_DE). The opposite may well be true for a device
   * sold in Europe.
   *
   * <p>You can use {@link Locale#getDefault} to get an appropriate locale for the <i>user</i> of the
   * device you're running on, or {@link Locale#getAvailableLocales} to get a list of all the locales
   * available on the device you're running on.
   *
   * <a name="locale_data"><h3>Locale data</h3></a>
   * <p>Note that locale data comes solely from ICU. User-supplied locale service providers (using
   * the {@code java.text.spi} or {@code java.util.spi} mechanisms) are not supported.
   *
   * <p>Here are the versions of ICU (and the corresponding CLDR and Unicode versions) used in
   * various Android releases:
   * <table BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
   * <tr><td>Android 1.5 (Cupcake)/Android 1.6 (Donut)/Android 2.0 (Eclair)</td>
   *     <td>ICU 3.8</td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-1-5">CLDR 1.5</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode5.0.0/">Unicode 5.0</a></td></tr>
   * <tr><td>Android 2.2 (Froyo)</td>
   *     <td>ICU 4.2</td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-1-7">CLDR 1.7</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode5.1.0/">Unicode 5.1</a></td></tr>
   * <tr><td>Android 2.3 (Gingerbread)/Android 3.0 (Honeycomb)</td>
   *     <td>ICU 4.4</td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-1-8">CLDR 1.8</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode5.2.0/">Unicode 5.2</a></td></tr>
   * <tr><td>Android 4.0 (Ice Cream Sandwich)</td>
   *     <td><a href="http://site.icu-project.org/download/46">ICU 4.6</a></td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-1-9">CLDR 1.9</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode6.0.0/">Unicode 6.0</a></td></tr>
   * <tr><td>Android 4.1 (Jelly Bean)</td>
   *     <td><a href="http://site.icu-project.org/download/48">ICU 4.8</a></td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-2-0">CLDR 2.0</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode6.0.0/">Unicode 6.0</a></td></tr>
   * <tr><td>Android 4.3 (Jelly Bean MR2)</td>
   *     <td><a href="http://site.icu-project.org/download/50">ICU 50</a></td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-22-1">CLDR 22.1</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode6.2.0/">Unicode 6.2</a></td></tr>
   * <tr><td>Android 4.4 (KitKat)</td>
   *     <td><a href="http://site.icu-project.org/download/51">ICU 51</a></td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-23">CLDR 23</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode6.2.0/">Unicode 6.2</a></td></tr>
   * <tr><td>Android 5.0 (Lollipop)</td>
   *     <td><a href="http://site.icu-project.org/download/53">ICU 53</a></td>
   *     <td><a href="http://cldr.unicode.org/index/downloads/cldr-25">CLDR 25</a></td>
   *     <td><a href="http://www.unicode.org/versions/Unicode6.3.0/">Unicode 6.3</a></td></tr>
   * </table>
   *
   * <a name="default_locale"><h3>Be wary of the default locale</h3></a>
   * <p>Note that there are many convenience methods that automatically use the default locale, but
   * using them may lead to subtle bugs.
   *
   * <p>The default locale is appropriate for tasks that involve presenting data to the user. In
   * this case, you want to use the user's date/time formats, number
   * formats, rules for conversion to lowercase, and so on. In this case, it's safe to use the
   * convenience methods.
   *
   * <p>The default locale is <i>not</i> appropriate for machine-readable output. The best choice
   * there is usually {@code Locale.US}&nbsp;&ndash; this locale is guaranteed to be available on all
   * devices, and the fact that it has no surprising special cases and is frequently used (especially
   * for computer-computer communication) means that it tends to be the most efficient choice too.
   *
   * <p>A common mistake is to implicitly use the default locale when producing output meant to be
   * machine-readable. This tends to work on the developer's test devices (especially because so many
   * developers use en_US), but fails when run on a device whose user is in a more complex locale.
   *
   * <p>For example, if you're formatting integers some locales will use non-ASCII decimal
   * digits. As another example, if you're formatting floating-point numbers some locales will use
   * {@code ','} as the decimal point and {@code '.'} for digit grouping. That's correct for
   * human-readable output, but likely to cause problems if presented to another
   * computer ({@link Double#parseDouble} can't parse such a number, for example).
   * You should also be wary of the {@link String#toLowerCase} and
   * {@link String#toUpperCase} overloads that don't take a {@code Locale}: in Turkey, for example,
   * the characters {@code 'i'} and {@code 'I'} won't be converted to {@code 'I'} and {@code 'i'}.
   * This is the correct behavior for Turkish text (such as user input), but inappropriate for, say,
   * HTTP headers.
   */
  CarClass(CLocale)
      , public Locale
  {
  public:
      CAR_OBJECT_DECL()
  };
  
  } // namespace Utility
  } // namespace Elastos
  
  #endif // __ELASTOS_UTILITY_CLOCALE_H__
  