1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/uformattable.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,283 @@
1.4 +/*
1.5 +********************************************************************************
1.6 +* Copyright (C) 2013, International Business Machines Corporation and others.
1.7 +* All Rights Reserved.
1.8 +********************************************************************************
1.9 +*
1.10 +* File UFORMATTABLE.H
1.11 +*
1.12 +* Modification History:
1.13 +*
1.14 +* Date Name Description
1.15 +* 2013 Jun 7 srl New
1.16 +********************************************************************************
1.17 +*/
1.18 +
1.19 +/**
1.20 + * \file
1.21 + * \brief C API: UFormattable is a thin wrapper for primitive types used for formatting and parsing.
1.22 + *
1.23 + * This is a C interface to the icu::Formattable class. Static functions on this class convert
1.24 + * to and from this interface (via reinterpret_cast). Note that Formattables (and thus UFormattables)
1.25 + * are mutable, and many operations (even getters) may actually modify the internal state. For this
1.26 + * reason, UFormattables are not thread safe, and should not be shared between threads.
1.27 + *
1.28 + * See {@link unum_parseToUFormattable} for example code.
1.29 + */
1.30 +
1.31 +#ifndef UFORMATTABLE_H
1.32 +#define UFORMATTABLE_H
1.33 +
1.34 +#include "unicode/utypes.h"
1.35 +
1.36 +#if !UCONFIG_NO_FORMATTING
1.37 +
1.38 +#ifndef U_HIDE_DRAFT_API
1.39 +
1.40 +#include "unicode/localpointer.h"
1.41 +
1.42 +/**
1.43 + * Enum designating the type of a UFormattable instance.
1.44 + * Practically, this indicates which of the getters would return without conversion
1.45 + * or error.
1.46 + * @see icu::Formattable::Type
1.47 + * @draft ICU 52
1.48 + */
1.49 +typedef enum UFormattableType {
1.50 + UFMT_DATE = 0, /**< ufmt_getDate() will return without conversion. @see ufmt_getDate*/
1.51 + UFMT_DOUBLE, /**< ufmt_getDouble() will return without conversion. @see ufmt_getDouble*/
1.52 + UFMT_LONG, /**< ufmt_getLong() will return without conversion. @see ufmt_getLong */
1.53 + UFMT_STRING, /**< ufmt_getUChars() will return without conversion. @see ufmt_getUChars*/
1.54 + UFMT_ARRAY, /**< ufmt_countArray() and ufmt_getArray() will return the value. @see ufmt_getArrayItemByIndex */
1.55 + UFMT_INT64, /**< ufmt_getInt64() will return without conversion. @see ufmt_getInt64 */
1.56 + UFMT_OBJECT, /**< ufmt_getObject() will return without conversion. @see ufmt_getObject*/
1.57 + UFMT_COUNT /**< Count of defined UFormattableType values */
1.58 +} UFormattableType;
1.59 +
1.60 +
1.61 +/**
1.62 + * Opaque type representing various types of data which may be used for formatting
1.63 + * and parsing operations.
1.64 + * @see icu::Formattable
1.65 + * @draft ICU 52
1.66 + */
1.67 +typedef void *UFormattable;
1.68 +
1.69 +/**
1.70 + * Initialize a UFormattable, to type UNUM_LONG, value 0
1.71 + * may return error if memory allocation failed.
1.72 + * parameter status error code.
1.73 + * See {@link unum_parseToUFormattable} for example code.
1.74 + * @draft ICU 52
1.75 + * @return the new UFormattable
1.76 + * @see ufmt_close
1.77 + * @see icu::Formattable::Formattable()
1.78 + */
1.79 +U_DRAFT UFormattable* U_EXPORT2
1.80 +ufmt_open(UErrorCode* status);
1.81 +
1.82 +/**
1.83 + * Cleanup any additional memory allocated by this UFormattable.
1.84 + * @param fmt the formatter
1.85 + * @draft ICU 52
1.86 + * @see ufmt_open
1.87 + */
1.88 +U_DRAFT void U_EXPORT2
1.89 +ufmt_close(UFormattable* fmt);
1.90 +
1.91 +#if U_SHOW_CPLUSPLUS_API
1.92 +
1.93 +U_NAMESPACE_BEGIN
1.94 +
1.95 +/**
1.96 + * \class LocalUFormattablePointer
1.97 + * "Smart pointer" class, closes a UFormattable via ufmt_close().
1.98 + * For most methods see the LocalPointerBase base class.
1.99 + *
1.100 + * @see LocalPointerBase
1.101 + * @see LocalPointer
1.102 + * @draft ICU 52
1.103 + */
1.104 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattablePointer, UFormattable, ufmt_close);
1.105 +
1.106 +U_NAMESPACE_END
1.107 +
1.108 +#endif
1.109 +
1.110 +/**
1.111 + * Return the type of this object
1.112 + * @param fmt the UFormattable object
1.113 + * @param status status code - U_ILLEGAL_ARGUMENT_ERROR is returned if the UFormattable contains data not supported by
1.114 + * the API
1.115 + * @return the value as a UFormattableType
1.116 + * @see ufmt_isNumeric
1.117 + * @see icu::Formattable::getType() const
1.118 + * @draft ICU 52
1.119 + */
1.120 +U_DRAFT UFormattableType U_EXPORT2
1.121 +ufmt_getType(const UFormattable* fmt, UErrorCode *status);
1.122 +
1.123 +/**
1.124 + * Return whether the object is numeric.
1.125 + * @param fmt the UFormattable object
1.126 + * @return true if the object is a double, long, or int64 value, else false.
1.127 + * @see ufmt_getType
1.128 + * @see icu::Formattable::isNumeric() const
1.129 + * @draft ICU 52
1.130 + */
1.131 +U_DRAFT UBool U_EXPORT2
1.132 +ufmt_isNumeric(const UFormattable* fmt);
1.133 +
1.134 +/**
1.135 + * Gets the UDate value of this object. If the type is not of type UFMT_DATE,
1.136 + * status is set to U_INVALID_FORMAT_ERROR and the return value is
1.137 + * undefined.
1.138 + * @param fmt the UFormattable object
1.139 + * @param status the error code - any conversion or format errors
1.140 + * @return the value
1.141 + * @draft ICU 52
1.142 + * @see icu::Formattable::getDate(UErrorCode&) const
1.143 + */
1.144 +U_DRAFT UDate U_EXPORT2
1.145 +ufmt_getDate(const UFormattable* fmt, UErrorCode *status);
1.146 +
1.147 +/**
1.148 + * Gets the double value of this object. If the type is not a UFMT_DOUBLE, or
1.149 + * if there are additional significant digits than fit in a double type,
1.150 + * a conversion is performed with possible loss of precision.
1.151 + * If the type is UFMT_OBJECT and the
1.152 + * object is a Measure, then the result of
1.153 + * getNumber().getDouble(status) is returned. If this object is
1.154 + * neither a numeric type nor a Measure, then 0 is returned and
1.155 + * the status is set to U_INVALID_FORMAT_ERROR.
1.156 + * @param fmt the UFormattable object
1.157 + * @param status the error code - any conversion or format errors
1.158 + * @return the value
1.159 + * @draft ICU 52
1.160 + * @see icu::Formattable::getDouble(UErrorCode&) const
1.161 + */
1.162 +U_DRAFT double U_EXPORT2
1.163 +ufmt_getDouble(UFormattable* fmt, UErrorCode *status);
1.164 +
1.165 +/**
1.166 + * Gets the long (int32_t) value of this object. If the magnitude is too
1.167 + * large to fit in a long, then the maximum or minimum long value,
1.168 + * as appropriate, is returned and the status is set to
1.169 + * U_INVALID_FORMAT_ERROR. If this object is of type UFMT_INT64 and
1.170 + * it fits within a long, then no precision is lost. If it is of
1.171 + * type kDouble or kDecimalNumber, then a conversion is peformed, with
1.172 + * truncation of any fractional part. If the type is UFMT_OBJECT and
1.173 + * the object is a Measure, then the result of
1.174 + * getNumber().getLong(status) is returned. If this object is
1.175 + * neither a numeric type nor a Measure, then 0 is returned and
1.176 + * the status is set to U_INVALID_FORMAT_ERROR.
1.177 + * @param fmt the UFormattable object
1.178 + * @param status the error code - any conversion or format errors
1.179 + * @return the value
1.180 + * @draft ICU 52
1.181 + * @see icu::Formattable::getLong(UErrorCode&) const
1.182 + */
1.183 +U_DRAFT int32_t U_EXPORT2
1.184 +ufmt_getLong(UFormattable* fmt, UErrorCode *status);
1.185 +
1.186 +
1.187 +/**
1.188 + * Gets the int64_t value of this object. If this object is of a numeric
1.189 + * type and the magnitude is too large to fit in an int64, then
1.190 + * the maximum or minimum int64 value, as appropriate, is returned
1.191 + * and the status is set to U_INVALID_FORMAT_ERROR. If the
1.192 + * magnitude fits in an int64, then a casting conversion is
1.193 + * peformed, with truncation of any fractional part. If the type
1.194 + * is UFMT_OBJECT and the object is a Measure, then the result of
1.195 + * getNumber().getDouble(status) is returned. If this object is
1.196 + * neither a numeric type nor a Measure, then 0 is returned and
1.197 + * the status is set to U_INVALID_FORMAT_ERROR.
1.198 + * @param fmt the UFormattable object
1.199 + * @param status the error code - any conversion or format errors
1.200 + * @return the value
1.201 + * @draft ICU 52
1.202 + * @see icu::Formattable::getInt64(UErrorCode&) const
1.203 + */
1.204 +U_DRAFT int64_t U_EXPORT2
1.205 +ufmt_getInt64(UFormattable* fmt, UErrorCode *status);
1.206 +
1.207 +/**
1.208 + * Returns a pointer to the UObject contained within this
1.209 + * formattable (as a const void*), or NULL if this object
1.210 + * is not of type UFMT_OBJECT.
1.211 + * @param fmt the UFormattable object
1.212 + * @param status the error code - any conversion or format errors
1.213 + * @return the value as a const void*. It is a polymorphic C++ object.
1.214 + * @draft ICU 52
1.215 + * @see icu::Formattable::getObject() const
1.216 + */
1.217 +U_DRAFT const void *U_EXPORT2
1.218 +ufmt_getObject(const UFormattable* fmt, UErrorCode *status);
1.219 +
1.220 +/**
1.221 + * Gets the string value of this object as a UChar string. If the type is not a
1.222 + * string, status is set to U_INVALID_FORMAT_ERROR and a NULL pointer is returned.
1.223 + * This function is not thread safe and may modify the UFormattable if need be to terminate the string.
1.224 + * The returned pointer is not valid if any other functions are called on this UFormattable, or if the UFormattable is closed.
1.225 + * @param fmt the UFormattable object
1.226 + * @param status the error code - any conversion or format errors
1.227 + * @param len if non null, contains the string length on return
1.228 + * @return the null terminated string value - must not be referenced after any other functions are called on this UFormattable.
1.229 + * @draft ICU 52
1.230 + * @see icu::Formattable::getString(UnicodeString&)const
1.231 + */
1.232 +U_DRAFT const UChar* U_EXPORT2
1.233 +ufmt_getUChars(UFormattable* fmt, int32_t *len, UErrorCode *status);
1.234 +
1.235 +/**
1.236 + * Get the number of array objects contained, if an array type UFMT_ARRAY
1.237 + * @param fmt the UFormattable object
1.238 + * @param status the error code - any conversion or format errors. U_ILLEGAL_ARGUMENT_ERROR if not an array type.
1.239 + * @return the number of array objects or undefined if not an array type
1.240 + * @draft ICU 52
1.241 + * @see ufmt_getArrayItemByIndex
1.242 + */
1.243 +U_DRAFT int32_t U_EXPORT2
1.244 +ufmt_getArrayLength(const UFormattable* fmt, UErrorCode *status);
1.245 +
1.246 +/**
1.247 + * Get the specified value from the array of UFormattables. Invalid if the object is not an array type UFMT_ARRAY
1.248 + * @param fmt the UFormattable object
1.249 + * @param n the number of the array to return (0 based).
1.250 + * @param status the error code - any conversion or format errors. Returns an error if n is out of bounds.
1.251 + * @return the nth array value, only valid while the containing UFormattable is valid. NULL if not an array.
1.252 + * @draft ICU 52
1.253 + * @see icu::Formattable::getArray(int32_t&, UErrorCode&) const
1.254 + */
1.255 +U_DRAFT UFormattable * U_EXPORT2
1.256 +ufmt_getArrayItemByIndex(UFormattable* fmt, int32_t n, UErrorCode *status);
1.257 +
1.258 +/**
1.259 + * Returns a numeric string representation of the number contained within this
1.260 + * formattable, or NULL if this object does not contain numeric type.
1.261 + * For values obtained by parsing, the returned decimal number retains
1.262 + * the full precision and range of the original input, unconstrained by
1.263 + * the limits of a double floating point or a 64 bit int.
1.264 + *
1.265 + * This function is not thread safe, and therfore is not declared const,
1.266 + * even though it is logically const.
1.267 + * The resulting buffer is owned by the UFormattable and is invalid if any other functions are
1.268 + * called on the UFormattable.
1.269 + *
1.270 + * Possible errors include U_MEMORY_ALLOCATION_ERROR, and
1.271 + * U_INVALID_STATE if the formattable object has not been set to
1.272 + * a numeric type.
1.273 + * @param fmt the UFormattable object
1.274 + * @param len if non-null, on exit contains the string length (not including the terminating null)
1.275 + * @param status the error code
1.276 + * @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.
1.277 + * @draft ICU 52
1.278 + * @see icu::Formattable::getDecimalNumber(UErrorCode&)
1.279 + */
1.280 +U_DRAFT const char * U_EXPORT2
1.281 +ufmt_getDecNumChars(UFormattable *fmt, int32_t *len, UErrorCode *status);
1.282 +#endif /* U_HIDE_DRAFT_API */
1.283 +
1.284 +#endif
1.285 +
1.286 +#endif
