Update ICU to 54.1 step 1

source/i18n/unicode/unum.h

 /*
 *******************************************************************************
-* Copyright (C) 1997-2013, International Business Machines Corporation and others.
+* Copyright (C) 1997-2014, International Business Machines Corporation and others.
 * All Rights Reserved.
 * Modification History:
 *
 *   Date        Name        Description
 *   06/24/99    helena      Integrated Alan's NF enhancements and Java2 bug fixes
 *******************************************************************************
 */
 
 #ifndef _UNUM
 #define _UNUM
 
 #include "unicode/utypes.h"
 
 #if !UCONFIG_NO_FORMATTING
 
 #include "unicode/localpointer.h"
 #include "unicode/uloc.h"
+#include "unicode/ucurr.h"
 #include "unicode/umisc.h"
 #include "unicode/parseerr.h"
 #include "unicode/uformattable.h"
+#include "unicode/udisplaycontext.h"
 
 /**
  * \file
  * \brief C API: NumberFormat
  *
  * <h2> Number Format C API </h2>
  *
  * Number Format C API  Provides functions for
  * formatting and parsing a number.  Also provides methods for
  * determining which locales have number formats, and what their names
@@ skipping 108 matching lines @@
     UNUM_PATTERN_DECIMAL=0,
     /**
      * Decimal format ("normal" style).
      * @stable ICU 2.0
      */
     UNUM_DECIMAL=1,
     /**
      * Currency format with a currency symbol, e.g., "$1.00".
      * @stable ICU 2.0
      */
-    UNUM_CURRENCY,
+    UNUM_CURRENCY=2,
     /**
      * Percent format
      * @stable ICU 2.0
      */
-    UNUM_PERCENT,
+    UNUM_PERCENT=3,
     /**
      * Scientific format
      * @stable ICU 2.1
      */
-    UNUM_SCIENTIFIC,
+    UNUM_SCIENTIFIC=4,
     /**
-     * Spellout rule-based format
+     * Spellout rule-based format. The default ruleset can be specified/changed using
+     * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets
+     * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS.
      * @stable ICU 2.0
      */
-    UNUM_SPELLOUT,
+    UNUM_SPELLOUT=5,
     /** 
-     * Ordinal rule-based format 
+     * Ordinal rule-based format . The default ruleset can be specified/changed using
+     * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets
+     * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS.
      * @stable ICU 3.0
      */
-    UNUM_ORDINAL,
+    UNUM_ORDINAL=6,
     /** 
      * Duration rule-based format 
      * @stable ICU 3.0
      */
-    UNUM_DURATION,
+    UNUM_DURATION=7,
     /** 
      * Numbering system rule-based format
      * @stable ICU 4.2
      */
-    UNUM_NUMBERING_SYSTEM,
+    UNUM_NUMBERING_SYSTEM=8,
     /** 
      * Rule-based format defined by a pattern string.
      * @stable ICU 3.0
      */
-    UNUM_PATTERN_RULEBASED,
+    UNUM_PATTERN_RULEBASED=9,
     /**
      * Currency format with an ISO currency code, e.g., "USD1.00".
      * @stable ICU 4.8
      */
-    UNUM_CURRENCY_ISO,
+    UNUM_CURRENCY_ISO=10,
     /**
      * Currency format with a pluralized currency name,
      * e.g., "1.00 US dollar" and "3.00 US dollars".
      * @stable ICU 4.8
      */
-    UNUM_CURRENCY_PLURAL,
+    UNUM_CURRENCY_PLURAL=11,
+#ifndef U_HIDE_DRAFT_API
+    /**
+     * Currency format for accounting, e.g., "($3.00)" for
+     * negative currency amount instead of "-$3.00" ({@link #UNUM_CURRENCY}).
+     * @draft ICU 53
+     */
+    UNUM_CURRENCY_ACCOUNTING=12,
+    /**
+     * Currency format with a currency symbol given CASH usage, e.g., 
+     * "NT$3" instead of "NT$3.23".
+     * @draft ICU 54
+     */
+    UNUM_CASH_CURRENCY=13,
+#endif /* U_HIDE_DRAFT_API */
+
     /**
      * One more than the highest number format style constant.
      * @stable ICU 4.8
      */
