qcalendar.cpp

Go to the documentation of this file.

/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qcalendar.h"
#include "qcalendarbackend_p.h"
#include "qgregoriancalendar_p.h"
#ifndef QT_BOOTSTRAPPED
#include "qjuliancalendar_p.h"
#include "qmilankoviccalendar_p.h"
#endif
#if QT_CONFIG(jalalicalendar)
#include "qjalalicalendar_p.h"
#endif
#if QT_CONFIG(islamiccivilcalendar)
#include "qislamiccivilcalendar_p.h"
#endif
 
#include "qatomic.h"
#include "qdatetime.h"
#include "qcalendarmath_p.h"
#include <qhash.h>
#include <qreadwritelock.h>
 
#include <vector>
 
QT_BEGIN_NAMESPACE
 
namespace {
 
struct CalendarName : public QString
{
    CalendarName(const QString &name) : QString(name) {}
};
 
inline bool operator==(const CalendarName &u, const CalendarName &v)
{
    return u.compare(v, Qt::CaseInsensitive) == 0;
}
 
inline size_t qHash(const CalendarName &key, size_t seed = 0) noexcept
{
    return qHash(key.toLower(), seed);
}
 
} // anonymous namespace
 
namespace QtPrivate {
 
/*
    \internal
    Handles calendar backend registration.
*/
class QCalendarRegistry
{
    Q_DISABLE_COPY_MOVE(QCalendarRegistry); // This is a singleton.
 
    /*
        Lock protecting the registry from concurrent modification.
    */
    QReadWriteLock lock;
 
    /*
        Vector containing all registered backends.
 
        The indices 0 to \c QCalendar::System::Last inclusive are allocated
        for system backends and always present (but may be null).
    */
    std::vector<QCalendarBackend *> byId;
 
    /*
        Backends registered by name.
 
        Each backend may be registered with several names associated with it.
        The names are case-insensitive.
    */
    QHash<CalendarName, QCalendarBackend *> byName;
 
    /*
        Pointer to the Gregorian backend for faster lockless access to it.
 
        This pointer may be null if the Gregorian backend is not yet registered.
        This pointer may only be set once and only when write lock is held on
        the registry.
    */
    QAtomicPointer<const QCalendarBackend> gregorianCalendar = nullptr;
 
    enum : int {
        Unpopulated, // The standard backends may not yet be created
        Populated, // All standard backends were created
        IsBeingDestroyed, // The registry and the backends are being destroyed
    };
 
    /*
        Fast way to check whether the standard calendars were populated.
 
        The status should only be changed while the write lock is held.
    */
    QAtomicInt status = Unpopulated;
 
    void ensurePopulated();
    QCalendarBackend *registerSystemBackendLockHeld(QCalendar::System system);
    void registerBackendLockHeld(QCalendarBackend *backend, const QStringList &names,
                                 QCalendar::System system);
 
public:
    QCalendarRegistry() { byId.resize(int(QCalendar::System::Last) + 1); }
 
    ~QCalendarRegistry();
 
    bool isBeingDestroyed() const { return status.loadRelaxed() == IsBeingDestroyed; }
 
    void registerCustomBackend(QCalendarBackend *backend, const QStringList &names);
 
    QStringList availableCalendars();
 
    /*
        Returns backend for Gregorian calendar.
 
        The backend is returned without locking the registry if possible.
    */
    const QCalendarBackend *gregorian()
    {
        const QCalendarBackend *backend = gregorianCalendar.loadAcquire();
        if (Q_LIKELY(backend != nullptr))
            return backend;
        return fromEnum(QCalendar::System::Gregorian);
    }
 
    /*
        Returns \a true if the argument matches the registered Gregorian backend.
 
        \a backend should not be \nullptr.
    */
    bool isGregorian(const QCalendarBackend *backend) const
    {
        return backend == gregorianCalendar.loadRelaxed();
    }
 
    const QCalendarBackend *fromName(QAnyStringView name);
    const QCalendarBackend *fromIndex(size_t index);
    const QCalendarBackend *fromEnum(QCalendar::System system);
 
