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"

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

Namespaces

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ UFormattedNumber

Function Documentation

◆ unumf_closeResult()

◆ unumf_openResult()

◆ unumf_resultAsValue()

◆ unumf_resultGetAllFieldPositions()

◆ unumf_resultNextFieldPosition()

◆ unumf_resultToDecimalNumber()

◆ unumf_resultToString()