Calendar Modules

The calendars plugin provides generic support for a number of world calendars. In general a calendar defines a series of years, each of which consists of a number of months that are then broken down into days. Days may also be grouped into weeks.

Each calendar implementation defines what the year sequence is (many have no year zero), how many months per year (varies in the Hebrew calendar), and how many days per month. Alongside this are the month and day names and localised values such as date format and start of the week.

Since JavaScript only supports the Gregorian calendar in its native Date object, a new date object with more generic calendar support is included within the plugin.

The calendars plugin is broken up into a series of modules to allow you to choose just the functionality you require.

ModulePurposeDependencies
jquery.calendars.js Base calendar support, including custom CDate object and Gregorian calendar. -
jquery.calendars.taiwan.js Taiwanese calendar support - also known as the Minguo calendar.
Since 1.1.0.
Base
jquery.calendars.thai.js Thai calendar support.
Since 1.1.0.
Base
jquery.calendars.julian.js Julian calendar implementation. Base
jquery.calendars.persian.js Persian calendar implementation - also known as Iranian or Jalali calendar. Base
jquery.calendars.islamic.js Islamic calendar implementation - the 'civil 16' version, also known as Hijri calendar. Base
jquery.calendars.ummalqura.js Umm al-Qura calendar support - also known as the Saudi calendar. Written by Amro Osama.
Since 1.2.1.
Base
jquery.calendars.hebrew.js Hebrew (civil) calendar implementation. Base
jquery.calendars.ethiopian.js Ethiopian calendar support.
Since 1.1.0.
Base
jquery.calendars.coptic.js Coptic calendar support.
Since 1.1.0.
Base
jquery.calendars.nepali.js Nepali calendar support - also known as Vikram Samvat. Written by Artur Neumann.
Since 1.2.1.
Base
jquery.calendars.nanakshahi.js Nanakshahi calendar support.
Since 2.0.2.
Base
jquery.calendars.mayan.js Mayan (Long Count) calendar implementation. Base
jquery.calendars.discworld.js Discworld calendar support.
Since 2.0.2.
Base
jquery.calendars.plus.js Additional calendar functionality, such as parsing and formatting dates. Base
jquery.calendars.picker.js A datepicker with full calendar support and localisation. See separate documentation. Base, Plus
jquery.calendars.picker.ext.js Datepicker extensions with alternate renderers and added functionality. Base, Plus, Picker
jquery.calendars.all.js Combines the base, plus, and datepicker modules into one. -
Calendars Access

The base module provides basic date and calendar support and includes an implementation of the Gregorian calendar.

Initial access is via the $.calendars variable. It offers the following functions:

SignatureReturnsComments
$.calendars.instance(name, language) *Calendar object Retrieve a specific calendar implementation.

name (string, optional) is the name of the calendar to find. Implementations for the following calendars are available by including the appropriate calendars module: 'gregorian', 'julian', 'persian', 'islamic', 'ummalqura', 'hebrew', 'ethiopian', 'coptic', 'nepali', 'nanakshahi', 'mayan', 'discworld'. If not specified a Gregorian calendar is returned.

language (string, optional) is the language code for a localisation pack for this calendar. It defaults to English.

var gc = $.calendars.instance();
var pc_fa = $.calendars.instance('persian', 'fa');
$.calendars.newDate(year, month, day, calendar, language) CDate object Create a new date object. An error is thrown if the date is not valid for the calendar. You can also create dates from a calendar or from another date.

year (CDate) is a date to clone or (number) is the year for the date.

month (number) is the month for the date. Omit if year is a date object.

day (number) is the day for the date. Omit if year is a date object.

calendar (*Calendar, optional) is the calendar to use for this date, or (string) the name of the calendar (see above). If not specified a Gregorian calendar is used. If year is a date object its calendar is used instead.

language (string, optional) is the language code for a localisation pack for this calendar. It defaults to English.

var d = $.calendars.newDate(2009, 1, 26);
var d = $.calendars.newDate(1388, 1, 1, 'persian', 'fa');
var d = $.calendars.newDate(1388, 1, 1, pc_fa);
$.calendars.substituteDigits(digits) function Create a number localisation function for use with the digits option. The returned function accepts a numeric value and substitutes local numerals for those in the value provided.

