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