Source code
Revision control
Copy as Markdown
Other Tools
// © 2022 and later: Unicode, Inc. and others.
#ifndef __USIMPLENUMBERFORMATTER_H__
#define __USIMPLENUMBERFORMATTER_H__
#include "unicode/utypes.h"
#if !UCONFIG_NO_FORMATTING
#include "unicode/uformattednumber.h"
#include "unicode/unumberoptions.h"
/**
* \file
* \brief C API: Simple number formatting focused on low memory and code size.
*
* These functions render locale-aware number strings but without the bells and whistles found in
* other number formatting APIs such as those in unumberformatter.h, like units and currencies.
*
* Example using C++ helpers:
*
* <pre>
* LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale("de-CH", status));
* LocalUFormattedNumberPointer uresult(unumf_openResult(status));
* usnumf_formatInt64(uformatter.getAlias(), 55, uresult.getAlias(), status);
* assertEquals("",
* u"55",
* ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), nullptr, status));
* </pre>
*
* Example using pure C:
*
* <pre>
* UErrorCode ec = U_ZERO_ERROR;
* USimpleNumberFormatter* uformatter = usnumf_openForLocale("bn", &ec);
* USimpleNumber* unumber = usnum_openForInt64(1000007, &ec);
* UFormattedNumber* uresult = unumf_openResult(&ec);
* usnumf_format(uformatter, unumber, uresult, &ec);
* int32_t len;
* const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec);
* if (assertSuccess("Formatting end-to-end", &ec)) {
* assertUEquals("Should produce a result in Bangla digits", u"১০,০০,০০৭", str);
* }
* // Cleanup:
* unumf_closeResult(uresult);
* usnum_close(unumber);
* usnumf_close(uformatter);
* </pre>
*/
#ifndef U_HIDE_DRAFT_API
/**
* An explicit sign option for a SimpleNumber.
*
* @draft ICU 73
*/
typedef enum USimpleNumberSign {
/**
* Render a plus sign.
*
* @draft ICU 73
*/
UNUM_SIMPLE_NUMBER_PLUS_SIGN,
/**
* Render no sign.
*
* @draft ICU 73
*/
UNUM_SIMPLE_NUMBER_NO_SIGN,
/**
* Render a minus sign.
*
* @draft ICU 73
*/
UNUM_SIMPLE_NUMBER_MINUS_SIGN,
} USimpleNumberSign;
struct USimpleNumber;
/**
* C-compatible version of icu::number::SimpleNumber.
*
* @draft ICU 73
*/
typedef struct USimpleNumber USimpleNumber;
struct USimpleNumberFormatter;
/**
* C-compatible version of icu::number::SimpleNumberFormatter.
*
* @draft ICU 73
*/
typedef struct USimpleNumberFormatter USimpleNumberFormatter;
/**
* Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter.
*
* @draft ICU 73
*/
U_CAPI USimpleNumber* U_EXPORT2
usnum_openForInt64(int64_t value, UErrorCode* ec);
/**
* Overwrites the value in a USimpleNumber to an int64_t.
*
* This can be used to reset the number value after formatting.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_setToInt64(USimpleNumber* unumber, int64_t value, UErrorCode* ec);
/**
* Changes the value of the USimpleNumber by a power of 10.
*
* This function immediately mutates the inner value.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_multiplyByPowerOfTen(USimpleNumber* unumber, int32_t power, UErrorCode* ec);
/**
* Rounds the value currently stored in the USimpleNumber to the given power of 10.
*
* This function immediately mutates the inner value.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_roundTo(USimpleNumber* unumber, int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode* ec);
/**
* Pads the beginning of the number with zeros up to the given minimum number of integer digits.
*
* This setting is applied upon formatting the number.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_setMinimumIntegerDigits(USimpleNumber* unumber, int32_t minimumIntegerDigits, UErrorCode* ec);
/**
* Pads the end of the number with zeros up to the given minimum number of fraction digits.
*
* This setting is applied upon formatting the number.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_setMinimumFractionDigits(USimpleNumber* unumber, int32_t minimumFractionDigits, UErrorCode* ec);
/**
* Truncates digits from the beginning of the number to the given maximum number of integer digits.
*
* This function immediately mutates the inner value.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_truncateStart(USimpleNumber* unumber, int32_t maximumIntegerDigits, UErrorCode* ec);
/**
* Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign.
*
* This setting is applied upon formatting the number.
*
* NOTE: This does not support accounting sign notation.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_setSign(USimpleNumber* unumber, USimpleNumberSign sign, UErrorCode* ec);
/**
* Creates a new USimpleNumberFormatter with all locale defaults.
*
* @draft ICU 73
*/
U_CAPI USimpleNumberFormatter* U_EXPORT2
usnumf_openForLocale(const char* locale, UErrorCode* ec);
/**
* Creates a new USimpleNumberFormatter, overriding the grouping strategy.
*
* @draft ICU 73
*/
U_CAPI USimpleNumberFormatter* U_EXPORT2
usnumf_openForLocaleAndGroupingStrategy(
const char* locale, UNumberGroupingStrategy groupingStrategy, UErrorCode* ec);
/**
* Formats a number using this SimpleNumberFormatter.
*
* The USimpleNumber is cleared after calling this function. It can be re-used via
* usnum_setToInt64.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnumf_format(
const USimpleNumberFormatter* uformatter,
USimpleNumber* unumber,
UFormattedNumber* uresult,
UErrorCode* ec);
/**
* Formats an integer using this SimpleNumberFormatter.
*
* For more control over the formatting, use USimpleNumber.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnumf_formatInt64(
const USimpleNumberFormatter* uformatter,
int64_t value,
UFormattedNumber* uresult,
UErrorCode* ec);
/**
* Frees the memory held by a USimpleNumber.
*
* NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnum_close(USimpleNumber* unumber);
/**
* Frees the memory held by a USimpleNumberFormatter.
*
* @draft ICU 73
*/
U_CAPI void U_EXPORT2
usnumf_close(USimpleNumberFormatter* uformatter);
#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
/**
* \class LocalUSimpleNumberPointer
* "Smart pointer" class; closes a USimpleNumber via usnum_close().
* For most methods see the LocalPointerBase base class.
*
* NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.
* If you use LocalUSimpleNumberPointer, call `.orphan()` when passing to that function.
*
* Usage:
* <pre>
* LocalUSimpleNumberPointer uformatter(usnumf_openForInteger(...));
* // no need to explicitly call usnum_close()
* </pre>
*
* @see LocalPointerBase
* @see LocalPointer
* @draft ICU 73
*/
U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberPointer, USimpleNumber, usnum_close);
/**
* \class LocalUSimpleNumberFormatterPointer
* "Smart pointer" class; closes a USimpleNumberFormatter via usnumf_close().
* For most methods see the LocalPointerBase base class.
*
* Usage:
* <pre>
* LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale(...));
* // no need to explicitly call usnumf_close()
* </pre>
*
* @see LocalPointerBase
* @see LocalPointer
* @draft ICU 73
*/
U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberFormatterPointer, USimpleNumberFormatter, usnumf_close);
U_NAMESPACE_END
#endif // U_SHOW_CPLUSPLUS_API
#endif // U_HIDE_DRAFT_API
#endif /* #if !UCONFIG_NO_FORMATTING */
#endif //__USIMPLENUMBERFORMATTER_H__