DP_DateExtensions

This static method returns “true” if the passed value is a JavaScript Date object.

Method Signature

Date.is(Input)

Arguments

This method has one argument:

• Input: Any, Required. A JavaScript value.

Return

Boolean. Returns true of the passed value is a JacaScript Date object, false if not.

This static method accepts a date/time mask and a string value. The passed value is first checked against the mask; if it matches then the value is converted to a native JavaScript date object.

When creating the date any ambigious or unsupplied values will use default values (as defined by the Default parameter). Some mask parts (such as “DDD”, “DDDD”, “TT”, etc) are ambigious by nature and will not inform the date creation. They are useful for recognizing the date format however (allowing this function to parse any output of the dateFormat() and timeFormat() functions with no manipulation). Also note that the mask must match the input exactly, including any spaces, for the conversion step to be attempted.

Method Signature

Date.parseFormat(Input, Mask, Default, CenturyMark)

Arguments

This method has three arguments:

• Input: String, Required. A string representing the date you wish to parse.
• Mask: String, Required. A mask representing the date format to convert. All mask characters used by the dateFormat() and timeFormat() functions are accepted:
  • D: The day of the month as a number.
  • DD: The day of the month as a number with, if applicable, a leading zero.
  • DDD: The day of the week as a three-character abbreviation (for example “Tue”).
  • DDDD: The full name of the day of the week (for example “Tuesday”).
  • M: The month as a number.
  • MM: The month as a number with, if applicable, a leading zero.
  • MMM: The month as a three-character abbreviation (for example “Jan”).
  • MMMM: The full name of the month (for example “January”).
  • YY: The last two digits of the year.
  • YYYY: The four-digit year.
  • h: Hours. 12-hour clock.
  • hh: Hours with, if applicable, a leading zero. 12-hour clock.
  • H: Hours. 24-hour clock.
  • HH: Hours with, if applicable, a leading zero. 24-hour clock.
  • m: Minutes.
  • mm: Minutes with, if applicable, a leading zero.
  • s: Seconds.
  • ss: Seconds with, if applicable, a leading zero.
  • l: Milliseconds.
  • t: Produces a single, lowercase character (“a” or “p”) for ante meridiem and post meridiem.
  • tt: Produces a two, lowercase characters (“am” or “pm”) for ante meridiem and post meridiem.
  • T: Produces a single, uppercase character (“A” or “P”) for ante meridiem and post meridiem.
  • TT: Produces a two, uppercase characters (“AM” or “PM”) for ante meridiem and post meridiem.
• Default: Integer, Optional. Defaults to 0. Specifies which values to use as defaults for date parts which are not specified in the specified format.
  • 0: Default. Use JavaScript’s default values (null). This will generally result in values at the beginning of the acceptable date range (for example January 1, 1899).
  • 1: Use the current date/time as default values.
  • 2: Use the current UTC date/time as default values.
• CenturyMark: Integer (0-99), Optional. Defaults to 50. Used when parsing two-digit years. Values less than the CenturyMark will be set as 21st century (2000′s) and values greater than will be set as 20th century (1900′s).

Return

Date or Null. If the passed information can be converted to a date the method returns a native JavaScript date object. If not a null value is returned.

This static method converts compliant ISO 8601 date strings into native JavaScript Date objects. The formats allowed are described in the Date and Time Formats W3C note.

Method Signature

Date.parseIso8601(Input)

Arguments

This method has one argument:

• Input: String, Required. A string representing the date you wish to convert.

Return

Date or Null. If the passed information can be converted to a date the method returns a native JavaScript date object. If not a null value is returned.

This static conveinence method converts HTTP dates (specified in RFC 822) date strings into native JavaScript Date objects. Identical to Date.parseFormat(CurDate, “DDD, D MMM YYYY HH:mm:ss z”).

Method Signature

Date.parseHttpTimeFormat(Input)

Arguments

This method has one argument:

• Input: String, Required. A string representing the date you wish to convert.

Return

Date or Null. If the passed information can be converted to a date the method returns a native JavaScript date object. If not a null value is returned.

Adds a specified number of the specified date units to the date.

Method Signature

DateInstance.add(Amount, DatePart, [Destructive])

