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. 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 1 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 1 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