icuSources/i18n/reldtfmt.h

   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