    QStringList backendNames(const QCalendarBackend *backend);
};
 
/*
    Destroy the registry.
 
    This destroys all registered backends. This destructor should only be called
    in a single-threaded context at program exit.
*/
QCalendarRegistry::~QCalendarRegistry()
{
    QWriteLocker locker(&lock);
 
    status.storeRelaxed(IsBeingDestroyed);
 
    qDeleteAll(byId);
}
 
/*
    Registers a custom backend.
 
    A new unique ID is allocated for the \a backend. The registry takes
    ownership of the \a backend.
 
    The \a names of the backend are also registered. Already registered
    names are not updated.
 
    The \a backend should not be already registered.
 
    The \a backend should be fully initialized. It becomes available
    to other threads before this function returns.
*/
void QCalendarRegistry::registerCustomBackend(QCalendarBackend *backend, const QStringList &names)
{
    Q_ASSERT(!backend->calendarId().isValid());
 
    ensurePopulated();
 
    QWriteLocker locker(&lock);
    registerBackendLockHeld(backend, names, QCalendar::System::User);
}
 
/*
    Ensures all system calendars have been instantiated.
 
    This arranges for each system backend to be registered. The method only
    does anything on its first call, which ensures that name-based lookups can
    always find all the calendars available via the \c QCalendar::System other
    than \c QCalendar::System::User.
*/
void QCalendarRegistry::ensurePopulated()
{
    if (Q_LIKELY(status.loadAcquire() != Unpopulated))
        return;
 
    QWriteLocker locker(&lock);
    if (status.loadAcquire() != Unpopulated)
        return;
 
    for (int i = 0; i <= int(QCalendar::System::Last); ++i) {
        if (byId[i] == nullptr)
            registerSystemBackendLockHeld(QCalendar::System(i));
    }
 
#if defined(QT_FORCE_ASSERTS) || !defined(QT_NO_DEBUG)
    auto oldValue = status.fetchAndStoreRelease(Populated);
    Q_ASSERT(oldValue == Unpopulated);
#else
    status.storeRelease(Populated);
#endif
}
 
/*
    Helper functions for system backend registration.
 
    This function must be called with write lock held on the registry.
 
    \sa registerSystemBackend
*/
QCalendarBackend *QCalendarRegistry::registerSystemBackendLockHeld(QCalendar::System system)
{
    Q_ASSERT(system != QCalendar::System::User);
 
    QCalendarBackend *backend = nullptr;
    QStringList names;
 
    switch (system) {
    case QCalendar::System::Gregorian:
        backend = new QGregorianCalendar;
        names = QGregorianCalendar::nameList();
        break;
#ifndef QT_BOOTSTRAPPED
    case QCalendar::System::Julian:
        backend = new QJulianCalendar;
        names = QJulianCalendar::nameList();
        break;
    case QCalendar::System::Milankovic:
        backend = new QMilankovicCalendar;
        names = QMilankovicCalendar::nameList();
        break;
#endif
#if QT_CONFIG(jalalicalendar)
    case QCalendar::System::Jalali:
        backend = new QJalaliCalendar;
        names = QJalaliCalendar::nameList();
        break;
#endif
#if QT_CONFIG(islamiccivilcalendar)
    case QCalendar::System::IslamicCivil:
        backend = new QIslamicCivilCalendar;
        names = QIslamicCivilCalendar::nameList();
        break;
#else // When highest-numbered system isn't enabled, ensure we have a case for Last:
    case QCalendar::System::Last:
#endif
    case QCalendar::System::User:
        Q_UNREACHABLE();
    }
    if (!backend)
        return nullptr;
 
    registerBackendLockHeld(backend, names, system);
    Q_ASSERT(backend == byId[size_t(system)]);
 
    return backend;
}
 
/*
    Helper function for backend registration.
 
    This function must be called with write lock held on the registry.
 
    \sa registerBackend
*/
void QCalendarRegistry::registerBackendLockHeld(QCalendarBackend *backend, const QStringList &names,
                                                QCalendar::System system)
{
    Q_ASSERT(!backend->calendarId().isValid());
 
    auto index = size_t(system);
 
    // Note: it is important to update the calendar ID before making
    // the calendar available for queries.
    if (system == QCalendar::System::User) {
        backend->setIndex(byId.size());
        byId.push_back(backend);
    } else if (byId[index] == nullptr) {
        backend->setIndex(index);
        if (system == QCalendar::System::Gregorian) {
#if defined(QT_FORCE_ASSERTS) || !defined(QT_NO_DEBUG)
            auto oldValue = gregorianCalendar.fetchAndStoreRelease(backend);
            Q_ASSERT(oldValue == nullptr);
#else
            gregorianCalendar.storeRelease(backend);
#endif
        }
 
        Q_ASSERT(byId.size() > index);
        Q_ASSERT(byId[index] == nullptr);
        byId[index] = backend;
    }
 
    // Register any names.
    for (const auto &name : names) {
        if (byName.contains(name)) {
            Q_ASSERT(system == QCalendar::System::User);
            qWarning("Cannot register name %ls (already in use) for %ls",
                     qUtf16Printable(name), qUtf16Printable(backend->name()));
        } else {
            byName[name] = backend;
        }
    }
}
 
/*
    Returns a list of names of the available calendar systems.
 
    Any QCalendarBackend sub-class must be registered before being exposed to Date
    and Time APIs.
 
    \sa fromName()
*/
QStringList QCalendarRegistry::availableCalendars()
{
    ensurePopulated();
 
    QReadLocker locker(&lock);
    return QStringList(byName.keyBegin(), byName.keyEnd());
}
 
/*
    Returns a pointer to a named calendar backend.
 
    If the given \a name is present in availableCalendars(), the backend
    matching it is returned. Otherwise, \nullptr is returned. Matching of
    names ignores case.
 
    \sa availableCalendars(), fromEnum(), fromIndex()
*/
const QCalendarBackend *QCalendarRegistry::fromName(QAnyStringView name)
{
    ensurePopulated();
 
    const QString nameU16 = name.toString();
    QReadLocker locker(&lock);
    return byName.value(nameU16, nullptr);
}
 
/*
    Returns a pointer to a calendar backend, specified by index.
 
    If a calendar with ID \a index is known to the calendar registry, the backend
    with this ID is returned. Otherwise, \nullptr is returned.
 
    \sa fromEnum(), calendarId()
*/
const QCalendarBackend *QCalendarRegistry::fromIndex(size_t index)
{
    {
        QReadLocker locker(&lock);
 
        if (index >= byId.size())
            return nullptr;
 
        if (auto backend = byId[index])
            return backend;
    }
 
    if (index <= size_t(QCalendar::System::Last))
        return fromEnum(QCalendar::System(index));
 
    return nullptr;
}
 
/*
    Returns a pointer to a calendar backend, specified by \a system.
 
    This will instantiate the indicated calendar (which will enable fromName()
    to return it subsequently), but only for the Qt-supported calendars for
    which (where relevant) the appropriate feature has been enabled.
 
    \a system should be a member of \a QCalendar::System other than
    \a QCalendar::System::User.
 
    \sa fromName(), fromId()
*/
const QCalendarBackend *QCalendarRegistry::fromEnum(QCalendar::System system)
{
    Q_ASSERT(system <= QCalendar::System::Last);
    auto index = size_t(system);
 
    {
        QReadLocker locker(&lock);
        Q_ASSERT(byId.size() > index);
        if (auto backend = byId[index])
            return backend;
    }
 
    QWriteLocker locker(&lock);
 
    // Check if the backend was registered after releasing the read lock above.
    if (auto backend = byId[index])
        return backend;
 
    return registerSystemBackendLockHeld(system);
}
 
/*
    Returns a list of names \a backend was registered with.
*/
QStringList QCalendarRegistry::backendNames(const QCalendarBackend *backend)
{
    QStringList l;
    l.reserve(byName.size()); // too large, but never really large, so ok
 
    // same as byName.keys(backend), except for
    // - the missing const on mapped_type and
    // - CalendarName != QString as the key_type
    for (auto it = byName.cbegin(), end = byName.cend(); it != end; ++it) {
        if (it.value() == backend)
            l.push_back(it.key());
    }
 
    return l;
}
 
} // namespace QtPrivate
 