digits (string[]) is an array of 10 characters to be substituted for the digits 0 through 9.

digits: $.calendars.substituteDigits(
	['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩']),

Since 2.0.2.
$.calendars.substituteChineseDigits(digits, powers) function Create a number localisation function for use with the digits option. The returned function accepts a numeric value and generates local numerals for those in the value provided.

digits (string[]) is an array of 10 characters to be substituted for the digits 0 through 9.

powers (string[]) is an array of characters to denote powers of 10, being for units, tens, hundred, thousands, etc.

digits: $.calendars.substituteChineseDigits(
	['〇', '一', '二', '三', '四', '五', '六', '七', '八', '九'],
	['', '十', '百', '千']),

Since 2.0.2.

The following attributes are defined:

NameTypeDefaultComments
calendars object - This attribute provides direct access to the various calendar implementations. Each calendar adds its implementation "class" to this object under its given name. It is only used internally to register and construct particular calendars. Use the instance function instead to retrieve calendars.

$.calendars.calendars.gregorian = GregorianCalendar;
baseCalendar BaseCalendar BaseCalendar This attribute provides access to the base "class" from which other calendar implementations inherit. It contains common code used by all calendars. It is only used internally to implement new calendars.

JulianCalendar.prototype = new $.calendars.baseCalendar;
regional object[] See below The base calendar processing may be localised by adding entries to this attribute, and then referring to them with the local attribute. Each entry is indexed by its language code and its value is an object with the regional fields shown below.

Within these values use '{n}', where n is a number starting from zero, to indicate insertion points for message-specific details.

$.calendars.regional['fr'] = {
	invalidCalendar: 'Le calendrier {0} n\'a pas trouvé',
	invalidDate: 'Date {0} inadmissible',
	invalidMonth: 'Mois {0} inadmissible',
	invalidMonth: 'Année {0} inadmissible',
	differentCalendars: 'Ne peut pas utiliser {0} avec {1}'};
local object $.calendars.regional[''] The regional settings that are currently in use are referenced by this attribute. You would only change this to localise the standard error messages generated by calendar implementations.

$.calendars.local = $.calendars.regional['fr'];

Regional Settings

NameTypeDefaultComments
invalidCalendarstring 'Calendar {0} not found' The eror message when a requested calendar implementation cannot be found. '{0}' is the calendar name.
invalidDatestring 'Invalid {0} date' The error message when a requested date is invalid for a calendar, e.g. Gregorian 02/29/2009. '{0}' is the calendar name.
invalidMonthstring 'Invalid {0} month' The eror message when a requested month is invalid for a calendar, e.g. Gregorian 13/2009. '{0}' is the calendar name.
invalidYearstring 'Invalid {0} year' The error message when a requested year is invalid for a calendar, e.g. Gregorian 0000. '{0}' is the calendar name.
differentCalendarsstring 'Cannot mix {0} and {1} dates' The error message when trying to use dates from two different calendars. '{0}' and '{1}' are the calendar names.
Calendars Dates

Since JavaScript only supports the Gregorian calendar in its native Date object, a new date object with more generic calendar support is included within the base module: CDate.

This date object is always associated with a particular calendar and is generally created through it.

Many of the date functions return the date itself so that further calls can be chained together. It offers the following functions:

add | calendar | compareTo | date | day | dayOfWeek | dayOfYear | daysInMonth | daysInYear | epoch | extraInfo | formatYear | fromJD | fromJSDate | leapYear | month | monthOfYear | newDate | set | toJD | toJSDate | toString | weekDay | weekOfYear | year

SignatureReturnsComments
newDate(year, month, day) CDate object Create a new date using this date's calendar. You can also create dates directly and from a calendar. An error is thrown if the requested date is invalid.

year (number, optional) is the year for the new date. If no parameters are specified the current date is cloned.

month (number, optional) is the month for the new date.

day (number, optional) is the day for the new date.

