QCalendarBackend Class

The QCalendarBackend class provides basic calendaring functions. More...

Header: #include <QCalendarBackend>
Inherited By:

QHijriCalendar, QJalaliCalendar, and QRomanCalendar

Public Functions

virtual ~QCalendarBackend()
QCalendar::System calendarSystem() const
virtual int dayOfWeek(qint64 jd) const
virtual int daysInYear(int year) const
virtual bool hasYearZero() const
virtual bool isDateValid(int year, int month, int day) const
virtual bool isProleptic() const
virtual int maximumDaysInMonth() const
virtual int maximumMonthsInYear() const
virtual int minimumDaysInMonth() const
virtual int monthsInYear(int year) const
QStringList names() const
QCalendar::SystemId registerCustomBackend(const QStringList &names)

Static Public Members

QStringList availableCalendars()

Detailed Description

\since5.14

\inmoduleQtCore \internal \reentrant

QCalendarBackend provides the base class on which all calendar types are implemented. The backend must be registered before it is available via QCalendar API. The registration for system backends is arranged by the calendar registry. Custom backends may be registered using the registerCustomBackend() method.

A backend may also be registered by one or more names. Registering with the name used by CLDR (the Unicode consortium's Common Locale Data Repository) is recommended, particularly when interacting with third-party software. Once a backend is registered for a name, QCalendar can be constructed using that name to select the backend.

Each built-in backend has a distinct primary name and all built-in backends are instantiated before any custom backend is registered, to prevent custom backends with conflicting names from replacing built-in backends.

Each calendar backend must inherit from QCalendarBackend and implement its pure virtual methods. It may also override some other virtual methods, as needed.

Most backends are pure code, with only one data element (this base-classe's m_id). Such backends should normally be implemented as singletons.

The backends may be used by multiple threads simultaneously. The virtual methods must be implemented in a thread-safe way.

Instantiating backends

Backends may be defined by third-party, plugin or user code. When such custom backends are registered they shall be allocated a unique ID, by which client code may access it. A custom backend instance can have no names if access by name is not needed, or impractical (e.g. because the backend is not a singleton and constructing names for each instance would not make sense). If a custom backend has names that are already registered for another backend, those names are ignored.

A backend class that has instance variables as well as code may be instantiated many times, each with a distinct set of names, to implement distinct backends - presumably variants on some parameterized calendar. Each instance is then a distinct backend. A pure code backend class shall typically only be instantiated once, as it is only capable of representing one backend.

Each backend should be instantiated exactly once, on the heap (using the C++ new operator), so that the registry can take ownership of it after registration.

Built-in backends, identified by QCalendar::System values other than User, should only be registered by QCalendarRegistry::fromEnum(); no other code should ever register one, this guarantees that such a backend will be a singleton.

The shareable base-classes for backends, QRomanCalendar and QHijriCalendar, are not themselves identified by QCalendar::System and may be used as base-classes for custom calendar backends, but cannot be instantiated themselves.

See also calendarId(), QDate, QDateTime, QDateEdit, QDateTimeEdit, and QCalendarWidget.

Member Function Documentation

[virtual noexcept] QCalendarBackend::~QCalendarBackend()

Destroys the calendar backend.

Each calendar backend, once instantiated and successfully registered by ID, shall exist until it is destroyed by the registry. Destroying a successfully-registered backend otherwise may leave existing QCalendar instances referencing the destroyed calendar, with undefined results.

If a backend has not been registered it may safely be deleted.

See also calendarId().

[static] QStringList QCalendarBackend::availableCalendars()

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.

See also fromName().

QCalendar::System QCalendarBackend::calendarSystem() const

The calendar system of this calendar.

See also fromEnum() and calendarId().

[virtual] int QCalendarBackend::dayOfWeek(qint64 jd) const

Returns the day of the week for the given Julian Day Number jd.

This is 1 for Monday through 7 for Sunday.

Calendars with intercallary days may return larger values for these intercallary days. They should avoid using 0 for any special purpose (it is already used in QDate::dayOfWeek() to mean an invalid date). The calendar should treat the numbers used as an enum, whose values need not be contiguous, nor need they follow closely from the 1 through 7 of the usual returns. It suffices that weekDayName() can recognize each such number as identifying a distinct name, that it returns to identify the particular intercallary day.

This base implementation uses the day-numbering that various calendars have borrowed off the Hebrew calendar.

See also weekDayName(), standaloneWeekDayName(), and QDate::dayOfWeek().

[virtual] int QCalendarBackend::daysInYear(int year) const

Returns the total number of days in the year number year. Returns zero if there is no such year in this calendar.

This base implementation returns 366 for leap years and 365 for ordinary years.

See also monthsInYear(), daysInMonth(), and isLeapYear().

[virtual] bool QCalendarBackend::hasYearZero() const

Returns true if year number 0 is considered a valid year in this calendar. Otherwise returns false.

See also isDateValid() and isProleptic().

[virtual] bool QCalendarBackend::isDateValid(int year, int month, int day) const

Returns true if the date specified by year, month, and day is valid for this calendar; otherwise returns false. For example, the date 2018-04-19 is valid for the Gregorian calendar, but 2018-16-19 and 2018-04-38 are invalid.

Calendars with intercallary days may represent these as extra days of the preceding month or as short months separate from the usual ones. In the former case, a day value greater than daysInMonth(\a{month}, \a{year}) may be valid.

See also daysInMonth() and monthsInYear().

[virtual] bool QCalendarBackend::isProleptic() const

Returns true if this calendar is a proleptic calendar. Otherwise returns false.

A proleptic calendar results from allowing negative year numbers to indicate years before the nominal start of the calendar system.

See also isLuniSolar(), isSolar(), isLunar(), and hasYearZero().

[virtual] int QCalendarBackend::maximumDaysInMonth() const

Returns the maximum number of days in a month for any year.

This base implementation returns 31, as this is a common case.

For calendars with intercallary days, although daysInMonth() doesn't include the intercallary days in its count for an individual month, maximumDaysInMonth() should include intercallary days, so that it is the maximum value of day for which isDateValid(year, month, day) can be true.

See also maximumMonthsInYear() and daysInMonth().

[virtual] int QCalendarBackend::maximumMonthsInYear() const

Returns the maximum number of months possible in any year.

This base implementation returns 12, as this is a common case.

See also maximumDaysInMonth() and monthsInYear().

[virtual] int QCalendarBackend::minimumDaysInMonth() const

Returns the minimum number of days in any valid month of any valid year.

This base implementation returns 29, as this is a common case.

See also maximumMonthsInYear() and daysInMonth().

[virtual] int QCalendarBackend::monthsInYear(int year) const

Returns the total number of months in the year number year. Returns zero if there is no such year in this calendar.

This base implementation returns 12 for any valid year.

See also daysInYear(), maximumMonthsInYear(), and isDateValid().

QStringList QCalendarBackend::names() const

Returns list of names this backend was registered with.

The list is a subset of the names passed to registerCustomBackend(). Some names passed during the registration may not be associated with a backend if they were claimed by another backend first.

See also registerCustomBackend().

QCalendar::SystemId QCalendarBackend::registerCustomBackend(const QStringList &names)

Register this backend as a custom backend.

The backend should not already be registered. This method should only be called on objects that are completely initialized because they become available to other threads immediately. In particular, this function should not be called from backend constructors.

The backend is also registered by names passed in names. Only the names that are not already registered are associated with the backend. The name matching is case-insensitive. The list of names associated with the backend can be queried using names() method after successful registration.

Returns the new ID assigned to this backend. If its isValid() is true, the calendar registry has taken ownership of the object; this ID can then be used to create QCalendar instances. Otherwise, registration failed and the caller is responsible for destruction of the backend, which shall not be available for use by QCalendar. Failure should normally only happen if registration is attempted during program termination.

See also names().