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

/*
 *******************************************************************************
 * Copyright (C) 2008-2012, Google, International Business Machines Corporation
 * and others. All Rights Reserved.
 *******************************************************************************
 */

#ifndef __TMUTFMT_H__
#define __TMUTFMT_H__

#include "unicode/utypes.h"

/**
 * \file
 * \brief C++ API: Format and parse duration in single time unit
 */


#if !UCONFIG_NO_FORMATTING

#include "unicode/unistr.h"
#include "unicode/tmunit.h"
#include "unicode/tmutamt.h"
#include "unicode/measfmt.h"
#include "unicode/numfmt.h"
#include "unicode/plurrule.h"

/**
 * Constants for various styles.
 * There are 2 styles: full name and abbreviated name.
 * For example, for English, the full name for hour duration is "3 hours",
 * and the abbreviated name is "3 hrs".
 * @stable ICU 4.8
 */
enum UTimeUnitFormatStyle {
    /** @stable ICU 4.8 */
    UTMUTFMT_FULL_STYLE,
    /** @stable ICU 4.8 */
    UTMUTFMT_ABBREVIATED_STYLE,
    /** @stable ICU 4.8 */
    UTMUTFMT_FORMAT_STYLE_COUNT
};
typedef enum UTimeUnitFormatStyle UTimeUnitFormatStyle; /**< @stable ICU 4.8 */

U_NAMESPACE_BEGIN

class Hashtable;
class UVector;

/**
 * Format or parse a TimeUnitAmount, using plural rules for the units where available.
 *
 * <P>
 * Code Sample:
 * <pre>
 *   // create time unit amount instance - a combination of Number and time unit
 *   UErrorCode status = U_ZERO_ERROR;
 *   TimeUnitAmount* source = new TimeUnitAmount(2, TimeUnit::UTIMEUNIT_YEAR, status);
 *   // create time unit format instance
 *   TimeUnitFormat* format = new TimeUnitFormat(Locale("en"), status);
 *   // format a time unit amount
 *   UnicodeString formatted;
 *   Formattable formattable;
 *   if (U_SUCCESS(status)) {
 *       formattable.adoptObject(source);
 *       formatted = ((Format*)format)->format(formattable, formatted, status);
 *       Formattable result;
 *       ((Format*)format)->parseObject(formatted, result, status);
 *       if (U_SUCCESS(status)) {
 *           assert (result == formattable);
 *       }
 *   }
 * </pre>
 *
 * <P>
 * @see TimeUnitAmount
 * @see TimeUnitFormat
 * @stable ICU 4.2
 */
class U_I18N_API TimeUnitFormat: public MeasureFormat {
public:

    /**
     * Create TimeUnitFormat with default locale, and full name style.
     * Use setLocale and/or setFormat to modify.
     * @stable ICU 4.2
     */
    TimeUnitFormat(UErrorCode& status);

    /**
     * Create TimeUnitFormat given locale, and full name style.
     * @stable ICU 4.2
     */
    TimeUnitFormat(const Locale& locale, UErrorCode& status);

    /**
     * Create TimeUnitFormat given locale and style.
     * @stable ICU 4.8
     */
    TimeUnitFormat(const Locale& locale, UTimeUnitFormatStyle style, UErrorCode& status);

    /**
     * Copy constructor.
     * @stable ICU 4.2
     */
    TimeUnitFormat(const TimeUnitFormat&);

    /**
     * deconstructor
     * @stable ICU 4.2
     */
    virtual ~TimeUnitFormat();

    /**
     * Clone this Format object polymorphically. The caller owns the result and
     * should delete it when done.
     * @return    A copy of the object.
     * @stable ICU 4.2
     */
    virtual Format* clone(void) const;

    /**
     * Assignment operator
     * @stable ICU 4.2
     */
    TimeUnitFormat& operator=(const TimeUnitFormat& other);


