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 "kmime_export.h"
37 #include <QDateTime>
38 #include <QString>
39 #include <ctime>
40 #include <memory>
41 
42 namespace KMime
43 {
44 class DateFormatterPrivate;
45 
46 /**
47  @brief
48  A class for abstracting date formatting.
49 
50  This class deals with different kinds of date display formats.
51  The formats supported include:
52  - @b fancy "Today 02:08:35"
53  - @b ctime as with the @ref ctime function, eg. "Sun Mar 31 02:08:35 2002"
54  - @b localized according to the control center setting, eg. "2002-03-31 02:08"
55  - @b iso according to the @ref ISO8601 standard, eg. "2002-03-31 02:08:35"
56  - @b rfc according to @ref RFC2822 (Section 3.3), eg. "Sun, 31 Mar 2002 02:08:35 -0500"
57  - @b custom "whatever you like"
58 */
59 class KMIME_EXPORT DateFormatter
60 {
61 public:
62  /**
63  The different types of date formats.
64  */
65  enum FormatType {
66  CTime, /**< ctime "Sun Mar 31 02:08:35 2002" */
67  Localized, /**< localized "2002-03-31 02:08" */
68  Fancy, /**< fancy "Today 02:08:35" */
69  Iso, /**< iso "2002-03-31 02:08:35" */
70  Rfc, /**< rfc "Sun, 31 Mar 2002 02:08:35 -0500" */
71  Custom /**< custom "whatever you like" */
72  };
73 
74  /**
75  Constructs a date formatter with a default #FormatType.
76 
77  @param ftype is the default #FormatType to use.
78  */
79  explicit DateFormatter(FormatType ftype = DateFormatter::Fancy);
80 
81  /**
82  Destroys the date formatter.
83  */
84  ~DateFormatter();
85 
86  /**
87  Returns the #FormatType currently set.
88 
89  @see setFormat().
90  */
91  Q_REQUIRED_RESULT FormatType format() const;
92 
93  /**
94  Sets the date format to @p ftype.
95 
96  @param ftype is the #FormatType.
97 
98  @see format().
99  */
100  void setFormat(FormatType ftype);
101 
102  /**
103  Constructs a formatted date string from time_t @p t.
104 
105  @param t is the time_t to use for formatting.
106  @param lang is the language, only used if #FormatType is #Localized.
107  @param shortFormat if true, create the short version of the date string,
108  only used if #FormatType is #Localized.
109 
110  @return a QString containing the formatted date.
111  */
112  Q_REQUIRED_RESULT QString dateString(time_t t, const QString &lang = QString(),
113  bool shortFormat = true) const;
114 
115  /**
116  Constructs a formatted date string from QDateTime @p dtime.
117 
118  @param dtime is the QDateTime to use for formatting.
119  @param lang is the language, only used if #FormatType is #Localized.
120  @param shortFormat if true, create the short version of the date string,
121  only used if #FormatType is #Localized.
122 
123  @return a QString containing the formatted date.
124  */
125  Q_REQUIRED_RESULT QString dateString(const QDateTime &dtime, const QString &lang = QString(),
126  bool shortFormat = true) const;
127 
128  /**
129  Sets the custom format for date to string conversions to @p format.
130  This method accepts the same arguments as QDateTime::toString(), but
131  also supports the "Z" expression which is substituted with the
132  @ref RFC2822 (Section 3.3) style numeric timezone (-0500).
133 
134  @param format is a QString containing the custom format.
135 
136  @see QDateTime::toString(), customFormat().
137  */
138  void setCustomFormat(const QString &format);
139 
140  /**
141  Returns the custom format string.
142 
143  @see setCustomFormat().
144  */
145  Q_REQUIRED_RESULT QString customFormat() const;
146 
147  //static methods
148  /**
149  Convenience function dateString
150 
151  @param ftype is the #FormatType to use.
152  @param t is the time_t to use for formatting.
153  @param data is either the format when #FormatType is Custom,
154  or language when #FormatType is #Localized.
155  @param shortFormat if true, create the short version of the date string,
156  only used if #FormatType is #Localized.
157 
158  @return a QString containing the formatted date.
159  */
160  Q_REQUIRED_RESULT static QString formatDate(DateFormatter::FormatType ftype, time_t t,
161  const QString &data = QString(),
162  bool shortFormat = true);
163 
164  /**
165  Convenience function, same as formatDate() but returns the current time
166  formatted.
167 
168  @param ftype is the #FormatType to use.
169  @param data is either the format when #FormatType is Custom,
170  or language when #FormatType is #Localized.
171  @param shortFormat if true, create the short version of the date string,
172  only used if #FormatType is #Localized.
173 
174  @return a QString containing the formatted date.
175  */
176  Q_REQUIRED_RESULT static QString formatCurrentDate(DateFormatter::FormatType ftype,
177  const QString &data = QString(),
178  bool shortFormat = true);
179 
180 private:
181  //@cond PRIVATE
182  Q_DISABLE_COPY(DateFormatter)
183  std::unique_ptr<DateFormatterPrivate> const d;
184  //@endcond
185 };
186 
187 } // namespace KMime
188 
@ CTime
ctime "Sun Mar 31 02:08:35 2002"
@ Iso
iso "2002-03-31 02:08:35"
@ Fancy
fancy "Today 02:08:35"
FormatType
The different types of date formats.
A class for abstracting date formatting.
@ Rfc
rfc "Sun, 31 Mar 2002 02:08:35 -0500"
@ Localized
localized "2002-03-31 02:08"
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Aug 11 2022 03:54:30 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.