-    UNUM_FORMAT_STYLE_COUNT,
+    UNUM_FORMAT_STYLE_COUNT=14,
+
     /**
      * Default format
      * @stable ICU 2.0
      */
     UNUM_DEFAULT = UNUM_DECIMAL,
     /**
      * Alias for UNUM_PATTERN_DECIMAL
      * @stable ICU 3.0
      */
     UNUM_IGNORE = UNUM_PATTERN_DECIMAL
@@ skipping 31 matching lines @@
 /** The possible number format pad positions. 
  *  @stable ICU 2.0
  */
 typedef enum UNumberFormatPadPosition {
     UNUM_PAD_BEFORE_PREFIX,
     UNUM_PAD_AFTER_PREFIX,
     UNUM_PAD_BEFORE_SUFFIX,
     UNUM_PAD_AFTER_SUFFIX
 } UNumberFormatPadPosition;
 
-#ifndef U_HIDE_DRAFT_API
 /**
  * Constants for specifying short or long format.
- * @draft ICU 51
+ * @stable ICU 51
  */
 typedef enum UNumberCompactStyle {
-  /** @draft ICU 51 */
+  /** @stable ICU 51 */
   UNUM_SHORT,
-  /** @draft ICU 51 */
+  /** @stable ICU 51 */
   UNUM_LONG
-  /** @draft ICU 51 */
+  /** @stable ICU 51 */
 } UNumberCompactStyle;
-#endif /* U_HIDE_DRAFT_API */
 
 /**
  * Constants for specifying currency spacing
  * @stable ICU 4.8
  */
 enum UCurrencySpacing {
     /** @stable ICU 4.8 */
     UNUM_CURRENCY_MATCH,
     /** @stable ICU 4.8 */
     UNUM_CURRENCY_SURROUNDING_MATCH,
@@ skipping 38 matching lines @@
 } UNumberFormatFields;
 
 
 /**
  * Create and return a new UNumberFormat for formatting and parsing
  * numbers.  A UNumberFormat may be used to format numbers by calling
  * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
  * The caller must call {@link #unum_close } when done to release resources
  * used by this object.
  * @param style The type of number format to open: one of
- * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT,
+ * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC,
+ * UNUM_CURRENCY_ISO, UNUM_CURRENCY_PLURAL, UNUM_SPELLOUT,
+ * UNUM_ORDINAL, UNUM_DURATION, UNUM_NUMBERING_SYSTEM,
  * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
  * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
  * number format is opened using the given pattern, which must conform
  * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
  * respectively.
  * @param pattern A pattern specifying the format to use. 
  * This parameter is ignored unless the style is
  * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
  * @param patternLength The number of characters in the pattern, or -1
  * if null-terminated. This parameter is ignored unless the style is
@@ skipping 218 matching lines @@
  */
 U_STABLE int32_t U_EXPORT2
 unum_formatDoubleCurrency(const UNumberFormat* fmt,
                           double number,
                           UChar* currency,
                           UChar* result,
                           int32_t resultLength,
                           UFieldPosition* pos,
                           UErrorCode* status);
 
-#ifndef U_HIDE_DRAFT_API
 /**
  * Format a UFormattable into a string.
  * @param fmt the formatter to use
  * @param number the number to format, as a UFormattable
  * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
  * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
  * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
  * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
  * @param resultLength the maximum number of UChars to write to result
  * @param pos a pointer to a UFieldPosition.  On input,
  * position->field is read.  On output, position->beginIndex and
  * position->endIndex indicate the beginning and ending indices of
  * field number position->field, if such a field exists.  This
  * parameter may be NULL, in which case it is ignored.
  * @param status a pointer to an input-output UErrorCode
  * @return the total buffer size needed; if greater than resultLength,
  * the output was truncated. Will return 0 on error.
  * @see unum_parseToUFormattable
- * @draft ICU 52
+ * @stable ICU 52
  */
