The QCalendar class describes calendar systems. More...

#include <qcalendar.h>

Collaboration diagram for QCalendar:

Classes
class	SystemId
	\inmodule QtCore More...

struct	YearMonthDay

Public Types
enum	: int { Unspecified = (std::numeric_limits<int>::min)() }

enum class	System { Gregorian , Julian = 8 , Milankovic = 9 , Last = 11 , User = -1 }
	This enumerated type is used to specify a choice of calendar system. More...

Public Member Functions
	QCalendar ()

	QCalendar (System system)

	QCalendar (QAnyStringView name)
	Constructs a calendar object.

	QCalendar (SystemId id)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool	isValid () const
	Returns true if this is a valid calendar object.

int	daysInMonth (int month, int year=Unspecified) const
	Returns the number of days in the given month of the given year.

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

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

bool	isDateValid (int year, int month, int day) const
	Returns `true` precisely if the given year, month, and day specify a valid date in this calendar.

bool	isLeapYear (int year) const
	Returns `true` if the given year is a leap year.

bool	isGregorian () const
	Returns `true` if this calendar object is the Gregorian calendar object used as default calendar by other Qt APIs, e.g.

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

bool	isLuniSolar () const
	Returns `true` if this calendar is luni-solar.

bool	isSolar () const
	Returns `true` if this calendar is solar.

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

bool	hasYearZero () const
	Returns `true` if this calendar has a year zero.

int	maximumDaysInMonth () const
	Returns the number of days in the longest month in the calendar, in any year.

int	minimumDaysInMonth () const
	Returns the number of days in the shortest month in the calendar, in any year.

int	maximumMonthsInYear () const
	Returns the largest number of months that any year may contain.

QString	name () const
	The primary name of this calendar.

QDate	dateFromParts (int year, int month, int day) const

QDate	dateFromParts (const YearMonthDay &parts) const
	Converts a year, month, and day to a QDate.

QDate	matchCenturyToWeekday (const YearMonthDay &parts, int dow) const

YearMonthDay	partsFromDate (QDate date) const
	Converts a QDate to a year, month, and day of the month.

int	dayOfWeek (QDate date) const
	Returns the day of the week number for the given date.

QString	monthName (const QLocale &locale, int month, int year=Unspecified, QLocale::FormatType format=QLocale::LongFormat) const
	Returns a suitably localised name for a month.

QString	standaloneMonthName (const QLocale &locale, int month, int year=Unspecified, QLocale::FormatType format=QLocale::LongFormat) const
	Returns a suitably localised standalone name for a month.

QString	weekDayName (const QLocale &locale, int day, QLocale::FormatType format=QLocale::LongFormat) const
	Returns a suitably localised name for a day of the week.

QString	standaloneWeekDayName (const QLocale &locale, int day, QLocale::FormatType format=QLocale::LongFormat) const
	Returns a suitably localised standalone name for a day of the week.

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.

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

Detailed Description

The QCalendar class describes calendar systems.

Since: 5.14

\inmodule QtCore \reentrant

A QCalendar object maps a year, month, and day-number to a specific day (ultimately identified by its Julian day number), using the rules of a particular system.

The default QCalendar() is a proleptic Gregorian calendar, which has no year zero. Other calendars may be supported by enabling suitable features or loading plugins. Calendars supported as features can be constructed by passing the QCalendar::System enumeration to the constructor. All supported calendars may be constructed by name, once they have been constructed. (Thus plugins instantiate their calendar backend to register it.) Built-in backends, accessible via QCalendar::System, are also always available by name. Calendars using custom backends may also be constructed using a unique ID allocated to the backend on construction.

A QCalendar value is immutable.

See also: QDate, QDateTime

Definition at line 52 of file qcalendar.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum : int

Enumerator
Unspecified

Definition at line 57 of file qcalendar.h.

◆ System

enum class QCalendar::System

strong

This enumerated type is used to specify a choice of calendar system.

\value Gregorian The default calendar, used internationally. \value Julian An ancient Roman calendar. \value Milankovic A revised Julian calendar used by some Orthodox churches. \value Jalali The Solar Hijri calendar (also called Persian). \value IslamicCivil The (tabular) Islamic Civil calendar. \omitvalue Last \omitvalue User

See also: QCalendar, QCalendar::SystemId

Enumerator
Gregorian
Julian
Milankovic
Last
User

Definition at line 72 of file qcalendar.h.

Constructor & Destructor Documentation

◆ QCalendar() [1/4]

QCalendar::QCalendar ( )

explicit

Definition at line 1210 of file qcalendar.cpp.

◆ QCalendar() [2/4]

QCalendar::QCalendar ( QCalendar::System system )

explicit

Definition at line 1216 of file qcalendar.cpp.

