DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (d38398e5144e)

VCS Links

UFormattableType

Macros

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
// Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
********************************************************************************
* Copyright (C) 2013-2014, International Business Machines Corporation and others.
* All Rights Reserved.
********************************************************************************
*
* File UFORMATTABLE.H
*
* Modification History:
*
*   Date        Name        Description
*   2013 Jun 7  srl         New
********************************************************************************
*/

/**
 * \file
 * \brief 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 {@link unum_parseToUFormattable} for example code.
 */

#ifndef UFORMATTABLE_H
#define UFORMATTABLE_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/localpointer.h"

/**
 * Enum designating the type of a UFormattable instance.
 * Practically, this indicates which of the getters would return without conversion
 * or error.
 * @see icu::Formattable::Type
 * @stable ICU 52
 */
typedef enum UFormattableType {
  UFMT_DATE = 0, /**< ufmt_getDate() will return without conversion. @see ufmt_getDate*/
  UFMT_DOUBLE,   /**< ufmt_getDouble() will return without conversion.  @see ufmt_getDouble*/
  UFMT_LONG,     /**< ufmt_getLong() will return without conversion. @see ufmt_getLong */
  UFMT_STRING,   /**< ufmt_getUChars() will return without conversion.  @see ufmt_getUChars*/
  UFMT_ARRAY,    /**< ufmt_countArray() and ufmt_getArray() will return the value.  @see ufmt_getArrayItemByIndex */
  UFMT_INT64,    /**< ufmt_getInt64() will return without conversion. @see ufmt_getInt64 */
  UFMT_OBJECT,   /**< ufmt_getObject() will return without conversion.  @see ufmt_getObject*/
#ifndef U_HIDE_DEPRECATED_API
    /**
     * One more than the highest normal UFormattableType value.
     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
     */
    UFMT_COUNT
#endif  // U_HIDE_DEPRECATED_API
} UFormattableType;


/**
 * Opaque type representing various types of data which may be used for formatting
 * and parsing operations.
 * @see icu::Formattable
 * @stable ICU 52
 */
typedef void *UFormattable;

/**
 * Initialize a UFormattable, to type UNUM_LONG, value 0
 * may return error if memory allocation failed.
 * parameter status error code.
 * See {@link unum_parseToUFormattable} for example code.
 * @stable ICU 52
 * @return the new UFormattable
 * @see ufmt_close
 * @see icu::Formattable::Formattable()
 */
U_STABLE UFormattable* U_EXPORT2
ufmt_open(UErrorCode* status);

/**
 * Cleanup any additional memory allocated by this UFormattable.
 * @param fmt the formatter
 * @stable ICU 52
 * @see ufmt_open
 */
U_STABLE void U_EXPORT2
ufmt_close(UFormattable* fmt);

#if U_SHOW_CPLUSPLUS_API

U_NAMESPACE_BEGIN

/**
 * \class LocalUFormattablePointer
 * "Smart pointer" class, closes a UFormattable via ufmt_close().
 * For most methods see the LocalPointerBase base class.
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 52
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattablePointer, UFormattable, ufmt_close);

U_NAMESPACE_END

#endif

/**
 * Return the type of this object
 * @param fmt the UFormattable object
 * @param status status code - U_ILLEGAL_ARGUMENT_ERROR is returned if the UFormattable contains data not supported by
 * the API
 * @return the value as a UFormattableType
 * @see ufmt_isNumeric
 * @see icu::Formattable::getType() const
 * @stable ICU 52
 */
U_STABLE UFormattableType U_EXPORT2
ufmt_getType(const UFormattable* fmt, UErrorCode *status);

/**
 * Return whether the object is numeric.
 * @param fmt the UFormattable object
 * @return true if the object is a double, long, or int64 value, else false.
 * @see ufmt_getType
 * @see icu::Formattable::isNumeric() const
 * @stable ICU 52
 */
U_STABLE UBool U_EXPORT2
ufmt_isNumeric(const UFormattable* fmt);

/**
 * 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.
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors
 * @return the value
 * @stable ICU 52
 * @see icu::Formattable::getDate(UErrorCode&) const
 */
U_STABLE UDate U_EXPORT2
ufmt_getDate(const 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.
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors
 * @return the value
 * @stable ICU 52
 * @see icu::Formattable::getDouble(UErrorCode&) const
 */
U_STABLE double U_EXPORT2
ufmt_getDouble(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.
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors
 * @return the value
 * @stable ICU 52
 * @see icu::Formattable::getLong(UErrorCode&) const
 */
U_STABLE int32_t U_EXPORT2
ufmt_getLong(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.
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors
 * @return the value
 * @stable ICU 52
 * @see icu::Formattable::getInt64(UErrorCode&) const
 */
U_STABLE int64_t U_EXPORT2
ufmt_getInt64(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.
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors
 * @return the value as a const void*. It is a polymorphic C++ object.
 * @stable ICU 52
 * @see icu::Formattable::getObject() const
 */
U_STABLE const void *U_EXPORT2
ufmt_getObject(const UFormattable* fmt, 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.
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors
 * @param len if non null, contains the string length on return
 * @return the null terminated string value - must not be referenced after any other functions are called on this UFormattable.
 * @stable ICU 52
 * @see icu::Formattable::getString(UnicodeString&)const
 */
U_STABLE const UChar* U_EXPORT2
ufmt_getUChars(UFormattable* fmt, int32_t *len, UErrorCode *status);

/**
 * Get the number of array objects contained, if an array type UFMT_ARRAY
 * @param fmt the UFormattable object
 * @param status the error code - any conversion or format errors. U_ILLEGAL_ARGUMENT_ERROR if not an array type.
 * @return the number of array objects or undefined if not an array type
 * @stable ICU 52
 * @see ufmt_getArrayItemByIndex
 */
U_STABLE int32_t U_EXPORT2
ufmt_getArrayLength(const UFormattable* fmt, UErrorCode *status);

/**
 * Get the specified value from the array of UFormattables. Invalid if the object is not an array type UFMT_ARRAY
 * @param fmt the UFormattable object
 * @param n the number of the array to return (0 based).
 * @param status the error code - any conversion or format errors. Returns an error if n is out of bounds.
 * @return the nth array value, only valid while the containing UFormattable is valid. NULL if not an array.
 * @stable ICU 52
 * @see icu::Formattable::getArray(int32_t&, UErrorCode&) const
 */
U_STABLE UFormattable * U_EXPORT2
ufmt_getArrayItemByIndex(UFormattable* fmt, int32_t n, 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.
 * @param fmt the UFormattable object
 * @param len if non-null, on exit contains the string length (not including the terminating null)
 * @param status the error code
 * @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.
 * @stable ICU 52
 * @see icu::Formattable::getDecimalNumber(UErrorCode&)
 */
U_STABLE const char * U_EXPORT2
ufmt_getDecNumChars(UFormattable *fmt, int32_t *len, UErrorCode *status);

#endif

#endif