    /**
     * Return true if the given Format objects are semantically equal. Objects
     * of different subclasses are considered unequal.
     * @param other    the object to be compared with.
     * @return         true if the given Format objects are semantically equal.
     * @stable ICU 4.2
     */
    virtual UBool operator==(const Format& other) const;

    /**
     * Return true if the given Format objects are not semantically equal.
     * Objects of different subclasses are considered unequal.
     * @param other the object to be compared with.
     * @return      true if the given Format objects are not semantically equal.
     * @stable ICU 4.2
     */
    UBool operator!=(const Format& other) const;

    /**
     * Set the locale used for formatting or parsing.
     * @param locale  the locale to be set
     * @param status  output param set to success/failure code on exit
     * @stable ICU 4.2
     */
    void setLocale(const Locale& locale, UErrorCode& status);


    /**
     * Set the number format used for formatting or parsing.
     * @param format  the number formatter to be set
     * @param status  output param set to success/failure code on exit
     * @stable ICU 4.2
     */
    void setNumberFormat(const NumberFormat& format, UErrorCode& status);


    using MeasureFormat::format;

    /**
     * Format a TimeUnitAmount.
     * If the formattable object is not a time unit amount object,
     * or the number in time unit amount is not a double type or long type
     * numeric, it returns a failing status: U_ILLEGAL_ARGUMENT_ERROR.
     * @see Format#format(const Formattable&, UnicodeString&, FieldPosition&,  UErrorCode&) const
     * @stable ICU 4.2
     */
    virtual UnicodeString& format(const Formattable& obj,
                                  UnicodeString& toAppendTo,
                                  FieldPosition& pos,
                                  UErrorCode& status) const;

    /**
     * Parse a TimeUnitAmount.
     * @see Format#parseObject(const UnicodeString&, Formattable&, ParsePosition&) const;
     * @stable ICU 4.2
     */
    virtual void parseObject(const UnicodeString& source,
                             Formattable& result,
                             ParsePosition& pos) const;

    /**
     * Return the class ID for this class. This is useful only for comparing to
     * a return value from getDynamicClassID(). For example:
     * <pre>
     * .   Base* polymorphic_pointer = createPolymorphicObject();
     * .   if (polymorphic_pointer->getDynamicClassID() ==
     * .       erived::getStaticClassID()) ...
     * </pre>
     * @return          The class ID for all objects of this class.
     * @stable ICU 4.2
     */
    static UClassID U_EXPORT2 getStaticClassID(void);

    /**
     * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
     * method is to implement a simple version of RTTI, since not all C++
     * compilers support genuine RTTI. Polymorphic operator==() and clone()
     * methods call this method.
     *
     * @return          The class ID for this object. All objects of a
     *                  given class have the same class ID.  Objects of
     *                  other classes have different class IDs.
     * @stable ICU 4.2
     */
    virtual UClassID getDynamicClassID(void) const;

private:
    NumberFormat* fNumberFormat;
    Locale        fLocale;
    Hashtable*    fTimeUnitToCountToPatterns[TimeUnit::UTIMEUNIT_FIELD_COUNT];
    PluralRules*  fPluralRules;
    UTimeUnitFormatStyle fStyle;

    void create(const Locale& locale, UTimeUnitFormatStyle style, UErrorCode& status);

    // it might actually be simpler to make them Decimal Formats later.
    // initialize all private data members
    void setup(UErrorCode& status);

    // initialize data member without fill in data for fTimeUnitToCountToPattern
    void initDataMembers(UErrorCode& status);

    // initialize fTimeUnitToCountToPatterns from current locale's resource.
    void readFromCurrentLocale(UTimeUnitFormatStyle style, const char* key, const UVector& pluralCounts,
                               UErrorCode& status);

    // check completeness of fTimeUnitToCountToPatterns against all time units,
    // and all plural rules, fill in fallback as necessary.
    void checkConsistency(UTimeUnitFormatStyle style, const char* key, UErrorCode& status);

