1 /* 2 ******************************************************************************* 3 * Copyright (C) 2007-2011, International Business Machines Corporation and * 4 * others. All Rights Reserved. * 5 ******************************************************************************* 6 */ 7 8 #ifndef RELDTFMT_H 9 #define RELDTFMT_H 10 11 #include "unicode/utypes.h" 12 13 /** 14 * \file 15 * \brief C++ API: Format and parse relative dates and times. 16 */ 17 18 #if !UCONFIG_NO_FORMATTING 19 20 #include "unicode/datefmt.h" 21 22 U_NAMESPACE_BEGIN 23 24 // forward declarations 25 class DateFormatSymbols; 26 class MessageFormat; 27 28 // internal structure used for caching strings 29 struct URelativeString; 30 31 /** 32 * This class is normally accessed using the kRelative or k...Relative values of EStyle as 33 * parameters to DateFormat::createDateInstance. 34 * 35 * Example: 36 * DateFormat *fullrelative = DateFormat::createDateInstance(DateFormat::kFullRelative, loc); 37 * 38 * @internal ICU 3.8 39 */ 40 41 class RelativeDateFormat : public DateFormat { 42 public: 43 RelativeDateFormat( UDateFormatStyle timeStyle, UDateFormatStyle dateStyle, const Locale& locale, UErrorCode& status); 44 45 // overrides 46 /** 47 * Copy constructor. 48 * @internal ICU 3.8 49 */ 50 RelativeDateFormat(const RelativeDateFormat&); 51 52 /** 53 * Assignment operator. 54 * @internal ICU 3.8 55 */ 56 RelativeDateFormat& operator=(const RelativeDateFormat&); 57 58 /** 59 * Destructor. 60 * @internal ICU 3.8 61 */ 62 virtual ~RelativeDateFormat(); 63 64 /** 65 * Clone this Format object polymorphically. The caller owns the result and 66 * should delete it when done. 67 * @return A copy of the object. 68 * @internal ICU 3.8 69 */ 70 virtual Format* clone(void) const; 71 72 /** 73 * Return true if the given Format objects are semantically equal. Objects 74 * of different subclasses are considered unequal. 75 * @param other the object to be compared with. 76 * @return true if the given Format objects are semantically equal. 77 * @internal ICU 3.8 78 */ 79 virtual UBool operator==(const Format& other) const; 80 81 82 using DateFormat::format; 83 84 /** 85 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 86 * 1, 1970. Overrides DateFormat pure virtual method. 87 * <P> 88 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 89 * 1996.07.10 AD at 15:08:56 PDT 90 * 91 * @param cal Calendar set to the date and time to be formatted 92 * into a date/time string. 93 * @param appendTo Output parameter to receive result. 94 * Result is appended to existing contents. 95 * @param pos The formatting position. On input: an alignment field, 96 * if desired. On output: the offsets of the alignment field. 97 * @return Reference to 'appendTo' parameter. 98 * @internal ICU 3.8 99 */ 100 virtual UnicodeString& format( Calendar& cal, 101 UnicodeString& appendTo, 102 FieldPosition& pos) const; 103 104 /** 105 * Format an object to produce a string. This method handles Formattable 106 * objects with a UDate type. If a the Formattable object type is not a Date, 107 * then it returns a failing UErrorCode. 108 * 109 * @param obj The object to format. Must be a Date. 110 * @param appendTo Output parameter to receive result. 111 * Result is appended to existing contents. 112 * @param pos On input: an alignment field, if desired. 113 * On output: the offsets of the alignment field. 114 * @param status Output param filled with success/failure status. 115 * @return Reference to 'appendTo' parameter. 116 * @internal ICU 3.8 117 */ 118 virtual UnicodeString& format(const Formattable& obj, 119 UnicodeString& appendTo, 120 FieldPosition& pos, 121 UErrorCode& status) const; 122 123 124 /** 125 * Parse a date/time string beginning at the given parse position. For 126 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 127 * that is equivalent to Date(837039928046). 128 * <P> 129 * By default, parsing is lenient: If the input is not in the form used by 130 * this object's format method but can still be parsed as a date, then the 131 * parse succeeds. Clients may insist on strict adherence to the format by 132 * calling setLenient(false). 133 * 134 * @param text The date/time string to be parsed 135 * @param cal a Calendar set to the date and time to be formatted 136 * into a date/time string. 137 * @param pos On input, the position at which to start parsing; on 138 * output, the position at which parsing terminated, or the 139 * start position if the parse failed. 140 * @return A valid UDate if the input could be parsed. 141 * @internal ICU 3.8 142 */ 143 virtual void parse( const UnicodeString& text, 144 Calendar& cal, 145 ParsePosition& pos) const; 146 147 /** 148 * Parse a date/time string starting at the given parse position. For 149 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 150 * that is equivalent to Date(837039928046). 151 * <P> 152 * By default, parsing is lenient: If the input is not in the form used by 153 * this object's format method but can still be parsed as a date, then the 154 * parse succeeds. Clients may insist on strict adherence to the format by 155 * calling setLenient(false). 156 * 157 * @see DateFormat::setLenient(boolean) 158 * 159 * @param text The date/time string to be parsed 160 * @param pos On input, the position at which to start parsing; on 161 * output, the position at which parsing terminated, or the 162 * start position if the parse failed. 163 * @return A valid UDate if the input could be parsed. 164 * @internal ICU 3.8 165 */ 166 UDate parse( const UnicodeString& text, 167 ParsePosition& pos) const; 168 169 170 /** 171 * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" 172 * will be parsed into a UDate that is equivalent to Date(837039928046). 173 * Parsing begins at the beginning of the string and proceeds as far as 174 * possible. Assuming no parse errors were encountered, this function 175 * doesn't return any information about how much of the string was consumed 176 * by the parsing. If you need that information, use the version of 177 * parse() that takes a ParsePosition. 178 * 179 * @param text The date/time string to be parsed 180 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 181 * an error value if there was a parse error. 182 * @return A valid UDate if the input could be parsed. 183 * @internal ICU 3.8 184 */ 185 virtual UDate parse( const UnicodeString& text, 186 UErrorCode& status) const; 187 188 /** 189 * Return a single pattern string generated by combining the patterns for the 190 * date and time formatters associated with this object. 191 * @param result Output param to receive the pattern. 192 * @return A reference to 'result'. 193 * @internal ICU 4.2 technology preview 194 */ 195 virtual UnicodeString& toPattern(UnicodeString& result, UErrorCode& status) const; 196 197 /** 198 * Get the date pattern for the the date formatter associated with this object. 199 * @param result Output param to receive the date pattern. 200 * @return A reference to 'result'. 201 * @internal ICU 4.2 technology preview 202 */ 203 virtual UnicodeString& toPatternDate(UnicodeString& result, UErrorCode& status) const; 204 205 /** 206 * Get the time pattern for the the time formatter associated with this object. 207 * @param result Output param to receive the time pattern. 208 * @return A reference to 'result'. 209 * @internal ICU 4.2 technology preview 210 */ 211 virtual UnicodeString& toPatternTime(UnicodeString& result, UErrorCode& status) const; 212 213 /** 214 * Apply the given unlocalized date & time pattern strings to this relative date format. 215 * (i.e., after this call, this formatter will format dates and times according to 216 * the new patterns) 217 * 218 * @param datePattern The date pattern to be applied. 219 * @param timePattern The time pattern to be applied. 220 * @internal ICU 4.2 technology preview 221 */ 222 virtual void applyPatterns(const UnicodeString& datePattern, const UnicodeString& timePattern, UErrorCode &status); 223 224 /** 225 * Gets the date/time formatting symbols (this is an object carrying 226 * the various strings and other symbols used in formatting: e.g., month 227 * names and abbreviations, time zone names, AM/PM strings, etc.) 228 * @return a copy of the date-time formatting data associated 229 * with this date-time formatter. 230 * @internal ICU 4.8 231 */ 232 virtual const DateFormatSymbols* getDateFormatSymbols(void) const; 233 234 235 private: 236 DateFormat *fDateFormat; // the held date format 237 DateFormat *fTimeFormat; // the held time format 238 MessageFormat *fCombinedFormat; // the {0} {1} format. 239 240 UDateFormatStyle fDateStyle; 241 UDateFormatStyle fTimeStyle; 242 Locale fLocale; 243 244 int32_t fDayMin; // day id of lowest # 245 int32_t fDayMax; // day id of highest # 246 int32_t fDatesLen; // Length of array 247 URelativeString *fDates; // array of strings 248 249 250 /** 251 * Get the string at a specific offset. 252 * @param day day offset ( -1, 0, 1, etc.. ) 253 * @param len on output, length of string. 254 * @return the string, or NULL if none at that location. 255 */ 256 const UChar *getStringForDay(int32_t day, int32_t &len, UErrorCode &status) const; 257 258 /** 259 * Load the Date string array 260 */ 261 void loadDates(UErrorCode &status); 262 263 /** 264 * @return the number of days in "until-now" 265 */ 266 static int32_t dayDifference(Calendar &until, UErrorCode &status); 267 268 /** 269 * initializes fCalendar from parameters. Returns fCalendar as a convenience. 270 * @param adoptZone Zone to be adopted, or NULL for TimeZone::createDefault(). 271 * @param locale Locale of the calendar 272 * @param status Error code 273 * @return the newly constructed fCalendar 274 * @internal ICU 3.8 275 */ 276 Calendar* initializeCalendar(TimeZone* adoptZone, const Locale& locale, UErrorCode& status); 277 278 public: 279 /** 280 * Return the class ID for this class. This is useful only for comparing to 281 * a return value from getDynamicClassID(). For example: 282 * <pre> 283 * . Base* polymorphic_pointer = createPolymorphicObject(); 284 * . if (polymorphic_pointer->getDynamicClassID() == 285 * . erived::getStaticClassID()) ... 286 * </pre> 287 * @return The class ID for all objects of this class. 288 * @internal ICU 3.8 289 */ 290 U_I18N_API static UClassID U_EXPORT2 getStaticClassID(void); 291 292 /** 293 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 294 * method is to implement a simple version of RTTI, since not all C++ 295 * compilers support genuine RTTI. Polymorphic operator==() and clone() 296 * methods call this method. 297 * 298 * @return The class ID for this object. All objects of a 299 * given class have the same class ID. Objects of 300 * other classes have different class IDs. 301 * @internal ICU 3.8 302 */ 303 virtual UClassID getDynamicClassID(void) const; 304 }; 305 306 307 U_NAMESPACE_END 308 309 #endif /* #if !UCONFIG_NO_FORMATTING */ 310 311 #endif // RELDTFMT_H 312 //eof 313