icuSources/i18n/unicode/tmutfmt.h

   1 /*
   2  *******************************************************************************
   3  * Copyright (C) 2008-2012, Google, International Business Machines Corporation
   4  * and others. All Rights Reserved.
   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 /**
  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
  34  */
  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 */
  44
  45 U_NAMESPACE_BEGIN
  46
  47 class Hashtable;
  48 class UVector;
  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
  78  * @stable ICU 4.2
  79  */
  80 class U_I18N_API TimeUnitFormat: public MeasureFormat {
  81 public:
  82
  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.
  98      * @stable ICU 4.8
  99      */
 100     TimeUnitFormat(const Locale& locale, UTimeUnitFormatStyle style, UErrorCode& status);
 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;
 220     UTimeUnitFormatStyle fStyle;
 221
 222     void create(const Locale& locale, UTimeUnitFormatStyle style, UErrorCode& status);
 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.
 232     void readFromCurrentLocale(UTimeUnitFormatStyle style, const char* key, const UVector& pluralCounts,
 233                                UErrorCode& status);
 234
 235     // check completeness of fTimeUnitToCountToPatterns against all time units,
 236     // and all plural rules, fill in fallback as necessary.
 237     void checkConsistency(UTimeUnitFormatStyle style, const char* key, UErrorCode& status);
 238
 239     // fill in fTimeUnitToCountToPatterns from locale fall-back chain
 240     void searchInLocaleChain(UTimeUnitFormatStyle style, const char* key, const char* localeName,
 241                              TimeUnit::UTimeUnitFields field, const UnicodeString&,
 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