C API: Simple number formatting focused on low memory and code size. More...

#include "unicode/utypes.h"
#include "unicode/uformattednumber.h"
#include "unicode/unumberoptions.h"

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef enum USimpleNumberSign	USimpleNumberSign
	An explicit sign option for a SimpleNumber. More...

typedef struct USimpleNumber	USimpleNumber
	C-compatible version of icu::number::SimpleNumber. More...

typedef struct USimpleNumberFormatter	USimpleNumberFormatter
	C-compatible version of icu::number::SimpleNumberFormatter. More...

Enumerations
enum	USimpleNumberSign { UNUM_SIMPLE_NUMBER_PLUS_SIGN , UNUM_SIMPLE_NUMBER_NO_SIGN , UNUM_SIMPLE_NUMBER_MINUS_SIGN }
	An explicit sign option for a SimpleNumber. More...

Functions
U_CAPI USimpleNumber *	usnum_openForInt64 (int64_t value, UErrorCode *ec)
	Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter. More...

U_CAPI void	usnum_setToInt64 (USimpleNumber unumber, int64_t value, UErrorCode ec)
	Overwrites the value in a USimpleNumber to an int64_t. More...

U_CAPI void	usnum_multiplyByPowerOfTen (USimpleNumber unumber, int32_t power, UErrorCode ec)
	Changes the value of the USimpleNumber by a power of 10. More...

U_CAPI void	usnum_roundTo (USimpleNumber unumber, int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode ec)
	Rounds the value currently stored in the USimpleNumber to the given power of 10. More...

U_CAPI void	usnum_setMinimumIntegerDigits (USimpleNumber unumber, int32_t minimumIntegerDigits, UErrorCode ec)
	Pads the beginning of the number with zeros up to the given minimum number of integer digits. More...

U_CAPI void	usnum_setMinimumFractionDigits (USimpleNumber unumber, int32_t minimumFractionDigits, UErrorCode ec)
	Pads the end of the number with zeros up to the given minimum number of fraction digits. More...

U_CAPI void	usnum_truncateStart (USimpleNumber unumber, int32_t maximumIntegerDigits, UErrorCode ec)
	Truncates digits from the beginning of the number to the given maximum number of integer digits. More...

U_CAPI void	usnum_setSign (USimpleNumber unumber, USimpleNumberSign sign, UErrorCode ec)
	Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign. More...

U_CAPI USimpleNumberFormatter *	usnumf_openForLocale (const char locale, UErrorCode ec)
	Creates a new USimpleNumberFormatter with all locale defaults. More...

U_CAPI USimpleNumberFormatter *	usnumf_openForLocaleAndGroupingStrategy (const char locale, UNumberGroupingStrategy groupingStrategy, UErrorCode ec)
	Creates a new USimpleNumberFormatter, overriding the grouping strategy. More...

U_CAPI void	usnumf_format (const USimpleNumberFormatter uformatter, USimpleNumber unumber, UFormattedNumber uresult, UErrorCode ec)
	Formats a number using this SimpleNumberFormatter. More...

U_CAPI void	usnumf_formatInt64 (const USimpleNumberFormatter uformatter, int64_t value, UFormattedNumber uresult, UErrorCode *ec)
	Formats an integer using this SimpleNumberFormatter. More...

U_CAPI void	usnum_close (USimpleNumber *unumber)
	Frees the memory held by a USimpleNumber. More...

U_CAPI void	usnumf_close (USimpleNumberFormatter *uformatter)
	Frees the memory held by a USimpleNumberFormatter. More...

Detailed Description

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:

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));

Example using pure C:

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);

Definition in file usimplenumberformatter.h.

Typedef Documentation

◆ USimpleNumber

typedef struct USimpleNumber USimpleNumber

C-compatible version of icu::number::SimpleNumber.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

Definition at line 89 of file usimplenumberformatter.h.

◆ USimpleNumberFormatter

typedef struct USimpleNumberFormatter USimpleNumberFormatter

C-compatible version of icu::number::SimpleNumberFormatter.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

Definition at line 98 of file usimplenumberformatter.h.

◆ USimpleNumberSign

typedef enum USimpleNumberSign USimpleNumberSign

An explicit sign option for a SimpleNumber.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

