usimplenumberformatter.h File Reference

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"

Go to the source code of this file.

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef enum USimpleNumberSign	USimpleNumberSign
	An explicit sign option for a SimpleNumber.
typedef struct USimpleNumber	USimpleNumber
	C-compatible version of icu::number::SimpleNumber.
typedef struct USimpleNumberFormatter	USimpleNumberFormatter
	C-compatible version of icu::number::SimpleNumberFormatter.

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.
U_CAPI void	usnum_setToInt64 (USimpleNumber *unumber, int64_t value, UErrorCode *ec)
	Overwrites the value in a USimpleNumber to an int64_t.
U_CAPI void	usnum_multiplyByPowerOfTen (USimpleNumber *unumber, int32_t power, UErrorCode *ec)
	Changes the value of the USimpleNumber by a power of 10.
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, which can be before or after the decimal separator.
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.
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.
U_CAPI void	usnum_setMaximumIntegerDigits (USimpleNumber *unumber, int32_t maximumIntegerDigits, UErrorCode *ec)
	Sets the number of integer digits to the given amount, truncating if necessary.
U_CAPI void	usnum_truncateStart (USimpleNumber *unumber, int32_t maximumIntegerDigits, UErrorCode *ec)
	Alias for setMaximumIntegerDigits.
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.
U_CAPI USimpleNumberFormatter *	usnumf_openForLocale (const char *locale, UErrorCode *ec)
	Creates a new USimpleNumberFormatter with all locale defaults.
U_CAPI USimpleNumberFormatter *	usnumf_openForLocaleAndGroupingStrategy (const char *locale, UNumberGroupingStrategy groupingStrategy, UErrorCode *ec)
	Creates a new USimpleNumberFormatter, overriding the grouping strategy.
U_CAPI void	usnumf_format (const USimpleNumberFormatter *uformatter, USimpleNumber *unumber, UFormattedNumber *uresult, UErrorCode *ec)
	Formats a number using this SimpleNumberFormatter.
U_CAPI void	usnumf_formatInt64 (const USimpleNumberFormatter *uformatter, int64_t value, UFormattedNumber *uresult, UErrorCode *ec)
	Formats an integer using this SimpleNumberFormatter.
U_CAPI void	usnum_close (USimpleNumber *unumber)
	Frees the memory held by a USimpleNumber.
U_CAPI void	usnumf_close (USimpleNumberFormatter *uformatter)
	Frees the memory held by a USimpleNumberFormatter.

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.

Stable:

ICU 73

Definition at line 86 of file usimplenumberformatter.h.

USimpleNumberFormatter

typedef struct USimpleNumberFormatter USimpleNumberFormatter

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

Stable:

ICU 73

Definition at line 95 of file usimplenumberformatter.h.

USimpleNumberSign

typedef enum USimpleNumberSign USimpleNumberSign

An explicit sign option for a SimpleNumber.

Stable:

ICU 73

Enumeration Type Documentation

USimpleNumberSign

enum USimpleNumberSign

An explicit sign option for a SimpleNumber.

Stable:

ICU 73

Enumerator
UNUM_SIMPLE_NUMBER_PLUS_SIGN	Render a plus sign. Stable: ICU 73
UNUM_SIMPLE_NUMBER_NO_SIGN	Render no sign. Stable: ICU 73
UNUM_SIMPLE_NUMBER_MINUS_SIGN	Render a minus sign. Stable: ICU 73

Definition at line 58 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.

Stable:

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.

Stable:

ICU 73

usnum_openForInt64()

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

Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter.

Stable:

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, which can be before or after the decimal separator.

This function does not change minimum integer digits.

Stable:

ICU 73

usnum_setMaximumIntegerDigits()

U_CAPI void usnum_setMaximumIntegerDigits	(	USimpleNumber *	unumber,
		int32_t	maximumIntegerDigits,
		UErrorCode *	ec
	)

Sets the number of integer digits to the given amount, truncating if necessary.

Draft:

This API may be changed in the future versions and was introduced in ICU 75

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.

Stable:

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.

Stable:

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.

Stable:

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.

Stable:

ICU 73

usnum_truncateStart()

U_CAPI void usnum_truncateStart	(	USimpleNumber *	unumber,
		int32_t	maximumIntegerDigits,
		UErrorCode *	ec
	)

Alias for setMaximumIntegerDigits.

Will be removed after ICU 75.

Deprecated:

ICU 75

usnumf_close()

U_CAPI void usnumf_close

(

USimpleNumberFormatter *

uformatter

)

Frees the memory held by a USimpleNumberFormatter.

Stable:

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.

Stable:

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.

Stable:

ICU 73

usnumf_openForLocale()

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

Creates a new USimpleNumberFormatter with all locale defaults.

Stable:

ICU 73

usnumf_openForLocaleAndGroupingStrategy()

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

Creates a new USimpleNumberFormatter, overriding the grouping strategy.

Stable:

ICU 73