Interface Date

Index

Methods

Methods

public addDays(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public addHours(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public addMilliseconds(num: number, reset?: boolean): Date

Adds of the unit to the date. If [reset] is true, all lower units will be reset.

method

addUnits

extra

Note that "months" is ambiguous as a unit of time. If the target date falls on a day that does not exist (ie. August 31 -> February 31), the date will be shifted to the last day of the month. Don't use %addMonths% if you need precision.

set

addMilliseconds addSeconds addMinutes addHours addDays addWeeks addMonths addYears

example

Date.create().addMilliseconds(5) -> current time + 5 milliseconds Date.create().addDays(5) -> current time + 5 days Date.create().addYears(5) -> current time + 5 years

Parameters

  • num: number

    Add this many [Units] to the date.

  • reset?: boolean optional

    If true lower units will be reset.

Returns

Date

Date

public addMinutes(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public addMonths(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public addSeconds(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public addWeeks(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public addYears(num: number, reset?: boolean): Date

see

addMilliseconds

Parameters

  • num: number
  • reset?: boolean optional

Returns

Date

public advance(set: string, reset?: boolean): Date

Sets the date forward.

method

advance(, [reset] = false)

extra

This method can accept multiple formats including an object, a string in the format %3 days%, a single number as milliseconds, or enumerated parameters (as with the Date constructor). If [reset] is %true%, any units more specific than those passed will be reset. For more see @date_format.

example

new Date().advance({ year: 2 }) -> 2 years in the future new Date().advance('2 days') -> 2 days in the future new Date().advance(0, 2, 3) -> 2 months 3 days in the future new Date().advance(86400000) -> 1 day in the future

Parameters

  • set: string

    Human readable amount of time to advance the date.

  • reset?: boolean optional

    If true resets the lower date fields to zero.

Returns

Date

Date

public advance(year: number, month: number, day: number, reset?: boolean): Date

see

advance

Parameters

  • year: number

    YYYY to advance.

  • month: number

    MM to advance.

  • day: number

    DD to advance.

  • reset?: boolean optional

Returns

Date

public advance(milliseconds: number, reset?: boolean): Date

see

advance

Parameters

  • milliseconds: number

    Milliseconds to advance the date.

  • reset?: boolean optional

Returns

Date

public advance(set: DateFields, reset?: boolean): Date

see

advance

Parameters

  • set: DateFields

    Advance the year/month/day of the date from a single object.

  • reset?: boolean optional

Returns

Date

public beginningOfDay(): Date

Sets the date to the beginning of the appropriate unit.

method

beginningOfUnit

set

beginningOfDay beginningOfWeek beginningOfMonth beginningOfYear

example

Date.create().beginningOfDay() -> the beginning of today (resets the time) Date.create().beginningOfWeek() -> the beginning of the week Date.create().beginningOfMonth() -> the beginning of the month Date.create().beginningOfYear() -> the beginning of the year

Returns

Date

Date

public beginningOfMonth(): Date

Returns

Date

public beginningOfWeek(): Date

Returns

Date

public beginningOfYear(): Date

Returns

Date

public clone(): Date

Clones the date.

method

clone()

example

Date.create().clone() -> Copy of now

Returns

Date

Date

public daysAgo(): number

Returns

number

public daysFromNow(): number

Returns

number

public daysInMonth(): number

Returns the number of days in the date's month.

method

daysInMonth()

example

Date.create('May').daysInMonth() -> 31 Date.create('February, 2000').daysInMonth() -> 29

Returns

number

Number

public daysSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public daysSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public daysUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public daysUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public endOfDay(): Date

Sets the date to the end of the appropriate unit.

method

endOfUnit

set

endOfDay endOfWeek endOfMonth endOfYear

example

Date.create().endOfDay() -> the end of today (sets the time to 23:59:59.999) Date.create().endOfWeek() -> the end of the week Date.create().endOfMonth() -> the end of the month Date.create().endOfYear() -> the end of the year

Returns

Date

Date

public endOfMonth(): Date

Returns

Date

public endOfWeek(): Date

Returns

Date

public endOfYear(): Date

Returns

Date

public format(format: string, locale?: string): string

Formats and outputs the date.

method

format(, [locale] = currentLocale)

extra

can be a number of pre-determined formats or a string of tokens. Locale-specific formats are %short%, %long%, and %full% which have their own aliases and can be called with %date.short()%, etc. If is not specified the %long% format is assumed. [locale] specifies a locale code to use (if not specified the current locale is used). See @date_format for more details.

set

short long full

example

Date.create().format() -> ex. July 4, 2003 Date.create().format('{Weekday} {d} {Month}, {yyyy}') -> ex. Monday July 4, 2003 Date.create().format('{hh}:{mm}') -> ex. 15:57 Date.create().format('{12hr}:{mm}{tt}') -> ex. 3:57pm Date.create().format(Date.ISO8601_DATETIME) -> ex. 2011-07-05 12:24:55.528Z Date.create('last week').format('short', 'ja') -> ex. ?? Date.create('yesterday').format(function(value,unit,ms,loc) { // value = 1, unit = 3, ms = -86400000, loc = [current locale object] }); -> ex. 1 day ago

Parameters

  • format: string
  • locale?: string optional

Returns

string

String

public full(locale?: string): string

Parameters

  • locale?: string optional

Returns

string

public getISOWeek(): number

Gets the date's week (of the year).

extra

If %utc% is set on the date, the week will be according to UTC time.

example

new Date().getWeek() -> today's week of the year

Returns

number

The date's week of the year as defined by the ISO-8601 standard.

public getUTCOffset(iso?: boolean): string

Returns a string representation of the offset from UTC time. If [iso] is true the offset will be in ISO8601 format.

method

getUTCOffset([iso])

example

new Date().getUTCOffset() -> "+0900" new Date().getUTCOffset(true) -> "+09:00"

Parameters

  • iso?: boolean optional

Returns

string

String

public getUTCWeekday(): number

Returns

number

public getWeekday(): number

Alias for %getDay%.

method

getWeekday()

set

getUTCWeekday

example

Date.create().getWeekday(); -> (ex.) 3 Date.create().getUTCWeekday(); -> (ex.) 3

Returns

number

Number

public hoursAgo(): number

Returns

number

public hoursFromNow(): number

Returns

number

public hoursSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public hoursSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public hoursUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public hoursUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public is(d: string, margin?: number): boolean

Returns true if the date is .

method

is(, [margin] = 0)

extra

will accept a date object, timestamp, or text format. %is% additionally understands more generalized expressions like month/weekday names, 'today', etc, and compares to the precision implied in . [margin] allows an extra margin of error in milliseconds. For more, see @date_format.

example

Date.create().is('July') -> true or false? Date.create().is('1776') -> false Date.create().is('today') -> true Date.create().is('weekday') -> true or false? Date.create().is('July 4, 1776') -> false Date.create().is(-6106093200000) -> false Date.create().is(new Date(1776, 6, 4)) -> false

Parameters

  • d: string
  • margin?: number optional

Returns

boolean

Boolean

public is(milliseconds: number, margin?: number): boolean

Parameters

  • milliseconds: number
  • margin?: number optional

Returns

boolean

public is(d: Date, margin?: number): boolean

Parameters

  • d: Date
  • margin?: number optional

Returns

boolean

public isAfter(d: string, margin?: number): boolean

Returns true if the date is after the .

method

isAfter(, [margin] = 0)

extra

[margin] is to allow extra margin of error (in ms). will accept a date object, timestamp, or text format. If not specified, is assumed to be now. See @date_format for more.

example

new Date().isAfter('tomorrow') -> false new Date().isAfter('yesterday') -> true

Parameters

  • d: string
  • margin?: number optional

Returns

boolean

Boolean

public isAfter(milliseconds: number, margin?: number): boolean

Parameters

  • milliseconds: number
  • margin?: number optional

Returns

boolean

public isAfter(d: Date, margin?: number): boolean

Parameters

  • d: Date
  • margin?: number optional

Returns

boolean

public isBefore(d: string, margin?: number): boolean

Returns true if the date is before .

method

isBefore(, [margin] = 0)

extra

[margin] is to allow extra margin of error (in ms). will accept a date object, timestamp, or text format. If not specified, is assumed to be now. See @date_format for more.

example

new Date().isBefore('tomorrow') -> true new Date().isBefore('yesterday') -> false

Parameters

  • d: string
  • margin?: number optional

Returns

boolean

Boolean

public isBefore(milliseconds: number, margin?: number): boolean

Parameters

  • milliseconds: number
  • margin?: number optional

Returns

boolean

public isBefore(d: Date, margin?: number): boolean

Parameters

  • d: Date
  • margin?: number optional

Returns

boolean

public isBefore(start: string, end: string, margin?: number): boolean

Returns true if the date falls between and .

method

isBetween(, , [margin] = 0)

extra

[margin] is to allow extra margin of error (in ms). and will accept a date object, timestamp, or text format. If not specified, they are assumed to be now. See @date_format for more.

example

new Date().isBetween('yesterday', 'tomorrow') -> true new Date().isBetween('last year', '2 years ago') -> false

Parameters

  • start: string
  • end: string
  • margin?: number optional

Returns

boolean

Boolean

public isBefore(start: number, end: string, margin?: number): boolean

Parameters

  • start: number
  • end: string
  • margin?: number optional

Returns

boolean

public isBefore(start: Date, end: Date, margin?: number): boolean

Parameters

  • start: Date
  • end: Date
  • margin?: number optional

Returns

boolean

public isFriday(): boolean

Returns

boolean

public isFuture(): boolean

Returns true if the date is in the future.

method

isFuture()

example

Date.create('next week').isFuture() -> true Date.create('last week').isFuture() -> false

Returns

boolean

Boolean

public isLastMonth(): boolean

Returns

boolean

public isLastWeek(): boolean

Returns true if the date is last week/month/year.

method

isLastUnit

set

isLastWeek isLastMonth isLastYear

example

Date.create('yesterday').isLastWeek() -> true or false? Date.create('yesterday').isLastMonth() -> probably not... Date.create('yesterday').isLastYear() -> even less likely...

Returns

boolean

Boolean

public isLastYear(): boolean

Returns

boolean

public isLeapYear(): boolean

Returns true if the date is a leap year.

method

isLeapYear()

example

Date.create('2000').isLeapYear() -> true

Returns

boolean

Boolean

public isMonday(): boolean

Returns

boolean

public isNextMonth(): boolean

Returns

boolean

public isNextWeek(): boolean

Returns true if the date is next week/month/year.

method

isNextUnit

set

isNextWeek isNextMonth isNextYear

example

Date.create('tomorrow').isNextWeek() -> true or false? Date.create('tomorrow').isNextMonth() -> probably not... Date.create('tomorrow').isNextYear() -> even less likely...

Returns

boolean

Boolean

public isNextYear(): boolean

Returns

boolean

public isPast(): boolean

Returns true if the date is in the past.

method

isPast()

example

Date.create('last week').isPast() -> true Date.create('next week').isPast() -> false

Returns

boolean

Boolean

public isSaturday(): boolean

Returns

boolean

public isSunday(): boolean

Returns

boolean

public isThisMonth(): boolean

Returns

boolean

public isThisWeek(): boolean

Returns true if the date is this week/month/year.

method

isThisUnit

set

isThisWeek isThisMonth isThisYear

example

Date.create('tomorrow').isThisWeek() -> true or false? Date.create('tomorrow').isThisMonth() -> probably... Date.create('tomorrow').isThisYear() -> signs point to yes...

Returns

boolean

Boolean

public isThisYear(): boolean

Returns

boolean

public isThursday(): boolean

Returns

boolean

public isToday(): boolean

Returns true if the date falls on that day.

method

isDay

extra

Also available: %isYesterday%, %isToday%, %isTomorrow%, %isWeekday%, and %isWeekend%.

set

isToday isYesterday isTomorrow isWeekday isWeekend isSunday isMonday isTuesday isWednesday isThursday isFriday isSaturday

example

Date.create('tomorrow').isToday() -> false Date.create('thursday').isTomorrow() -> ? Date.create('yesterday').isWednesday() -> ? Date.create('today').isWeekend() -> ?

Returns

boolean

Boolean

public isTomorrow(): boolean

Returns

boolean

public isTuesday(): boolean

Returns

boolean

public isUTC(): boolean

Returns true if the date has no timezone offset.

method

isUTC()

extra

This will also return true for a date that has had %toUTC% called on it. This is intended to help approximate shifting timezones which is not possible in client-side Javascript. Note that the native method %getTimezoneOffset% will always report the same thing, even if %isUTC% becomes true.

example

new Date().isUTC() -> true or false? new Date().toUTC().isUTC() -> true

Returns

boolean

Boolean

public isValid(): boolean

Returns true if the date is valid.

method

isValid()

example

new Date().isValid() -> true new Date('flexor').isValid() -> false

Returns

boolean

Boolean

public isWednesday(): boolean

Returns

boolean

public isWeekday(): boolean

Returns

boolean

public isWeekend(): boolean

Returns

boolean

public isYesterday(): boolean

Returns

boolean

public iso(): string

method

iso()

method

toISOString()

extra

This will always format as UTC time. Provided for browsers that do not support this method.

example

Date.create().toISOString() -> ex. 2011-07-05 12:24:55.528Z

Returns

string

String Formats the string to ISO8601 format.

public long(locale?: string): string

Parameters

  • locale?: string optional

Returns

string

public millisecondsAgo(): number

Returns the time ago in the appropriate unit.

method

[units]Ago()

set

millisecondsAgo secondsAgo minutesAgo hoursAgo daysAgo weeksAgo monthsAgo yearsAgo

example

Date.create('last year').millisecondsAgo() -> 3,600,000 Date.create('last year').daysAgo() -> 7 Date.create('last year').yearsAgo() -> 15

Returns

number

Number

public millisecondsFromNow(): number

Returns the time from now in the appropriate unit.

method

[units]FromNow()

set

millisecondsFromNow secondsFromNow minutesFromNow hoursFromNow daysFromNow weeksFromNow monthsFromNow yearsFromNow

example

Date.create('next year').millisecondsFromNow() -> 3,600,000 Date.create('next year').daysFromNow() -> 7 Date.create('next year').yearsFromNow() -> 15

Returns

number

Number

public millisecondsSince(date?: Date, locale?: string): number

Returns the time since [d] in the appropriate unit.

method

[units]Since([d], [locale] = currentLocale)

extra

[d] will accept a date object, timestamp, or text format. If not specified, [d] is assumed to be now. [locale] can be passed to specify the locale that the date is in. %[unit]Ago% is provided as an alias to make this more readable when [d] is assumed to be the current date. For more see @date_format.

set

millisecondsSince secondsSince minutesSince hoursSince daysSince weeksSince monthsSince yearsSince

example

Date.create().millisecondsSince('1 hour ago') -> 3,600,000 Date.create().daysSince('1 week ago') -> 7 Date.create().yearsSince('15 years ago') -> 15 Date.create('15 years ago').yearsAgo() -> 15

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

Number

public millisecondsSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public millisecondsUntil(date?: Date, locale?: string): number

Returns the time until [d] in the appropriate unit.

method

[units]Until([d], [locale] = currentLocale)

extra

[d] will accept a date object, timestamp, or text format. If not specified, [d] is assumed to be now. [locale] can be passed to specify the locale that the date is in. %[unit]FromNow% is provided as an alias to make this more readable when [d] is assumed to be the current date. For more see @date_format.

set

millisecondsUntil secondsUntil minutesUntil hoursUntil daysUntil weeksUntil monthsUntil yearsUntil

example

Date.create().millisecondsUntil('1 hour from now') -> 3,600,000 Date.create().daysUntil('1 week from now') -> 7 Date.create().yearsUntil('15 years from now') -> 15 Date.create('15 years from now').yearsFromNow() -> 15

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

Number

public millisecondsUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public minutesAgo(): number

Returns

number

public minutesFromNow(): number

Returns

number

public minutesSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public minutesSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public minutesUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public minutesUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public monthsAgo(): number

Returns

number

public monthsFromNow(): number

Returns

number

public monthsSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public monthsSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public monthsUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public monthsUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public relative(locale: string): string

Returns a relative date string offset to the current time.

method

relative([fn], [locale] = currentLocale)

extra

[fn] can be passed to provide for more granular control over the resulting string. [fn] is passed 4 arguments: the adjusted value, unit, offset in milliseconds, and a localization object. As an alternate syntax, [locale] can also be passed as the first (and only) parameter. For more, see @date_format.

example

Date.create('90 seconds ago').relative() -> 1 minute ago Date.create('January').relative() -> ex. 5 months ago Date.create('January').relative('ja') -> 3??? Date.create('120 minutes ago').relative(function(val,unit,ms,loc) { // value = 2, unit = 3, ms = -7200, loc = [current locale object] }); -> ex. 5 months ago

Parameters

  • locale: string

Returns

string

String

public relative(fn?: (value: number, unit: string, ms: number, loc: Locale) => string, locale?: string): string

Parameters

  • fn?: (value: number, unit: string, ms: number, loc: Locale) => string optional
  • locale?: string optional

Returns

string

public reset(unit?: string): Date

Resets the unit passed and all smaller units. Default is "hours", effectively resetting the time.

method

reset([unit] = 'hours')

example

Date.create().reset('day') -> Beginning of today Date.create().reset('month') -> 1st of the month

Parameters

  • unit?: string optional

Returns

Date

Date

public rewind(ms: number, reset?: boolean): Date

Sets the date back.

method

rewind(, [reset] = false)

extra

This method can accept multiple formats including a single number as a timestamp, an object, or enumerated parameters (as with the Date constructor). If [reset] is %true%, any units more specific than those passed will be reset. For more see @date_format.

example

new Date().rewind({ year: 2 }) -> 2 years in the past new Date().rewind(0, 2, 3) -> 2 months 3 days in the past new Date().rewind(86400000) -> 1 day in the past

Parameters

  • ms: number
  • reset?: boolean optional

Returns

Date

Date

public rewind(year: number, month: number, day: number, reset?: boolean): Date

Parameters

  • year: number
  • month: number
  • day: number
  • reset?: boolean optional

Returns

Date

public rewind(d: DateFields, reset?: boolean): Date

Parameters

Returns

Date

public secondsAgo(): number

Returns

number

public secondsFromNow(): number

Returns

number

public secondsSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public secondsSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public secondsUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public secondsUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public set(ms: number): Date

Sets the date object.

method

set(, [reset] = false)

extra

This method can accept multiple formats including a single number as a timestamp, an object, or enumerated parameters (as with the Date constructor). If [reset] is %true%, any units more specific than those passed will be reset.

example

new Date().set({ year: 2011, month: 11, day: 31 }) -> December 31, 2011 new Date().set(2011, 11, 31) -> December 31, 2011 new Date().set(86400000) -> 1 day after Jan 1, 1970 new Date().set({ year: 2004, month: 6 }, true) -> June 1, 2004, 00:00:00.000

Parameters

  • ms: number

Returns

Date

Date

public set(year: number, month: number, day: number): Date

Parameters

  • year: number
  • month: number
  • day: number

Returns

Date

public set(d: DateFields, reset?: boolean): Date

Parameters

Returns

Date

public setISOWeek(week: number)

Sets the week (of the year).

example

d = new Date(); d.setWeek(15); d; -> 15th week of the year

Parameters

  • week: number

public setWeekday(day: number)

Sets the weekday of the date.

method

setWeekday()

example

d = new Date(); d.setWeekday(1); d; -> Monday of this week d = new Date(); d.setWeekday(6); d; -> Saturday of this week

Parameters

  • day: number

public short(locale?: string): string

Parameters

  • locale?: string optional

Returns

string

public toJSON(): string

Returns a JSON representation of the date.

method

toJSON()

extra

This is effectively an alias for %toISOString%. Will always return the date in UTC time. Provided for browsers that do not support this method.

example

Date.create().toJSON() -> ex. 2011-07-05 12:24:55.528Z

Returns

string

String

public utc(on?: boolean): Date

Sets the internal utc flag for the date. When on, UTC-based methods will be called internally.

method

utc([on] = true)

extra

For more see @date_format.

example

new Date().utc(true) new Date().utc(false)

Parameters

  • on?: boolean optional

Returns

Date

Date

public weeksAgo(): number

Returns

number

public weeksFromNow(): number

Returns

number

public weeksSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public weeksSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public weeksUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public weeksUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public yearsAgo(): number

Returns

number

public yearsFromNow(): number

Returns

number

public yearsSince(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public yearsSince(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number

public yearsUntil(date?: Date, locale?: string): number

Parameters

  • date?: Date optional
  • locale?: string optional

Returns

number

public yearsUntil(date: string, locale?: string): number

Parameters

  • date: string
  • locale?: string optional

Returns

number