Arguments

This method has three arguments:

• Amount: Integer, Required. The number of units by which to modify the date. Positive numbers will result in future dates; negative numbers will result in past dates.
• DatePart: String, Required. The unit to add to the date. The following date parts are supported:
  • milliseconds: Milliseconds.
  • seconds: Seconds.
  • minutes: Minutes.
  • quarterhours: 15 minutes.
  • warhols: 15 minutes (of fame).
  • halfhours: 30 minutes.
  • hours: Hours.
  • days: Days.
  • weeks: Weeks (periods of 7 days).
  • businessdays: Days excluding Saturday and Sunday. Note that holidays are NOT considered.
  • businessweeks: Business weeks (periods of 5 business days).
  • wholeweeks: Weeks from Sunday to Saturday. Essentially the current date will be moved to the next Sunday, then the week(s) specified will be added.
  • months: Months. The date (day of month) may change (to the last day of the new month) if months have an incompatible number of days. For example adding one month to March 31 will result in April 30.
  • years: Years. If the date is February 29th (a leap year) it may be changed to February 28th if the resulting year is not a leap year.
• Destructive: Boolean, Optional. Defaults to false. If false (the default) the method will return a new date object with the results; if true the method will update the date in place and return a reference to the original date.

Return

Date.

Does a comparison of two dates to an optionally specified precision.

Method Signature

DateInstance.compare(Date, [Precision])

Arguments

This method has two arguments:

• Date: Date, Required. The date to compare.
• Precision: String, Optional. Defaults to “millisecond”. Acceptable values are:
  • millisecond: (The default.) Comparison precise to the millisecond.
  • second: Comparison precise to the second.
  • minute: Comparison precise to the minute.
  • hour: Comparison precise to the hour.
  • day: Comparison precise to the day.
  • month: Comparison precise to the month.
  • year: Comparison precise to the year.

Return

Integer. The method returns zero (“0″) if the dates are equal, negative one (“-1″) if the original date falls prior to the passed date or positive one (“1″) if the original date falls after the passed date.

Formats a date using a supplied format mask.

Method Signature

DateInstance.dateFormat(Mask)

Arguments

This method has one argument:

• Mask: String, Required. The mask to apply to the date. The following case-sensitive mask values are supported:
  • D: The day of the month as a number.
  • DD: The day of the month as a number with, if applicable, a leading zero.
  • DDD: The day of the week as a three-character abbreviation (for example “Tue”).
  • DDDD: The full name of the day of the week (for example “Tuesday”).
  • M: The month as a number.
  • MM: The month as a number with, if applicable, a leading zero.
  • MMM: The month as a three-character abbreviation (for example “Jan”).
  • MMMM: The full name of the month (for example “January”).
  • YY: The last two digits of the year.
  • YYYY: The four-digit year.

  In addition the following case-sensitive short-hand values are also acceptable:

  • short: Identical to “M/D/YY”.
  • medium: Identical to “MMM D, YYYY”.
  • long: Identical to “MMMM D, YYYY”.
  • full: Identical to “DDDD, MMMM D, YYYY”.

  These short-hand values cannot be mixed with other mask values.

Return

String. The formatted date as described by the specified mask.

This function returns the ordinal day of the year.

Method Signature

DateInstance.dayOfYear()

Arguments

This method has no arguments:

Return

Integer. The day of year (1-366).

Returns the number of specified date units between two dates.

Method Signature

DateInstance.diff(Date, DatePart)

Arguments

This method has two arguments:

• Date: Date, Required. The date to calculate the difference from.
• DatePart: String, Required. The kind of unit to count. The following date parts are supported:
  • milliseconds: Milliseconds.
  • seconds: Seconds.
  • minutes: Minutes.
  • quarterhours: 15 minutes.
  • warhols: 15 minutes (of fame).
  • halfhours: 30 minutes.
  • hours: Hours.
  • days: Days.
  • weeks: Weeks (periods of 7 days).
  • businessdays: Days excluding Saturday and Sunday. Note that holidays are NOT considered.
  • businessweeks: Business weeks (periods of 5 business days).
  • wholeweeks: Weeks from Sunday to Saturday. Only whole weeks will be counted.
  • months: Months.
  • years: Years.

