summaryrefslogtreecommitdiff
path: root/kmime/kmime_dateformatter.h
blob: 35b4431ee61037f91fc6f666f25b21780eeb1f16 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
/*  -*- c++ -*-
    kmime_dateformatter.h

    KMime, the KDE Internet mail/usenet news message library.
    Copyright (c) 2001 the KMime authors.
    See file AUTHORS for details

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/
/**
  @file
  This file is part of the API for handling @ref MIME data and
  defines the DateFormatter class.

  @brief
  Defines the DateFormatter class.

  @authors the KMime authors (see AUTHORS file)

  @glossary @anchor RFC2822 @anchor rfc2822 @b RFC @b 2822:
  RFC that defines the <a href="http://tools.ietf.org/html/rfc2822">
  Internet Message Format</a>.

  @glossary @anchor ISO8601 @anchor iso8601 @b ISO @b 8601:
  International Standards Organization (ISO) standard that defines the
  <a href="http://http://en.wikipedia.org/wiki/ISO_8601">
  international standard for date and time representations</a>.

  @glossary @anchor ctime @b ctime:
  a Unix library call which returns the local time as a human readable
  ASCII string of the form "Sun Mar 31 02:08:35 2002".
*/

#ifndef __KMIME_DATEFORMATTER_H__
#define __KMIME_DATEFORMATTER_H__

#include <time.h>
#include <QtCore/QDateTime>
#include <QtCore/QString>
#include "kmime_export.h"

namespace KMime {

/**
  @brief
  A class for abstracting date formatting.

  This class deals with different kinds of date display formats.
  The formats supported include:
  - @b fancy "Today 02:08:35"
  - @b ctime as with the @ref ctime function, eg. "Sun Mar 31 02:08:35 2002"
  - @b localized according to the control center setting, eg. "2002-03-31 02:08"
  - @b iso  according to the @ref ISO8601 standard, eg. "2002-03-31 02:08:35"
  - @b rfc according to @ref RFC2822 (Section 3.3), eg. "Sun, 31 Mar 2002 02:08:35 -0500"
  - @b custom "whatever you like"
*/
class KMIME_EXPORT DateFormatter
{
  public:
    /**
      The different types of date formats.
    */
    enum FormatType {
      CTime,      /**< ctime "Sun Mar 31 02:08:35 2002" */
      Localized,  /**< localized "2002-03-31 02:08" */
      Fancy,      /**< fancy "Today 02:08:35" */
      Iso,        /**< iso  "2002-03-31 02:08:35" */
      Rfc,        /**< rfc  "Sun, 31 Mar 2002 02:08:35 -0500" */
      Custom      /**< custom "whatever you like" */
    };

    /**
      Constructs a date formatter with a default #FormatType.

      @param ftype is the default #FormatType to use.
    */
    explicit DateFormatter( FormatType ftype=DateFormatter::Fancy );

    /**
      Destroys the date formatter.
    */
    ~DateFormatter();

    /**
      Returns the #FormatType currently set.

      @see setFormat().
    */
    FormatType format() const;

    /**
      Sets the date format to @p ftype.

      @param ftype is the #FormatType.

      @see format().
    */
    void setFormat( FormatType ftype );

    /**
      Constructs a formatted date string from time_t @p t.

      @param t is the time_t to use for formatting.
      @param lang is the language, only used if #FormatType is #Localized.
      @param shortFormat if true, create the short version of the date string,
      only used if #FormatType is #Localized.
      @param includeSecs if true, include the seconds field in the date string,
      only used if #FormatType is #Localized.

      @return a QString containing the formatted date.
    */
    QString dateString( time_t t, const QString &lang=QString(),
                        bool shortFormat=true, bool includeSecs=false ) const;

    /**
      Constructs a formatted date string from QDateTime @p dtime.

      @param dtime is the QDateTime to use for formatting.
      @param lang is the language, only used if #FormatType is #Localized.
      @param shortFormat if true, create the short version of the date string,
      only used if #FormatType is #Localized.
      @param includeSecs if true, include the seconds field in the date string,
      only used if #FormatType is #Localized.

      @return a QString containing the formatted date.
    */
    QString dateString( const QDateTime &dtime, const QString &lang=QString(),
                        bool shortFormat=true, bool includeSecs=false ) const;

