qcalendar.cpp

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#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 <private/qflatmap_p.h>
#include "qatomic.h"
#include "qdatetime.h"
#include "qcalendarmath_p.h"
#include <qhash.h>
#include <qreadwritelock.h>
 
#include <vector>
 
QT_BEGIN_NAMESPACE
 
struct QCalendarRegistryCaseInsensitiveAnyStringViewLessThan
{
    struct is_transparent {};
    bool operator()(QAnyStringView lhs, QAnyStringView rhs) const
    {
        return QAnyStringView::compare(lhs, rhs, Qt::CaseInsensitive) < 0;
    }
};
 
namespace QtPrivate {
 
/*
    \internal
    Handles calendar backend registration.
*/
class QCalendarRegistry
{
    Q_DISABLE_COPY_MOVE(QCalendarRegistry); // This is a singleton.
 
    static constexpr qsizetype ExpectedNumberOfBackends = qsizetype(QCalendar::System::Last) + 1;
 
    /*
        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.
    */
    QFlatMap<
        QString, QCalendarBackend *,
        QCalendarRegistryCaseInsensitiveAnyStringViewLessThan,
        QStringList,
        std::vector<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(ExpectedNumberOfBackends);
        byName.reserve(ExpectedNumberOfBackends * 2); // assume one alias on average
    }
 
    ~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) {
        auto [it, inserted] = byName.try_emplace(name, backend);
        if (!inserted) {
            Q_ASSERT(system == QCalendar::System::User);
            qWarning("Cannot register name %ls (already in use) for %ls",
                     qUtf16Printable(name), qUtf16Printable(backend->name()));
        }
    }
}
 
/*
    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 byName.keys();
}
 
/*
    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();
 
    QReadLocker locker(&lock);
    return byName.value(name, 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
 
    QT_WARNING_PUSH
    // Clang complains about the reference still causing a copy. The reference is idiomatic, but
    // runs afoul of QFlatMap's iterators which return a pair of references instead of a reference
    // to pair. Suppress the warning, because `const auto [key, value]` would look wrong.
    QT_WARNING_DISABLE_CLANG("-Wrange-loop-analysis")
    for (const auto &[key, value] : byName) {
        if (value == backend)
            l.push_back(key);
    }
    QT_WARNING_POP
 
    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<7>(jd) + 1;
}
 
qint64 QCalendarBackend::matchCenturyToWeekday(const QCalendar::YearMonthDay &parts, int dow) const
{
    Q_ASSERT(parts.isValid());
    // Brute-force solution as fall-back.
    const auto checkOffset = [parts, dow, this](int centuries) -> std::optional<qint64> {
        // Offset parts.year by the given number of centuries:
        int year = parts.year + centuries * 100;
        // but take into account the effect of crossing zero, if we did:
        if (!hasYearZero() && (parts.year > 0) != (year > 0))
            year += parts.year > 0 ? -1 : +1;
        qint64 jd;
        if (isDateValid(year, parts.month, parts.day)
            && dateToJulianDay(year, parts.month, parts.day, &jd)
            && dayOfWeek(jd) == dow) {
            return jd;
        }
        return std::nullopt;
    };
    // Empirically, aside from Gregorian, each calendar finds every dow within
    // any 29-century run, so 14 centuries is the biggest offset we ever need.
    for (int offset = 0; offset < 15; ++offset) {
        if (auto jd = checkOffset(offset))
            return *jd;
        if (offset) {
            if (auto jd = checkOffset(-offset))
                return *jd;
        }
    }
    return (std::numeric_limits<qint64>::min)();
}
 
// 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(QAnyStringView 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();
}
 
QDate QCalendar::matchCenturyToWeekday(const QCalendar::YearMonthDay &parts, int dow) const
{
    SAFE_D();
    return d && parts.isValid()
        ? QDate::fromJulianDay(d->matchCenturyToWeekday(parts, dow)) : 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