var date1 = date.newDate(); // Clone
var date2 = date.newDate(2010, 1, 26);
year(year) this CDate or number Set or retrieve the year for this date. If no parameter is supplied the current year is returned. Otherwise the year for the date is changed and the date object is returned. Use negative values for years before the current epoch. This is equivalent to set(year, 'y'). To change all the periods, use the date() function. An error is thrown if the requested date is invalid.

year (number, optional) is the new year for the date.

var y = date.year();
date.year(2008);
month(month) this CDate or number Set or retrieve the month for this date. If no parameter is supplied the current month is returned. Otherwise the month for the date is changed and the date object is returned. This is equivalent to set(month, 'm'). To change all the periods, use the date() function. An error is thrown if the requested date is invalid.

month (number, optional) is the new month for the date.

var m = date.month();
date.month(2);
day(day) this CDate or number Set or retrieve the day for this date. If no parameter is supplied the current day is returned. Otherwise the day for the date is changed and the date object is returned. This is equivalent to set(day, 'd'). To change all the periods, use the date() function. An error is thrown if the requested date is invalid.

day (number, optional) is the new day for the date.

var d = date.day();
date.day(29);
date(year, month, day) this CDate Set this date's values. To change individual periods, use the year(), month(), day(), or set() functions. An error is thrown if the requested date is invalid.

year (number) is the new year for this date.

month (number) is the new month for this date.

day (number) is the new day for this date.

date.date(2004, 1, 26);
leapYear() boolean Determine whether or not this date is in a leap year. It returns true if it is, or false if it is not. You can also determine a leap year from the calendar.

if (date.leapYear()) ...
epoch() string Retrieve the epoch designator for this date. For the Gregorian calendar this is 'BCE' for negative years or 'CE' for positive years. You can also find the epoch from the calendar.

var e = date.epoch();
formatYear() string Retrieve the formatted year for this date. Typically this is the same as the normal year, padded to four digits. For the Mayan calendar it is the long count year in the format: b'ak'tun.k'atun.tun. You can also find the formatted year from the calendar.

var fy = date.formatYear();
monthOfYear() number Retrieve the ordinal month number for this date, i.e. the number of the month within a numbered year as opposed to its number within the list of months. This is only different in the Hebrew calendar where the year numbering changes on month 7. You can also find the month of the year from the calendar.

var moy = date.monthOfYear();
weekOfYear(); number Retrieve the number of the week within the year in which this date is located. By default this uses the ISO 8601 definition of a week: weeks start on Monday, the first week of the year contains the first Thursday of the year. This means that some dates at the start and end of some years will appear in weeks from other years. You can also find the week of the year from the calendar.

var woy = date.weekOfYear();
daysInYear() number Retrieve the number of days in this date's year. You can also find the days in a year from the calendar.

var diy = date.daysInYear();
dayOfYear() number Retrieve this date's position within the year. It returns 1 through the number of days in the year. You can also find the day of the year from the calendar.

var doy = date.dayOfYear()
daysInMonth() number Retrieve the number of days in this date's month. You can also find the days in a month from the calendar.

var dim = date.daysInMonth();
dayOfWeek() number Determine this date's day of the week. The returned value ranges from zero to one less than the number of days in the week, with 0 being Sunday (or equivalent), 1 being Monday, etc. You can also find the day of the week from the calendar.

var dow = date.dayOfWeek();
weekDay() boolean Determine whether or not this date is a normal week day. It returns true if it is (Monday through Friday in the Gregorian calendar), or false if it is not. You can also determine week days from the calendar.

if (date.weekDay()) ...
extraInfo() object Retrieve extra information about this date - the returned object's attributes depend on the calendar implementation. For example, the Mayan calendar returns the corresponding Tzolkin and Haab dates. You can also find the extra information about a day from the calendar.

var ei = date.extraInfo();
alert(ei.tzolkinDayName);
add(offset, period) this CDate Add a number of periods to this date. If changing by month or year and the new month has fewer days, the day is adjusted to the end of that new month. You can also add periods from the calendar.

offset (number) is the amount of change, which may be negative.

period (string) is the unit of change: 'y' for years, 'm' for months, 'w' for weeks, 'd' for days.