Return

Integer. The number of whole units between the two dates (no fractions will be returned).

A convenience method which generates HTTP dates (specified in RFC 822) for output. For example “Sun, 13 May 2007 18:05:45 -0400″.

Method Signature

DateInstance.httpTimeFormat(isUTC)

Arguments

This method has one argument:

• isUTC: Boolean, Optional. Defaults to “false”. Pass “true” if the datetime is UTC, “false” if the datetime is local time.

Return

String. An date formatted accorded to RFC 822.

Returns true if the datetime falls within a Leap Year.

Method Signature

DateInstance.isLeapYear()

Arguments

This method has no arguments:

Return

Boolean. True if the datetime is within a Leap Year, false if not.

Returns true if the datetime falls on a weekday (monday through friday, inclusive).

Method Signature

DateInstance.isWeekday()

Arguments

This method has no arguments:

Return

Boolean. True if the datetime falls on a weekday, false if not.

A convenience method which generates ISO 8601 formatted dates for output.

Method Signature

DateInstance.iso8601Format(Style, [isUTC])

Arguments

This method has two arguments:

• Style: String, Optional. Defaults to “YMDHMSM”. The style of the date to be output. Can be any of the following:
  • Y or 1: “Year”. Equivalent to dateFormat(“yyyy”).
  • YM or 2: “Year and Month”. Equivalent to dateFormat(“yyyy-mm”).
  • YMD or 3: “Year, Month and Day”. Equivalent to dateFormat(“yyyy-mm-dd”).
  • YMDHM or 4: “Year, Month, Day, Hours and Minutes”. Equivalent to dateFormat(“yyyy-mm-dd”) + “T” + timeFormat(“HH:mm”) plus timezone information.
  • YMDHMS or 5: “Year, Month, Day, Hours, Minutes and Seconds”. Equivalent to dateFormat(“yyyy-mm-dd”) + “T” + timeFormat(“HH:mm:ss”) plus timezone information.
  • YMDHMSM or 6: “Year, Month, Day, Hours, Minutes, Seconds and Milliseconds”. Equivalent to dateFormat(“yyyy-mm-dd”) + “T” + timeFormat(“HH:mm:ss.l”) plus timezone information.
• isUTC: Boolean, Optional. Default to “false”. Specifies if the date is to be treated as a UTC date or not. If “true” the UTC indicator will be appended to the dates with time values, if “false” timezone information will be appended to dates with time values.

Return

String. An ISO 8601 formatted date.

Formats the time portion of a date using a supplied mask.

Method Signature

DateInstance.timeFormat(Mask)

Arguments

This method has one argument:

• Mask: String, Required. The mask to apply to the time. The following case-sensitive mask values are supported:
  • h: Hours. 12-hour clock.
  • hh: Hours with, if applicable, a leading zero. 12-hour clock.
  • H: Hours. 24-hour clock.
  • HH: Hours with, if applicable, a leading zero. 24-hour clock.
  • m: Minutes.
  • mm: Minutes with, if applicable, a leading zero.
  • s: Seconds.
  • ss: Seconds with, if applicable, a leading zero.
  • l: Milliseconds.
  • t: Produces a single, lowercase character (“a” or “p”) for ante meridiem and post meridiem.
  • tt: Produces a two, lowercase characters (“am” or “pm”) for ante meridiem and post meridiem.
  • T: Produces a single, uppercase character (“A” or “P”) for ante meridiem and post meridiem.
  • TT: Produces a two, uppercase characters (“AM” or “PM”) for ante meridiem and post meridiem.

  In addition the following case-sensitive short-hand values are also acceptable:

  • short: Identical to “h:mm tt”.
  • medium: Identical to “h:mm:ss tt”.
  • long: Identical to “h:mm:ss.l tt”.
  • full: Identical to “long” (reserved).

  These short-hand values cannot be mixed with other mask values.

Return

String. The formatted date as described by the specified mask.

Returns the week of year on which the datetime falls, from 1 to 52.

Method Signature

DateInstance.weekOfYear()

Arguments

This method has no arguments:

Return

Integer. The week of the year.