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