Q_GLOBAL_STATIC(QtPrivate::QCalendarRegistry, calendarRegistry);
 
QCalendarBackend::~QCalendarBackend()
{
    Q_ASSERT(!m_id.isValid() || calendarRegistry.isDestroyed()
             || calendarRegistry->isBeingDestroyed());
}
 
QStringList QCalendarBackend::names() const
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed()))
        return {};
 
    return calendarRegistry->backendNames(this);
}
 
void QCalendarBackend::setIndex(size_t index)
{
    Q_ASSERT(!m_id.isValid());
    m_id.id = index;
}
 
QCalendar::SystemId QCalendarBackend::registerCustomBackend(const QStringList &names)
{
    Q_ASSERT(!m_id.isValid());
 
    if (Q_LIKELY(!calendarRegistry.isDestroyed()))
        calendarRegistry->registerCustomBackend(this, names);
 
    return m_id;
}
 
bool QCalendarBackend::isGregorian() const
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed()))
        return false;
 
    return calendarRegistry->isGregorian(this);
}
 
QCalendar::System QCalendarBackend::calendarSystem() const
{
    return m_id.isInEnum() ? QCalendar::System(m_id.index()) : QCalendar::System::User;
}
 
/*
    Create local variable d containing the backend associated with a QCalendar
    instance unless the calendar registry is destroyed together with all backends,
    then return nullptr.
 
    This assumes that the registry is only destroyed in single threaded context.
*/
#define SAFE_D() const auto d = Q_UNLIKELY(calendarRegistry.isDestroyed()) ? nullptr : d_ptr
 
