KMime

kmime_dateformatter.h
Go to the documentation of this file.
1 /* -*- c++ -*-
2  kmime_dateformatter.h
3 
4  KMime, the KDE Internet mail/usenet news message library.
5  SPDX-FileCopyrightText: 2001 the KMime authors.
6  See file AUTHORS for details
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 /**
11  @file
12  This file is part of the API for handling @ref MIME data and
13  defines the DateFormatter class.
14 
15  @brief
16  Defines the DateFormatter class.
17 
18  @authors the KMime authors (see AUTHORS file)
19 
20  @glossary @anchor RFC2822 @anchor rfc2822 @b RFC @b 2822:
21  RFC that defines the <a href="https://tools.ietf.org/html/rfc2822">
22  Internet Message Format</a>.
23 
24  @glossary @anchor ISO8601 @anchor iso8601 @b ISO @b 8601:
25  International Standards Organization (ISO) standard that defines the
26  <a href="https://en.wikipedia.org/wiki/ISO_8601">
27  international standard for date and time representations</a>.
28 
29  @glossary @anchor ctime @b ctime:
30  a Unix library call which returns the local time as a human readable
31  ASCII string of the form "Sun Mar 31 02:08:35 2002".
32 */
33 
34 #pragma once
35 
36 #include <time.h>
37 #include <QDateTime>
38 #include <QString>
39 #include "kmime_export.h"
40 
41 namespace KMime
42 {
43 class DateFormatterPrivate;
44 
45 /**
46  @brief
47  A class for abstracting date formatting.
48 
49  This class deals with different kinds of date display formats.
50  The formats supported include:
51  - @b fancy "Today 02:08:35"
52  - @b ctime as with the @ref ctime function, eg. "Sun Mar 31 02:08:35 2002"
53  - @b localized according to the control center setting, eg. "2002-03-31 02:08"
54  - @b iso according to the @ref ISO8601 standard, eg. "2002-03-31 02:08:35"
55  - @b rfc according to @ref RFC2822 (Section 3.3), eg. "Sun, 31 Mar 2002 02:08:35 -0500"
56  - @b custom "whatever you like"
57 */
58 class KMIME_EXPORT DateFormatter
59 {
60 public:
61  /**
62  The different types of date formats.
63  */
64  enum FormatType {
65  CTime, /**< ctime "Sun Mar 31 02:08:35 2002" */
66  Localized, /**< localized "2002-03-31 02:08" */
67  Fancy, /**< fancy "Today 02:08:35" */
68  Iso, /**< iso "2002-03-31 02:08:35" */
69  Rfc, /**< rfc "Sun, 31 Mar 2002 02:08:35 -0500" */
70  Custom /**< custom "whatever you like" */
71  };
72 
73  /**
74  Constructs a date formatter with a default #FormatType.
75 
76  @param ftype is the default #FormatType to use.
77  */
79 
80  /**
81  Destroys the date formatter.
82  */
83  ~DateFormatter();
84 
85  /**
86  Returns the #FormatType currently set.
87 
88  @see setFormat().
89  */
90  Q_REQUIRED_RESULT FormatType format() const;
91 
92  /**
93  Sets the date format to @p ftype.
94 
95  @param ftype is the #FormatType.
96 
97  @see format().
98  */
99  void setFormat(FormatType ftype);
100 
101  /**
102  Constructs a formatted date string from time_t @p t.
103 
104  @param t is the time_t to use for formatting.
105  @param lang is the language, only used if #FormatType is #Localized.
106  @param shortFormat if true, create the short version of the date string,
107  only used if #FormatType is #Localized.
108 
109  @return a QString containing the formatted date.
110  */
111  Q_REQUIRED_RESULT QString dateString(time_t t, const QString &lang = QString(),
112  bool shortFormat = true) const;
113 
114  /**
115  Constructs a formatted date string from QDateTime @p dtime.
116 
117  @param dtime is the QDateTime to use for formatting.
118  @param lang is the language, only used if #FormatType is #Localized.
119  @param shortFormat if true, create the short version of the date string,
120  only used if #FormatType is #Localized.
121 
122  @return a QString containing the formatted date.
123  */
124  Q_REQUIRED_RESULT QString dateString(const QDateTime &dtime, const QString &lang = QString(),
125  bool shortFormat = true) const;
126 
127  /**
128  Sets the custom format for date to string conversions to @p format.
129  This method accepts the same arguments as QDateTime::toString(), but
130  also supports the "Z" expression which is substituted with the
131  @ref RFC2822 (Section 3.3) style numeric timezone (-0500).
132 
133  @param format is a QString containing the custom format.
134 
135  @see QDateTime::toString(), customFormat().
136  */
137  void setCustomFormat(const QString &format);
138 
139  /**
140  Returns the custom format string.
141 
142  @see setCustomFormat().
143  */
144  Q_REQUIRED_RESULT QString customFormat() const;
145 
146  //static methods
147  /**
148  Convenience function dateString
149 
150  @param ftype is the #FormatType to use.
151  @param t is the time_t to use for formatting.
152  @param data is either the format when #FormatType is Custom,
153  or language when #FormatType is #Localized.
154  @param shortFormat if true, create the short version of the date string,
155  only used if #FormatType is #Localized.
156 
157  @return a QString containing the formatted date.
158  */
159  Q_REQUIRED_RESULT static QString formatDate(DateFormatter::FormatType ftype, time_t t,
160  const QString &data = QString(),
161  bool shortFormat = true);
162 
163  /**
164  Convenience function, same as formatDate() but returns the current time
165  formatted.
166 
167  @param ftype is the #FormatType to use.
168  @param data is either the format when #FormatType is Custom,
169  or language when #FormatType is #Localized.
170  @param shortFormat if true, create the short version of the date string,
171  only used if #FormatType is #Localized.
172 
173  @return a QString containing the formatted date.
174  */
175  Q_REQUIRED_RESULT static QString formatCurrentDate(DateFormatter::FormatType ftype,
176  const QString &data = QString(),
177  bool shortFormat = true);
178 
179 private:
180  //@cond PRIVATE
181  Q_DISABLE_COPY(DateFormatter)
182  DateFormatterPrivate *const d;
183  //@endcond
184 };
185 
186 } // namespace KMime
187 
iso "2002-03-31 02:08:35"
A class for abstracting date formatting.
localized "2002-03-31 02:08"
ctime "Sun Mar 31 02:08:35 2002"
rfc "Sun, 31 Mar 2002 02:08:35 -0500"
FormatType
The different types of date formats.
fancy "Today 02:08:35"
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Sep 25 2021 23:14:46 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.