    /**
      Sets the custom format for date to string conversions to @p format.
      This method accepts the same arguments as QDateTime::toString(), but
      also supports the "Z" expression which is substituted with the
      @ref RFC2822 (Section 3.3) style numeric timezone (-0500).

      @param format is a QString containing the custom format.

      @see QDateTime::toString(), customFormat().
    */
    void setCustomFormat( const QString &format );

    /**
      Returns the custom format string.

      @see setCustomFormat().
    */
    QString customFormat() const;

    /**
      Resets the cached current date used for calculating the fancy date.
      This should be called whenever the current date changed, i.e. on midnight.
      @deprecated Can be safely removed. The date change is taken care of internally (as of 4.3).
    */
    void reset();

    //static methods
    /**
      Convenience function dateString

      @param ftype is the #FormatType to use.
      @param t is the time_t to use for formatting.
      @param data is either the format when #FormatType is Custom,
      or language when #FormatType is #Localized.
      @param shortFormat if true, create the short version of the date string,
      only used if #FormatType is #Localized.
      @param includeSecs if true, include the seconds field in the date string,
      only used if #FormatType is #Localized.

      @return a QString containing the formatted date.
    */
    static QString formatDate( DateFormatter::FormatType ftype, time_t t,
                               const QString &data=QString(),
                               bool shortFormat=true,
                               bool includeSecs=false );

    /**
      Convenience function, same as formatDate() but returns the current time
      formatted.

      @param ftype is the #FormatType to use.
      @param data is either the format when #FormatType is Custom,
      or language when #FormatType is #Localized.
      @param shortFormat if true, create the short version of the date string,
      only used if #FormatType is #Localized.
      @param includeSecs if true, include the seconds field in the date string,
      only used if #FormatType is #Localized.

      @return a QString containing the formatted date.
    */
    static QString formatCurrentDate( DateFormatter::FormatType ftype,
                                      const QString &data=QString(),
                                      bool shortFormat=true,
                                      bool includeSecs=false );

    /**
      Returns true if the current time is on daylight savings time; else false.
    */
    static bool isDaylight();

  protected:
    /**
      Returns a QString containing the specified time_t @p t formatted
      using the #Fancy #FormatType.

      @param t is the time_t to use for formatting.
    */
    QString fancy( time_t t ) const ;

    /**
      Returns a QString containing the specified time_t @p t formatted
      using the #Localized #FormatType.

      @param t is the time_t to use for formatting.
      @param shortFormat if true, create the short version of the date string.
      @param includeSecs if true, include the seconds field in the date string.
      @param lang is a QString containing the language to use.
    */
    QString localized( time_t t, bool shortFormat=true,
                       bool includeSecs=false,
                       const QString &lang=QString() ) const;

    /**
      Returns a QString containing the specified time_t @p t formatted
      with the ctime() function.

      @param t is the time_t to use for formatting.
    */
    QString cTime( time_t t ) const;

    /**
      Returns a QString containing the specified time_t @p t in the
      "%Y-%m-%d %H:%M:%S" #Iso #FormatType.

      @param t is the time_t to use for formatting.
    */
    QString isoDate( time_t t ) const;

    /**
      Returns a QString containing the specified time_t @p t in the
      #Rfc #FormatType.

      @param t is the time_t to use for formatting.
    */
    QString rfc2822( time_t t ) const;

    /**
      Returns a QString containing the specified time_t @p t formatted
      with a previously specified custom format.

      @param t time used for formatting
    */
    QString custom( time_t t ) const;

    /**
      Returns a QString that identifies the timezone (eg."-0500")
      of the specified time_t @p t.

      @param t time to compute timezone from.
    */
    QByteArray zone( time_t t ) const;

    /**
      Converts QDateTime @p dt to a time_t value.

      @param dt is the QDateTime to be converted.
      @return the time_t equivalent of the specified QDateTime.
    */
    time_t qdateToTimeT( const QDateTime &dt ) const;

  private:
    //@cond PRIVATE
    FormatType          mFormat;
    mutable time_t      mTodayOneSecondBeforeMidnight;
    mutable QDateTime   mUnused; // KDE5: remove
    QString             mCustomFormat;
    static int          mDaylight;
    //@endcond
};

} // namespace KMime

#endif /* __KMIME_DATEFORMATTER_H__ */