// © 2018 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
-#if !UCONFIG_NO_FORMATTING
#ifndef __NUMBERRANGEFORMATTER_H__
#define __NUMBERRANGEFORMATTER_H__
+#include "unicode/utypes.h"
+
+#if U_SHOW_CPLUSPLUS_API
+
+#if !UCONFIG_NO_FORMATTING
+
#include <atomic>
#include "unicode/appendable.h"
#include "unicode/fieldpos.h"
#include "unicode/fpositer.h"
#include "unicode/numberformatter.h"
-#ifndef U_HIDE_DRAFT_API
-
/**
* \file
* \brief C++ API: Library for localized formatting of number, currency, and unit ranges.
/**
* Defines how to merge fields that are identical across the range sign.
*
- * @draft ICU 63
+ * @stable ICU 63
*/
typedef enum UNumberRangeCollapse {
/**
*
* The heuristics used for this option are subject to change over time.
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_RANGE_COLLAPSE_AUTO,
/**
* Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_RANGE_COLLAPSE_NONE,
* Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousand
* kilograms"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_RANGE_COLLAPSE_UNIT,
* Collapse any field that is equal across the range sign. May introduce ambiguity on the magnitude of the
* number. Example: "3.2 – 5.3 thousand kilograms"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_RANGE_COLLAPSE_ALL
} UNumberRangeCollapse;
* Defines the behavior when the two numbers in the range are identical after rounding. To programmatically detect
* when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.
*
- * @draft ICU 63
+ * @stable ICU 63
* @see NumberRangeFormatter
*/
typedef enum UNumberRangeIdentityFallback {
/**
* Show the number as a single value rather than a range. Example: "$5"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_IDENTITY_FALLBACK_SINGLE_VALUE,
* Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding,
* show the single value. Example: "~$5" or "$5"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE,
* Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the
* inputs are the same. Example: "~$5"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
* Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the
* same. Example (with RangeCollapse.NONE): "$5 – $5"
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UNUM_IDENTITY_FALLBACK_RANGE
} UNumberRangeIdentityFallback;
* Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range
* were equal or not, and whether or not the identity fallback was applied.
*
- * @draft ICU 63
+ * @stable ICU 63
* @see NumberRangeFormatter
*/
typedef enum UNumberRangeIdentityResult {
/**
* Used to indicate that the two numbers in the range were equal, even before any rounding rules were applied.
*
- * @draft ICU 63
+ * @stable ICU 63
* @see NumberRangeFormatter
*/
UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING,
/**
* Used to indicate that the two numbers in the range were equal, but only after rounding rules were applied.
*
- * @draft ICU 63
+ * @stable ICU 63
* @see NumberRangeFormatter
*/
UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING,
/**
* Used to indicate that the two numbers in the range were not equal, even after rounding rules were applied.
*
- * @draft ICU 63
+ * @stable ICU 63
* @see NumberRangeFormatter
*/
UNUM_IDENTITY_RESULT_NOT_EQUAL,
} UNumberRangeIdentityResult;
-#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
namespace number { // icu::number
* @param formatter
* The formatter to use for both numbers in the range.
* @return The fluent chain.
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) const &;
* The formatter to use for both numbers in the range.
* @return The fluent chain.
* @see #numberFormatterBoth
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterBoth(const UnlocalizedNumberFormatter &formatter) &&;
* The formatter to use for both numbers in the range.
* @return The fluent chain.
* @see #numberFormatterBoth
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) const &;
* The formatter to use for both numbers in the range.
* @return The fluent chain.
* @see #numberFormatterBoth
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterBoth(UnlocalizedNumberFormatter &&formatter) &&;
* @param formatterFirst
* The formatter to use for the first number in the range.
* @return The fluent chain.
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) const &;
* The formatter to use for the first number in the range.
* @return The fluent chain.
* @see #numberFormatterFirst
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterFirst(const UnlocalizedNumberFormatter &formatterFirst) &&;
* The formatter to use for the first number in the range.
* @return The fluent chain.
* @see #numberFormatterFirst
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) const &;
* The formatter to use for the first number in the range.
* @return The fluent chain.
* @see #numberFormatterFirst
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterFirst(UnlocalizedNumberFormatter &&formatterFirst) &&;
* @param formatterSecond
* The formatter to use for the second number in the range.
* @return The fluent chain.
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) const &;
* The formatter to use for the second number in the range.
* @return The fluent chain.
* @see #numberFormatterSecond
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterSecond(const UnlocalizedNumberFormatter &formatterSecond) &&;
* The formatter to use for the second number in the range.
* @return The fluent chain.
* @see #numberFormatterSecond
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) const &;
* The formatter to use for the second number in the range.
* @return The fluent chain.
* @see #numberFormatterSecond
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived numberFormatterSecond(UnlocalizedNumberFormatter &&formatterSecond) &&;
* @param collapse
* The collapsing strategy to use for this range.
* @return The fluent chain.
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived collapse(UNumberRangeCollapse collapse) const &;
* The collapsing strategy to use for this range.
* @return The fluent chain.
* @see #collapse
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived collapse(UNumberRangeCollapse collapse) &&;
* @param identityFallback
* The strategy to use when formatting two numbers that end up being the same.
* @return The fluent chain.
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived identityFallback(UNumberRangeIdentityFallback identityFallback) const &;
* The strategy to use when formatting two numbers that end up being the same.
* @return The fluent chain.
* @see #identityFallback
- * @draft ICU 63
+ * @stable ICU 63
*/
Derived identityFallback(UNumberRangeIdentityFallback identityFallback) &&;
+#ifndef U_HIDE_DRAFT_API
/**
* Returns the current (Un)LocalizedNumberRangeFormatter as a LocalPointer
* wrapping a heap-allocated copy of the current object.
* @draft ICU 64
*/
LocalPointer<Derived> clone() &&;
+#endif /* U_HIDE_DRAFT_API */
/**
* Sets the UErrorCode if an error occurred in the fluent chain.
* Preserves older error codes in the outErrorCode.
* @return TRUE if U_FAILURE(outErrorCode)
- * @draft ICU 63
+ * @stable ICU 63
*/
UBool copyErrorTo(UErrorCode &outErrorCode) const {
if (U_FAILURE(outErrorCode)) {
* Instances of this class are immutable and thread-safe.
*
* @see NumberRangeFormatter
- * @draft ICU 63
+ * @stable ICU 63
*/
class U_I18N_API UnlocalizedNumberRangeFormatter
: public NumberRangeFormatterSettings<UnlocalizedNumberRangeFormatter>, public UMemory {
* @param locale
* The locale to use when loading data for number formatting.
* @return The fluent chain.
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter locale(const icu::Locale &locale) const &;
* The locale to use when loading data for number formatting.
* @return The fluent chain.
* @see #locale
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter locale(const icu::Locale &locale) &&;
/**
* Default constructor: puts the formatter into a valid but undefined state.
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UnlocalizedNumberRangeFormatter() = default;
/**
* Returns a copy of this UnlocalizedNumberRangeFormatter.
- * @draft ICU 63
+ * @stable ICU 63
*/
UnlocalizedNumberRangeFormatter(const UnlocalizedNumberRangeFormatter &other);
/**
* Move constructor:
* The source UnlocalizedNumberRangeFormatter will be left in a valid but undefined state.
- * @draft ICU 63
+ * @stable ICU 63
*/
UnlocalizedNumberRangeFormatter(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
/**
* Copy assignment operator.
- * @draft ICU 63
+ * @stable ICU 63
*/
UnlocalizedNumberRangeFormatter& operator=(const UnlocalizedNumberRangeFormatter& other);
/**
* Move assignment operator:
* The source UnlocalizedNumberRangeFormatter will be left in a valid but undefined state.
- * @draft ICU 63
+ * @stable ICU 63
*/
UnlocalizedNumberRangeFormatter& operator=(UnlocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
* Instances of this class are immutable and thread-safe.
*
* @see NumberFormatter
- * @draft ICU 63
+ * @stable ICU 63
*/
class U_I18N_API LocalizedNumberRangeFormatter
: public NumberRangeFormatterSettings<LocalizedNumberRangeFormatter>, public UMemory {
* @param status
* Set if an error occurs while formatting.
* @return A FormattedNumberRange object; call .toString() to get the string.
- * @draft ICU 63
+ * @stable ICU 63
*/
FormattedNumberRange formatFormattableRange(
const Formattable& first, const Formattable& second, UErrorCode& status) const;
/**
* Default constructor: puts the formatter into a valid but undefined state.
*
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter() = default;
/**
* Returns a copy of this LocalizedNumberRangeFormatter.
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter(const LocalizedNumberRangeFormatter &other);
/**
* Move constructor:
* The source LocalizedNumberRangeFormatter will be left in a valid but undefined state.
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
/**
* Copy assignment operator.
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter& operator=(const LocalizedNumberRangeFormatter& other);
/**
* Move assignment operator:
* The source LocalizedNumberRangeFormatter will be left in a valid but undefined state.
- * @draft ICU 63
+ * @stable ICU 63
*/
LocalizedNumberRangeFormatter& operator=(LocalizedNumberRangeFormatter&& src) U_NOEXCEPT;
void formatImpl(impl::UFormattedNumberRangeData& results, bool equalBeforeRounding,
UErrorCode& status) const;
-#endif
+#endif /* U_HIDE_INTERNAL_API */
/**
* Destruct this LocalizedNumberRangeFormatter, cleaning up any memory it might own.
- * @draft ICU 63
+ * @stable ICU 63
*/
~LocalizedNumberRangeFormatter();
*
* Instances of this class are immutable and thread-safe.
*
- * @draft ICU 63
+ * @stable ICU 63
*/
class U_I18N_API FormattedNumberRange : public UMemory, public FormattedValue {
public:
*
* For more information, see FormattedValue::toString()
*
- * @draft ICU 63
+ * @stable ICU 63
*/
UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
*
* For more information, see FormattedValue::appendTo()
*
- * @draft ICU 63
+ * @stable ICU 63
*/
Appendable &appendTo(Appendable &appendable, UErrorCode& status) const U_OVERRIDE;
/** @copydoc FormattedValue::nextPosition() */
UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
+#ifndef U_HIDE_DRAFT_API
/**
* Determines the start (inclusive) and end (exclusive) indices of the next occurrence of the given
* <em>field</em> in the output string. This allows you to determine the locations of, for example,
* @see #getFirstDecimal
*/
UnicodeString getSecondDecimal(UErrorCode& status) const;
+#endif // U_HIDE_DRAFT_API
/**
* Returns whether the pair of numbers was successfully formatted as a range or whether an identity fallback was
* identity fallback was used.
*
* @return An indication the resulting identity situation in the formatted number range.
- * @draft ICU 63
+ * @stable ICU 63
* @see UNumberRangeIdentityFallback
*/
UNumberRangeIdentityResult getIdentityResult(UErrorCode& status) const;
/**
* Move constructor:
* Leaves the source FormattedNumberRange in an undefined state.
- * @draft ICU 63
+ * @stable ICU 63
*/
FormattedNumberRange(FormattedNumberRange&& src) U_NOEXCEPT;
/**
* Move assignment:
* Leaves the source FormattedNumberRange in an undefined state.
- * @draft ICU 63
+ * @stable ICU 63
*/
FormattedNumberRange& operator=(FormattedNumberRange&& src) U_NOEXCEPT;
/**
* Destruct an instance of FormattedNumberRange, cleaning up any memory it might own.
- * @draft ICU 63
+ * @stable ICU 63
*/
~FormattedNumberRange();
/**
* Internal constructor from data type. Adopts the data pointer.
- * @internal
*/
explicit FormattedNumberRange(impl::UFormattedNumberRangeData *results)
: fData(results), fErrorCode(U_ZERO_ERROR) {}
/**
* See the main description in numberrangeformatter.h for documentation and examples.
*
- * @draft ICU 63
+ * @stable ICU 63
*/
class U_I18N_API NumberRangeFormatter final {
public:
* known at the call site.
*
* @return An {@link UnlocalizedNumberRangeFormatter}, to be used for chaining.
- * @draft ICU 63
+ * @stable ICU 63
*/
static UnlocalizedNumberRangeFormatter with();
* @param locale
* The locale from which to load formats and symbols for number range formatting.
* @return A {@link LocalizedNumberRangeFormatter}, to be used for chaining.
- * @draft ICU 63
+ * @stable ICU 63
*/
static LocalizedNumberRangeFormatter withLocale(const Locale &locale);
} // namespace number
U_NAMESPACE_END
-#endif // U_SHOW_CPLUSPLUS_API
-#endif // U_HIDE_DRAFT_API
+#endif /* #if !UCONFIG_NO_FORMATTING */
+
+#endif /* U_SHOW_CPLUSPLUS_API */
#endif // __NUMBERRANGEFORMATTER_H__
-#endif /* #if !UCONFIG_NO_FORMATTING */
projects / apple / icu.git / blobdiff