ICU 74.1 74.1
Namespaces | Typedefs | Enumerations | Functions
uformattable.h File Reference

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

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

Go to the source code of this file.

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 UFormattableufmt_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 UCharufmt_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 UFormattableufmt_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

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 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
fmtthe 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
fmtthe UFormattable object
nthe number of the array to return (0 based).
statusthe 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
fmtthe UFormattable object
statusthe 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
fmtthe UFormattable object
statusthe 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
fmtthe UFormattable object
lenif non-null, on exit contains the string length (not including the terminating null)
statusthe 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
fmtthe UFormattable object
statusthe 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
fmtthe UFormattable object
statusthe 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
fmtthe UFormattable object
statusthe 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
fmtthe UFormattable object
statusthe 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
fmtthe UFormattable object
statusstatus 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
fmtthe UFormattable object
statusthe error code - any conversion or format errors
lenif 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
fmtthe 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()