+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 1997-2015, International Business Machines Corporation and others.
#include "unicode/parseerr.h"
#include "unicode/uformattable.h"
#include "unicode/udisplaycontext.h"
+#include "unicode/ufieldpositer.h"
/**
* \file
- * \brief C API: NumberFormat
+ * \brief C API: Compatibility APIs for number formatting.
*
* <h2> Number Format C API </h2>
+ *
+ * <p><strong>IMPORTANT:</strong> New users with are strongly encouraged to
+ * see if unumberformatter.h fits their use case. Although not deprecated,
+ * this header is provided for backwards compatibility only.
*
* Number Format C API Provides functions for
* formatting and parsing a number. Also provides methods for
* <P>
* You can also control the display of numbers with such function as
* unum_getAttributes() and unum_setAttributes(), which let you set the
- * miminum fraction digits, grouping, etc.
+ * minimum fraction digits, grouping, etc.
* @see UNumberFormatAttributes for more details
* <P>
* You can also use forms of the parse and format methods with
* </ul>
* <p>
* It is also possible to change or set the symbols used for a particular
- * locale like the currency symbol, the grouping seperator , monetary seperator
+ * locale like the currency symbol, the grouping separator , monetary separator
* etc by making use of functions unum_setSymbols() and unum_getSymbols().
*/
*/
UNUM_DECIMAL=1,
/**
- * Currency format with a currency symbol, e.g., "$1.00".
+ * Currency format (generic).
+ * Defaults to UNUM_CURRENCY_STANDARD style
+ * (using currency symbol, e.g., "$1.00", with non-accounting
+ * style for negative values e.g. using minus sign).
+ * The specific style may be specified using the -cf- locale key.
* @stable ICU 2.0
*/
UNUM_CURRENCY=2,
/**
* Currency format for accounting, e.g., "($3.00)" for
* negative currency amount instead of "-$3.00" ({@link #UNUM_CURRENCY}).
+ * Overrides any style specified using -cf- key in locale.
* @stable ICU 53
*/
UNUM_CURRENCY_ACCOUNTING=12,
-#ifndef U_HIDE_DRAFT_API
/**
* Currency format with a currency symbol given CASH usage, e.g.,
* "NT$3" instead of "NT$3.23".
- * @draft ICU 54
+ * @stable ICU 54
*/
UNUM_CASH_CURRENCY=13,
-#endif /* U_HIDE_DRAFT_API */
-#ifndef U_HIDE_DRAFT_API
/**
* Decimal format expressed using compact notation
* (short form, corresponds to UNumberCompactStyle=UNUM_SHORT)
* e.g. "23K", "45B"
- * @draft ICU 56
+ * @stable ICU 56
*/
UNUM_DECIMAL_COMPACT_SHORT=14,
/**
* Decimal format expressed using compact notation
* (long form, corresponds to UNumberCompactStyle=UNUM_LONG)
* e.g. "23 thousand", "45 billion"
- * @draft ICU 56
+ * @stable ICU 56
*/
UNUM_DECIMAL_COMPACT_LONG=15,
-#endif /* U_HIDE_DRAFT_API */
+ /**
+ * Currency format with a currency symbol, e.g., "$1.00",
+ * using non-accounting style for negative values (e.g. minus sign).
+ * Overrides any style specified using -cf- key in locale.
+ * @stable ICU 56
+ */
+ UNUM_CURRENCY_STANDARD=16,
+#ifndef U_HIDE_DEPRECATED_API
/**
- * One more than the highest number format style constant.
- * @stable ICU 4.8
+ * One more than the highest normal UNumberFormatStyle value.
+ * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
*/
- UNUM_FORMAT_STYLE_COUNT=16,
+ UNUM_FORMAT_STYLE_COUNT=17,
+#endif /* U_HIDE_DEPRECATED_API */
/**
* Default format
UNUM_IGNORE = UNUM_PATTERN_DECIMAL
} UNumberFormatStyle;
-/** The possible number format rounding modes.
- * @stable ICU 2.0
+/** The possible number format rounding modes.
+ *
+ * <p>
+ * For more detail on rounding modes, see:
+ * http://userguide.icu-project.org/formatparse/numbers/rounding-modes
+ *
+ * @stable ICU 2.0
*/
typedef enum UNumberFormatRoundingMode {
UNUM_ROUND_CEILING,
UNUM_CURRENCY_SURROUNDING_MATCH,
/** @stable ICU 4.8 */
UNUM_CURRENCY_INSERT,
- /** @stable ICU 4.8 */
+
+ /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
+ * it is needed for layout of DecimalFormatSymbols object. */
+ /**
+ * One more than the highest normal UCurrencySpacing value.
+ * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+ */
UNUM_CURRENCY_SPACING_COUNT
};
typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */
UNUM_PERMILL_FIELD,
/** @stable ICU 49 */
UNUM_SIGN_FIELD,
- /** @stable ICU 49 */
+#ifndef U_HIDE_DEPRECATED_API
+ /**
+ * One more than the highest normal UNumberFormatFields value.
+ * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+ */
UNUM_FIELD_COUNT
+#endif /* U_HIDE_DEPRECATED_API */
} UNumberFormatFields;
* number format is opened using the given pattern, which must conform
* to the syntax described in DecimalFormat or RuleBasedNumberFormat,
* respectively.
+ *
+ * <p><strong>NOTE::</strong> New users with are strongly encouraged to
+ * use unumf_openWithSkeletonAndLocale instead of unum_open.
+ *
* @param pattern A pattern specifying the format to use.
* This parameter is ignored unless the style is
* UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
U_NAMESPACE_END
-#endif
+#endif // U_SHOW_CPLUSPLUS_API
/**
* Open a copy of a UNumberFormat.
UFieldPosition *pos, /* 0 if ignore */
UErrorCode* status);
+/**
+* Format a double using a UNumberFormat according to the UNumberFormat's locale,
+* and initialize a UFieldPositionIterator that enumerates the subcomponents of
+* the resulting string.
+*
+* @param format
+* The formatter to use.
+* @param number
+* The number to format.
+* @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 size of result.
+* @param fpositer
+* A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}
+* (may be NULL if field position information is not needed, but in this
+* case it's preferable to use {@link #unum_formatDouble}). Iteration
+* information already present in the UFieldPositionIterator is deleted,
+* and the iterator is reset to apply to the fields in the formatted
+* string created by this function call. The field values and indexes
+* returned by {@link #ufieldpositer_next} represent fields denoted by
+* the UNumberFormatFields enum. Fields are not returned in a guaranteed
+* order. Fields cannot overlap, but they may nest. For example, 1234
+* could format as "1,234" which might consist of a grouping separator
+* field for ',' and an integer field encompassing the entire string.
+* @param status
+* A pointer to an UErrorCode to receive any errors
+* @return
+* The total buffer size needed; if greater than resultLength, the
+* output was truncated.
+* @see unum_formatDouble
+* @see unum_parse
+* @see unum_parseDouble
+* @see UFieldPositionIterator
+* @see UNumberFormatFields
+* @stable ICU 59
+*/
+U_STABLE int32_t U_EXPORT2
+unum_formatDoubleForFields(const UNumberFormat* format,
+ double number,
+ UChar* result,
+ int32_t resultLength,
+ UFieldPositionIterator* fpositer,
+ UErrorCode* status);
+
+
/**
* Format a decimal number using a UNumberFormat.
* The number will be formatted according to the UNumberFormat's locale.
* @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
+ * @param parseError A pointer to UParseError to receive information
* about errors occurred during parsing, or NULL if no parse error
* information is desired.
* @param status A pointer to an input-output UErrorCode.
UNUM_YES = 1,
/** @internal */
UNUM_MAYBE = 2
+#else
+ /** @internal */
+ UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN
#endif /* U_HIDE_INTERNAL_API */
} UNumberFormatAttributeValue;
#endif
* This is an internal ICU API. Do not use.
* @internal
*/
- UNUM_PARSE_ALL_INPUT = UNUM_LENIENT_PARSE + 1,
+ UNUM_PARSE_ALL_INPUT = 20,
#endif
/**
* Scale, which adjusts the position of the
* <p>Example: setting the scale to 3, 123 formats as "123,000"
* <p>Example: setting the scale to -4, 123 formats as "0.0123"
*
+ * This setting is analogous to getMultiplierScale() and setMultiplierScale() in decimfmt.h.
+ *
* @stable ICU 51 */
- UNUM_SCALE = UNUM_LENIENT_PARSE + 2,
-
+ UNUM_SCALE = 21,
+#ifndef U_HIDE_INTERNAL_API
+ /**
+ * Minimum grouping digits, technology preview.
+ * See DecimalFormat::getMinimumGroupingDigits().
+ *
+ * @internal technology preview
+ */
+ UNUM_MINIMUM_GROUPING_DIGITS = 22,
+ /* TODO: test C API when it becomes @draft */
+#endif /* U_HIDE_INTERNAL_API */
#ifndef U_HIDE_INTERNAL_API
/** Count of "regular" numeric attributes.
+ * This internal value was unused by ICU and removed in ICU 56.
+ * Unfortunately CF references it (but does not use it) so it
+ * is being temporarily restored per <rdar://problem/23544928>
* @internal */
- UNUM_NUMERIC_ATTRIBUTE_COUNT = UNUM_LENIENT_PARSE + 3,
+ UNUM_NUMERIC_ATTRIBUTE_COUNT = 23, /* UNUM_LENIENT_PARSE + 4 */
+
+ /** For unum_formatDouble and similar, Boolean that controls
+ * whether to pin double to string conversion at DBL_DIG=15
+ * (from <float.h>) significant digits. This was the default
+ * in open-source ICU before ICU 61,and is currently the default
+ * in Apple ICU, but can be overriden. <rdar://problem/39240173>.
+ * @internal */
+ UNUM_FORMAT_WITH_FULL_PRECISION = 48,
#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
+ * @stable ICU 54
*/
- UNUM_CURRENCY_USAGE = UNUM_LENIENT_PARSE + 4,
-#endif /* U_HIDE_DRAFT_API */
+ UNUM_CURRENCY_USAGE = 23,
/* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed in .h file variable declararions */
/** One below the first bitfield-boolean item.
* Default: 0 (unset)
* @stable ICU 50
*/
- UNUM_PARSE_NO_EXPONENT,
+ UNUM_PARSE_NO_EXPONENT = 0x1001,
-#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
+ * @stable ICU 54
*/
- UNUM_PARSE_DECIMAL_MARK_REQUIRED = UNUM_PARSE_NO_EXPONENT+1,
-#endif /* U_HIDE_DRAFT_API */
+ UNUM_PARSE_DECIMAL_MARK_REQUIRED = 0x1002,
/* The following cannot be #ifndef U_HIDE_INTERNAL_API, needed in .h file variable declararions */
/** Limit of boolean attributes.
* @internal */
- UNUM_LIMIT_BOOLEAN_ATTRIBUTE = UNUM_PARSE_NO_EXPONENT+2
+ UNUM_LIMIT_BOOLEAN_ATTRIBUTE = 0x1003,
+
+ /**
+ * Whether parsing is sensitive to case (lowercase/uppercase).
+ * TODO: Add to the test suite.
+ * @internal This API is a technical preview. It may change in an upcoming release.
+ */
+ UNUM_PARSE_CASE_SENSITIVE = 0x1004,
+
+ /**
+ * Formatting: whether to show the plus sign on non-negative numbers.
+ * TODO: Add to the test suite.
+ * @internal This API is a technical preview. It may change in an upcoming release.
+ */
+ UNUM_SIGN_ALWAYS_SHOWN = 0x1005,
} UNumberFormatAttribute;
/**
* 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,
-* UNUM_SCALE.
+* UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS.
* @return The value of attr.
* @see unum_setAttribute
* @see unum_getDoubleAttribute
* 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,
-* UNUM_LENIENT_PARSE, or UNUM_SCALE.
+* UNUM_LENIENT_PARSE, UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS.
* @param newValue The new value of attr.
* @see unum_getAttribute
* @see unum_getDoubleAttribute
*/
UNUM_NINE_DIGIT_SYMBOL = 26,
-#ifndef U_HIDE_DRAFT_API
/** Multiplication sign
- * @draft ICU 54
+ * @stable ICU 54
*/
UNUM_EXPONENT_MULTIPLICATION_SYMBOL = 27,
-#endif /* U_HIDE_DRAFT_API */
- /** count symbol constants */
+#ifndef U_HIDE_DEPRECATED_API
+ /**
+ * One more than the highest normal UNumberFormatSymbol value.
+ * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+ */
UNUM_FORMAT_SYMBOL_COUNT = 28
+#endif /* U_HIDE_DEPRECATED_API */
} UNumberFormatSymbol;
/**
projects / apple / icu.git / blobdiff