    // fill in fTimeUnitToCountToPatterns from locale fall-back chain
    void searchInLocaleChain(UTimeUnitFormatStyle style, const char* key, const char* localeName,
                             TimeUnit::UTimeUnitFields field, const UnicodeString&,
                             const char*, Hashtable*, UErrorCode&);

    // initialize hash table
    Hashtable* initHash(UErrorCode& status);

    // delete hash table
    void deleteHash(Hashtable* htable);

    // copy hash table
    void copyHash(const Hashtable* source, Hashtable* target, UErrorCode& status);
    // get time unit name, such as "year", from time unit field enum, such as
    // UTIMEUNIT_YEAR.
    static const char* getTimeUnitName(TimeUnit::UTimeUnitFields field, UErrorCode& status);
};


inline UBool
TimeUnitFormat::operator!=(const Format& other) const  {
    return !operator==(other);
}


U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif // __TMUTFMT_H__
//eof
Commit	Line	Data
729e4ab9 A	1	/*
729e4ab9 A	2	*******************************************************************************
4388f060 A	3	* Copyright (C) 2008-2012, Google, International Business Machines Corporation
4388f060 A	4	* and others. All Rights Reserved.
729e4ab9 A	5	*******************************************************************************
	6	*/
	7
	8	#ifndef __TMUTFMT_H__
	9	#define __TMUTFMT_H__
	10
	11	#include "unicode/utypes.h"
	12
	13	/**
	14	* \file
	15	* \brief C++ API: Format and parse duration in single time unit
	16	*/
	17
	18
	19	#if !UCONFIG_NO_FORMATTING
	20
	21	#include "unicode/unistr.h"
	22	#include "unicode/tmunit.h"
	23	#include "unicode/tmutamt.h"
	24	#include "unicode/measfmt.h"
	25	#include "unicode/numfmt.h"
	26	#include "unicode/plurrule.h"
	27
	28	/**
4388f060 A	29	* Constants for various styles.
	30	* There are 2 styles: full name and abbreviated name.
	31	* For example, for English, the full name for hour duration is "3 hours",
	32	* and the abbreviated name is "3 hrs".
	33	* @stable ICU 4.8
729e4ab9	34	*/
4388f060 A	35	enum UTimeUnitFormatStyle {
	36	/** @stable ICU 4.8 */
	37	UTMUTFMT_FULL_STYLE,
	38	/** @stable ICU 4.8 */
	39	UTMUTFMT_ABBREVIATED_STYLE,
	40	/** @stable ICU 4.8 */
	41	UTMUTFMT_FORMAT_STYLE_COUNT
	42	};
	43	typedef enum UTimeUnitFormatStyle UTimeUnitFormatStyle; /*< @stable ICU 4.8 /
729e4ab9 A	44
	45	U_NAMESPACE_BEGIN
	46
	47	class Hashtable;
51004dcb	48	class UVector;
729e4ab9 A	49
	50	/**
	51	* Format or parse a TimeUnitAmount, using plural rules for the units where available.
	52	*
	53	* <P>
	54	* Code Sample:
	55	* <pre>
	56	* // create time unit amount instance - a combination of Number and time unit
	57	* UErrorCode status = U_ZERO_ERROR;
	58	* TimeUnitAmount* source = new TimeUnitAmount(2, TimeUnit::UTIMEUNIT_YEAR, status);
	59	* // create time unit format instance
	60	* TimeUnitFormat* format = new TimeUnitFormat(Locale("en"), status);
	61	* // format a time unit amount
	62	* UnicodeString formatted;
	63	* Formattable formattable;
	64	* if (U_SUCCESS(status)) {
	65	* formattable.adoptObject(source);
	66	* formatted = ((Format*)format)->format(formattable, formatted, status);
	67	* Formattable result;
	68	* ((Format*)format)->parseObject(formatted, result, status);
	69	* if (U_SUCCESS(status)) {
	70	* assert (result == formattable);
	71	* }
	72	* }
	73	* </pre>
	74	*
	75	* <P>
	76	* @see TimeUnitAmount
	77	* @see TimeUnitFormat
4388f060	78	* @stable ICU 4.2
729e4ab9 A	79	*/
	80	class U_I18N_API TimeUnitFormat: public MeasureFormat {
	81	public:
	82
729e4ab9 A	83	/**
	84	* Create TimeUnitFormat with default locale, and full name style.
	85	* Use setLocale and/or setFormat to modify.
	86	* @stable ICU 4.2
	87	*/
	88	TimeUnitFormat(UErrorCode& status);
	89
	90	/**
	91	* Create TimeUnitFormat given locale, and full name style.
	92	* @stable ICU 4.2
	93	*/
	94	TimeUnitFormat(const Locale& locale, UErrorCode& status);
	95
	96	/**
	97	* Create TimeUnitFormat given locale and style.
4388f060	98	* @stable ICU 4.8
729e4ab9	99	*/
4388f060	100	TimeUnitFormat(const Locale& locale, UTimeUnitFormatStyle style, UErrorCode& status);
729e4ab9 A	101
	102	/**
	103	* Copy constructor.
	104	* @stable ICU 4.2
	105	*/
	106	TimeUnitFormat(const TimeUnitFormat&);
	107
	108	/**
	109	* deconstructor
	110	* @stable ICU 4.2
	111	*/
	112	virtual ~TimeUnitFormat();
	113
	114	/**
	115	* Clone this Format object polymorphically. The caller owns the result and
	116	* should delete it when done.
	117	* @return A copy of the object.
	118	* @stable ICU 4.2
	119	*/
	120	virtual Format* clone(void) const;
	121
	122	/**
	123	* Assignment operator
	124	* @stable ICU 4.2
	125	*/
	126	TimeUnitFormat& operator=(const TimeUnitFormat& other);
	127
	128
	129	/**
	130	* Return true if the given Format objects are semantically equal. Objects
	131	* of different subclasses are considered unequal.
	132	* @param other the object to be compared with.
	133	* @return true if the given Format objects are semantically equal.
	134	* @stable ICU 4.2
	135	*/
	136	virtual UBool operator==(const Format& other) const;
	137
	138	/**
	139	* Return true if the given Format objects are not semantically equal.
	140	* Objects of different subclasses are considered unequal.
	141	* @param other the object to be compared with.
	142	* @return true if the given Format objects are not semantically equal.
	143	* @stable ICU 4.2
	144	*/
	145	UBool operator!=(const Format& other) const;
	146
	147	/**
	148	* Set the locale used for formatting or parsing.
	149	* @param locale the locale to be set
	150	* @param status output param set to success/failure code on exit
	151	* @stable ICU 4.2
	152	*/
	153	void setLocale(const Locale& locale, UErrorCode& status);
	154
	155
	156	/**
	157	* Set the number format used for formatting or parsing.
	158	* @param format the number formatter to be set
	159	* @param status output param set to success/failure code on exit
	160	* @stable ICU 4.2
	161	*/
	162	void setNumberFormat(const NumberFormat& format, UErrorCode& status);
	163
	164
165	using MeasureFormat::format;
166
167	/**
168	* Format a TimeUnitAmount.
169	* If the formattable object is not a time unit amount object,
170	* or the number in time unit amount is not a double type or long type
171	* numeric, it returns a failing status: U_ILLEGAL_ARGUMENT_ERROR.
172	* @see Format#format(const Formattable&, UnicodeString&, FieldPosition&, UErrorCode&) const
173	* @stable ICU 4.2
174	*/
175	virtual UnicodeString& format(const Formattable& obj,
176	UnicodeString& toAppendTo,
177	FieldPosition& pos,
178	UErrorCode& status) const;
179
180	/**
181	* Parse a TimeUnitAmount.
182	* @see Format#parseObject(const UnicodeString&, Formattable&, ParsePosition&) const;
183	* @stable ICU 4.2
184	*/
185	virtual void parseObject(const UnicodeString& source,
186	Formattable& result,
187	ParsePosition& pos) const;
188
189	/**
190	* Return the class ID for this class. This is useful only for comparing to
191	* a return value from getDynamicClassID(). For example:
192	* <pre>
193	* . Base* polymorphic_pointer = createPolymorphicObject();
194	* . if (polymorphic_pointer->getDynamicClassID() ==
195	* . erived::getStaticClassID()) ...
196	* </pre>
197	* @return The class ID for all objects of this class.
198	* @stable ICU 4.2
199	*/
200	static UClassID U_EXPORT2 getStaticClassID(void);
201
202	/**
203	* Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
204	* method is to implement a simple version of RTTI, since not all C++
205	* compilers support genuine RTTI. Polymorphic operator==() and clone()
206	* methods call this method.
207	*
208	* @return The class ID for this object. All objects of a
209	* given class have the same class ID. Objects of
210	* other classes have different class IDs.
211	* @stable ICU 4.2
212	*/
213	virtual UClassID getDynamicClassID(void) const;
214
215	private:
216	NumberFormat* fNumberFormat;
217	Locale fLocale;
218	Hashtable* fTimeUnitToCountToPatterns[TimeUnit::UTIMEUNIT_FIELD_COUNT];
219	PluralRules* fPluralRules;
4388f060	220	UTimeUnitFormatStyle fStyle;
729e4ab9	221
4388f060	222	void create(const Locale& locale, UTimeUnitFormatStyle style, UErrorCode& status);
729e4ab9 A	223
	224	// it might actually be simpler to make them Decimal Formats later.
	225	// initialize all private data members
	226	void setup(UErrorCode& status);
	227
	228	// initialize data member without fill in data for fTimeUnitToCountToPattern
	229	void initDataMembers(UErrorCode& status);
	230
	231	// initialize fTimeUnitToCountToPatterns from current locale's resource.
51004dcb A	232	void readFromCurrentLocale(UTimeUnitFormatStyle style, const char* key, const UVector& pluralCounts,
51004dcb A	233	UErrorCode& status);
729e4ab9 A	234
	235	// check completeness of fTimeUnitToCountToPatterns against all time units,
	236	// and all plural rules, fill in fallback as necessary.
4388f060	237	void checkConsistency(UTimeUnitFormatStyle style, const char* key, UErrorCode& status);
729e4ab9 A	238
729e4ab9 A	239	// fill in fTimeUnitToCountToPatterns from locale fall-back chain
4388f060 A	240	void searchInLocaleChain(UTimeUnitFormatStyle style, const char* key, const char* localeName,
4388f060 A	241	TimeUnit::UTimeUnitFields field, const UnicodeString&,
729e4ab9 A	242	const char, Hashtable, UErrorCode&);
	243
	244	// initialize hash table
	245	Hashtable* initHash(UErrorCode& status);
	246
	247	// delete hash table
	248	void deleteHash(Hashtable* htable);
	249
	250	// copy hash table
	251	void copyHash(const Hashtable* source, Hashtable* target, UErrorCode& status);
	252	// get time unit name, such as "year", from time unit field enum, such as
	253	// UTIMEUNIT_YEAR.
	254	static const char* getTimeUnitName(TimeUnit::UTimeUnitFields field, UErrorCode& status);
	255	};
	256
	257
	258
	259	inline UBool
	260	TimeUnitFormat::operator!=(const Format& other) const {
	261	return !operator==(other);
	262	}
	263
	264
	265
	266	U_NAMESPACE_END
	267
	268	#endif /* #if !UCONFIG_NO_FORMATTING */
	269
	270	#endif // __TMUTFMT_H__
	271	//eof