C API: UFormattable is a thin wrapper for primitive types used for formatting and parsing. More...

#include "unicode/utypes.h"
#include "unicode/localpointer.h"

Typedefs
typedef enum UFormattableType	UFormattableType

typedef void *	UFormattable

Enumerations
enum	UFormattableType { UFMT_DATE = 0, UFMT_DOUBLE, UFMT_LONG, UFMT_STRING, UFMT_ARRAY, UFMT_INT64, UFMT_OBJECT, UFMT_COUNT }

Functions
U_DRAFT UFormattable *U_EXPORT2	ufmt_open (UErrorCode *status)

U_DRAFT void U_EXPORT2	ufmt_close (UFormattable *fmt)

U_DRAFT UFormattableType U_EXPORT2	ufmt_getType (const UFormattable fmt, UErrorCode status)

U_DRAFT UBool U_EXPORT2	ufmt_isNumeric (const UFormattable *fmt)

U_DRAFT UDate U_EXPORT2	ufmt_getDate (const UFormattable fmt, UErrorCode status)

U_DRAFT double U_EXPORT2	ufmt_getDouble (UFormattable fmt, UErrorCode status)

U_DRAFT int32_t U_EXPORT2	ufmt_getLong (UFormattable fmt, UErrorCode status)

U_DRAFT int64_t U_EXPORT2	ufmt_getInt64 (UFormattable fmt, UErrorCode status)

U_DRAFT const void *U_EXPORT2	ufmt_getObject (const UFormattable fmt, UErrorCode status)

U_DRAFT const UChar *U_EXPORT2	ufmt_getUChars (UFormattable fmt, int32_t len, UErrorCode *status)

U_DRAFT int32_t U_EXPORT2	ufmt_getArrayLength (const UFormattable fmt, UErrorCode status)

U_DRAFT UFormattable *U_EXPORT2	ufmt_getArrayItemByIndex (UFormattable fmt, int32_t n, UErrorCode status)

U_DRAFT const char *U_EXPORT2	ufmt_getDecNumChars (UFormattable fmt, int32_t len, UErrorCode *status)

Detailed Description

C API: UFormattable is a thin wrapper for primitive types used for formatting and parsing.

This is a C interface to the icu::Formattable class. Static functions on this class convert to and from this interface (via reinterpret_cast). Note that Formattables (and thus UFormattables) are mutable, and many operations (even getters) may actually modify the internal state. For this reason, UFormattables are not thread safe, and should not be shared between threads.

See unum_parseToUFormattable for example code.

Typedef Documentation

◆ UFormattable

typedef void* UFormattable

Opaque type representing various types of data which may be used for formatting and parsing operations.

See also: icu::Formattable ICU 52

◆ UFormattableType

typedef enum UFormattableType UFormattableType

Enum designating the type of a UFormattable instance. Practically, this indicates which of the getters would return without conversion or error.

See also: icu::Formattable::Type ICU 52

Enumeration Type Documentation

◆ UFormattableType

enum UFormattableType

Enum designating the type of a UFormattable instance. Practically, this indicates which of the getters would return without conversion or error.

See also: icu::Formattable::Type ICU 52

Enumerator
UFMT_DATE	ufmt_getDate() will return without conversion. See also ufmt_getDate
UFMT_DOUBLE	ufmt_getDouble() will return without conversion. See also ufmt_getDouble
UFMT_LONG	ufmt_getLong() will return without conversion. See also ufmt_getLong
UFMT_STRING	ufmt_getUChars() will return without conversion. See also ufmt_getUChars
UFMT_ARRAY	ufmt_countArray() and ufmt_getArray() will return the value. See also ufmt_getArrayItemByIndex
UFMT_INT64	ufmt_getInt64() will return without conversion. See also ufmt_getInt64
UFMT_OBJECT	ufmt_getObject() will return without conversion. See also ufmt_getObject
UFMT_COUNT	Count of defined UFormattableType values

Function Documentation

◆ ufmt_close()

U_DRAFT void U_EXPORT2 ufmt_close ( UFormattable * fmt )

