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

| 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, which can be before or after the decimal separator. 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_setMaximumIntegerDigits (USimpleNumber *unumber, int32_t maximumIntegerDigits, UErrorCode *ec)
| Sets the number of integer digits to the given amount, truncating if necessary. 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.

Stable:
  ICU 73

Definition at line 1 of file usimplenumberformatter.h.

## USimpleNumberFormatter

typedef struct USimpleNumberFormatter USimpleNumberFormatter

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

Stable:
  ICU 73

Definition at line 1 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