date.add(1, 'w');
date.add(-18, 'm');
date.add(1, 'y').add(1, 'd');
set(value, period) this CDate Set a period for this date. An error is thrown if the requested date is invalid. Alternately, use the year(), month(), or day() functions. To change all the periods, use the date() function. You can also set periods from the calendar.

value (number) is the new period value.

period (string) is the period designator: 'y' for year, 'm' for month, 'd' for day.

date.set(2010, 'y');
date.set(1, 'm').set(16, 'd');
compareTo(date) number Compare this date to another date. It returns -1 if this date is before the other date, 0 if they are equal, or +1 if this date is after the other date. An error is thrown if the two dates belong to different calendars.

date (CDate) is the other date to compare.

if (date.compareTo(date2) == -1) ...
calendar() *Calendar Retrieve the calendar implementation backing this date.

var c = date.calendar();
toJD() number Retrieve the Julian date for this date. This is the number of days since 1 January, 4713 BCE, Greenwich noon. You can also convert to a Julian date from the calendar.

var jd = date.toJD();
fromJD(jd) CDate Create a new date for a given Julian date.

jd (number) is the Julian date to convert. Typically it would end in .5, e.g. 2454857.5. You can also convert from a Julian date from the calendar.

var date2 = date.fromJD(jd);
toJSDate() Date Convert this date into the equivalent JavaScript Date. You can also convert to a JavaScript Date from the calendar.

var jsd = date.toJSDate();
fromJSDate(jsd) CDate Convert a JavaScript Date into the equivalent CDate. You can also convert from a JavaScript date from the calendar.

jsd (Date) is the JavaScript date to convert.

var date2 = date.fromJSDate(jsd);
toString() string Retrieve a string representation of this date. Usually this would be for debugging purposes only. You should use the formatDate function for more flexible formatting.

alert(date.toString());
Generic Calendar Functions

All the calendar implementations within this plugin offer the same functionality, providing basic information about the calendar and generating and manipulating dates from that calendar.

add | dayOfWeek | dayOfYear | daysInMonth | daysInWeek | daysInYear | epoch | extraInfo | formatYear | fromJD | fromJSDate | fromMonthOfYear | isValid | leapYear | monthsInYear | monthOfYear | newDate | set | toJD | toJSDate | today | weekDay | weekOfYear

SignatureReturnsComments
newDate(year, month, day) CDate Create a new date object within this calendar. You can also create dates directly or from another date. An error is thrown if the requested date is not valid.

year (CDate) is a date to clone or (number) is the year for the new date.

month (number, optional) is the month for the date.

day (number, optional) is the day for the date.

var d = gc.newDate(2009, 1, 26);
var d2 = gc.newDate(d);
var d = pc.newDate(1388, 1, 1);
today() CDate Create a new date object representing today within this calendar.

var d = gc.today();
leapYear(year) boolean Determine whether or not this date is in a leap year. It returns true if it is, or false if it is not. You can also determine a leap year from the date itself.

year (CDate) is a date to get the year from or (number) is the year to examine.

if (gc.leapYear(d)) ...
if (hc.leapYear(5768)) ...
epoch(year) string Retrieve the epoch designator for this date. For the Gregorian calendar this is 'BCE' for negative years or 'CE' for positive years. You can also find the epoch from the date itself.

year (CDate) is a date to get the year from or (number) is the year to examine.

var e = gc.epoch(d);
var e = pc.epoch(1388);
formatYear(year) string Retrieve the formatted year for this date. Typically this is the same as the normal year, padded to four digits. For the Mayan calendar it is the long count year in the format: baktun.katun.tun. You can also find the formatted year from the date itself.

year (CDate) is a date to get the year from or (number) is the year to examine.

var fy = gc.formatYear(d);
var fy = mc.newDate(5160);
monthsInYear(year) number Retrieve the number of months in a given year for this calendar.

year (CDate) is a date to get the year from or (number) is the year to examine.

var m = gc.monthsInYear(d);
var m = hc.monthsInYear(5768); // = 13
monthOfYear(year, month) number Retrieve the ordinal month number for a given month, i.e. the number of the month within a numbered year as opposed to its number within the list of months. This is only different in the Hebrew calendar where the year numbering changes on month 7. You can also find the month of the year from the date itself. The inverse function is fromMonthOfYear.