Cleanup any additional memory allocated by this UFormattable.

Parameters

fmt	the formatter ICU 52

See also: ufmt_open

◆ ufmt_getArrayItemByIndex()

U_DRAFT UFormattable* U_EXPORT2 ufmt_getArrayItemByIndex	(	UFormattable *	fmt,
		int32_t	n,
		UErrorCode *	status
	)

Get the specified value from the array of UFormattables. Invalid if the object is not an array type UFMT_ARRAY

Parameters

fmt	the UFormattable object
n	the number of the array to return (0 based).
status	the error code - any conversion or format errors. Returns an error if n is out of bounds.

Returns: the nth array value, only valid while the containing UFormattable is valid. NULL if not an array. ICU 52

See also: icu::Formattable::getArray(int32_t&, UErrorCode&) const

◆ ufmt_getArrayLength()

U_DRAFT int32_t U_EXPORT2 ufmt_getArrayLength	(	const UFormattable *	fmt,
		UErrorCode *	status
	)

Get the number of array objects contained, if an array type UFMT_ARRAY

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors. U_ILLEGAL_ARGUMENT_ERROR if not an array type.

Returns: the number of array objects or undefined if not an array type ICU 52

See also: ufmt_getArrayItemByIndex

◆ ufmt_getDate()

U_DRAFT UDate U_EXPORT2 ufmt_getDate	(	const UFormattable *	fmt,
		UErrorCode *	status
	)

Gets the UDate value of this object. If the type is not of type UFMT_DATE, status is set to U_INVALID_FORMAT_ERROR and the return value is undefined.

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors

Returns: the value ICU 52

See also: icu::Formattable::getDate(UErrorCode&) const

◆ ufmt_getDecNumChars()

U_DRAFT const char* U_EXPORT2 ufmt_getDecNumChars	(	UFormattable *	fmt,
		int32_t *	len,
		UErrorCode *	status
	)

Returns a numeric string representation of the number contained within this formattable, or NULL if this object does not contain numeric type. For values obtained by parsing, the returned decimal number retains the full precision and range of the original input, unconstrained by the limits of a double floating point or a 64 bit int.

This function is not thread safe, and therfore is not declared const, even though it is logically const. The resulting buffer is owned by the UFormattable and is invalid if any other functions are called on the UFormattable.

Possible errors include U_MEMORY_ALLOCATION_ERROR, and U_INVALID_STATE if the formattable object has not been set to a numeric type.

Parameters

fmt	the UFormattable object
len	if non-null, on exit contains the string length (not including the terminating null)
status	the error code

Returns: the character buffer as a NULL terminated string, which is owned by the object and must not be accessed if any other functions are called on this object. ICU 52

See also: icu::Formattable::getDecimalNumber(UErrorCode&)

◆ ufmt_getDouble()

U_DRAFT double U_EXPORT2 ufmt_getDouble	(	UFormattable *	fmt,
		UErrorCode *	status
	)

Gets the double value of this object. If the type is not a UFMT_DOUBLE, or if there are additional significant digits than fit in a double type, a conversion is performed with possible loss of precision. If the type is UFMT_OBJECT and the object is a Measure, then the result of getNumber().getDouble(status) is returned. If this object is neither a numeric type nor a Measure, then 0 is returned and the status is set to U_INVALID_FORMAT_ERROR.

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors

Returns: the value ICU 52

See also: icu::Formattable::getDouble(UErrorCode&) const

◆ ufmt_getInt64()

U_DRAFT int64_t U_EXPORT2 ufmt_getInt64	(	UFormattable *	fmt,
		UErrorCode *	status
	)

Gets the int64_t value of this object. If this object is of a numeric type and the magnitude is too large to fit in an int64, then the maximum or minimum int64 value, as appropriate, is returned and the status is set to U_INVALID_FORMAT_ERROR. If the magnitude fits in an int64, then a casting conversion is peformed, with truncation of any fractional part. If the type is UFMT_OBJECT and the object is a Measure, then the result of getNumber().getDouble(status) is returned. If this object is neither a numeric type nor a Measure, then 0 is returned and the status is set to U_INVALID_FORMAT_ERROR.

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors

Returns: the value ICU 52

See also: icu::Formattable::getInt64(UErrorCode&) const

◆ ufmt_getLong()

U_DRAFT int32_t U_EXPORT2 ufmt_getLong	(	UFormattable *	fmt,
		UErrorCode *	status
	)

Gets the long (int32_t) value of this object. If the magnitude is too large to fit in a long, then the maximum or minimum long value, as appropriate, is returned and the status is set to U_INVALID_FORMAT_ERROR. If this object is of type UFMT_INT64 and it fits within a long, then no precision is lost. If it is of type kDouble or kDecimalNumber, then a conversion is peformed, with truncation of any fractional part. If the type is UFMT_OBJECT and the object is a Measure, then the result of getNumber().getLong(status) is returned. If this object is neither a numeric type nor a Measure, then 0 is returned and the status is set to U_INVALID_FORMAT_ERROR.

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors

Returns: the value ICU 52

See also: icu::Formattable::getLong(UErrorCode&) const

◆ ufmt_getObject()

U_DRAFT const void* U_EXPORT2 ufmt_getObject	(	const UFormattable *	fmt,
		UErrorCode *	status
	)

Returns a pointer to the UObject contained within this formattable (as a const void*), or NULL if this object is not of type UFMT_OBJECT.

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors

Returns: the value as a const void*. It is a polymorphic C++ object. ICU 52

See also: icu::Formattable::getObject() const

◆ ufmt_getType()

U_DRAFT UFormattableType U_EXPORT2 ufmt_getType	(	const UFormattable *	fmt,
		UErrorCode *	status
	)

Return the type of this object

Parameters

fmt	the UFormattable object
status	status code - U_ILLEGAL_ARGUMENT_ERROR is returned if the UFormattable contains data not supported by the API

Returns: the value as a UFormattableType

See also: ufmt_isNumeric; icu::Formattable::getType() const ICU 52

◆ ufmt_getUChars()

U_DRAFT const UChar* U_EXPORT2 ufmt_getUChars	(	UFormattable *	fmt,
		int32_t *	len,
		UErrorCode *	status
	)

Gets the string value of this object as a UChar string. If the type is not a string, status is set to U_INVALID_FORMAT_ERROR and a NULL pointer is returned. This function is not thread safe and may modify the UFormattable if need be to terminate the string. The returned pointer is not valid if any other functions are called on this UFormattable, or if the UFormattable is closed.

Parameters

fmt	the UFormattable object
status	the error code - any conversion or format errors
len	if non null, contains the string length on return

Returns: the null terminated string value - must not be referenced after any other functions are called on this UFormattable. ICU 52

See also: icu::Formattable::getString(UnicodeString&)const

◆ ufmt_isNumeric()

U_DRAFT UBool U_EXPORT2 ufmt_isNumeric ( const UFormattable * fmt )

Return whether the object is numeric.

Parameters

fmt	the UFormattable object

Returns: true if the object is a double, long, or int64 value, else false.

See also: ufmt_getType; icu::Formattable::isNumeric() const ICU 52

◆ ufmt_open()

U_DRAFT UFormattable* U_EXPORT2 ufmt_open ( UErrorCode * status )

Initialize a UFormattable, to type UNUM_LONG, value 0 may return error if memory allocation failed. parameter status error code. See unum_parseToUFormattable for example code. ICU 52

Returns: the new UFormattable

See also: ufmt_close; icu::Formattable::Formattable()

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ UFormattable

◆ UFormattableType

Enumeration Type Documentation

◆ UFormattableType

Function Documentation

◆ ufmt_close()

◆ ufmt_getArrayItemByIndex()

◆ ufmt_getArrayLength()

◆ ufmt_getDate()

◆ ufmt_getDecNumChars()

◆ ufmt_getDouble()

◆ ufmt_getInt64()

◆ ufmt_getLong()

◆ ufmt_getObject()

◆ ufmt_getType()

◆ ufmt_getUChars()

◆ ufmt_isNumeric()

◆ ufmt_open()