File indexing completed on 2022-10-04 16:37:44

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 <ctime>
0040 #include <memory>
0041 
0042 namespace KMime
0043 {
0044 class DateFormatterPrivate;
0045 
0046 /**
0047   @brief
0048   A class for abstracting date formatting.
0049 
0050   This class deals with different kinds of date display formats.
0051   The formats supported include:
0052   - @b fancy "Today 02:08:35"
0053   - @b ctime as with the @ref ctime function, eg. "Sun Mar 31 02:08:35 2002"
0054   - @b localized according to the control center setting, eg. "2002-03-31 02:08"
0055   - @b iso  according to the @ref ISO8601 standard, eg. "2002-03-31 02:08:35"
0056   - @b rfc according to @ref RFC2822 (Section 3.3), eg. "Sun, 31 Mar 2002 02:08:35 -0500"
0057   - @b custom "whatever you like"
0058 */
0059 class KMIME_EXPORT DateFormatter
0060 {
0061 public:
0062     /**
0063       The different types of date formats.
0064     */
0065     enum FormatType {
0066         CTime,      /**< ctime "Sun Mar 31 02:08:35 2002" */
0067         Localized,  /**< localized "2002-03-31 02:08" */
0068         Fancy,      /**< fancy "Today 02:08:35" */
0069         Iso,        /**< iso  "2002-03-31 02:08:35" */
0070         Rfc,        /**< rfc  "Sun, 31 Mar 2002 02:08:35 -0500" */
0071         Custom      /**< custom "whatever you like" */
0072     };
0073 
0074     /**
0075       Constructs a date formatter with a default #FormatType.
0076 
0077       @param ftype is the default #FormatType to use.
0078     */
0079     explicit DateFormatter(FormatType ftype = DateFormatter::Fancy);
0080 
0081     /**
0082       Destroys the date formatter.
0083     */
0084     ~DateFormatter();
0085 
0086     /**
0087       Returns the #FormatType currently set.
0088 
0089       @see setFormat().
0090     */
0091     Q_REQUIRED_RESULT FormatType format() const;
0092 
0093     /**
0094       Sets the date format to @p ftype.
0095 
0096       @param ftype is the #FormatType.
0097 
0098       @see format().
0099     */
0100     void setFormat(FormatType ftype);
0101 
0102     /**
0103       Constructs a formatted date string from time_t @p t.
0104 
0105       @param t is the time_t to use for formatting.
0106       @param lang is the language, only used if #FormatType is #Localized.
0107       @param shortFormat if true, create the short version of the date string,
0108       only used if #FormatType is #Localized.
0109 
0110       @return a QString containing the formatted date.
0111     */
0112     Q_REQUIRED_RESULT QString dateString(time_t t, const QString &lang = QString(),
0113                        bool shortFormat = true) const;
0114 
0115     /**
0116       Constructs a formatted date string from QDateTime @p dtime.
0117 
0118       @param dtime is the QDateTime to use for formatting.
0119       @param lang is the language, only used if #FormatType is #Localized.
0120       @param shortFormat if true, create the short version of the date string,
0121       only used if #FormatType is #Localized.
0122 
0123       @return a QString containing the formatted date.
0124     */
0125     Q_REQUIRED_RESULT QString dateString(const QDateTime &dtime, const QString &lang = QString(),
0126                        bool shortFormat = true) const;
0127 
0128     /**
0129       Sets the custom format for date to string conversions to @p format.
0130       This method accepts the same arguments as QDateTime::toString(), but
0131       also supports the "Z" expression which is substituted with the
0132       @ref RFC2822 (Section 3.3) style numeric timezone (-0500).
0133 
0134       @param format is a QString containing the custom format.
0135 
0136       @see QDateTime::toString(), customFormat().
0137     */
0138     void setCustomFormat(const QString &format);
0139 
0140     /**
0141       Returns the custom format string.
0142 
0143       @see setCustomFormat().
0144     */
0145     Q_REQUIRED_RESULT QString customFormat() const;
0146 
0147     //static methods
0148     /**
0149       Convenience function dateString
0150 
0151       @param ftype is the #FormatType to use.
0152       @param t is the time_t to use for formatting.
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     Q_REQUIRED_RESULT static QString formatDate(DateFormatter::FormatType ftype, time_t t,
0161                               const QString &data = QString(),
0162                               bool shortFormat = true);
0163 
0164     /**
0165       Convenience function, same as formatDate() but returns the current time
0166       formatted.
0167 
0168       @param ftype is the #FormatType to use.
0169       @param data is either the format when #FormatType is Custom,
0170       or language when #FormatType is #Localized.
0171       @param shortFormat if true, create the short version of the date string,
0172       only used if #FormatType is #Localized.
0173 
0174       @return a QString containing the formatted date.
0175     */
0176     Q_REQUIRED_RESULT static QString formatCurrentDate(DateFormatter::FormatType ftype,
0177                                      const QString &data = QString(),
0178                                      bool shortFormat = true);
0179 
0180 private:
0181     //@cond PRIVATE
0182     Q_DISABLE_COPY(DateFormatter)
0183     std::unique_ptr<DateFormatterPrivate> const d;
0184     //@endcond
0185 };
0186 
0187 } // namespace KMime
0188