year (CDate) is a date to get the month from or (number) is the year to exmaine.

month (number, optional) is the month to examine.

var moy = gc.monthOfYear(d);
var moy = hc.monthOfYear(5768, 7); // = 1
fromMonthOfYear(year, ord) number Retrieve the month for a given ordinal month number, i.e. the number of the month within the list of months as opposed to its number within a numbered year. This is only different in the Hebrew calendar where the year numbering changes on month 7. The inverse function is monthOfYear.

year(number) is the year to exmaine.

ord (number) is the ordinal month number.

var m = gc.fromMonthOfYear(y, o);
weekOfYear(year, month, day) number Retrieve the number of the week within the year in which a date is located. By default this uses the ISO 8601 definition of a week: weeks start on Monday, the first week of the year contains the first Thursday of the year. This means that some dates at the start and end of some years will appear in weeks from other years. An error is thrown if the date is not valid for the calendar. You can also find the week of the year from the date itself.

year (CDate) is the date to examine or (number) is the year to examine.

month (number, optional) is the month to examine.

day (number, optional) is the day to examine.

var woy = gc.weekOfYear(d);
var woy = pc.weekOfYear(1388, 1, 1);
daysInYear(year) number Retrieve the number of days in a given year. You can also find the day in a year from the date itself.

year (CDate) is a date to get the year from or (number) is the year to examine.

var diy = gc.daysInYear(d);
var diy = hc.daysInYear(5768);
dayOfYear(year, month, day) number Retrieve the number of the given day within its year. An error is thrown if the date is not valid for the calendar. You can also find the day of the year from the date itself.

year (CDate) is a date to examine or (number) is the year to examine.

month (number, optional) is the month to examine.

day (number, optional) is the day to examine.

var doy = gc.dayOfYear(d);
var doy = pc.dayOfYear(1388, 1, 1);
daysInMonth(year, month) number Retrieve the number of days in a given month. An error is thrown if the year or month is invalid. You can also find the days in a month from the date itself.

year (CDate) is a date to get the month and year from or (number) is the year to examine.

month (number, optional) is the month to examine.

var dim = gc.daysInMonth(d);
var dim = pc.daysInMonth(1388, 12);
daysInWeek() number Retrieve the number of days in a week.

var diw = gc.daysInWeek();
dayOfWeek(year, month, day) number Retrieve the number of the given day within its week. An error is thrown if the date is not valid for the calendar. You can also find the day of the week from the date itself.

year (CDate) is a date to examine or (number) is the year to examine.

month (number, optional) is the month to examine.

day (number, optional) is the day to examine.

var dow = gc.dayOfWeek(d);
var dow = pc.dayOfWeek(1388, 1, 1);
weekDay(year, month, day) boolean Determine whether or not this date is a normal week day. It returns true if it is (Monday through Friday in the Gregorian calendar), or false if it is not. You can also determine a week day from the date itself.

year (CDate) is a date to examine or (number) is the year to examine.

month (number, optional) is the month to examine.

day (number, optional) is the day to examine.

if (gc.weekDay(d)) ...
if (pc.weekDay(1388, 1, 1)) ...
extraInfo(year, month, day) object Retrieve extra information about this date - the returned object's attributes depend on the calendar implementation. For example, the Mayan calendar returns the corresponding Tzolkin and Haab dates. An error is thrown if the date is not valid for the calendar. You can also find extra information from the date itself.

year (CDate) is a date to examine or (number) is the year to examine.

month (number, optional) is the month to examine.

day (number, optional) is the day to examine.

var ei = hc.extraInfo(d);
var ei = mc.extraInfo(5160, 1, 1);
alert(ei.tzolkinDayName);
add(date, offset, period) CDate Add a number of periods to a date and return the modified date. If changing by month or year and the new month has fewer days, the day is adjusted to the end of that new month. You can also add periods to the date itself.

date (CDate)the day to modify.

offset (number) is the amount of change; it may be negative.

period (string) is the unit of change: 'y' for years, 'm' for months, 'w' for weeks, 'd' for days.

