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

ICU 76.1 76.1

Namespaces | Typedefs | Functions
uformattednumber.h File Reference

C API: Formatted number result from various number formatting functions. More...

`#include "unicode/utypes.h"`
`#include "unicode/ufieldpositer.h"`
`#include "unicode/uformattedvalue.h"`
`#include "unicode/umisc.h"`

Go to the source code of this file.

## Namespaces
namespace | icu
| File coll.h.

## Typedefs
typedef struct UFormattedNumber | UFormattedNumber
| C-compatible version of icu::number::FormattedNumber.

## Functions
U_CAPI UFormattedNumber * | unumf_openResult (UErrorCode *ec)
| Creates an object to hold the result of a UNumberFormatter operation.
U_CAPI const UFormattedValue * | unumf_resultAsValue (const UFormattedNumber *uresult, UErrorCode *ec)
| Returns a representation of a UFormattedNumber as a UFormattedValue, which can be subsequently passed to any API requiring that type.
U_CAPI int32_t | unumf_resultToString (const UFormattedNumber *uresult, UChar *buffer, int32_t bufferCapacity, UErrorCode *ec)
| Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible.
U_CAPI UBool | unumf_resultNextFieldPosition (const UFormattedNumber *uresult, UFieldPosition *ufpos, UErrorCode *ec)
| Determines the start and end indices of the next occurrence of the given field in the output string.
U_CAPI void | unumf_resultGetAllFieldPositions (const UFormattedNumber *uresult, UFieldPositionIterator *ufpositer, UErrorCode *ec)
| Populates the given iterator with all fields in the formatted output string.
U_CAPI int32_t | unumf_resultToDecimalNumber (const UFormattedNumber *uresult, char *dest, int32_t destCapacity, UErrorCode *ec)
| Extracts the formatted number as a "numeric string" conforming to the syntax defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal.
U_CAPI void | unumf_closeResult (UFormattedNumber *uresult)
| Releases the UFormattedNumber created by unumf_openResult().

## Detailed Description

C API: Formatted number result from various number formatting functions.

Create a `UFormattedNumber` to hold the result of a number formatting operation. The same `UFormattedNumber` can be reused multiple times.

    LocalUFormattedNumberPointer uresult(unumf_openResult(status));

    // pass uresult.getAlias() to your number formatter

    int32_t length;
    const UChar* s = ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), &length, status));

    // The string result is in `s` with the given `length` (it is also NUL-terminated).

Definition in file uformattednumber.h.

## Typedef Documentation

## ◆ UFormattedNumber

typedef struct UFormattedNumber UFormattedNumber

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

NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.

Stable
  ICU 62

Definition at line 43 of file uformattednumber.h.

## Function Documentation

## ◆ unumf_closeResult()

U_CAPI void unumf_closeResult | ( | UFormattedNumber * | uresult | ) |

Releases the UFormattedNumber created by unumf_openResult().

Parameters

  uresult | An object created by unumf_openResult().

Stable
  ICU 62

## ◆ unumf_openResult()

U_CAPI UFormattedNumber * unumf_openResult | ( | UErrorCode * | ec | ) |

Creates an object to hold the result of a UNumberFormatter operation.

The object can be used repeatedly; it is cleared whenever passed to a format function.

Parameters

  ec | Set if an error occurs.

Stable
  ICU 62

## ◆ unumf_resultAsValue()

U_CAPI const UFormattedValue * unumf_resultAsValue | ( | const UFormattedNumber * | uresult,
|  | UErrorCode * | ec )

Returns a representation of a UFormattedNumber as a UFormattedValue, which can be subsequently passed to any API requiring that type.

The returned object is owned by the UFormattedNumber and is valid only as long as the UFormattedNumber is present and unchanged in memory.

You can think of this method as a cast between types.

Parameters

  uresult | The object containing the formatted string.
  ec | Set if an error occurs.

Returns
  A UFormattedValue owned by the input object.

Stable
  ICU 64

## ◆ unumf_resultGetAllFieldPositions()

