1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/unumsys.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,174 @@
1.4 +/*
1.5 +*****************************************************************************************
1.6 +* Copyright (C) 2013, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +*****************************************************************************************
1.9 +*/
1.10 +
1.11 +#ifndef UNUMSYS_H
1.12 +#define UNUMSYS_H
1.13 +
1.14 +#include "unicode/utypes.h"
1.15 +
1.16 +#if !UCONFIG_NO_FORMATTING
1.17 +
1.18 +#include "unicode/uenum.h"
1.19 +#include "unicode/localpointer.h"
1.20 +
1.21 +/**
1.22 + * \file
1.23 + * \brief C API: UNumberingSystem, information about numbering systems
1.24 + *
1.25 + * Defines numbering systems. A numbering system describes the scheme by which
1.26 + * numbers are to be presented to the end user. In its simplest form, a numbering
1.27 + * system describes the set of digit characters that are to be used to display
1.28 + * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a
1.29 + * positional numbering system with a specified radix (typically 10).
1.30 + * More complicated numbering systems are algorithmic in nature, and require use
1.31 + * of an RBNF formatter (rule based number formatter), in order to calculate
1.32 + * the characters to be displayed for a given number. Examples of algorithmic
1.33 + * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals.
1.34 + * Formatting rules for many commonly used numbering systems are included in
1.35 + * the ICU package, based on the numbering system rules defined in CLDR.
1.36 + * Alternate numbering systems can be specified to a locale by using the
1.37 + * numbers locale keyword.
1.38 + */
1.39 +
1.40 +#ifndef U_HIDE_DRAFT_API
1.41 +
1.42 +/**
1.43 + * Opaque UNumberingSystem object for use in C programs.
1.44 + * @draft ICU 52
1.45 + */
1.46 +struct UNumberingSystem;
1.47 +typedef struct UNumberingSystem UNumberingSystem; /**< C typedef for struct UNumberingSystem. @draft ICU 52 */
1.48 +
1.49 +/**
1.50 + * Opens a UNumberingSystem object using the default numbering system for the specified
1.51 + * locale.
1.52 + * @param locale The locale for which the default numbering system should be opened.
1.53 + * @param status A pointer to a UErrorCode to receive any errors. For example, this
1.54 + * may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that
1.55 + * specifies a numbering system unknown to ICU.
1.56 + * @return A UNumberingSystem for the specified locale, or NULL if an error
1.57 + * occurred.
1.58 + * @draft ICU 52
1.59 + */
1.60 +U_DRAFT UNumberingSystem * U_EXPORT2
1.61 +unumsys_open(const char *locale, UErrorCode *status);
1.62 +
1.63 +/**
1.64 + * Opens a UNumberingSystem object using the name of one of the predefined numbering
1.65 + * systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec";
1.66 + * the full list is returned by unumsys_openAvailableNames. Note that some of the names
1.67 + * listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g.
1.68 + * default, native, traditional, finance - do not identify specific numbering systems,
1.69 + * but rather key values that may only be used as part of a locale, which in turn
1.70 + * defines how they are mapped to a specific numbering system such as "latn" or "hant".
1.71 + *
1.72 + * @param name The name of the numbering system for which a UNumberingSystem object
1.73 + * should be opened.
1.74 + * @param status A pointer to a UErrorCode to receive any errors. For example, this
1.75 + * may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that
1.76 + * is unknown to ICU.
1.77 + * @return A UNumberingSystem for the specified name, or NULL if an error
1.78 + * occurred.
1.79 + * @draft ICU 52
1.80 + */
1.81 +U_DRAFT UNumberingSystem * U_EXPORT2
1.82 +unumsys_openByName(const char *name, UErrorCode *status);
1.83 +
1.84 +/**
1.85 + * Close a UNumberingSystem object. Once closed it may no longer be used.
1.86 + * @param unumsys The UNumberingSystem object to close.
1.87 + * @draft ICU 52
1.88 + */
1.89 +U_DRAFT void U_EXPORT2
1.90 +unumsys_close(UNumberingSystem *unumsys);
1.91 +
1.92 +#if U_SHOW_CPLUSPLUS_API
1.93 +U_NAMESPACE_BEGIN
1.94 +
1.95 +/**
1.96 + * \class LocalUNumberingSystemPointer
1.97 + * "Smart pointer" class, closes a UNumberingSystem via unumsys_close().
1.98 + * For most methods see the LocalPointerBase base class.
1.99 + * @see LocalPointerBase
1.100 + * @see LocalPointer
1.101 + * @draft ICU 52
1.102 + */
1.103 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close);
1.104 +
1.105 +U_NAMESPACE_END
1.106 +#endif
1.107 +
1.108 +/**
1.109 + * Returns an enumeration over the names of all of the predefined numbering systems known
1.110 + * to ICU.
1.111 + * @param status A pointer to a UErrorCode to receive any errors.
1.112 + * @return A pointer to a UEnumeration that must be closed with uenum_close(),
1.113 + * or NULL if an error occurred.
1.114 + * @draft ICU 52
1.115 + */
1.116 +U_DRAFT UEnumeration * U_EXPORT2
1.117 +unumsys_openAvailableNames(UErrorCode *status);
1.118 +
1.119 +/**
1.120 + * Returns the name of the specified UNumberingSystem object (if it is one of the
1.121 + * predefined names known to ICU).
1.122 + * @param unumsys The UNumberingSystem whose name is desired.
1.123 + * @return A pointer to the name of the specified UNumberingSystem object, or
1.124 + * NULL if the name is not one of the ICU predefined names. The pointer
1.125 + * is only valid for the lifetime of the UNumberingSystem object.
1.126 + * @draft ICU 52
1.127 + */
1.128 +U_DRAFT const char * U_EXPORT2
1.129 +unumsys_getName(const UNumberingSystem *unumsys);
1.130 +
1.131 +/**
1.132 + * Returns whether the given UNumberingSystem object is for an algorithmic (not purely
1.133 + * positional) system.
1.134 + * @param unumsys The UNumberingSystem whose algorithmic status is desired.
1.135 + * @return TRUE if the specified UNumberingSystem object is for an algorithmic
1.136 + * system.
1.137 + * @draft ICU 52
1.138 + */
1.139 +U_DRAFT UBool U_EXPORT2
1.140 +unumsys_isAlgorithmic(const UNumberingSystem *unumsys);
1.141 +
1.142 +/**
1.143 + * Returns the radix of the specified UNumberingSystem object. Simple positional
1.144 + * numbering systems typically have radix 10, but might have a radix of e.g. 16 for
1.145 + * hexadecimal. The radix is less well-defined for non-positional algorithmic systems.
1.146 + * @param unumsys The UNumberingSystem whose radix is desired.
1.147 + * @return The radix of the specified UNumberingSystem object.
1.148 + * @draft ICU 52
1.149 + */
1.150 +U_DRAFT int32_t U_EXPORT2
1.151 +unumsys_getRadix(const UNumberingSystem *unumsys);
1.152 +
1.153 +/**
1.154 + * Get the description string of the specified UNumberingSystem object. For simple
1.155 + * positional systems this is the ordered string of digits (with length matching
1.156 + * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D"
1.157 + * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For
1.158 + * algorithmic systems this is the name of the RBNF ruleset used for formatting,
1.159 + * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for
1.160 + * "grek".
1.161 + * @param unumsys The UNumberingSystem whose description string is desired.
1.162 + * @param result A pointer to a buffer to receive the description string.
1.163 + * @param resultLength The maximum size of result.
1.164 + * @param status A pointer to a UErrorCode to receive any errors.
1.165 + * @return The total buffer size needed; if greater than resultLength, the
1.166 + * output was truncated.
1.167 + * @draft ICU 52
1.168 + */
1.169 +U_DRAFT int32_t U_EXPORT2
1.170 +unumsys_getDescription(const UNumberingSystem *unumsys, UChar *result,
1.171 + int32_t resultLength, UErrorCode *status);
1.172 +
1.173 +#endif /* U_HIDE_DRAFT_API */
1.174 +
1.175 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.176 +
1.177 +#endif