◆ QCalendar() [3/4]

QCalendar::QCalendar ( QAnyStringView name )

explicit

Constructs a calendar object.

The choice of calendar to use may be indicated by system, using the enumeration QCalendar::System, or by name, using a string (either Unicode or Latin 1). Construction by name may depend on an instance of the given calendar being constructed by other means first. With no argument, the default constructor returns the Gregorian calendar.

Note: In Qt versions before 6.4, the constructor by name accepted only QStringView and QLatin1String, not QAnyStringView.

See also: QCalendar, System, isValid()

Definition at line 1240 of file qcalendar.cpp.

◆ QCalendar() [4/4]

QCalendar::QCalendar ( QCalendar::SystemId id )

explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since: 6.2

Constructs a calendar object.

When using a custom calendar implementation, its backend is allocated a unique ID when created; passing that as id to this constructor will get a QCalendar using that backend. This can be useful when the backend is not registered by name.

Definition at line 1234 of file qcalendar.cpp.

Member Function Documentation

◆ availableCalendars()

QStringList QCalendar::availableCalendars ( )

static

Returns a list of names of the available calendar systems.

These may be supplied by plugins or other code linked into an application, in addition to the ones provided by Qt, some of which are controlled by features.

Definition at line 1678 of file qcalendar.cpp.

◆ dateFromParts() [1/2]

QDate QCalendar::dateFromParts ( const YearMonthDay & parts ) const

Converts a year, month, and day to a QDate.

The year, month, and day may be passed as separate numbers or packaged together as the members of parts. Returns a QDate with the given year, month, and day of the month in this calendar, if there is one. Otherwise, including the case where any of the values is QCalendar::Unspecified, returns a QDate whose isNull() is true.

See also: isDateValid(), partsFromDate()

Definition at line 1477 of file qcalendar.cpp.

◆ dateFromParts() [2/2]

QDate QCalendar::dateFromParts	(	int	year,
		int	month,
		int	day ) const

Definition at line 1469 of file qcalendar.cpp.

◆ dateTimeToString()

QString QCalendar::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.

If datetime is valid, it is represented and format specifiers for both date and time fields are recognized; otherwise, if dateOnly is valid, it is represented and only format specifiers for date fields are recognized; finally, if timeOnly is valid, it is represented and only format specifiers for time fields are recognized. If none of these is valid, an empty string is returned.

See QDate::toString and QTime::toString() for the supported field specifiers. Characters in format that are recognized as field specifiers are replaced by text representing appropriate data from the date and/or time being represented. The texts to represent them may depend on the locale specified. Other charagers in format are copied verbatim into the returned string.

See also: monthName(), weekDayName(), QDate::toString(), QTime::toString()

Definition at line 1663 of file qcalendar.cpp.

◆ dayOfWeek()

int QCalendar::dayOfWeek ( QDate date ) const

Returns the day of the week number for the given date.

Returns zero if the calendar is unable to represent the indicated date. Returns 1 for Monday through 7 for Sunday. Calendars with intercallary days may use other numbers to represent these.

See also: partsFromDate(), Qt::DayOfWeek

Definition at line 1532 of file qcalendar.cpp.

◆ daysInMonth()

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

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

Months are numbered consecutively, starting with 1 for the first month of each year. If year is Unspecified (its default, if not passed), the month's greatest length in any year is returned.

See also: maximumDaysInMonth(), minimumDaysInMonth()

Definition at line 1266 of file qcalendar.cpp.

◆ daysInYear()

int QCalendar::daysInYear ( int year ) const

Returns the number of days in the given year.

Handling of Unspecified as year is undefined.

Definition at line 1277 of file qcalendar.cpp.

◆ hasYearZero()

bool QCalendar::hasYearZero ( ) const

Returns true if this calendar has a year zero.

A calendar may represent years from its first year onwards but provide no way to describe years before its first; such a calendar has no year zero and is not proleptic.

A calendar which represents years before its first may number these years simply by following the usual integer counting, so that the year before the first is year zero, with negative-numbered years preceding this; such a calendar is proleptic and has a year zero. A calendar might also have a year zero (for example, the year of some great event, with subsequent years being the first year after that event, the second year after, and so on) without describing years before its year zero. Such a calendar would have a year zero without being proleptic.

Some calendars, however, represent years before their first by an alternate numbering; for example, the proleptic Gregorian calendar's first year is 1 CE and the year before it is 1 BCE, preceded by 2 BCE and so on. In this case, we use negative year numbers for this alternate numbering, with year -1 as the year before year 1, year -2 as the year before year -1 and so on. Such a calendar is proleptic but has no year zero.

See also: isProleptic()

Definition at line 1414 of file qcalendar.cpp.