Enumeration Type Documentation

◆ USimpleNumberSign

enum USimpleNumberSign

An explicit sign option for a SimpleNumber.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

Enumerator

UNUM_SIMPLE_NUMBER_PLUS_SIGN

Render a plus sign.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

UNUM_SIMPLE_NUMBER_NO_SIGN

Render no sign.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

UNUM_SIMPLE_NUMBER_MINUS_SIGN

Render a minus sign.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

Definition at line 61 of file usimplenumberformatter.h.

Function Documentation

◆ usnum_close()

U_CAPI void usnum_close ( USimpleNumber * unumber )

Frees the memory held by a USimpleNumber.

NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_multiplyByPowerOfTen()

U_CAPI void usnum_multiplyByPowerOfTen	(	USimpleNumber *	unumber,
		int32_t	power,
		UErrorCode *	ec
	)

Changes the value of the USimpleNumber by a power of 10.

This function immediately mutates the inner value.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_openForInt64()

U_CAPI USimpleNumber * usnum_openForInt64	(	int64_t	value,
		UErrorCode *	ec
	)

Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_roundTo()

U_CAPI void usnum_roundTo	(	USimpleNumber *	unumber,
		int32_t	power,
		UNumberFormatRoundingMode	roundingMode,
		UErrorCode *	ec
	)

Rounds the value currently stored in the USimpleNumber to the given power of 10.

This function immediately mutates the inner value.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_setMinimumFractionDigits()

U_CAPI void usnum_setMinimumFractionDigits	(	USimpleNumber *	unumber,
		int32_t	minimumFractionDigits,
		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:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_setMinimumIntegerDigits()

U_CAPI void usnum_setMinimumIntegerDigits	(	USimpleNumber *	unumber,
		int32_t	minimumIntegerDigits,
		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:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_setSign()

U_CAPI void usnum_setSign	(	USimpleNumber *	unumber,
		USimpleNumberSign	sign,
		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:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_setToInt64()

U_CAPI void usnum_setToInt64	(	USimpleNumber *	unumber,
		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:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnum_truncateStart()

U_CAPI void usnum_truncateStart	(	USimpleNumber *	unumber,
		int32_t	maximumIntegerDigits,
		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:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnumf_close()

U_CAPI void usnumf_close ( USimpleNumberFormatter * uformatter )

Frees the memory held by a USimpleNumberFormatter.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnumf_format()

U_CAPI void usnumf_format	(	const USimpleNumberFormatter *	uformatter,
		USimpleNumber *	unumber,
		UFormattedNumber *	uresult,
		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:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnumf_formatInt64()

U_CAPI void usnumf_formatInt64	(	const USimpleNumberFormatter *	uformatter,
		int64_t	value,
		UFormattedNumber *	uresult,
		UErrorCode *	ec
	)

Formats an integer using this SimpleNumberFormatter.

For more control over the formatting, use USimpleNumber.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnumf_openForLocale()

U_CAPI USimpleNumberFormatter * usnumf_openForLocale	(	const char *	locale,
		UErrorCode *	ec
	)

Creates a new USimpleNumberFormatter with all locale defaults.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

◆ usnumf_openForLocaleAndGroupingStrategy()

U_CAPI USimpleNumberFormatter * usnumf_openForLocaleAndGroupingStrategy	(	const char *	locale,
		UNumberGroupingStrategy	groupingStrategy,
		UErrorCode *	ec
	)

Creates a new USimpleNumberFormatter, overriding the grouping strategy.

Draft:: This API may be changed in the future versions and was introduced in ICU 73

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ USimpleNumber

◆ USimpleNumberFormatter

◆ USimpleNumberSign

Enumeration Type Documentation

◆ USimpleNumberSign

Function Documentation

◆ usnum_close()

◆ usnum_multiplyByPowerOfTen()

◆ usnum_openForInt64()

◆ usnum_roundTo()

◆ usnum_setMinimumFractionDigits()

◆ usnum_setMinimumIntegerDigits()

◆ usnum_setSign()

◆ usnum_setToInt64()

◆ usnum_truncateStart()

◆ usnumf_close()

◆ usnumf_format()

◆ usnumf_formatInt64()

◆ usnumf_openForLocale()

◆ usnumf_openForLocaleAndGroupingStrategy()