-U_DRAFT int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
 unum_formatUFormattable(const UNumberFormat* fmt,
                         const UFormattable *number,
                         UChar *result,
                         int32_t resultLength,
                         UFieldPosition *pos,
                         UErrorCode *status);
-#endif  /* U_HIDE_DRAFT_API */
 
 /**
 * Parse a string into an integer using a UNumberFormat.
 * The string will be parsed according to the UNumberFormat's locale.
 * @param fmt The formatter to use.
 * @param text The text to parse.
 * @param textLength The length of text, or -1 if null-terminated.
 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
 * to begin parsing.  If not NULL, on output the offset at which parsing ended.
 * @param status A pointer to an UErrorCode to receive any errors
@@ skipping 115 matching lines @@
  * @stable ICU 3.0
  */
 U_STABLE double U_EXPORT2
 unum_parseDoubleCurrency(const UNumberFormat* fmt,
                          const UChar* text,
                          int32_t textLength,
                          int32_t* parsePos, /* 0 = start */
                          UChar* currency,
                          UErrorCode* status);
 
-#ifndef U_HIDE_DRAFT_API
 /**
  * Parse a UChar string into a UFormattable.
  * Example code:
  * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable
  * @param fmt the formatter to use
  * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close).
  * @param text the text to parse
  * @param textLength the length of text, or -1 if null-terminated
  * @param parsePos a pointer to an offset index into text at which to
  * begin parsing. On output, *parsePos will point after the last
  * parsed character.  This parameter may be NULL in which case parsing
  * begins at offset 0.
  * @param status a pointer to an input-output UErrorCode
  * @return the UFormattable.  Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable.
  * @see ufmt_getType
  * @see ufmt_close
- * @draft ICU 52
+ * @stable ICU 52
  */
-U_DRAFT UFormattable* U_EXPORT2
+U_STABLE UFormattable* U_EXPORT2
 unum_parseToUFormattable(const UNumberFormat* fmt,
                          UFormattable *result,
                          const UChar* text,
                          int32_t textLength,
                          int32_t* parsePos, /* 0 = start */
                          UErrorCode* status);
-#endif  /* U_HIDE_DRAFT_API */
 
 /**
  * Set the pattern used by a UNumberFormat.  This can only be used
  * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR
  * in the status.
  * @param format The formatter to set.
  * @param localized TRUE if the pattern is localized, FALSE otherwise.
  * @param pattern The new pattern
  * @param patternLength The length of pattern, or -1 if null-terminated.
  * @param parseError A pointer to UParseError to recieve information
@@ skipping 32 matching lines @@
 * This function is useful for determining the loop ending condition for
 * calls to {@link #unum_getAvailable }.
 * @return The number of locales for which decimal formatting patterns are available.
 * @see unum_getAvailable
 * @stable ICU 2.0
 */
 U_STABLE int32_t U_EXPORT2 
 unum_countAvailable(void);
 
 #if UCONFIG_HAVE_PARSEALLINPUT
+/* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */
 /**
  * @internal
  */
 typedef enum UNumberFormatAttributeValue {
+#ifndef U_HIDE_INTERNAL_API
   /** @internal */
   UNUM_NO = 0,
   /** @internal */
   UNUM_YES = 1,
   /** @internal */
   UNUM_MAYBE = 2
+#endif /* U_HIDE_INTERNAL_API */
 } UNumberFormatAttributeValue;
 #endif
 
 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
 typedef enum UNumberFormatAttribute {
   /** Parse integers only */
   UNUM_PARSE_INT_ONLY,
   /** Use grouping separator */
   UNUM_GROUPING_USED,
   /** Always show decimal point */
@@ skipping 37 matching lines @@
    * @stable ICU 3.0
    */
   UNUM_LENIENT_PARSE,
 #if UCONFIG_HAVE_PARSEALLINPUT
   /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic).
    * This is an internal ICU API. Do not use.
    * @internal
    */
   UNUM_PARSE_ALL_INPUT = UNUM_LENIENT_PARSE + 1,
 #endif