◆ isDateValid()

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

Returns true precisely if the given year, month, and day specify a valid date in this calendar.

Usually this means 1 <= month <= monthsInYear(year) and 1 <= day <= daysInMonth(month, year). However, calendars with intercallary days or months may complicate that.

Definition at line 1305 of file qcalendar.cpp.

◆ isGregorian()

bool QCalendar::isGregorian ( ) const

Returns true if this calendar object is the Gregorian calendar object used as default calendar by other Qt APIs, e.g.

in QDate.

Definition at line 1317 of file qcalendar.cpp.

◆ isLeapYear()

bool QCalendar::isLeapYear ( int year ) const

Returns true if the given year is a leap year.

Since the year is not a whole number of days long, some years are longer than others. The difference may be a whole month or just a single day; the details vary between calendars.

See also: isDateValid()

Definition at line 1332 of file qcalendar.cpp.

◆ isLunar()

bool QCalendar::isLunar ( ) const

Returns true if this calendar is a lunar calendar.

A lunar calendar is one based primarily on the phases of the moon.

Definition at line 1343 of file qcalendar.cpp.

◆ isLuniSolar()

bool QCalendar::isLuniSolar ( ) const

Returns true if this calendar is luni-solar.

A luni-solar calendar expresses the phases of the moon but adapts itself to also keep track of the Sun's varying position in the sky, relative to the fixed stars.

Definition at line 1356 of file qcalendar.cpp.

◆ isProleptic()

bool QCalendar::isProleptic ( ) const

Returns true if this calendar is proleptic.

A proleptic calendar is able to describe years arbitrarily long before its first. These are represented by negative year numbers and possibly by a year zero.

See also: hasYearZero()

Definition at line 1383 of file qcalendar.cpp.

◆ isSolar()

bool QCalendar::isSolar ( ) const

Returns true if this calendar is solar.

A solar calendar is based primarily on the Sun's varying position in the sky, relative to the fixed stars.

Definition at line 1368 of file qcalendar.cpp.

◆ isValid()

bool QCalendar::isValid ( ) const

inline

Returns true if this is a valid calendar object.

Constructing a calendar with an unrecognised calendar name may result in an invalid object. Use this method to check after creating a calendar by name.

Definition at line 121 of file qcalendar.h.

◆ matchCenturyToWeekday()

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

Since: 6.7 Adjusts the century of a date to match a given day of the week.

For use when given a date's day of week, day of month, month and last two digits of the year. Returns a QDate instance with the given dow as its \l {QDate::}{dayOfWeek()}, matching the given parts in month and day of the month. The returned QDate's \l {QDate::}{year()} shall differ from {parts.year} by a multiple of 100, preferring small multiples over larger and positive multiples over their negations.

If no date matches these conditions, an invalid QDate is returned: the day of week is incompatible with the other data given. This arises, for example, with the Gregorian calendar, whose 400-year cycle is a whole number of weeks long, so any given month and day of that month only ever falls, in years with a given last two digits, on four days of the week. (In the special case of February 29th at the turn of a century, when that is a leap year, only one day of the week is possible: Tuesday.)

Definition at line 1501 of file qcalendar.cpp.

◆ maximumDaysInMonth()

int QCalendar::maximumDaysInMonth ( ) const

Returns the number of days in the longest month in the calendar, in any year.

See also: daysInMonth(), minimumDaysInMonth()

Definition at line 1425 of file qcalendar.cpp.

◆ maximumMonthsInYear()

int QCalendar::maximumMonthsInYear ( ) const

Returns the largest number of months that any year may contain.

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

Definition at line 1447 of file qcalendar.cpp.

◆ minimumDaysInMonth()

int QCalendar::minimumDaysInMonth ( ) const

Returns the number of days in the shortest month in the calendar, in any year.

See also: daysInMonth(), maximumDaysInMonth()

Definition at line 1436 of file qcalendar.cpp.

◆ monthName()

QString QCalendar::monthName	(	const QLocale &	locale,
		int	month,
		int	year = Unspecified,
		QLocale::FormatType	format = QLocale::LongFormat ) const

Returns a suitably localised name for a month.

The month is indicated by a number, with month = 1 meaning the first month of the year and subsequent months numbered accordingly. Returns an empty string if the month number is unrecognized.

The year may be Unspecified, in which case the mapping from numbers to names for a typical year's months should be used. Some calendars have leap months that aren't always at the end of the year; their mapping of month numbers to names may then depend on the placement of a leap month. Thus the year should normally be specified, if known.

The name is returned in the form that would normally be used in a full date, in the specified locale; the format determines how fully it shall be expressed (i.e. to what extent it is abbreviated).

