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

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

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef enum UFormattableType	UFormattableType
	Enum designating the type of a UFormattable instance. More...

typedef void *	UFormattable
	Opaque type representing various types of data which may be used for formatting and parsing operations. More...

Enumerations
enum	UFormattableType { UFMT_DATE = 0 , UFMT_DOUBLE , UFMT_LONG , UFMT_STRING , UFMT_ARRAY , UFMT_INT64 , UFMT_OBJECT , UFMT_COUNT }
	Enum designating the type of a UFormattable instance. More...

Functions
U_CAPI UFormattable *	ufmt_open (UErrorCode *status)
	Initialize a UFormattable, to type UNUM_LONG, value 0 may return error if memory allocation failed. More...

U_CAPI void	ufmt_close (UFormattable *fmt)
	Cleanup any additional memory allocated by this UFormattable. More...

U_CAPI UFormattableType	ufmt_getType (const UFormattable fmt, UErrorCode status)
	Return the type of this object. More...

U_CAPI UBool	ufmt_isNumeric (const UFormattable *fmt)
	Return whether the object is numeric. More...

U_CAPI UDate	ufmt_getDate (const UFormattable fmt, UErrorCode status)
	Gets the UDate value of this object. More...

U_CAPI double	ufmt_getDouble (UFormattable fmt, UErrorCode status)
	Gets the double value of this object. More...

U_CAPI int32_t	ufmt_getLong (UFormattable fmt, UErrorCode status)
	Gets the long (int32_t) value of this object. More...

U_CAPI int64_t	ufmt_getInt64 (UFormattable fmt, UErrorCode status)
	Gets the int64_t value of this object. More...

U_CAPI const void *	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. More...

U_CAPI const UChar *	ufmt_getUChars (UFormattable fmt, int32_t len, UErrorCode *status)
	Gets the string value of this object as a UChar string. More...

U_CAPI int32_t	ufmt_getArrayLength (const UFormattable fmt, UErrorCode status)
	Get the number of array objects contained, if an array type UFMT_ARRAY. More...

U_CAPI UFormattable *	ufmt_getArrayItemByIndex (UFormattable fmt, int32_t n, UErrorCode status)
	Get the specified value from the array of UFormattables. More...

U_CAPI const char *	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. More...

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.

Definition in file uformattable.h.

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

Stable:: ICU 52

Definition at line 72 of file uformattable.h.

◆ 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

Stable:: 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

Stable:: 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	One more than the highest normal UFormattableType value. Deprecated: ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 48 of file uformattable.h.

Function Documentation

◆ ufmt_close()

U_CAPI void ufmt_close ( UFormattable * fmt )

Cleanup any additional memory allocated by this UFormattable.

Parameters

fmt	the formatter

Stable:: ICU 52

See also: ufmt_open

◆ ufmt_getArrayItemByIndex()

U_CAPI UFormattable * 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.

Stable:: ICU 52

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

◆ ufmt_getArrayLength()

U_CAPI int32_t 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

Stable:: ICU 52

See also: ufmt_getArrayItemByIndex

◆ ufmt_getDate()

U_CAPI UDate 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

Stable:: ICU 52

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

◆ ufmt_getDecNumChars()

U_CAPI const char * 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 therefore 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.

Stable:: ICU 52

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

◆ ufmt_getDouble()

U_CAPI double 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

Stable:: ICU 52

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

◆ ufmt_getInt64()

U_CAPI int64_t 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 performed, 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

Stable:: ICU 52

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

◆ ufmt_getLong()

U_CAPI int32_t 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 performed, 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

Stable:: ICU 52

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

◆ ufmt_getObject()

U_CAPI const void * 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.

Stable:: ICU 52

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

◆ ufmt_getType()

U_CAPI UFormattableType 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

Stable:: ICU 52

◆ ufmt_getUChars()

U_CAPI const UChar * 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.

Stable:: ICU 52

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

◆ ufmt_isNumeric()

U_CAPI UBool 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

Stable:: ICU 52

◆ ufmt_open()

U_CAPI UFormattable * 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.

Stable:: ICU 52

Returns: the new UFormattable

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

Namespaces

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()