Messagelib

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

KDE's Doxygen guidelines are available online.