ICU 55.1 55.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- File List
- Globals

All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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
UFormattable * | ufmt_open (UErrorCode *status)
| Initialize a UFormattable, to type UNUM_LONG, value 0 may return error if memory allocation failed.
void | ufmt_close (UFormattable *fmt)
| Cleanup any additional memory allocated by this UFormattable.
UFormattableType | ufmt_getType (const UFormattable *fmt, UErrorCode *status)
| Return the type of this object.
UBool | ufmt_isNumeric (const UFormattable *fmt)
| Return whether the object is numeric.
UDate | ufmt_getDate (const UFormattable *fmt, UErrorCode *status)
| Gets the UDate value of this object.
double | ufmt_getDouble (UFormattable *fmt, UErrorCode *status)
| Gets the double value of this object.
int32_t | ufmt_getLong (UFormattable *fmt, UErrorCode *status)
| Gets the long (int32_t) value of this object.
int64_t | ufmt_getInt64 (UFormattable *fmt, UErrorCode *status)
| Gets the int64_t value of this object.
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.
const UChar * | ufmt_getUChars (UFormattable *fmt, int32_t *len, UErrorCode *status)
| Gets the string value of this object as a UChar string.
int32_t | ufmt_getArrayLength (const UFormattable *fmt, UErrorCode *status)
| Get the number of array objects contained, if an array type UFMT_ARRAY.
UFormattable * | ufmt_getArrayItemByIndex (UFormattable *fmt, int32_t n, UErrorCode *status)
| Get the specified value from the array of UFormattables.
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

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 62 of file uformattable.h.

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

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 | Count of defined UFormattableType values.

Definition at line 44 of file uformattable.h.

## Function Documentation

void ufmt_close | ( | UFormattable * | fmt | ) |

Cleanup any additional memory allocated by this UFormattable.

Parameters

  fmt | the formatter

Stable:
  ICU 52

See Also
  ufmt_open

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

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

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

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 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.

Stable:
  ICU 52

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

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

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

Stable:
  ICU 52

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

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

Stable:
  ICU 52

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

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

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

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

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

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