QString QCalendar::name() const
{
    SAFE_D();
    return d ? d->name() : QString();
}
 
// date queries
// properties of the calendar
 
int QCalendarBackend::daysInYear(int year) const
{
    return monthsInYear(year) ? isLeapYear(year) ? 366 : 365 : 0;
}
 
int QCalendarBackend::monthsInYear(int year) const
{
    return year > 0 || (year < 0 ? isProleptic() : hasYearZero()) ? 12 : 0;
}
 
bool QCalendarBackend::isDateValid(int year, int month, int day) const
{
    return day > 0 && day <= daysInMonth(month, year);
}
 
bool QCalendarBackend::isProleptic() const
{
    return true;
}
 
bool QCalendarBackend::hasYearZero() const
{
    return false;
}
 
int QCalendarBackend::maximumDaysInMonth() const
{
    return 31;
}
 
int QCalendarBackend::minimumDaysInMonth() const
{
    return 29;
}
 
int QCalendarBackend::maximumMonthsInYear() const
{
    return 12;
}
 
// Julian day number calculations
 
int QCalendarBackend::dayOfWeek(qint64 jd) const
{
    return QRoundingDown::qMod(jd, 7) + 1;
}
 
// Month and week-day name look-ups (implemented in qlocale.cpp):
// End of methods implemented in qlocale.cpp
 
QStringList QCalendarBackend::availableCalendars()
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed()))
        return {};
 
    return calendarRegistry->availableCalendars();
}
 
const QCalendarBackend *QCalendarBackend::fromName(QAnyStringView name)
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed()))
        return nullptr;
 
    return calendarRegistry->fromName(name);
}
 
const QCalendarBackend *QCalendarBackend::fromId(QCalendar::SystemId id)
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed() || !id.isValid()))
        return nullptr;
 
    return calendarRegistry->fromIndex(id.index());
}
 
const QCalendarBackend *QCalendarBackend::fromEnum(QCalendar::System system)
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed() || system == QCalendar::System::User))
        return nullptr;
 
    return calendarRegistry->fromEnum(system);
}
 
const QCalendarBackend *QCalendarBackend::gregorian()
{
    if (Q_UNLIKELY(calendarRegistry.isDestroyed()))
        return nullptr;
 
    return calendarRegistry->gregorian();
}
 
QCalendar::QCalendar()
    : d_ptr(QCalendarBackend::gregorian())
{
    Q_ASSERT(!d_ptr || d_ptr->calendarId().isValid());
}
 
QCalendar::QCalendar(QCalendar::System system) : d_ptr(QCalendarBackend::fromEnum(system))
{
    // If system is valid, we should get a valid d for that system.
    Q_ASSERT(!d_ptr || (uint(system) > uint(QCalendar::System::Last))
             || (d_ptr->calendarId().index() == size_t(system)));
}
 
QCalendar::QCalendar(QCalendar::SystemId id)
    : d_ptr(QCalendarBackend::fromId(id))
{
    Q_ASSERT(!d_ptr || d_ptr->calendarId().index() == id.index());
}
 
QCalendar::QCalendar(QLatin1String name)
    : d_ptr(QCalendarBackend::fromName(name))
{
    Q_ASSERT(!d_ptr || d_ptr->calendarId().isValid());
}
 
QCalendar::QCalendar(QStringView name)
    : d_ptr(QCalendarBackend::fromName(name))
{
    Q_ASSERT(!d_ptr || d_ptr->calendarId().isValid());
}
 
// Date queries:
 
int QCalendar::daysInMonth(int month, int year) const
{
    SAFE_D();
    return d ? d->daysInMonth(month, year) : 0;
}
 
