Class ilib.Date

Construct a new date object. Each parameter is a numeric value, but its accepted range can vary depending on the subclass of this date. For example, Gregorian months can be from 1 to 12, whereas months in the Hebrew calendar can be from 1 to 13.

Note that this really calls the newInstance factory method underneath in order to instantiate the correct subclass of ilib.Date. Depends directive: !depends date.js
Defined in: ilib-dyn-full.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	ilib.Date(options)

Method Summary
Method Attributes	Method Name and Description
	after(dow) Return a new date instance in the current calendar that represents the first instance of the given day of the week after the current date.
	before(dow) Return a new date instance in the current calendar that represents the first instance of the given day of the week before the current date.
	firstSunday(year) Return the rd number of the first Sunday of the given ISO year.
	getJSDate() Return a Javascript Date object that is equivalent to this date object.
	getJulianDay() Return the Julian Day equivalent to this calendar date as a number.
	getRataDie() Return the Rata Die (fixed day) number of this date.
	getTime() Return the unix time equivalent to this date instance.
	getTimeExtended() Return the extended unix time equivalent to this Gregorian date instance.
	getTimeZone() Return the time zone associated with this date, or undefined if none was specified in the constructor.
	getWeekOfMonth(locale) Return the ordinal number of the week within the month.
	getWeekOfYear() Return the ISO 8601 week number in the current year for the current date.
<static>	ilib.Date.initAstro(sync, loadParams, callback) Load in all the data needed for astrological calculations.
<static>	ilib.Date.newInstance(options) Factory method to create a new instance of a date subclass.
	onOrAfter(dow) Return a new Gregorian date instance that represents the first instance of the given day of the week on or after the current date.
	onOrBefore(dow) Return a new Gregorian date instance that represents the first instance of the given day of the week on or before the current date.
	setJulianDay(date) Set the date of this instance using a Julian Day.
	setRd(rd) Set the date components of this instance based on the given rd.
	setTime(millis) Set the time of this instance according to the given unix time.
	setTimeZone(tzName) Set the time zone associated with this date.

Class Detail

ilib.Date(options)

Parameters:
{Object=} options: The date components to initialize this date with

Method Detail

{ilib.Date} after(dow)

Return a new date instance in the current calendar that represents the first instance of the given day of the week after the current date. The day of the week is encoded as a number where 0 = Sunday, 1 = Monday, etc.

Parameters:
{number} dow: the day of the week after the current date that is being sought

Returns:: {ilib.Date} the date being sought

{ilib.Date} before(dow)

Return a new date instance in the current calendar that represents the first instance of the given day of the week before the current date. The day of the week is encoded as a number where 0 = Sunday, 1 = Monday, etc.

Parameters:
{number} dow: the day of the week before the current date that is being sought

Returns:: {ilib.Date} the date being sought

{number} firstSunday(year)

Return the rd number of the first Sunday of the given ISO year.

Parameters:
{number} year: the year for which the first Sunday is being sought

Returns:: {number} the rd of the first Sunday of the ISO year

{Date|undefined} getJSDate()

Return a Javascript Date object that is equivalent to this date object.

Returns:: {Date|undefined} a javascript Date object

{number} getJulianDay()

Return the Julian Day equivalent to this calendar date as a number.

Returns:: {number} the julian date equivalent of this date

{number} getRataDie()

Return the Rata Die (fixed day) number of this date.

Returns:: {number} the rd date as a number

{number} getTime()

Return the unix time equivalent to this date instance. Unix time is the number of milliseconds since midnight on Jan 1, 1970 UTC (Gregorian). This method only returns a valid number for dates between midnight, Jan 1, 1970 UTC (Gregorian) and Jan 19, 2038 at 3:14:07am UTC (Gregorian) when the unix time runs out. If this instance encodes a date outside of that range, this method will return -1. For date types that are not Gregorian, the point in time represented by this date object will only give a return value if it is in the correct range in the Gregorian calendar as given previously.

Returns:: {number} a number giving the unix time, or -1 if the date is outside the valid unix time range

{number} getTimeExtended()

Return the extended unix time equivalent to this Gregorian date instance. Unix time is the number of milliseconds since midnight on Jan 1, 1970 UTC. Traditionally unix time (or the type "time_t" in C/C++) is only encoded with an unsigned 32 bit integer, and thus runs out on Jan 19, 2038. However, most Javascript engines encode numbers well above 32 bits and the Date object allows you to encode up to 100 million days worth of time after Jan 1, 1970, and even more interestingly, 100 million days worth of time before Jan 1, 1970 as well. This method returns the number of milliseconds in that extended range. If this instance encodes a date outside of that range, this method will return NaN.