-#ifndef U_HIDE_DRAFT_API
   /** 
     * Scale, which adjusts the position of the
     * decimal point when formatting.  Amounts will be multiplied by 10 ^ (scale)
     * before they are formatted.  The default value for the scale is 0 ( no adjustment ).
     *
     * <p>Example: setting the scale to 3, 123 formats as "123,000"
     * <p>Example: setting the scale to -4, 123 formats as "0.0123"
     *
-   * @draft ICU 51 */
+   * @stable ICU 51 */
   UNUM_SCALE = UNUM_LENIENT_PARSE + 2,
-#endif /* U_HIDE_DRAFT_API */
 
 #ifndef U_HIDE_INTERNAL_API
   /** Count of "regular" numeric attributes.
    * @internal */
   UNUM_NUMERIC_ATTRIBUTE_COUNT = UNUM_LENIENT_PARSE + 3,
+#endif  /* U_HIDE_INTERNAL_API */
 
+#ifndef U_HIDE_DRAFT_API
+  /** 
+   * if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose,
+   * otherwise it is UNUM_CURRENCY_CASH purpose
+   * Default: 0 (UNUM_CURRENCY_STANDARD purpose)
+   * @draft ICU 54
+   */
+  UNUM_CURRENCY_USAGE = UNUM_LENIENT_PARSE + 4,
+#endif  /* U_HIDE_DRAFT_API */
+
+  /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed in .h file variable declararions */
   /** One below the first bitfield-boolean item.
    * All items after this one are stored in boolean form.
    * @internal */
   UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF,
-#endif  /* U_HIDE_INTERNAL_API */
 
   /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating.
    * For example,  formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing.
    * Default: 0 (not set)
    * @stable ICU 50
    */
   UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS = 0x1000,
   /** 
    * if this attribute is set to 1, specifies that, if the pattern doesn't contain an exponent, the exponent will not be parsed. If the pattern does contain an exponent, this attribute has no effect.
    * Has no effect on formatting.
    * Default: 0 (unset)
    * @stable ICU 50
    */
   UNUM_PARSE_NO_EXPONENT,
 
-#ifndef U_HIDE_INTERNAL_API
+#ifndef U_HIDE_DRAFT_API
+  /** 
+   * if this attribute is set to 1, specifies that, if the pattern contains a 
+   * decimal mark the input is required to have one. If this attribute is set to 0,
+   * specifies that input does not have to contain a decimal mark.
+   * Has no effect on formatting.
+   * Default: 0 (unset)
+   * @draft ICU 54
+   */
+  UNUM_PARSE_DECIMAL_MARK_REQUIRED = UNUM_PARSE_NO_EXPONENT+1,
+#endif  /* U_HIDE_DRAFT_API */
+
+  /* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed in .h file variable declararions */
   /** Limit of boolean attributes.
    * @internal */
