[apple/icu.git] / icuSources / i18n / unicode / uformattable.h

/*
********************************************************************************
* 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*/
  UFMT_COUNT     /**< Count of defined UFormattableType values */
} 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
Commit	Line	Data
57a6839d A	1	/*
57a6839d A	2	********************************************************************************
b331163b	3	* Copyright (C) 2013-2014, International Business Machines Corporation and others.
57a6839d A	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
57a6839d A	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
b331163b	42	* @stable ICU 52
57a6839d A	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
b331163b	60	* @stable ICU 52
57a6839d A	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.
b331163b	69	* @stable ICU 52
57a6839d A	70	* @return the new UFormattable
	71	* @see ufmt_close
	72	* @see icu::Formattable::Formattable()
	73	*/
b331163b	74	U_STABLE UFormattable* U_EXPORT2
57a6839d A	75	ufmt_open(UErrorCode* status);
	76
	77	/**
	78	* Cleanup any additional memory allocated by this UFormattable.
	79	* @param fmt the formatter
b331163b	80	* @stable ICU 52
57a6839d A	81	* @see ufmt_open
57a6839d A	82	*/
b331163b	83	U_STABLE void U_EXPORT2
57a6839d A	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
b331163b	97	* @stable ICU 52
57a6839d A	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
b331163b	113	* @stable ICU 52
57a6839d	114	*/
b331163b	115	U_STABLE UFormattableType U_EXPORT2
57a6839d A	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
b331163b	124	* @stable ICU 52
57a6839d	125	*/
b331163b	126	U_STABLE UBool U_EXPORT2
57a6839d A	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
b331163b	136	* @stable ICU 52
57a6839d A	137	* @see icu::Formattable::getDate(UErrorCode&) const
57a6839d A	138	*/
b331163b	139	U_STABLE UDate U_EXPORT2
57a6839d A	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
b331163b	154	* @stable ICU 52
57a6839d A	155	* @see icu::Formattable::getDouble(UErrorCode&) const
57a6839d A	156	*/
b331163b	157	U_STABLE double U_EXPORT2
57a6839d A	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
b331163b	175	* @stable ICU 52
57a6839d A	176	* @see icu::Formattable::getLong(UErrorCode&) const
57a6839d A	177	*/
b331163b	178	U_STABLE int32_t U_EXPORT2
57a6839d A	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
b331163b	196	* @stable ICU 52
57a6839d A	197	* @see icu::Formattable::getInt64(UErrorCode&) const
57a6839d A	198	*/
b331163b	199	U_STABLE int64_t U_EXPORT2
57a6839d A	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.
b331163b	209	* @stable ICU 52
57a6839d A	210	* @see icu::Formattable::getObject() const
57a6839d A	211	*/
b331163b	212	U_STABLE const void *U_EXPORT2
57a6839d A	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.
b331163b	224	* @stable ICU 52
57a6839d A	225	* @see icu::Formattable::getString(UnicodeString&)const
57a6839d A	226	*/
b331163b	227	U_STABLE const UChar* U_EXPORT2
57a6839d A	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
b331163b	235	* @stable ICU 52
57a6839d A	236	* @see ufmt_getArrayItemByIndex
57a6839d A	237	*/
b331163b	238	U_STABLE int32_t U_EXPORT2
57a6839d A	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.
b331163b	247	* @stable ICU 52
57a6839d A	248	* @see icu::Formattable::getArray(int32_t&, UErrorCode&) const
57a6839d A	249	*/
b331163b	250	U_STABLE UFormattable * U_EXPORT2
57a6839d A	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.
b331163b	272	* @stable ICU 52
57a6839d A	273	* @see icu::Formattable::getDecimalNumber(UErrorCode&)
57a6839d A	274	*/
b331163b	275	U_STABLE const char * U_EXPORT2
57a6839d	276	ufmt_getDecNumChars(UFormattable fmt, int32_t len, UErrorCode *status);
57a6839d A	277
	278	#endif
	279
	280	#endif