source/i18n/unicode/uformattable.h

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