ICU 74.2 74.2
Namespaces | Typedefs | Enumerations | Functions
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 USimpleNumberusnum_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.
 
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_truncateStart (USimpleNumber *unumber, int32_t maximumIntegerDigits, UErrorCode *ec)
 Truncates digits from the beginning of the number to the given maximum number of integer digits.
 
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 USimpleNumberFormatterusnumf_openForLocale (const char *locale, UErrorCode *ec)
 Creates a new USimpleNumberFormatter with all locale defaults.
 
U_CAPI USimpleNumberFormatterusnumf_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.

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

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

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

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