U_CAPI void unumf_resultGetAllFieldPositions | ( | const UFormattedNumber * | uresult,
|  | UFieldPositionIterator * | ufpositer,
|  | UErrorCode * | ec )

Populates the given iterator with all fields in the formatted output string.

This allows you to determine the locations of the integer part, fraction part, and sign.

This is an alternative to the more powerful `ufmtval_nextPosition` API.

If you need information on only one field, use `ufmtval_nextPosition` or `unumf_resultNextFieldPosition`.

Parameters

  uresult | The object containing the formatted number.
  ufpositer | A pointer to a UFieldPositionIterator created by `ufieldpositer_open`. Iteration information already present in the UFieldPositionIterator is deleted, and the iterator is reset to apply to the fields in the formatted string created by this function call. The field values and indexes returned by `ufieldpositer_next` represent fields denoted by the UNumberFormatFields enum. Fields are not returned in a guaranteed order. Fields cannot overlap, but they may nest. For example, 1234 could format as "1,234" which might consist of a grouping separator field for ',' and an integer field encompassing the entire string.
  ec | Set if an error occurs.

Stable
  ICU 62

## ◆ unumf_resultNextFieldPosition()

U_CAPI UBool unumf_resultNextFieldPosition | ( | const UFormattedNumber * | uresult,
|  | UFieldPosition * | ufpos,
|  | UErrorCode * | ec )

Determines the start and end indices of the next occurrence of the given field in the output string.

This allows you to determine the locations of, for example, the integer part, fraction part, or symbols.

This is a simpler but less powerful alternative to `ufmtval_nextPosition`.

If a field occurs just once, calling this method will find that occurrence and return it. If a field occurs multiple times, this method may be called repeatedly with the following pattern:

    UFieldPosition ufpos = {UNUM_GROUPING_SEPARATOR_FIELD, 0, 0};
    while (unumf_resultNextFieldPosition(uresult, ufpos, &ec)) {
      // do something with ufpos.
    }

This method is useful if you know which field to query. If you want all available field position information, use unumf_resultGetAllFieldPositions().

NOTE: All fields of the UFieldPosition must be initialized before calling this method.

Parameters

  uresult | The object containing the formatted number.
  ufpos | Input+output variable. On input, the "field" property determines which field to look up, and the "endIndex" property determines where to begin the search. On output, the "beginIndex" field is set to the beginning of the first occurrence of the field after the input "endIndex", and "endIndex" is set to the end of that occurrence of the field (exclusive index). If a field position is not found, the FieldPosition is not changed and the method returns false.
  ec | Set if an error occurs.

Stable
  ICU 62

## ◆ unumf_resultToDecimalNumber()

U_CAPI int32_t unumf_resultToDecimalNumber | ( | const UFormattedNumber * | uresult,
|  | char * | dest,
|  | int32_t | destCapacity,
|  | UErrorCode * | ec )

Extracts the formatted number as a "numeric string" conforming to the syntax defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal.

This endpoint is useful for obtaining the exact number being printed after scaling and rounding have been applied by the number formatter.

Parameters

  uresult | The input object containing the formatted number.
  dest | the 8-bit char buffer into which the decimal number is placed
  destCapacity | The size, in chars, of the destination buffer. May be zero for precomputing the required size.
  ec | receives any error status. If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for preflighting.

Returns
  Number of chars in the data. Does not include a trailing NUL.

Stable
  ICU 68

## ◆ unumf_resultToString()

U_CAPI int32_t unumf_resultToString | ( | const UFormattedNumber * | uresult,
|  | UChar * | buffer,
|  | int32_t | bufferCapacity,
|  | UErrorCode * | ec )

Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible.

If bufferCapacity is greater than the required length, a terminating NUL is written. If bufferCapacity is less than the required length, an error code is set.

Also see ufmtval_getString, which returns a NUL-terminated string:

    int32_t len;
    const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec);

NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.

Parameters

  uresult | The object containing the formatted number.
  buffer | Where to save the string output.
  bufferCapacity | The number of UChars available in the buffer.
  ec | Set if an error occurs.

Returns
  The required length.

Stable
  ICU 62