icuSources/i18n/reldtfmt.h

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