int QCalendar::daysInYear(int year) const
{
    SAFE_D();
    return d ? d->daysInYear(year) : 0;
}
 
int QCalendar::monthsInYear(int year) const
{
    SAFE_D();
    return d ? year == Unspecified ? d->maximumMonthsInYear() : d->monthsInYear(year) : 0;
}
 
bool QCalendar::isDateValid(int year, int month, int day) const
{
    SAFE_D();
    return d && d->isDateValid(year, month, day);
}
 
// properties of the calendar
 
bool QCalendar::isGregorian() const
{
    SAFE_D();
    return d && d->isGregorian();
}
 
bool QCalendar::isLeapYear(int year) const
{
    SAFE_D();
    return d && d->isLeapYear(year);
}
 
bool QCalendar::isLunar() const
{
    SAFE_D();
    return d && d->isLunar();
}
 
bool QCalendar::isLuniSolar() const
{
    SAFE_D();
    return d && d->isLuniSolar();
}
 
bool QCalendar::isSolar() const
{
    SAFE_D();
    return d && d->isSolar();
}
 
bool QCalendar::isProleptic() const
{
    SAFE_D();
    return d && d->isProleptic();
}
 
bool QCalendar::hasYearZero() const
{
    SAFE_D();
    return d && d->hasYearZero();
}
 
int QCalendar::maximumDaysInMonth() const
{
    SAFE_D();
    return d ? d->maximumDaysInMonth() : 0;
}
 
int QCalendar::minimumDaysInMonth() const
{
    SAFE_D();
    return d ? d->minimumDaysInMonth() : 0;
}
 
int QCalendar::maximumMonthsInYear() const
{
    SAFE_D();
    return d ? d->maximumMonthsInYear() : 0;
}
 
// Julian Day conversions:
 
QDate QCalendar::dateFromParts(int year, int month, int day) const
{
    SAFE_D();
    qint64 jd;
    return d && d->dateToJulianDay(year, month, day, &jd)
        ? QDate::fromJulianDay(jd) : QDate();
}
 
QDate QCalendar::dateFromParts(const QCalendar::YearMonthDay &parts) const
{
    return parts.isValid() ? dateFromParts(parts.year, parts.month, parts.day) : QDate();
}
 
QCalendar::YearMonthDay QCalendar::partsFromDate(QDate date) const
{
    SAFE_D();
    return d && date.isValid() ? d->julianDayToDate(date.toJulianDay()) : YearMonthDay();
}
 
int QCalendar::dayOfWeek(QDate date) const
{
    SAFE_D();
    return d && date.isValid() ? d->dayOfWeek(date.toJulianDay()) : 0;
}
 
// Locale data access
 
QString QCalendar::monthName(const QLocale &locale, int month, int year,
                             QLocale::FormatType format) const
{
    SAFE_D();
    const int maxMonth = year == Unspecified ? maximumMonthsInYear() : monthsInYear(year);
    if (!d || month < 1 || month > maxMonth)
        return QString();
 
    return d->monthName(locale, month, year, format);
}
 
QString QCalendar::standaloneMonthName(const QLocale &locale, int month, int year,
                                       QLocale::FormatType format) const
{
    SAFE_D();
    const int maxMonth = year == Unspecified ? maximumMonthsInYear() : monthsInYear(year);
    if (!d || month < 1 || month > maxMonth)
        return QString();
 
    return d->standaloneMonthName(locale, month, year, format);
}
 
QString QCalendar::weekDayName(const QLocale &locale, int day,
                               QLocale::FormatType format) const
{
    SAFE_D();
    return d ? d->weekDayName(locale, day, format) : QString();
}
 
QString QCalendar::standaloneWeekDayName(const QLocale &locale, int day,
                                         QLocale::FormatType format) const
{
    SAFE_D();
    return d ? d->standaloneWeekDayName(locale, day, format) : QString();
}
 
QString QCalendar::dateTimeToString(QStringView format, const QDateTime &datetime,
                                    QDate dateOnly, QTime timeOnly,
                                    const QLocale &locale) const
{
    SAFE_D();
    return d ? d->dateTimeToString(format, datetime, dateOnly, timeOnly, locale) : QString();
}
 
QStringList QCalendar::availableCalendars()
{
    return QCalendarBackend::availableCalendars();
}
 
QT_END_NAMESPACE
 
#ifndef QT_BOOTSTRAPPED
#include "moc_qcalendar.cpp"
#endif