See also: standaloneMonthName(), maximumMonthsInYear(), dateTimeToString()

Definition at line 1559 of file qcalendar.cpp.

◆ monthsInYear()

int QCalendar::monthsInYear ( int year ) const

Returns the number of months in the given year.

If year is Unspecified, returns the maximum number of months in a year.

See also: maximumMonthsInYear()

Definition at line 1291 of file qcalendar.cpp.

◆ name()

QString QCalendar::name ( ) const

The primary name of this calendar.

The calendar may also be known by some aliases. A calendar instantiated by name may use such an alias, in which case its name() need not match the alias by which it was instantiated.

Definition at line 634 of file qcalendar.cpp.

◆ partsFromDate()

QCalendar::YearMonthDay QCalendar::partsFromDate ( QDate date ) const

Converts a QDate to a year, month, and day of the month.

The returned structure's isValid() shall be false if the calendar is unable to represent the given date. Otherwise its year, month, and day members record the so-named parts of its representation.

See also: dateFromParts(), isProleptic(), hasYearZero()

Definition at line 1517 of file qcalendar.cpp.

◆ standaloneMonthName()

QString QCalendar::standaloneMonthName	(	const QLocale &	locale,
		int	month,
		int	year = Unspecified,
		QLocale::FormatType	format = QLocale::LongFormat ) const

Returns a suitably localised standalone name for a month.

The month is indicated by a number, with month = 1 meaning the first month of the year and subsequent months numbered accordingly. Returns an empty string if the month number is unrecognized.

The year may be Unspecified, in which case the mapping from numbers to names for a typical year's months should be used. Some calendars have leap months that aren't always at the end of the year; their mapping of month numbers to names may then depend on the placement of a leap month. Thus the year should normally be specified, if known.

The name is returned in the form that would be used in isolation in the specified locale; the format determines how fully it shall be expressed (i.e. to what extent it is abbreviated).

See also: monthName(), maximumMonthsInYear(), dateTimeToString()

Definition at line 1589 of file qcalendar.cpp.

◆ standaloneWeekDayName()

QString QCalendar::standaloneWeekDayName	(	const QLocale &	locale,
		int	day,
		QLocale::FormatType	format = QLocale::LongFormat ) const

Returns a suitably localised standalone name for a day of the week.

The days of the week are numbered from 1 for Monday through 7 for Sunday. Some calendars may support higher numbers for other days (e.g. intercallary days, that are not part of any week). Returns an empty string if the day number is unrecognized.

The name is returned in the form that would be used in isolation (for example as a column heading in a calendar's tabular display of a month with successive weeks as rows) in the specified locale; the format determines how fully it shall be expressed (i.e. to what extent it is abbreviated).

See also: weekDayName(), dayOfWeek()

Definition at line 1637 of file qcalendar.cpp.

◆ weekDayName()

QString QCalendar::weekDayName	(	const QLocale &	locale,
		int	day,
		QLocale::FormatType	format = QLocale::LongFormat ) const

Returns a suitably localised name for a day of the week.

The days of the week are numbered from 1 for Monday through 7 for Sunday. Some calendars may support higher numbers for other days (e.g. intercallary days, that are not part of any week). Returns an empty string if the day number is unrecognized.

The name is returned in the form that would normally be used in a full date, in the specified locale; the format determines how fully it shall be expressed (i.e. to what extent it is abbreviated).

See also: standaloneWeekDayName(), dayOfWeek()

Definition at line 1614 of file qcalendar.cpp.

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

qtbase/src/corelib/time/qcalendar.h (b8fac538032cee6eb6f4e5dcbb5a31485bb59e46)
qtbase/src/corelib/time/qcalendar.cpp (cd442e439b73b8de4e0fc1434320a3ed1a465d2f)

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ System

Constructor & Destructor Documentation

◆ QCalendar() [1/4]

◆ QCalendar() [2/4]

◆ QCalendar() [3/4]

◆ QCalendar() [4/4]

Member Function Documentation

◆ availableCalendars()

◆ dateFromParts() [1/2]

◆ dateFromParts() [2/2]

◆ dateTimeToString()

◆ dayOfWeek()

◆ daysInMonth()

◆ daysInYear()

◆ hasYearZero()

◆ isDateValid()

◆ isGregorian()

◆ isLeapYear()

◆ isLunar()

◆ isLuniSolar()

◆ isProleptic()

◆ isSolar()

◆ isValid()

◆ matchCenturyToWeekday()

◆ maximumDaysInMonth()

◆ maximumMonthsInYear()

◆ minimumDaysInMonth()

◆ monthName()

◆ monthsInYear()

◆ name()

◆ partsFromDate()

◆ standaloneMonthName()

◆ standaloneWeekDayName()

◆ weekDayName()