icuSources/i18n/reldtfmt.h

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