Returns:: {number} a number giving the extended unix time, or Nan if the date is outside the valid extended unix time range

{string|undefined} getTimeZone()

Return the time zone associated with this date, or undefined if none was specified in the constructor.

Returns:: {string|undefined} the name of the time zone for this date instance

{number} getWeekOfMonth(locale)

Return the ordinal number of the week within the month. The first week of a month is the first one that contains 4 or more days in that month. If any days precede this first week, they are marked as being in week 0. This function returns values from 0 through 6.

The locale is a required parameter because different locales that use the same Gregorian calendar consider different days of the week to be the beginning of the week. This can affect the week of the month in which some days are located.

Parameters:
{ilib.Locale|string} locale: the locale or locale spec to use when figuring out the first day of the week

Returns:: {number} the ordinal number of the week within the current month

{number} getWeekOfYear()

Return the ISO 8601 week number in the current year for the current date. The week number ranges from 0 to 55, as some years have 55 weeks assigned to them in some calendars.

Returns:: {number} the week number for the current date

<static> ilib.Date.initAstro(sync, loadParams, callback)

Load in all the data needed for astrological calculations.

Parameters:
{boolean} sync
{*} loadParams
{function(*)|undefined} callback

<static> {ilib.Date} ilib.Date.newInstance(options)

Factory method to create a new instance of a date subclass.

The options parameter can be an object that contains the following properties:

type - specify the type/calendar of the date desired. The list of valid values changes depending on which calendars are defined. When assembling your iliball.js, include those date type you wish to use in your program or web page, and they will register themselves with this factory method. The "gregorian", and "julian" calendars are all included by default, as they are the standard calendars for much of the world. If not specified, the type of the date returned is the one that is appropriate for the locale. This property may also be given as "calendar" instead of "type".

The options object is also passed down to the date constructor, and thus can contain the the properties as the date object being instantiated. See the documentation for ilib.Date.GregDate, and other subclasses for more details on other parameter that may be passed in.

Please note that if you do not give the type parameter, this factory method will create a date object that is appropriate for the calendar that is most commonly used in the specified or current ilib locale. For example, in Thailand, the most common calendar is the Thai solar calendar. If the current locale is "th-TH" (Thai for Thailand) and you use this factory method to construct a new date without specifying the type, it will automatically give you back an instance of ilib.Date.ThaiSolarDate. This is convenient because you do not need to know which locales use which types of dates. In fact, you should always use this factory method to make new date instances unless you know that you specifically need a date in a particular calendar.

Also note that when you pass in the date components such as year, month, day, etc., these components should be appropriate for the given date being instantiated. That is, in our Thai example in the previous paragraph, the year and such should be given as a Thai solar year, not the Gregorian year that you get from the Javascript Date class. In order to initialize a date instance when you don't know what subclass will be instantiated for the locale, use a parameter such as "unixtime" or "julianday" which are unambiguous and based on UTC time, instead of the year/month/date date components. The date components for that UTC time will be calculated and the time zone offset will be automatically factored in.

Parameters:
{Object=} options: options controlling the construction of this instance, or undefined to use the default options

Returns:: {ilib.Date} an instance of a calendar object of the appropriate type

{ilib.Date} onOrAfter(dow)

Return a new Gregorian date instance that represents the first instance of the given day of the week on or after the current date. The day of the week is encoded as a number where 0 = Sunday, 1 = Monday, etc.

Parameters:
{number} dow: the day of the week on or after the current date that is being sought

Returns:: {ilib.Date} the date being sought

{ilib.Date} onOrBefore(dow)

Return a new Gregorian date instance that represents the first instance of the given day of the week on or before the current date. The day of the week is encoded as a number where 0 = Sunday, 1 = Monday, etc.

Parameters:
{number} dow: the day of the week on or before the current date that is being sought

Returns:: {ilib.Date} the date being sought

setJulianDay(date)

Set the date of this instance using a Julian Day.

Parameters:
{number|ilib.JulianDay} date: the Julian Day to use to set this date

setRd(rd)

Set the date components of this instance based on the given rd.

Parameters:
{number} rd: the rata die date to set

setTime(millis)

Set the time of this instance according to the given unix time. Unix time is the number of milliseconds since midnight on Jan 1, 1970.

Parameters:
{number} millis: the unix time to set this date to in milliseconds

setTimeZone(tzName)

Set the time zone associated with this date.

Parameters:
{string=} tzName: the name of the time zone to set into this date instance, or "undefined" to unset the time zone

Classes

Class ilib.Date