ICU 74.2: i18n/unicode/uformattable.h File Reference

ICU 74.2 74.2

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.
typedef void * | UFormattable
| Opaque type representing various types of data which may be used for formatting and parsing operations.

## 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.
U_CAPI void | ufmt_close (UFormattable *fmt)
| Cleanup any additional memory allocated by this UFormattable.
U_CAPI UFormattableType | ufmt_getType (const UFormattable *fmt, UErrorCode *status)
| Return the type of this object.
U_CAPI UBool | ufmt_isNumeric (const UFormattable *fmt)
| Return whether the object is numeric.
U_CAPI UDate | ufmt_getDate (const UFormattable *fmt, UErrorCode *status)
| Gets the UDate value of this object.
U_CAPI double | ufmt_getDouble (UFormattable *fmt, UErrorCode *status)
| Gets the double value of this object.
U_CAPI int32_t | ufmt_getLong (UFormattable *fmt, UErrorCode *status)
| Gets the long (int32_t) value of this object.
U_CAPI int64_t | ufmt_getInt64 (UFormattable *fmt, UErrorCode *status)
| Gets the int64_t value of this object.
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.
U_CAPI const UChar * | ufmt_getUChars (UFormattable *fmt, int32_t *len, UErrorCode *status)
| Gets the string value of this object as a UChar string.
U_CAPI int32_t | ufmt_getArrayLength (const UFormattable *fmt, UErrorCode *status)
| Get the number of array objects contained, if an array type UFMT_ARRAY.
U_CAPI UFormattable * | ufmt_getArrayItemByIndex (UFormattable *fmt, int32_t n, UErrorCode *status)
| Get the specified value from the array of UFormattables.
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.

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