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.
void invalidateReferenceDate() const
Invalidates the cached reference date used by the Fancy formatter to determine the meaning of "Today"...
static QString formatCurrentDate(DateFormatter::FormatType ftype, const QString &data=QString(), bool shortFormat=true)
Convenience function, same as formatDate() but returns the current time formatted.
FormatType
The different types of date formats.
@ Localized
localized "2002-03-31 02:08"
@ Fancy
fancy "Today 02:08:35"
@ Custom
custom "whatever you like"
@ CTime
ctime "Sun Mar 31 02:08:35 2002"
void setCustomFormat(const QString &format)
Sets the custom format for date to string conversions to format.
void setFormat(FormatType ftype)
Sets the date format to ftype.
QString customFormat() const
Returns the custom format string.
FormatType format() const
Returns the FormatType currently set.
static QString formatDate(DateFormatter::FormatType ftype, const QDateTime &t, const QString &data=QString(), bool shortFormat=true)
Convenience function dateString.
QString dateString(const QDateTime &dtime, const QString &lang=QString(), bool shortFormat=true) const
Constructs a formatted date string from QDateTime dtime.
DateFormatter(FormatType ftype=DateFormatter::Fancy)
Constructs a date formatter with a default FormatType.
~DateFormatter()
Destroys the date formatter.
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 31 2025 12:05:41 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.