icuSources/i18n/unicode/uformattable.h

   1 /*
   2 ********************************************************************************
   3 * Copyright (C) 2013-2014, International Business Machines Corporation and others.
   4 * All Rights Reserved.
   5 ********************************************************************************
   6 *
   7 * File UFORMATTABLE.H
   8 *
   9 * Modification History:
  10 *
  11 *   Date        Name        Description
  12 *   2013 Jun 7  srl         New
  13 ********************************************************************************
  14 */
  15
  16 /**
  17  * \file
  18  * \brief C API: UFormattable is a thin wrapper for primitive types used for formatting and parsing.
  19  *
  20  * This is a C interface to the icu::Formattable class. Static functions on this class convert
  21  * to and from this interface (via reinterpret_cast).  Note that Formattables (and thus UFormattables)
  22  * are mutable, and many operations (even getters) may actually modify the internal state. For this
  23  * reason, UFormattables are not thread safe, and should not be shared between threads.
  24  *
  25  * See {@link unum_parseToUFormattable} for example code.
  26  */
  27
  28 #ifndef UFORMATTABLE_H
  29 #define UFORMATTABLE_H
  30
  31 #include "unicode/utypes.h"
  32
  33 #if !UCONFIG_NO_FORMATTING
  34
  35 #include "unicode/localpointer.h"
  36
  37 /**
  38  * Enum designating the type of a UFormattable instance.
  39  * Practically, this indicates which of the getters would return without conversion
  40  * or error.
  41  * @see icu::Formattable::Type
  42  * @stable ICU 52
  43  */
  44 typedef enum UFormattableType {
  45   UFMT_DATE = 0, /**< ufmt_getDate() will return without conversion. @see ufmt_getDate*/
  46   UFMT_DOUBLE,   /**< ufmt_getDouble() will return without conversion.  @see ufmt_getDouble*/
  47   UFMT_LONG,     /**< ufmt_getLong() will return without conversion. @see ufmt_getLong */
  48   UFMT_STRING,   /**< ufmt_getUChars() will return without conversion.  @see ufmt_getUChars*/
  49   UFMT_ARRAY,    /**< ufmt_countArray() and ufmt_getArray() will return the value.  @see ufmt_getArrayItemByIndex */
  50   UFMT_INT64,    /**< ufmt_getInt64() will return without conversion. @see ufmt_getInt64 */
  51   UFMT_OBJECT,   /**< ufmt_getObject() will return without conversion.  @see ufmt_getObject*/
  52   UFMT_COUNT     /**< Count of defined UFormattableType values */
  53 } UFormattableType;
  54
  55
  56 /**
  57  * Opaque type representing various types of data which may be used for formatting
  58  * and parsing operations.
  59  * @see icu::Formattable
  60  * @stable ICU 52
  61  */
  62 typedef void *UFormattable;
  63
  64 /**
  65  * Initialize a UFormattable, to type UNUM_LONG, value 0
  66  * may return error if memory allocation failed.
  67  * parameter status error code.
  68  * See {@link unum_parseToUFormattable} for example code.
  69  * @stable ICU 52
  70  * @return the new UFormattable
  71  * @see ufmt_close
  72  * @see icu::Formattable::Formattable()
  73  */
  74 U_STABLE UFormattable* U_EXPORT2
  75 ufmt_open(UErrorCode* status);
  76
  77 /**
  78  * Cleanup any additional memory allocated by this UFormattable.
  79  * @param fmt the formatter
  80  * @stable ICU 52
  81  * @see ufmt_open
  82  */
  83 U_STABLE void U_EXPORT2
  84 ufmt_close(UFormattable* fmt);
  85
  86 #if U_SHOW_CPLUSPLUS_API
  87
  88 U_NAMESPACE_BEGIN
  89
  90 /**
  91  * \class LocalUFormattablePointer
  92  * "Smart pointer" class, closes a UFormattable via ufmt_close().
  93  * For most methods see the LocalPointerBase base class.
  94  *
  95  * @see LocalPointerBase
  96  * @see LocalPointer
  97  * @stable ICU 52
  98  */
  99 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattablePointer, UFormattable, ufmt_close);
 100
 101 U_NAMESPACE_END
 102
 103 #endif
 104
 105 /**
 106  * Return the type of this object
 107  * @param fmt the UFormattable object
 108  * @param status status code - U_ILLEGAL_ARGUMENT_ERROR is returned if the UFormattable contains data not supported by
 109  * the API
 110  * @return the value as a UFormattableType
 111  * @see ufmt_isNumeric
 112  * @see icu::Formattable::getType() const
 113  * @stable ICU 52
 114  */
 115 U_STABLE UFormattableType U_EXPORT2
 116 ufmt_getType(const UFormattable* fmt, UErrorCode *status);
 117
 118 /**
 119  * Return whether the object is numeric.
 120  * @param fmt the UFormattable object
 121  * @return true if the object is a double, long, or int64 value, else false.
 122  * @see ufmt_getType
 123  * @see icu::Formattable::isNumeric() const
 124  * @stable ICU 52
 125  */
 126 U_STABLE UBool U_EXPORT2
 127 ufmt_isNumeric(const UFormattable* fmt);
 128
 129 /**
 130  * Gets the UDate value of this object.  If the type is not of type UFMT_DATE,
 131  * status is set to U_INVALID_FORMAT_ERROR and the return value is
 132  * undefined.
 133  * @param fmt the UFormattable object
 134  * @param status the error code - any conversion or format errors
 135  * @return the value
 136  * @stable ICU 52
 137  * @see icu::Formattable::getDate(UErrorCode&) const
 138  */
 139 U_STABLE UDate U_EXPORT2
 140 ufmt_getDate(const UFormattable* fmt, UErrorCode *status);
 141
 142 /**
 143  * Gets the double value of this object. If the type is not a UFMT_DOUBLE, or
 144  * if there are additional significant digits than fit in a double type,
 145  * a conversion is performed with  possible loss of precision.
 146  * If the type is UFMT_OBJECT and the
 147  * object is a Measure, then the result of
 148  * getNumber().getDouble(status) is returned.  If this object is
 149  * neither a numeric type nor a Measure, then 0 is returned and
 150  * the status is set to U_INVALID_FORMAT_ERROR.
 151  * @param fmt the UFormattable object
 152  * @param status the error code - any conversion or format errors
 153  * @return the value
 154  * @stable ICU 52
 155  * @see icu::Formattable::getDouble(UErrorCode&) const
 156  */
 157 U_STABLE double U_EXPORT2
 158 ufmt_getDouble(UFormattable* fmt, UErrorCode *status);
 159
 160 /**
 161  * Gets the long (int32_t) value of this object. If the magnitude is too
 162  * large to fit in a long, then the maximum or minimum long value,
 163  * as appropriate, is returned and the status is set to
 164  * U_INVALID_FORMAT_ERROR.  If this object is of type UFMT_INT64 and
 165  * it fits within a long, then no precision is lost.  If it is of
 166  * type kDouble or kDecimalNumber, then a conversion is peformed, with
 167  * truncation of any fractional part.  If the type is UFMT_OBJECT and
 168  * the object is a Measure, then the result of
 169  * getNumber().getLong(status) is returned.  If this object is
 170  * neither a numeric type nor a Measure, then 0 is returned and
 171  * the status is set to U_INVALID_FORMAT_ERROR.
 172  * @param fmt the UFormattable object
 173  * @param status the error code - any conversion or format errors
 174  * @return the value
 175  * @stable ICU 52
 176  * @see icu::Formattable::getLong(UErrorCode&) const
 177  */
 178 U_STABLE int32_t U_EXPORT2
 179 ufmt_getLong(UFormattable* fmt, UErrorCode *status);
 180
 181
 182 /**
 183  * Gets the int64_t value of this object. If this object is of a numeric
 184  * type and the magnitude is too large to fit in an int64, then
 185  * the maximum or minimum int64 value, as appropriate, is returned
 186  * and the status is set to U_INVALID_FORMAT_ERROR.  If the
 187  * magnitude fits in an int64, then a casting conversion is
 188  * peformed, with truncation of any fractional part.  If the type
 189  * is UFMT_OBJECT and the object is a Measure, then the result of
 190  * getNumber().getDouble(status) is returned.  If this object is
 191  * neither a numeric type nor a Measure, then 0 is returned and
 192  * the status is set to U_INVALID_FORMAT_ERROR.
 193  * @param fmt the UFormattable object
 194  * @param status the error code - any conversion or format errors
 195  * @return the value
 196  * @stable ICU 52
 197  * @see icu::Formattable::getInt64(UErrorCode&) const
 198  */
 199 U_STABLE int64_t U_EXPORT2
 200 ufmt_getInt64(UFormattable* fmt, UErrorCode *status);
 201
 202 /**
 203  * Returns a pointer to the UObject contained within this
 204  * formattable (as a const void*), or NULL if this object
 205  * is not of type UFMT_OBJECT.
 206  * @param fmt the UFormattable object
 207  * @param status the error code - any conversion or format errors
 208  * @return the value as a const void*. It is a polymorphic C++ object.
 209  * @stable ICU 52
 210  * @see icu::Formattable::getObject() const
 211  */
 212 U_STABLE const void *U_EXPORT2
 213 ufmt_getObject(const UFormattable* fmt, UErrorCode *status);
 214
 215 /**
 216  * Gets the string value of this object as a UChar string. If the type is not a
 217  * string, status is set to U_INVALID_FORMAT_ERROR and a NULL pointer is returned.
 218  * This function is not thread safe and may modify the UFormattable if need be to terminate the string.
 219  * The returned pointer is not valid if any other functions are called on this UFormattable, or if the UFormattable is closed.
 220  * @param fmt the UFormattable object
 221  * @param status the error code - any conversion or format errors
 222  * @param len if non null, contains the string length on return
 223  * @return the null terminated string value - must not be referenced after any other functions are called on this UFormattable.
 224  * @stable ICU 52
 225  * @see icu::Formattable::getString(UnicodeString&)const
 226  */
 227 U_STABLE const UChar* U_EXPORT2
 228 ufmt_getUChars(UFormattable* fmt, int32_t *len, UErrorCode *status);
 229
 230 /**
 231  * Get the number of array objects contained, if an array type UFMT_ARRAY
 232  * @param fmt the UFormattable object
 233  * @param status the error code - any conversion or format errors. U_ILLEGAL_ARGUMENT_ERROR if not an array type.
 234  * @return the number of array objects or undefined if not an array type
 235  * @stable ICU 52
 236  * @see ufmt_getArrayItemByIndex
 237  */
 238 U_STABLE int32_t U_EXPORT2
 239 ufmt_getArrayLength(const UFormattable* fmt, UErrorCode *status);
 240
 241 /**
 242  * Get the specified value from the array of UFormattables. Invalid if the object is not an array type UFMT_ARRAY
 243  * @param fmt the UFormattable object
 244  * @param n the number of the array to return (0 based).
 245  * @param status the error code - any conversion or format errors. Returns an error if n is out of bounds.
 246  * @return the nth array value, only valid while the containing UFormattable is valid. NULL if not an array.
 247  * @stable ICU 52
 248  * @see icu::Formattable::getArray(int32_t&, UErrorCode&) const
 249  */
 250 U_STABLE UFormattable * U_EXPORT2
 251 ufmt_getArrayItemByIndex(UFormattable* fmt, int32_t n, UErrorCode *status);
 252
 253 /**
 254  * Returns a numeric string representation of the number contained within this
 255  * formattable, or NULL if this object does not contain numeric type.
 256  * For values obtained by parsing, the returned decimal number retains
 257  * the full precision and range of the original input, unconstrained by
 258  * the limits of a double floating point or a 64 bit int.
 259  *
 260  * This function is not thread safe, and therfore is not declared const,
 261  * even though it is logically const.
 262  * The resulting buffer is owned by the UFormattable and is invalid if any other functions are
 263  * called on the UFormattable.
 264  *
 265  * Possible errors include U_MEMORY_ALLOCATION_ERROR, and
 266  * U_INVALID_STATE if the formattable object has not been set to
 267  * a numeric type.
 268  * @param fmt the UFormattable object
 269  * @param len if non-null, on exit contains the string length (not including the terminating null)
 270  * @param status the error code
 271  * @return 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.
 272  * @stable ICU 52
 273  * @see icu::Formattable::getDecimalNumber(UErrorCode&)
 274  */
 275 U_STABLE const char * U_EXPORT2
 276 ufmt_getDecNumChars(UFormattable *fmt, int32_t *len, UErrorCode *status);
 277
 278 #endif
 279
 280 #endif