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
55namespace 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*/
70class 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