1 | /* -*- c++ -*- |
2 | kmime_dateformatter.h |
3 | |
4 | KMime, the KDE Internet mail/usenet news message library. |
5 | Copyright (c) 2001 the KMime authors. |
6 | See file AUTHORS for details |
7 | |
8 | This library is free software; you can redistribute it and/or |
9 | modify it under the terms of the GNU Library General Public |
10 | License as published by the Free Software Foundation; either |
11 | version 2 of the License, or (at your option) any later version. |
12 | |
13 | This library is distributed in the hope that it will be useful, |
14 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
16 | Library General Public License for more details. |
17 | |
18 | You should have received a copy of the GNU Library General Public License |
19 | along with this library; see the file COPYING.LIB. If not, write to |
20 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
21 | Boston, MA 02110-1301, USA. |
22 | */ |
23 | /** |
24 | @file |
25 | This file is part of the API for handling @ref MIME data and |
26 | defines the DateFormatter class. |
27 | |
28 | @brief |
29 | Defines the DateFormatter class. |
30 | |
31 | @authors the KMime authors (see AUTHORS file) |
32 | |
33 | @glossary @anchor RFC2822 @anchor rfc2822 @b RFC @b 2822: |
34 | RFC that defines the <a href="http://tools.ietf.org/html/rfc2822"> |
35 | Internet Message Format</a>. |
36 | |
37 | @glossary @anchor ISO8601 @anchor iso8601 @b ISO @b 8601: |
38 | International Standards Organization (ISO) standard that defines the |
39 | <a href="http://http://en.wikipedia.org/wiki/ISO_8601"> |
40 | international standard for date and time representations</a>. |
41 | |
42 | @glossary @anchor ctime @b ctime: |
43 | a Unix library call which returns the local time as a human readable |
44 | ASCII string of the form "Sun Mar 31 02:08:35 2002". |
45 | */ |
46 | |
47 | #ifndef __KMIME_DATEFORMATTER_H__ |
48 | #define __KMIME_DATEFORMATTER_H__ |
49 | |
50 | #include <time.h> |
51 | #include <QtCore/QDateTime> |
52 | #include <QtCore/QString> |
53 | #include "kmime_export.h" |
54 | |
55 | namespace KMime { |
56 | |
57 | /** |
58 | @brief |
59 | A class for abstracting date formatting. |
60 | |
61 | This class deals with different kinds of date display formats. |
62 | The formats supported include: |
63 | - @b fancy "Today 02:08:35" |
64 | - @b ctime as with the @ref ctime function, eg. "Sun Mar 31 02:08:35 2002" |
65 | - @b localized according to the control center setting, eg. "2002-03-31 02:08" |
66 | - @b iso according to the @ref ISO8601 standard, eg. "2002-03-31 02:08:35" |
67 | - @b rfc according to @ref RFC2822 (Section 3.3), eg. "Sun, 31 Mar 2002 02:08:35 -0500" |
68 | - @b custom "whatever you like" |
69 | */ |
70 | class KMIME_EXPORT DateFormatter |
71 | { |
72 | public: |
73 | /** |
74 | The different types of date formats. |
75 | */ |
76 | enum FormatType { |
77 | CTime, /**< ctime "Sun Mar 31 02:08:35 2002" */ |
78 | Localized, /**< localized "2002-03-31 02:08" */ |
79 | Fancy, /**< fancy "Today 02:08:35" */ |
80 | Iso, /**< iso "2002-03-31 02:08:35" */ |
81 | Rfc, /**< rfc "Sun, 31 Mar 2002 02:08:35 -0500" */ |
82 | Custom /**< custom "whatever you like" */ |
83 | }; |
84 | |
85 | /** |
86 | Constructs a date formatter with a default #FormatType. |
87 | |
88 | @param ftype is the default #FormatType to use. |
89 | */ |
90 | explicit DateFormatter( FormatType ftype=DateFormatter::Fancy ); |
91 | |
92 | /** |
93 | Destroys the date formatter. |
94 | */ |
95 | ~DateFormatter(); |
96 | |
97 | /** |
98 | Returns the #FormatType currently set. |
99 | |
100 | @see setFormat(). |
101 | */ |
102 | FormatType format() const; |
103 | |
104 | /** |
105 | Sets the date format to @p ftype. |
106 | |
107 | @param ftype is the #FormatType. |
108 | |
109 | @see format(). |
110 | */ |
111 | void setFormat( FormatType ftype ); |
112 | |
113 | /** |
114 | Constructs a formatted date string from time_t @p t. |
115 | |
116 | @param t is the time_t to use for formatting. |
117 | @param lang is the language, only used if #FormatType is #Localized. |
118 | @param shortFormat if true, create the short version of the date string, |
119 | only used if #FormatType is #Localized. |
120 | @param includeSecs if true, include the seconds field in the date string, |
121 | only used if #FormatType is #Localized. |
122 | |
123 | @return a QString containing the formatted date. |
124 | */ |
125 | QString dateString( time_t t, const QString &lang=QString(), |
126 | bool shortFormat=true, bool includeSecs=false ) const; |
127 | |
128 | /** |
129 | Constructs a formatted date string from QDateTime @p dtime. |
130 | |
131 | @param dtime is the QDateTime to use for formatting. |
132 | @param lang is the language, only used if #FormatType is #Localized. |
133 | @param shortFormat if true, create the short version of the date string, |
134 | only used if #FormatType is #Localized. |
135 | @param includeSecs if true, include the seconds field in the date string, |
136 | only used if #FormatType is #Localized. |
137 | |
138 | @return a QString containing the formatted date. |
139 | */ |
140 | QString dateString( const QDateTime &dtime, const QString &lang=QString(), |
141 | bool shortFormat=true, bool includeSecs=false ) const; |
142 | |
143 | /** |
144 | Sets the custom format for date to string conversions to @p format. |
145 | This method accepts the same arguments as QDateTime::toString(), but |
146 | also supports the "Z" expression which is substituted with the |
147 | @ref RFC2822 (Section 3.3) style numeric timezone (-0500). |
148 | |
149 | @param format is a QString containing the custom format. |
150 | |
151 | @see QDateTime::toString(), customFormat(). |
152 | */ |
153 | void setCustomFormat( const QString &format ); |
154 | |
155 | /** |
156 | Returns the custom format string. |
157 | |
158 | @see setCustomFormat(). |
159 | */ |
160 | QString customFormat() const; |
161 | |
162 | /** |
163 | Resets the cached current date used for calculating the fancy date. |
164 | This should be called whenever the current date changed, i.e. on midnight. |
165 | @deprecated Can be safely removed. The date change is taken care of internally (as of 4.3). |
166 | */ |
167 | void reset(); |
168 | |
169 | //static methods |
170 | /** |
171 | Convenience function dateString |
172 | |
173 | @param ftype is the #FormatType to use. |
174 | @param t is the time_t to use for formatting. |
175 | @param data is either the format when #FormatType is Custom, |
176 | or language when #FormatType is #Localized. |
177 | @param shortFormat if true, create the short version of the date string, |
178 | only used if #FormatType is #Localized. |
179 | @param includeSecs if true, include the seconds field in the date string, |
180 | only used if #FormatType is #Localized. |
181 | |
182 | @return a QString containing the formatted date. |
183 | */ |
184 | static QString formatDate( DateFormatter::FormatType ftype, time_t t, |
185 | const QString &data=QString(), |
186 | bool shortFormat=true, |
187 | bool includeSecs=false ); |
188 | |
189 | /** |
190 | Convenience function, same as formatDate() but returns the current time |
191 | formatted. |
192 | |
193 | @param ftype is the #FormatType to use. |
194 | @param data is either the format when #FormatType is Custom, |
195 | or language when #FormatType is #Localized. |
196 | @param shortFormat if true, create the short version of the date string, |
197 | only used if #FormatType is #Localized. |
198 | @param includeSecs if true, include the seconds field in the date string, |
199 | only used if #FormatType is #Localized. |
200 | |
201 | @return a QString containing the formatted date. |
202 | */ |
203 | static QString formatCurrentDate( DateFormatter::FormatType ftype, |
204 | const QString &data=QString(), |
205 | bool shortFormat=true, |
206 | bool includeSecs=false ); |
207 | |
208 | /** |
209 | Returns true if the current time is on daylight savings time; else false. |
210 | */ |
211 | static bool isDaylight(); |
212 | |
213 | protected: |
214 | /** |
215 | Returns a QString containing the specified time_t @p t formatted |
216 | using the #Fancy #FormatType. |
217 | |
218 | @param t is the time_t to use for formatting. |
219 | */ |
220 | QString fancy( time_t t ) const ; |
221 | |
222 | /** |
223 | Returns a QString containing the specified time_t @p t formatted |
224 | using the #Localized #FormatType. |
225 | |
226 | @param t is the time_t to use for formatting. |
227 | @param shortFormat if true, create the short version of the date string. |
228 | @param includeSecs if true, include the seconds field in the date string. |
229 | @param lang is a QString containing the language to use. |
230 | */ |
231 | QString localized( time_t t, bool shortFormat=true, |
232 | bool includeSecs=false, |
233 | const QString &lang=QString() ) const; |
234 | |
235 | /** |
236 | Returns a QString containing the specified time_t @p t formatted |
237 | with the ctime() function. |
238 | |
239 | @param t is the time_t to use for formatting. |
240 | */ |
241 | QString cTime( time_t t ) const; |
242 | |
243 | /** |
244 | Returns a QString containing the specified time_t @p t in the |
245 | "%Y-%m-%d %H:%M:%S" #Iso #FormatType. |
246 | |
247 | @param t is the time_t to use for formatting. |
248 | */ |
249 | QString isoDate( time_t t ) const; |
250 | |
251 | /** |
252 | Returns a QString containing the specified time_t @p t in the |
253 | #Rfc #FormatType. |
254 | |
255 | @param t is the time_t to use for formatting. |
256 | */ |
257 | QString rfc2822( time_t t ) const; |
258 | |
259 | /** |
260 | Returns a QString containing the specified time_t @p t formatted |
261 | with a previously specified custom format. |
262 | |
263 | @param t time used for formatting |
264 | */ |
265 | QString custom( time_t t ) const; |
266 | |
267 | /** |
268 | Returns a QString that identifies the timezone (eg."-0500") |
269 | of the specified time_t @p t. |
270 | |
271 | @param t time to compute timezone from. |
272 | */ |
273 | QByteArray zone( time_t t ) const; |
274 | |
275 | /** |
276 | Converts QDateTime @p dt to a time_t value. |
277 | |
278 | @param dt is the QDateTime to be converted. |
279 | @return the time_t equivalent of the specified QDateTime. |
280 | */ |
281 | time_t qdateToTimeT( const QDateTime &dt ) const; |
282 | |
283 | private: |
284 | //@cond PRIVATE |
285 | FormatType mFormat; |
286 | mutable time_t mTodayOneSecondBeforeMidnight; |
287 | mutable QDateTime mUnused; // KDE5: remove |
288 | QString mCustomFormat; |
289 | static int mDaylight; |
290 | //@endcond |
291 | }; |
292 | |
293 | } // namespace KMime |
294 | |
295 | #endif /* __KMIME_DATEFORMATTER_H__ */ |
296 | |