ICU 76.1: i18n/unicode/usimplenumberformatter.h File Reference

ICU 76.1 76.1

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 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_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

## ◆ 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