ICU 74.1 74.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. More...
 

Functions

U_CAPI UFormattedNumberunumf_openResult (UErrorCode *ec)
 Creates an object to hold the result of a UNumberFormatter operation. More...
 
U_CAPI const UFormattedValueunumf_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. More...
 
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. More...
 
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. More...
 
U_CAPI void unumf_resultGetAllFieldPositions (const UFormattedNumber *uresult, UFieldPositionIterator *ufpositer, UErrorCode *ec)
 Populates the given iterator with all fields in the formatted output string. More...
 
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. More...
 
U_CAPI void unumf_closeResult (UFormattedNumber *uresult)
 Releases the UFormattedNumber created by unumf_openResult(). More...
 

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

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
uresultAn 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
ecSet 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
uresultThe object containing the formatted string.
ecSet 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
uresultThe object containing the formatted number.
ufpositerA 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.
ecSet 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
uresultThe object containing the formatted number.
ufposInput+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.
ecSet 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
uresultThe input object containing the formatted number.
destthe 8-bit char buffer into which the decimal number is placed
destCapacityThe size, in chars, of the destination buffer. May be zero for precomputing the required size.
ecreceives 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
uresultThe object containing the formatted number.
bufferWhere to save the string output.
bufferCapacityThe number of UChars available in the buffer.
ecSet if an error occurs.
Returns
The required length.
Stable:
ICU 62