gc.add(d, 1, 'w');
gc.add(d, 18, 'm');
set(date, value, period) CDate Set a period for a date. An error is thrown if the date is not valid for the calendar. You can also set periods for the date itself.

date (CDate)the day to modify.

value (number) is the new period value.

period (string) is the period designator: 'y' for year, 'm' for month, 'd' for day.

gc.set(d, 2010, 'y');
pc.set(d, 1, 'm');
isValid(year, month, day) boolean Determine whether or not a given date is valid within this calendar. It returns true if valid, or false if not.

year (number) is the year to examine.

month (number) is the month to examine.

day (number) is the day to examine.

if (gc.isValid(2009, 1, 26)) ... // true
if (gc.isValid(2009, 2, 29)) ... // false
toJD(year, month, day) number Convert a date into its Julian date equivalent. This is the number of days since 1 January, 4713 BCE, Greenwich noon. An error is thrown if the date is not valid for the calendar. You can also convert to a Julian date from the date itself.

year (CDate) is a date to convert or (number) is the year to convert.

month (number, optional) is the month to convert.

day (number, optional) is the day to convert.

var jd = gc.toJD(d);
var jd = pc.toJD(1388, 1, 1);
fromJD(jd) CDate Create a new date for a given Julian date. You can also convert from a Julian date from another date.

jd (number) is the Julian date to convert. Typically it would end in .5, e.g. 2454857.5.

var d = gc.fromJD(jd);
toJSDate(year, month, day) Date Convert this date into the equivalent JavaScript Date. An error is thrown if the date is not valid for the calendar. You can also convert to a JavaScript Date from the date itself.

year (CDate) is a date to convert or (number) is the year to convert.

month (number, optional) is the month to convert.

day (number, optional) is the day to convert.

var jsd = gc.toJSDate(d);
var jsd = pc.toJSDate(1388, 1, 1);
fromJSDate(jsd) CDate Convert a JavaScript Date into the equivalent CDate. You can also convert from a JavaScript Date from another date.

jsd (Date) is the JavaScript date to convert.

var d = gc.fromJSDate(jsd);
var d = pc.fromJSDate(new Date(2009, 1 - 1, 26));
Generic Calendar Fields

All the calendar implementations within this plugin offer the same functionality, providing basic information about the calendar and generating and manipulating dates from that calendar.

NameTypeComments
namestring The unchanging name of this calendar implementation.
jdEpochnumber The Julian Date of the start of the epoch for this calendar, e.g. the date for 1 January 0001 CE in the Gregorian calendar.
hasYearZeroboolean True if this calendar has a year zero or false if not.
minMonthnumber The minimum month number, e.g. 1 in most calendars but 0 in the Mayan calendar.
firstMonthnumber The number of the first month within a year, e.g. the same as minMonth in most calendars, but 7 in the Hebrew calendar.
minDaynumber The minimum day number, e.g. 1 in most calendars but 0 in the Mayan calendar.
regionalobject[] The localised settings for this calendar. Entries are indexed by their language code and consist of an object with the fields shown below.

Regional Settings

NameTypeComments
namestring The name of this calendar implementation.
epochsstring[2] The epoch indicators, e.g. 'BCE' and 'CE' for the Gregorian calendar.
monthNamesstring[] The full names of the months.
monthNamesShortstring[] The abbreviated names of the months.
dayNamesstring[] The full names of the days of the week.
dayNamesShortstring[] The abbreviated names of the days of the week.
dayNamesMinstring[] The minimal names of the days of the week.
digitsfunction The function to localise numeric values, or null to use the standard Arabic numerals. The function accepts a numeric value and returns the corresponding localised value. For a straight character substitution use the substituteDigits function. For a substitution that includes powers of 10 use the substituteChineseDigits function.

digits: $.calendars.substituteDigits(
	['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩']),

Since 2.0.2.
dateFormatstring The default date format. See the formatDate function for a description of this field.
firstDaynumber The first day of the week, 0 = Sunday, 1 = Monday, ...
isRTLboolean True if this language runs right-to-left or false if it does not.
Calendar Implementations

Several world calendars are implemented within this plugin. Details about their implementation are shown below.