-  UNUM_LIMIT_BOOLEAN_ATTRIBUTE
-#endif  /* U_HIDE_INTERNAL_API */
+  UNUM_LIMIT_BOOLEAN_ATTRIBUTE = UNUM_PARSE_NO_EXPONENT+2
 } UNumberFormatAttribute;
 
 /**
 * Get a numeric attribute associated with a UNumberFormat.
 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 * @param fmt The formatter to query.
 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
@@ skipping 80 matching lines @@
   UNUM_POSITIVE_SUFFIX,
   /** Negative prefix */
   UNUM_NEGATIVE_PREFIX,
   /** Negative suffix */
   UNUM_NEGATIVE_SUFFIX,
   /** The character used to pad to the format width. */
   UNUM_PADDING_CHARACTER,
   /** The ISO currency code */
   UNUM_CURRENCY_CODE,
   /**
-   * The default rule set.  This is only available with rule-based formatters.
+   * The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:",
+   * "%spellout-ordinal-masculine-plural:", "%spellout-ordinal-feminine:", or
+   * "%spellout-ordinal-neuter:". The available public rulesets can be listed using
+   * unum_getTextAttribute with UNUM_PUBLIC_RULESETS. This is only available with
+   * rule-based formatters.
    * @stable ICU 3.0
    */
   UNUM_DEFAULT_RULESET,
   /**
    * The public rule sets.  This is only available with rule-based formatters.
    * This is a read-only attribute.  The public rulesets are returned as a
-   * single string, with each ruleset name delimited by ';' (semicolon).
+   * single string, with each ruleset name delimited by ';' (semicolon). See the
+   * CLDR LDML spec for more information about RBNF rulesets:
+   * http://www.unicode.org/reports/tr35/tr35-numbers.html#Rule-Based_Number_Formatting
    * @stable ICU 3.0
    */
   UNUM_PUBLIC_RULESETS
 } UNumberFormatTextAttribute;
 
 /**
 * Get a text attribute associated with a UNumberFormat.
 * An example of a text attribute is the suffix for positive numbers.  If the formatter
 * does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status.
 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
@@ skipping 137 matching lines @@
    */
   UNUM_SEVEN_DIGIT_SYMBOL = 24,
   /** Eight
    * @stable ICU 4.6
    */
   UNUM_EIGHT_DIGIT_SYMBOL = 25,
   /** Nine
    * @stable ICU 4.6
    */
   UNUM_NINE_DIGIT_SYMBOL = 26,
+
+#ifndef U_HIDE_DRAFT_API
+  /** Multiplication sign
+   * @draft ICU 54
+   */
+  UNUM_EXPONENT_MULTIPLICATION_SYMBOL = 27,
+#endif  /* U_HIDE_DRAFT_API */
+
   /** count symbol constants */
-  UNUM_FORMAT_SYMBOL_COUNT = 27
+  UNUM_FORMAT_SYMBOL_COUNT = 28
 } UNumberFormatSymbol;
 
 /**
 * Get a symbol associated with a UNumberFormat.
 * A UNumberFormat uses symbols to represent the special locale-dependent
 * characters in a number, for example the percent sign. This API is not
 * supported for rule-based formatters.
 * @param fmt The formatter to query.
 * @param symbol The UNumberFormatSymbol constant for the symbol to get
 * @param buffer The string buffer that will receive the symbol string;
@@ skipping 40 matching lines @@
  * @param type type of the locale we're looking for (valid or actual) 
  * @param status error code for the operation
  * @return the locale name
  * @stable ICU 2.8
  */
 U_STABLE const char* U_EXPORT2
 unum_getLocaleByType(const UNumberFormat *fmt,
                      ULocDataLocaleType type,
                      UErrorCode* status); 
 
+#ifndef U_HIDE_DRAFT_API
+/**
+ * Set a particular UDisplayContext value in the formatter, such as
+ * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
+ * @param fmt The formatter for which to set a UDisplayContext value.
+ * @param value The UDisplayContext value to set.
+ * @param status A pointer to an UErrorCode to receive any errors
+ * @draft ICU 53
+ */
+U_DRAFT void U_EXPORT2
+unum_setContext(UNumberFormat* fmt, UDisplayContext value, UErrorCode* status);
+
+/**
+ * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
+ * such as UDISPCTX_TYPE_CAPITALIZATION.
+ * @param fmt The formatter to query.
+ * @param type The UDisplayContextType whose value to return
+ * @param status A pointer to an UErrorCode to receive any errors
+ * @return The UDisplayContextValue for the specified type.
+ * @draft ICU 53
+ */
+U_DRAFT UDisplayContext U_EXPORT2
+unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status);
+
+#endif  /* U_HIDE_DRAFT_API */
+
 #endif /* #if !UCONFIG_NO_FORMATTING */
 
 #endif