icuSources/i18n/reldtfmt.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 2007-2010, 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  * @draft 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      * @draft ICU 3.8
  49      */
  50     RelativeDateFormat(const RelativeDateFormat&);
  51
  52     /**
  53      * Assignment operator.
  54      * @draft ICU 3.8
  55      */
  56     RelativeDateFormat& operator=(const RelativeDateFormat&);
  57
  58     /**
  59      * Destructor.
  60      * @draft 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      * @draft 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      * @draft 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      * @draft 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      * @draft 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      * @draft 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      * @draft 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      * @draft 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 technology preview
 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      * @draft 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      * @draft 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      * @draft 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