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
22U_NAMESPACE_BEGIN
23
24// forward declarations
25class MessageFormat;
26
27// internal structure used for caching strings
28struct 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
39class RelativeDateFormat : public DateFormat {
40public:
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
220private:
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
263public:
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
292U_NAMESPACE_END
293
294#endif /* #if !UCONFIG_NO_FORMATTING */
295
296#endif // RELDTFMT_H
297//eof
298