icuSources/i18n/unicode/numsys.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 * Copyright (C) 2010-2014, International Business Machines Corporation and
   6 * others. All Rights Reserved.
   7 *******************************************************************************
   8 *
   9 *
  10 * File NUMSYS.H
  11 *
  12 * Modification History:*
  13 *   Date        Name        Description
  14 *
  15 ********************************************************************************
  16 */
  17
  18 #ifndef NUMSYS
  19 #define NUMSYS
  20
  21 #include "unicode/utypes.h"
  22
  23 /**
  24  * \file
  25  * \brief C++ API: NumberingSystem object
  26  */
  27
  28 #if !UCONFIG_NO_FORMATTING
  29
  30 #include "unicode/format.h"
  31 #include "unicode/uobject.h"
  32
  33 #if U_SHOW_CPLUSPLUS_API
  34 U_NAMESPACE_BEGIN
  35
  36 // can't be #ifndef U_HIDE_INTERNAL_API; needed for char[] field size
  37 /**
  38  * Size of a numbering system name.
  39  * @internal
  40  */
  41 constexpr const size_t kInternalNumSysNameCapacity = 8;
  42
  43 /**
  44  * Defines numbering systems. A numbering system describes the scheme by which
  45  * numbers are to be presented to the end user.  In its simplest form, a numbering
  46  * system describes the set of digit characters that are to be used to display
  47  * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a
  48  * positional numbering system with a specified radix (typically 10).
  49  * More complicated numbering systems are algorithmic in nature, and require use
  50  * of an RBNF formatter ( rule based number formatter ), in order to calculate
  51  * the characters to be displayed for a given number.  Examples of algorithmic
  52  * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals.
  53  * Formatting rules for many commonly used numbering systems are included in
  54  * the ICU package, based on the numbering system rules defined in CLDR.
  55  * Alternate numbering systems can be specified to a locale by using the
  56  * numbers locale keyword.
  57  */
  58
  59 class U_I18N_API NumberingSystem : public UObject {
  60 public:
  61
  62     /**
  63      * Default Constructor.
  64      *
  65      * @stable ICU 4.2
  66      */
  67     NumberingSystem();
  68
  69     /**
  70      * Copy constructor.
  71      * @stable ICU 4.2
  72      */
  73     NumberingSystem(const NumberingSystem& other);
  74
  75     /**
  76      * Destructor.
  77      * @stable ICU 4.2
  78      */
  79     virtual ~NumberingSystem();
  80
  81     /**
  82      * Create the default numbering system associated with the specified locale.
  83      * @param inLocale The given locale.
  84      * @param status ICU status
  85      * @stable ICU 4.2
  86      */
  87     static NumberingSystem* U_EXPORT2 createInstance(const Locale & inLocale, UErrorCode& status);
  88
  89     /**
  90      * Create the default numbering system associated with the default locale.
  91      * @stable ICU 4.2
  92      */
  93     static NumberingSystem* U_EXPORT2 createInstance(UErrorCode& status);
  94
  95     /**
  96      * Create a numbering system using the specified radix, type, and description.
  97      * @param radix         The radix (base) for this numbering system.
  98      * @param isAlgorithmic TRUE if the numbering system is algorithmic rather than numeric.
  99      * @param description   The string representing the set of digits used in a numeric system, or the name of the RBNF
 100      *                      ruleset to be used in an algorithmic system.
 101      * @param status ICU status
 102      * @stable ICU 4.2
 103      */
 104     static NumberingSystem* U_EXPORT2 createInstance(int32_t radix, UBool isAlgorithmic, const UnicodeString& description, UErrorCode& status );
 105
 106     /**
 107      * Return a StringEnumeration over all the names of numbering systems known to ICU.
 108      * The numbering system names will be in alphabetical (invariant) order.
 109      *
 110      * The returned StringEnumeration is owned by the caller, who must delete it when
 111      * finished with it.
 112      *
 113      * @stable ICU 4.2
 114      */
 115      static StringEnumeration * U_EXPORT2 getAvailableNames(UErrorCode& status);
 116
 117     /**
 118      * Create a numbering system from one of the predefined numbering systems specified
 119      * by CLDR and known to ICU, such as "latn", "arabext", or "hanidec"; the full list
 120      * is returned by unumsys_openAvailableNames. Note that some of the names listed at
 121      * http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g.
 122      * default, native, traditional, finance - do not identify specific numbering systems,
 123      * but rather key values that may only be used as part of a locale, which in turn
 124      * defines how they are mapped to a specific numbering system such as "latn" or "hant".
 125      *
 126      * @param name   The name of the numbering system.
 127      * @param status ICU status; set to U_UNSUPPORTED_ERROR if numbering system not found.
 128      * @return The NumberingSystem instance, or nullptr if not found.
 129      * @stable ICU 4.2
 130      */
 131     static NumberingSystem* U_EXPORT2 createInstanceByName(const char* name, UErrorCode& status);
 132
 133
 134     /**
 135      * Returns the radix of this numbering system. Simple positional numbering systems
 136      * typically have radix 10, but might have a radix of e.g. 16 for hexadecimal. The
 137      * radix is less well-defined for non-positional algorithmic systems.
 138      * @stable ICU 4.2
 139      */
 140     int32_t getRadix() const;
 141
 142     /**
 143      * Returns the name of this numbering system if it was created using one of the predefined names
 144      * known to ICU.  Otherwise, returns NULL.
 145      * The predefined names are identical to the numbering system names as defined by
 146      * the BCP47 definition in Unicode CLDR.
 147      * See also, http://www.unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml
 148      * @stable ICU 4.6
 149      */
 150     const char * getName() const;
 151
 152     /**
 153      * Returns the description string of this numbering system. For simple
 154      * positional systems this is the ordered string of digits (with length matching
 155      * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D"
 156      * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For
 157      * algorithmic systems this is the name of the RBNF ruleset used for formatting,
 158      * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for
 159      * "grek".
 160      * @stable ICU 4.2
 161      */
 162     virtual UnicodeString getDescription() const;
 163
 164
 165
 166     /**
 167      * Returns TRUE if the given numbering system is algorithmic
 168      *
 169      * @return         TRUE if the numbering system is algorithmic.
 170      *                 Otherwise, return FALSE.
 171      * @stable ICU 4.2
 172      */
 173     UBool isAlgorithmic() const;
 174
 175     /**
 176      * ICU "poor man's RTTI", returns a UClassID for this class.
 177      *
 178      * @stable ICU 4.2
 179      *
 180     */
 181     static UClassID U_EXPORT2 getStaticClassID(void);
 182
 183     /**
 184      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 185      *
 186      * @stable ICU 4.2
 187      */
 188     virtual UClassID getDynamicClassID() const;
 189
 190
 191 private:
 192     UnicodeString   desc;
 193     int32_t         radix;
 194     UBool           algorithmic;
 195     char            name[kInternalNumSysNameCapacity+1];
 196
 197     void setRadix(int32_t radix);
 198
 199     void setAlgorithmic(UBool algorithmic);
 200
 201     void setDesc(const UnicodeString &desc);
 202
 203     void setName(const char* name);
 204
 205     static UBool isValidDigitString(const UnicodeString &str);
 206
 207     UBool hasContiguousDecimalDigits() const;
 208 };
 209
 210 U_NAMESPACE_END
 211 #endif // U_SHOW_CPLUSPLUS_API
 212
 213 #endif /* #if !UCONFIG_NO_FORMATTING */
 214
 215 #endif // _NUMSYS
 216 //eof