Coptic | Discworld | Ethiopian | Gregorian | Hebrew | Islamic | Julian | Mayan | Nanakshahi | Nepali | Persian | Taiwan | Thai | Umm al-Qura

Gregorian Calendar

This is the proleptic Gregorian calendar that extends the normal Gregorian calendar back to dates before it was introduced on 15 October 1582 CE. It is the internationally accepted civil calendar. Points to note are:

Taiwan Calendar

This is the Taiwanese calendar, which is identical to the Gregorian calendar except in its year numbering. It is used in the Republic of China (ROC). Points to note are:

Thai Calendar

This is the Thai calendar, which is identical to the Gregorian calendar except in its year numbering. It is used in Thailand. Points to note are:

Julian Calendar

This is the proleptic Julian calendar that extends the normal Julian calendar to dates outside its actual use. It was widely used from 1 AD until 1582 AD when it was replaced by the Gregorian calendar. Points to note are:

Persian Calendar

This is the Persian calendar, also known as the Jalali or Iranian calendar. It is used in Iran, Afganistan, and related societies. Points to note are:

Islamic Calendar

This is the Islamic calendar using the '16 civil' version, also known as the Hijri calendar. It is used in many Muslim countries. Points to note are:

Umm al-Qura Calendar

This is the Umm al-Qura calendar, also known as the Saudi calendar. It is used in many Muslim countries and is very similar to the Islamic calendar. It was written by Amro Osama. Points to note are:

Hebrew Calendar

This is the civil Hebrew calendar. It is used by Jews and followers of Judaism. Points to note are:

Ethiopian Calendar

This is the Ethiopian calendar. It is identical to the Coptic calendar except in its year numbering. It is used in Ethiopia and surrounding countries. Points to note are:

Coptic Calendar

This is the Coptic calendar. It is identical to the Ethiopian calendar except in its year numbering. It is used in Egypt. Points to note are:

Nepali Calendar

This is the Nepali calendar, also known as Vikram Samvat. It is used in Nepal and Northern India. It was written by Artur Neumann. Points to note are:

Nanakshahi Calendar

This is the Nanakshahi calendar, a calendar for the Sikh community. Points to note are:

Mayan Calendar

This is the Mayan Long Count calendar used by the Maya civilization of pre-Columbian Mesoamerica. Points to note are:

Discworld Calendar

This is the Unseen University's Discworld calendar, used in the fictional Discworld in the books by Terry Pratchett. Points to note are:

Plus Module

The plus module adds extra functionality to CDate.

SignatureReturnsComments
formatDate(format, settings) string Format a date into a string representation.

format (string, optional) is the format to apply (see the calendar version for a full description). If not specified, it uses the default format for the calendar.

settings (object, optional) is any additional settings (see the calendar version for a full description).

var f = d.formatDate();
var f = d.formatDate('yyyy-mm-dd');

Since 2.0.2 - added settings.

The plus module adds extra functionality to calendars.

determineDate | formatDate | parseDate

SignatureReturnsComments
formatDate(format, date, settings) string Format a date into a string representation. An error is thrown if the date belongs to a different calendar.

format (string, optional) is the format to apply, consisting of any combination of the specifications below or one of the predefined formats. If not specified, it uses the default format for the calendar.

  • d - day of month (no leading zero)
  • dd - day of month (two digit)
  • o - day of year (no leading zeros)
  • oo - day of year (three digit)
  • D - day name short
  • DD - day name long
  • w - week of year (no leading zero)
  • ww - week of year (two digit)
  • m - month of year (no leading zero)
  • mm - month of year (two digit)
  • M - month name short
  • MM - month name long
  • yy - year (two digit)
  • yyyy - year (four digit)
  • YYYY - formatted year
  • J - Julian date (days since January 1, 4713 BCE Greenwich noon)
  • @ - Unix timestamp (secs since 01/01/1970)
  • ! - Windows ticks (100ns since 01/01/0001)
  • '...' - literal text
  • '' - single quote

date (CDate) is the date to format.

