michael@0: /*
michael@0: *****************************************************************************************
michael@0: * Copyright (C) 2013, International Business Machines
michael@0: * Corporation and others. All Rights Reserved.
michael@0: *****************************************************************************************
michael@0: */
michael@0: 
michael@0: #ifndef UNUMSYS_H
michael@0: #define UNUMSYS_H
michael@0: 
michael@0: #include "unicode/utypes.h"
michael@0: 
michael@0: #if !UCONFIG_NO_FORMATTING
michael@0: 
michael@0: #include "unicode/uenum.h"
michael@0: #include "unicode/localpointer.h"
michael@0: 
michael@0: /**
michael@0:  * \file
michael@0:  * \brief C API: UNumberingSystem, information about numbering systems
michael@0:  *
michael@0:  * Defines numbering systems. A numbering system describes the scheme by which 
michael@0:  * numbers are to be presented to the end user. In its simplest form, a numbering
michael@0:  * system describes the set of digit characters that are to be used to display
michael@0:  * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a
michael@0:  * positional numbering system with a specified radix (typically 10).
michael@0:  * More complicated numbering systems are algorithmic in nature, and require use
michael@0:  * of an RBNF formatter (rule based number formatter), in order to calculate
michael@0:  * the characters to be displayed for a given number. Examples of algorithmic
michael@0:  * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals.
michael@0:  * Formatting rules for many commonly used numbering systems are included in
michael@0:  * the ICU package, based on the numbering system rules defined in CLDR.
michael@0:  * Alternate numbering systems can be specified to a locale by using the
michael@0:  * numbers locale keyword.
michael@0:  */
michael@0: 
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0: 
michael@0: /**
michael@0:  * Opaque UNumberingSystem object for use in C programs.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: struct UNumberingSystem;
michael@0: typedef struct UNumberingSystem UNumberingSystem;  /**< C typedef for struct UNumberingSystem. @draft ICU 52 */
michael@0: 
michael@0: /**
michael@0:  * Opens a UNumberingSystem object using the default numbering system for the specified
michael@0:  * locale.
michael@0:  * @param locale    The locale for which the default numbering system should be opened.
michael@0:  * @param status    A pointer to a UErrorCode to receive any errors. For example, this
michael@0:  *                  may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that
michael@0:  *                  specifies a numbering system unknown to ICU.
michael@0:  * @return          A UNumberingSystem for the specified locale, or NULL if an error
michael@0:  *                  occurred.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT UNumberingSystem * U_EXPORT2
michael@0: unumsys_open(const char *locale, UErrorCode *status);
michael@0: 
michael@0: /**
michael@0:  * Opens a UNumberingSystem object using the name of one of the predefined numbering
michael@0:  * systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec";
michael@0:  * the full list is returned by unumsys_openAvailableNames. Note that some of the names
michael@0:  * listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g.
michael@0:  * default, native, traditional, finance - do not identify specific numbering systems,
michael@0:  * but rather key values that may only be used as part of a locale, which in turn
michael@0:  * defines how they are mapped to a specific numbering system such as "latn" or "hant".
michael@0:  *
michael@0:  * @param name      The name of the numbering system for which a UNumberingSystem object
michael@0:  *                  should be opened.
michael@0:  * @param status    A pointer to a UErrorCode to receive any errors. For example, this
michael@0:  *                  may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that
michael@0:  *                  is unknown to ICU.
michael@0:  * @return          A UNumberingSystem for the specified name, or NULL if an error
michael@0:  *                  occurred.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT UNumberingSystem * U_EXPORT2
michael@0: unumsys_openByName(const char *name, UErrorCode *status);
michael@0: 
michael@0: /**
michael@0:  * Close a UNumberingSystem object. Once closed it may no longer be used.
michael@0:  * @param unumsys   The UNumberingSystem object to close.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT void U_EXPORT2
michael@0: unumsys_close(UNumberingSystem *unumsys);
michael@0: 
michael@0: #if U_SHOW_CPLUSPLUS_API
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: /**
michael@0:  * \class LocalUNumberingSystemPointer
michael@0:  * "Smart pointer" class, closes a UNumberingSystem via unumsys_close().
michael@0:  * For most methods see the LocalPointerBase base class.
michael@0:  * @see LocalPointerBase
michael@0:  * @see LocalPointer
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close);
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: #endif
michael@0: 
michael@0: /**
michael@0:  * Returns an enumeration over the names of all of the predefined numbering systems known
michael@0:  * to ICU.
michael@0:  * @param status    A pointer to a UErrorCode to receive any errors.
michael@0:  * @return          A pointer to a UEnumeration that must be closed with uenum_close(),
michael@0:  *                  or NULL if an error occurred.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT UEnumeration * U_EXPORT2
michael@0: unumsys_openAvailableNames(UErrorCode *status);
michael@0: 
michael@0: /**
michael@0:  * Returns the name of the specified UNumberingSystem object (if it is one of the
michael@0:  * predefined names known to ICU).
michael@0:  * @param unumsys   The UNumberingSystem whose name is desired.
michael@0:  * @return          A pointer to the name of the specified UNumberingSystem object, or
michael@0:  *                  NULL if the name is not one of the ICU predefined names. The pointer
michael@0:  *                  is only valid for the lifetime of the UNumberingSystem object.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT const char * U_EXPORT2
michael@0: unumsys_getName(const UNumberingSystem *unumsys);
michael@0: 
michael@0: /**
michael@0:  * Returns whether the given UNumberingSystem object is for an algorithmic (not purely
michael@0:  * positional) system.
michael@0:  * @param unumsys   The UNumberingSystem whose algorithmic status is desired.
michael@0:  * @return          TRUE if the specified UNumberingSystem object is for an algorithmic
michael@0:  *                  system.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT UBool U_EXPORT2
michael@0: unumsys_isAlgorithmic(const UNumberingSystem *unumsys);
michael@0: 
michael@0: /**
michael@0:  * Returns the radix of the specified UNumberingSystem object. Simple positional
michael@0:  * numbering systems typically have radix 10, but might have a radix of e.g. 16 for
michael@0:  * hexadecimal. The radix is less well-defined for non-positional algorithmic systems.
michael@0:  * @param unumsys   The UNumberingSystem whose radix is desired.
michael@0:  * @return          The radix of the specified UNumberingSystem object.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT int32_t U_EXPORT2
michael@0: unumsys_getRadix(const UNumberingSystem *unumsys);
michael@0: 
michael@0: /**
michael@0:  * Get the description string of the specified UNumberingSystem object. For simple
michael@0:  * positional systems this is the ordered string of digits (with length matching
michael@0:  * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D"
michael@0:  * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For
michael@0:  * algorithmic systems this is the name of the RBNF ruleset used for formatting,
michael@0:  * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for
michael@0:  * "grek".
michael@0:  * @param unumsys   The UNumberingSystem whose description string is desired.
michael@0:  * @param result    A pointer to a buffer to receive the description string.
michael@0:  * @param resultLength  The maximum size of result.
michael@0:  * @param status    A pointer to a UErrorCode to receive any errors.
michael@0:  * @return          The total buffer size needed; if greater than resultLength, the
michael@0:  *                  output was truncated.
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT int32_t U_EXPORT2
michael@0: unumsys_getDescription(const UNumberingSystem *unumsys, UChar *result,
michael@0:                        int32_t resultLength, UErrorCode *status);
michael@0: 
michael@0: #endif  /* U_HIDE_DRAFT_API */
michael@0: 
michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */
michael@0: 
michael@0: #endif