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

#include <qcalendarbackend_p.h>

Inheritance diagram for QCalendarBackend:

Collaboration diagram for QCalendarBackend:

Public Member Functions
	QCalendarBackend ()=default

virtual	~QCalendarBackend ()
	Destroys the calendar backend.

virtual QString	name () const =0
	Returns the primary name of the calendar.

QStringList	names () const
	Returns list of names this backend was registered with.

QCalendar::System	calendarSystem () const
	The calendar system of this calendar.

QCalendar::SystemId	calendarId () const

virtual int	daysInMonth (int month, int year=QCalendar::Unspecified) const =0
	Returns number of days in the month number month, in year year.

virtual int	daysInYear (int year) const
	Returns the total number of days in the year number year.

virtual int	monthsInYear (int year) const
	Returns the total number of months in the year number year.

virtual bool	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`.

virtual bool	isLeapYear (int year) const =0
	Returns `true` if the specified year is a leap year for this calendar.

virtual bool	isLunar () const =0
	Returns `true` if this calendar is a lunar calendar.

virtual bool	isLuniSolar () const =0
	Returns `true` if this calendar is a lunisolar calendar.

virtual bool	isSolar () const =0
	Returns `true` if this calendar is a solar calendar.

virtual bool	isProleptic () const
	Returns `true` if this calendar is a proleptic calendar.

virtual bool	hasYearZero () const
	Returns `true` if year number `0` is considered a valid year in this calendar.

virtual int	maximumDaysInMonth () const
	Returns the maximum number of days in a month for any year.

virtual int	minimumDaysInMonth () const
	Returns the minimum number of days in any valid month of any valid year.

virtual int	maximumMonthsInYear () const
	Returns the maximum number of months possible in any year.

virtual bool	dateToJulianDay (int year, int month, int day, qint64 *jd) const =0
	Computes the Julian day number corresponding to the specified year, month, and day.

virtual QCalendar::YearMonthDay	julianDayToDate (qint64 jd) const =0
	Computes the year, month, and day in this calendar for the given Julian day number jd.

virtual int	dayOfWeek (qint64 jd) const
	Returns the day of the week for the given Julian Day Number jd.

virtual qint64	matchCenturyToWeekday (const QCalendar::YearMonthDay &parts, int dow) const

virtual QString	monthName (const QLocale &locale, int month, int year, QLocale::FormatType format) const
	Returns the name of the specified month in the given year for the chosen locale, using the given format to determine how complete the name is.

virtual QString	standaloneMonthName (const QLocale &locale, int month, int year, QLocale::FormatType format) const
	Returns the standalone name of the specified month in the chosen locale, using the specified format to determine how complete the name is.

virtual QString	weekDayName (const QLocale &locale, int day, QLocale::FormatType format) const
	Returns the name of the specified day of the week in the chosen locale, using the specified format to determine how complete the name is.

virtual QString	standaloneWeekDayName (const QLocale &locale, int day, QLocale::FormatType format) const
	Returns the standalone name of the specified day of the week in the chosen locale, using the specified format to determine how complete the name is.

virtual QString	dateTimeToString (QStringView format, const QDateTime &datetime, QDate dateOnly, QTime timeOnly, const QLocale &locale) const
	Returns a string representing a given date, time or date-time.

bool	isGregorian () const

QCalendar::SystemId	registerCustomBackend (const QStringList &names)
	Register this backend as a custom backend.

Static Public Member Functions
static QStringList	availableCalendars ()
	Returns a list of names of the available calendar systems.

Protected Member Functions
virtual const QCalendarLocale *	localeMonthIndexData () const =0

virtual const char16_t *	localeMonthData () const =0

Friends
class	QCalendar

class	QtPrivate::QCalendarRegistry

Detailed Description

The QCalendarBackend class provides basic calendaring functions.

Since: 5.14

\inmodule QtCore

\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 \l {thread-safe} way.

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, QCalendarWidget, {The Low-Level API: Extending Qt Applications}

Definition at line 58 of file qcalendarbackend_p.h.

Constructor & Destructor Documentation

◆ QCalendarBackend()

QCalendarBackend::QCalendarBackend ( )

default

◆ ~QCalendarBackend()

QCalendarBackend::~QCalendarBackend ( )

virtual

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()

Definition at line 517 of file qcalendar.cpp.

Member Function Documentation

◆ availableCalendars()

QStringList QCalendarBackend::availableCalendars ( )

static

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()

Definition at line 1035 of file qcalendar.cpp.

◆ calendarId()

QCalendar::SystemId QCalendarBackend::calendarId ( ) const

inline

Since: 6.2

Each backend is allocated an ID when successfully registered. A backend whose calendarId() has isValid() {false} has not been registered; it also cannot be used, as it is not known to any of the available ways to create a QCalendar.

See also: calendarSystem(), fromId()

Definition at line 72 of file qcalendarbackend_p.h.

◆ calendarSystem()

QCalendar::System QCalendarBackend::calendarSystem ( ) const

The calendar system of this calendar.

See also: fromEnum(), calendarId()

Definition at line 613 of file qcalendar.cpp.

◆ dateTimeToString()

QString QCalendarBackend::dateTimeToString	(	QStringView	format,
		const QDateTime &	datetime,
		QDate	dateOnly,
		QTime	timeOnly,
		const QLocale &	locale ) const

virtual

Returns a string representing a given date, time or date-time.

If datetime is specified and valid, it is used and both date and time format tokens are converted to appropriate representations of the parts of the datetime. Otherwise, if dateOnly is valid, only date format tokens are converted; else, if timeOnly is valid, only time format tokens are converted. If none are valid, an empty string is returned.

The specified locale influences how some format tokens are converted; for example, when substituting day and month names and their short-forms. For the supported formatting tokens, see QDate::toString() and QTime::toString(). As described above, the provided date, time and date-time determine which of these tokens are recognized: where these appear in format they are replaced by data. Any text in format not recognized as a format token is copied verbatim into the result string.

See also: QDate::toString(), QTime::toString(), QDateTime::toString()

Definition at line 3816 of file qlocale.cpp.

◆ dateToJulianDay()

virtual bool QCalendarBackend::dateToJulianDay	(	int	year,
		int	month,
		int	day,
		qint64 *	jd ) const

pure virtual

Computes the Julian day number corresponding to the specified year, month, and day.

Returns true and sets jd if there is such a date in this calendar; otherwise, returns false.

See also: QCalendar::partsFromDate(), julianDayToDate()

Implemented in QGregorianCalendar, QIslamicCivilCalendar, QJalaliCalendar, QJulianCalendar, and QMilankovicCalendar.

◆ dayOfWeek()

int QCalendarBackend::dayOfWeek ( qint64 jd ) const

virtual

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; \list

weekDayName() can recognize each such number as identifying a distinct name, that it returns to identify the particular intercallary day; and
matchCenturyToWeekday() can determine what century adjustment aligns a given date within a century to a given day of the week, where this is relevant and possible. \endlist

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

See also: weekDayName(), standaloneWeekDayName(), QDate::dayOfWeek(), Qt::DayOfWeek

Definition at line 870 of file qcalendar.cpp.

◆ daysInMonth()

virtual int QCalendarBackend::daysInMonth	(	int	month,
		int	year = QCalendar::Unspecified ) const

pure virtual

Returns number of days in the month number month, in year year.

An implementation should return 0 if the given year had no such month. If year is QCalendar::Unspecified, return the usual number of days for the month, in those years that include it.

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, daysInMonth(month, year) should be the number of ordinary days in the month, although {isDateValid(year, month, day)} might return true for some larger values of day.

See also: daysInYear(), monthsInYear(), minimumDaysInMonth(), maximumDaysInMonth()

Implemented in QHijriCalendar, QJalaliCalendar, and QRomanCalendar.

◆ daysInYear()

int QCalendarBackend::daysInYear ( int year ) const

virtual

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(), isLeapYear()

Reimplemented in QHijriCalendar.

Definition at line 717 of file qcalendar.cpp.

◆ hasYearZero()

bool QCalendarBackend::hasYearZero ( ) const

virtual

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

Otherwise returns false.

See also: isDateValid(), isProleptic()

Definition at line 775 of file qcalendar.cpp.

◆ isDateValid()

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

virtual

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({month}, {year})} may be valid.

See also: daysInMonth(), monthsInYear()

Definition at line 748 of file qcalendar.cpp.

◆ isGregorian()

bool QCalendarBackend::isGregorian ( ) const

Definition at line 589 of file qcalendar.cpp.

◆ isLeapYear()

virtual bool QCalendarBackend::isLeapYear ( int year ) const

pure virtual

Returns true if the specified year is a leap year for this calendar.

See also: daysInYear(), isDateValid()

Implemented in QGregorianCalendar, QIslamicCivilCalendar, QJalaliCalendar, QJulianCalendar, and QMilankovicCalendar.

◆ isLunar()

virtual bool QCalendarBackend::isLunar ( ) const

pure virtual

Returns true if this calendar is a lunar calendar.

Otherwise returns false.

A lunar calendar is a calendar based upon the monthly cycles of the Moon's phases (synodic months). This contrasts with solar calendars, whose annual cycles are based only upon the solar year.

See also: isLuniSolar(), isSolar(), isProleptic()

Implemented in QHijriCalendar, QJalaliCalendar, and QRomanCalendar.

◆ isLuniSolar()

virtual bool QCalendarBackend::isLuniSolar ( ) const

pure virtual

Returns true if this calendar is a lunisolar calendar.

Otherwise returns false.

A lunisolar calendar is a calendar whose date indicates both the moon phase and the time of the solar year.

See also: isLunar(), isSolar(), isProleptic()

Implemented in QHijriCalendar, QJalaliCalendar, and QRomanCalendar.

◆ isProleptic()

bool QCalendarBackend::isProleptic ( ) const

virtual

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(), hasYearZero()

Definition at line 763 of file qcalendar.cpp.

◆ isSolar()

virtual bool QCalendarBackend::isSolar ( ) const

pure virtual

Returns true if this calendar is a solar calendar.

Otherwise returns false.

A solar calendar is a calendar whose dates indicate the season or almost equivalently the apparent position of the sun relative to the fixed stars. The Gregorian calendar, widely accepted as standard in the world, is an example of solar calendar.

See also: isLuniSolar(), isLunar(), isProleptic()

Implemented in QHijriCalendar, QJalaliCalendar, and QRomanCalendar.

◆ julianDayToDate()

virtual QCalendar::YearMonthDay QCalendarBackend::julianDayToDate ( qint64 jd ) const

pure virtual

Computes the year, month, and day in this calendar for the given Julian day number jd.

If the given day falls outside this calendar's scope (e.g. before the start-date of a non-proleptic calendar), the returned structure's isValid() is false; otherwise, its year, month, and day fields provide this calendar's description of the date.

See also: QCalendar::dateFromParts(), dateToJulianDay()

Implemented in QGregorianCalendar, QIslamicCivilCalendar, QJalaliCalendar, QJulianCalendar, and QMilankovicCalendar.

◆ localeMonthData()

virtual const char16_t * QCalendarBackend::localeMonthData ( ) const

protectedpure virtual

Implemented in QHijriCalendar, QJalaliCalendar, and QRomanCalendar.

◆ localeMonthIndexData()

virtual const QCalendarLocale * QCalendarBackend::localeMonthIndexData ( ) const

protectedpure virtual

Implemented in QHijriCalendar, QJalaliCalendar, and QRomanCalendar.

◆ matchCenturyToWeekday()

qint64 QCalendarBackend::matchCenturyToWeekday	(	const QCalendar::YearMonthDay &	parts,
		int	dow ) const

virtual

Since: 6.7 Adjusts century of parts to match dow.

Preserves parts.month and parts.day while adjusting parts.year by a multiple of 100 (taking the absence of year zero into account, when relevant) to obtain a date for which dayOfWeek() is dow. Prefers smaller changes over larger and increases to the century over decreases of the same magnitude. Returns the Julian Day number for the selected date or std::numeric_limits<qint64>::min(), a.k.a. QDate::nullJd(), if there is no date matching these requirements.

The base-class provides a brute-force implementation that steps outwards from the given date by centures, above and below by up to 14 centuries, in search of a matching date. This is neither computationally efficient nor elegant but should work as advertised for calendars in which every month-day combination does appear on all days of the week, across sufficiently many centuries.

Reimplemented in QGregorianCalendar.

Definition at line 894 of file qcalendar.cpp.

◆ maximumDaysInMonth()

int QCalendarBackend::maximumDaysInMonth ( ) const

virtual

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(), daysInMonth()

Reimplemented in QHijriCalendar.

Definition at line 793 of file qcalendar.cpp.

◆ maximumMonthsInYear()

int QCalendarBackend::maximumMonthsInYear ( ) const

virtual

Returns the maximum number of months possible in any year.

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

See also: maximumDaysInMonth(), monthsInYear()

Definition at line 817 of file qcalendar.cpp.

◆ minimumDaysInMonth()

int QCalendarBackend::minimumDaysInMonth ( ) const

virtual

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(), daysInMonth()

Reimplemented in QRomanCalendar.

Definition at line 805 of file qcalendar.cpp.

◆ monthName()

QString QCalendarBackend::monthName	(	const QLocale &	locale,
		int	month,
		int	year,
		QLocale::FormatType	format ) const

virtual

Returns the name of the specified month in the given year for the chosen locale, using the given format to determine how complete the name is.

If year is Unspecified, return the name for the month that usually has this number within a typical year. Calendars with a leap month that isn't always the last may need to take account of the year to map the month number to the particular year's month with that number.

Note: Backends for which CLDR provides data can configure the default implementation of the two month name look-up methods by arranging for localeMonthIndexData() and localeMonthData() to provide access to the CLDR data (see cldr2qlocalexml.py, qlocalexml2cpp.py and existing backends). Conversely, backends that override both month name look-up methods need not return anything meaningful from localeMonthIndexData() or localeMonthData().

See also: standaloneMonthName(), QLocale::monthName()

Reimplemented in QRomanCalendar.

Definition at line 3407 of file qlocale.cpp.

◆ monthsInYear()

int QCalendarBackend::monthsInYear ( int year ) const

virtual

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(), isDateValid()

Definition at line 730 of file qcalendar.cpp.

◆ name()

virtual QString QCalendarBackend::name ( ) const

pure virtual

Returns the primary name of the calendar.

Implemented in QGregorianCalendar, QIslamicCivilCalendar, QJalaliCalendar, QJulianCalendar, and QMilankovicCalendar.

◆ names()

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()

Definition at line 537 of file qcalendar.cpp.

◆ 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()

Definition at line 579 of file qcalendar.cpp.

◆ standaloneMonthName()

QString QCalendarBackend::standaloneMonthName	(	const QLocale &	locale,
		int	month,
		int	year,
		QLocale::FormatType	format ) const

virtual

Returns the standalone name of the specified month in the chosen locale, using the specified format to determine how complete the name is.

If year is Unspecified, return the standalone name for the month that usually has this number within a typical year. Calendars with a leap month that isn't always the last may need to take account of the year to map the month number to the particular year's month with that number.

See also: monthName(), QLocale::standaloneMonthName()

Reimplemented in QRomanCalendar.

Definition at line 3442 of file qlocale.cpp.

◆ standaloneWeekDayName()

QString QCalendarBackend::standaloneWeekDayName	(	const QLocale &	locale,
		int	day,
		QLocale::FormatType	format ) const

virtual

Returns the standalone name of the specified day of the week in the chosen locale, using the specified format to determine how complete the name is.

The base implementation handles day values from 1 to 7 using the standalone day names CLDR provides, which are suitable for calendards that use the same (Hebrew-derived) week as the Gregorian calendar.

Calendars whose dayOfWeek() returns a value outside the range from 1 to 7 need to reimplement this method to handle such extra week-day values. They can assume that day is a value returned by the same calendar's dayOfWeek().

See also: dayOfWeek(), weekDayName(), QLocale::standaloneDayName()

Definition at line 3508 of file qlocale.cpp.

◆ weekDayName()

QString QCalendarBackend::weekDayName	(	const QLocale &	locale,
		int	day,
		QLocale::FormatType	format ) const

virtual

Returns the name of the specified day of the week in the chosen locale, using the specified format to determine how complete the name is.

The base implementation handles day values from 1 to 7 using the day names CLDR provides, which are suitable for calendards that use the same (Hebrew-derived) week as the Gregorian calendar.

Calendars whose dayOfWeek() returns a value outside the range from 1 to 7 need to reimplement this method to handle such extra week-day values. They can assume that day is a value returned by the same calendar's dayOfWeek().

See also: dayOfWeek(), standaloneWeekDayName(), QLocale::dayName()

Definition at line 3479 of file qlocale.cpp.

Friends And Related Symbol Documentation

◆ QCalendar

friend class QCalendar

friend

Definition at line 60 of file qcalendarbackend_p.h.

◆ QtPrivate::QCalendarRegistry

friend class QtPrivate::QCalendarRegistry

friend

Definition at line 61 of file qcalendarbackend_p.h.

The documentation for this class was generated from the following files:

qtbase/src/corelib/time/qcalendarbackend_p.h (b211d8a8c0196a96b2aa324c9e3d991ae378c7f4)
qtbase/src/corelib/text/qlocale.cpp (9fee7cdfcce00ce6500b8eebf67f4a6c91be98bd)
qtbase/src/corelib/time/qcalendar.cpp (cd442e439b73b8de4e0fc1434320a3ed1a465d2f)

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ QCalendarBackend()

◆ ~QCalendarBackend()

Member Function Documentation

◆ availableCalendars()

◆ calendarId()

◆ calendarSystem()

◆ dateTimeToString()

◆ dateToJulianDay()

◆ dayOfWeek()

◆ daysInMonth()

◆ daysInYear()

◆ hasYearZero()

◆ isDateValid()

◆ isGregorian()

◆ isLeapYear()

◆ isLunar()

◆ isLuniSolar()

◆ isProleptic()

◆ isSolar()

◆ julianDayToDate()

◆ localeMonthData()

◆ localeMonthIndexData()

◆ matchCenturyToWeekday()

◆ maximumDaysInMonth()

◆ maximumMonthsInYear()

◆ minimumDaysInMonth()

◆ monthName()

◆ monthsInYear()

◆ name()

◆ names()

◆ registerCustomBackend()

◆ standaloneMonthName()

◆ standaloneWeekDayName()

◆ weekDayName()

Friends And Related Symbol Documentation

◆ QCalendar

◆ QtPrivate::QCalendarRegistry