settings (object, optional) is any overrides for the formatting, being an object with the following attributes - all are optional with the current calendar settings being used if they are not present:

    dayNames (string[]) is the full names of the days

    dayNamesShort (string[]) is the abbreviated names of the days

    monthNames (string[]) is the full names of the months

    monthNamesShort (string[]) is the abbreviated names of the months

    calculateWeek (function) is a function to determine the week of the year - it receives a CDate as a parameter and returns a number being the corresponding week

    localNumbers (boolean) is true if localisation of numbers should occur (if available) or false> if standard Arabic numerals are used

var f = gc.formatDate('yyyy-mm-dd', date);
var f = gc.formatDate(
	'\'day\' d \'of\' MM \'in the year\' yyyy', date,
	{monthNames: ['1st month', '2nd month', ...]});

Since 2.0.2 - localNumbers added.
parseDate(format, value, settings) CDate Convert a string representation into an actual date.

format (string) is the format to apply. See the possibilities in the formatDate function, with the following addition:

  • * - ignore the remainder of the value

value (string) is the string to extract the date from.

settings (object, optional) is any overrides for the parsing, being an object with the following attributes - all are optional with the current calendar settings being used if they are not present:

    dayNames (string[]) is the full names of the days

    dayNamesShort (string[]) is the abbreviated names of the days

    monthNames (string[]) is the full names of the months

    monthNamesShort (string[]) is the abbreviated names of the months

    shortYearCutoff (number or string) is the cutoff point for the current or previous century when using the shortened year format; if this is a string it is added to the current year value, e.g. '+10'

var date = gc.parseDate('yyyy-mm-dd', '2009-01-26');
var date = gc.parseDate(
	'\'day\' d \'of\' MM \'in the year\' yyyy',
	'day 26 of 1st month in the year 2009',
	{monthNames: ['1st month', '2nd month', ...]});

Since 1.2.0 - name parsing is case-insensitive.
determineDate(dateSpec, defaultDate, currentDate, dateFormat, settings) CDate Convert multiple representations of a date into an actual date.

dateSpec (CDate) is the date to use or (number) is the offset in days from today or (string) is the date in the current format or (string) is one or more amounts and periods to offset from today. For the last use 'y' for years, 'm' for months, 'w' for weeks, or 'd' for days, e.g. '+1y +1d'. Prefix the value with 'c' to use the currentDate as the starting point instead of today.

defaultDate (CDate) is the date to use if no other is specified. It may be null.

currentDate (CDate, optional) is the current date to base offsets from. Today is used if this is not specified.

dateFormat (string, optional) is the date format to use to check the dateSpec. If not specified, the current format for the calendar is used.

settings (object, optional) is any overrides for the formatting. See the formatDate function for more details.

var date = gc.determineDate(+2);
var date = gc.determineDate('+2y -3w',
	gc.newDate(2001, 1, 1));
var date = gc.determineDate('2004-01-26',
	gc.newDate(2001, 1, 26), 'yyyy-mm-dd');

This module also adds several predefined date formats to the calendars:

NameValueComments
ATOMyyyy-mm-ddRFC 3339/ISO 8601
COOKIED, dd M yyyy
FULLDD, MM d, yyyy
ISO_8601yyyy-mm-dd
JULIANJ
RFC_822D, d M yy
RFC_850DD, dd-M-yy
RFC_1036D, d M yy
RFC_1123D, d M yyyy
RFC_2822D, d M yyyy
RSSD, d M yyRFC 822
TICKS!
TIMESTAMP@
W3Cyyyy-mm-ddISO 8601

Several error messages used during parsing and formatting are added to the global regional settings.

NameTypeDefaultComments
invalidArgumentsstring 'Invalid arguments' The eror message when no date is given to parse.
invalidFormatstring 'Cannot format a date from another calendar' The error message when trying to format a date with a different calendar.
missingNumberAtstring 'Missing number at position {0}' The eror message when an expected number is missing during parsing. '{0}' is the position at which the number was expected.
unknownNameAtstring 'Unknown name at position {0}' The error message when an unknown day or month name is found during parsing. '{0}' is the position at which the name was expected.
unexpectedLiteralAtstring 'Unexpected literal at position {0}' The error message when an unexpected literal value is found during parsing. '{0}' is the position at which the literal was expected.
unexpectedTextstring 'Additional text found at end' The error message when additional text is found at the completion of parsing.