File indexing completed on 2024-04-14 15:27:16
0001 /* -*- c++ -*- 0002 kmime_dateformatter.h 0003 0004 KMime, the KDE Internet mail/usenet news message library. 0005 SPDX-FileCopyrightText: 2001 the KMime authors. 0006 See file AUTHORS for details 0007 0008 SPDX-License-Identifier: LGPL-2.0-or-later 0009 */ 0010 /** 0011 @file 0012 This file is part of the API for handling @ref MIME data and 0013 defines the DateFormatter class. 0014 0015 @brief 0016 Defines the DateFormatter class. 0017 0018 @authors the KMime authors (see AUTHORS file) 0019 0020 @glossary @anchor RFC2822 @anchor rfc2822 @b RFC @b 2822: 0021 RFC that defines the <a href="https://tools.ietf.org/html/rfc2822"> 0022 Internet Message Format</a>. 0023 0024 @glossary @anchor ISO8601 @anchor iso8601 @b ISO @b 8601: 0025 International Standards Organization (ISO) standard that defines the 0026 <a href="https://en.wikipedia.org/wiki/ISO_8601"> 0027 international standard for date and time representations</a>. 0028 0029 @glossary @anchor ctime @b ctime: 0030 a Unix library call which returns the local time as a human readable 0031 ASCII string of the form "Sun Mar 31 02:08:35 2002". 0032 */ 0033 0034 #pragma once 0035 0036 #include "kmime_export.h" 0037 #include <QDateTime> 0038 #include <QString> 0039 #include <memory> 0040 0041 namespace KMime 0042 { 0043 class DateFormatterPrivate; 0044 0045 /** 0046 @brief 0047 A class for abstracting date formatting. 0048 0049 This class deals with different kinds of date display formats. 0050 The formats supported include: 0051 - @b fancy "Today 02:08:35" 0052 - @b ctime as with the @ref ctime function, eg. "Sun Mar 31 02:08:35 2002" 0053 - @b localized according to the control center setting, eg. "2002-03-31 02:08" 0054 - @b custom "whatever you like" 0055 */ 0056 class KMIME_EXPORT DateFormatter 0057 { 0058 public: 0059 /** 0060 The different types of date formats. 0061 */ 0062 enum FormatType { 0063 CTime, /**< ctime "Sun Mar 31 02:08:35 2002" */ 0064 Localized, /**< localized "2002-03-31 02:08" */ 0065 Fancy, /**< fancy "Today 02:08:35" */ 0066 Custom /**< custom "whatever you like" */ 0067 }; 0068 0069 /** 0070 Constructs a date formatter with a default #FormatType. 0071 0072 @param ftype is the default #FormatType to use. 0073 */ 0074 explicit DateFormatter(FormatType ftype = DateFormatter::Fancy); 0075 0076 /** 0077 Destroys the date formatter. 0078 */ 0079 ~DateFormatter(); 0080 0081 /** 0082 Returns the #FormatType currently set. 0083 0084 @see setFormat(). 0085 */ 0086 [[nodiscard]] FormatType format() const; 0087 0088 /** 0089 Sets the date format to @p ftype. 0090 0091 @param ftype is the #FormatType. 0092 0093 @see format(). 0094 */ 0095 void setFormat(FormatType ftype); 0096 0097 /** 0098 Constructs a formatted date string from QDateTime @p dtime. 0099 0100 @param dtime is the QDateTime to use for formatting. 0101 @param lang is the language, only used if #FormatType is #Localized. 0102 @param shortFormat if true, create the short version of the date string, 0103 only used if #FormatType is #Localized. 0104 0105 @return a QString containing the formatted date. 0106 */ 0107 [[nodiscard]] QString dateString(const QDateTime &dtime, 0108 const QString &lang = QString(), 0109 bool shortFormat = true) const; 0110 0111 /** 0112 Sets the custom format for date to string conversions to @p format. 0113 This method accepts the same arguments as QDateTime::toString(), but 0114 also supports the "Z" expression which is substituted with the 0115 @ref RFC2822 (Section 3.3) style numeric timezone (-0500). 0116 0117 @param format is a QString containing the custom format. 0118 0119 @see QDateTime::toString(), customFormat(). 0120 */ 0121 void setCustomFormat(const QString &format); 0122 0123 /** 0124 Returns the custom format string. 0125 0126 @see setCustomFormat(). 0127 */ 0128 [[nodiscard]] QString customFormat() const; 0129 0130 //static methods 0131 /** 0132 Convenience function dateString 0133 0134 @param ftype is the #FormatType to use. 0135 @param t is the time to use for formatting. 0136 @param data is either the format when #FormatType is Custom, 0137 or language when #FormatType is #Localized. 0138 @param shortFormat if true, create the short version of the date string, 0139 only used if #FormatType is #Localized. 0140 0141 @return a QString containing the formatted date. 0142 */ 0143 [[nodiscard]] static QString formatDate(DateFormatter::FormatType ftype, 0144 const QDateTime &t, 0145 const QString &data = QString(), 0146 bool shortFormat = true); 0147 0148 /** 0149 Convenience function, same as formatDate() but returns the current time 0150 formatted. 0151 0152 @param ftype is the #FormatType to use. 0153 @param data is either the format when #FormatType is Custom, 0154 or language when #FormatType is #Localized. 0155 @param shortFormat if true, create the short version of the date string, 0156 only used if #FormatType is #Localized. 0157 0158 @return a QString containing the formatted date. 0159 */ 0160 [[nodiscard]] static QString 0161 formatCurrentDate(DateFormatter::FormatType ftype, 0162 const QString &data = QString(), bool shortFormat = true); 0163 0164 private: 0165 //@cond PRIVATE 0166 Q_DISABLE_COPY(DateFormatter) 0167 std::unique_ptr<DateFormatterPrivate> const d; 0168 //@endcond 0169 }; 0170 0171 } // namespace KMime 0172