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.
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?: booleanoptional
If true lower units will be reset.
Returns
Date
Date
public addMinutes(num: number, reset?: boolean): Date
see
addMilliseconds
Parameters
num: number
reset?: booleanoptional
Returns
Date
public addMonths(num: number, reset?: boolean): Date
see
addMilliseconds
Parameters
num: number
reset?: booleanoptional
Returns
Date
public addSeconds(num: number, reset?: boolean): Date
see
addMilliseconds
Parameters
num: number
reset?: booleanoptional
Returns
Date
public addWeeks(num: number, reset?: boolean): Date
see
addMilliseconds
Parameters
num: number
reset?: booleanoptional
Returns
Date
public addYears(num: number, reset?: boolean): Date
see
addMilliseconds
Parameters
num: number
reset?: booleanoptional
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?: booleanoptional
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?: booleanoptional
Returns
Date
public advance(milliseconds: number, reset?: boolean): Date
see
advance
Parameters
milliseconds: number
Milliseconds to advance the date.
reset?: booleanoptional
Returns
Date
public advance(set: DateFields, reset?: boolean): Date
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
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?: stringoptional
Returns
string
String
public full(locale?: string): string
Parameters
locale?: stringoptional
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"
public hoursSince(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public hoursSince(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
Returns
number
public hoursUntil(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public hoursUntil(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
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.
public is(milliseconds: number, margin?: number): boolean
Parameters
milliseconds: number
margin?: numberoptional
Returns
boolean
public is(d: Date, margin?: number): boolean
Parameters
d: Date
margin?: numberoptional
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?: numberoptional
Returns
boolean
Boolean
public isAfter(milliseconds: number, margin?: number): boolean
Parameters
milliseconds: number
margin?: numberoptional
Returns
boolean
public isAfter(d: Date, margin?: number): boolean
Parameters
d: Date
margin?: numberoptional
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?: numberoptional
Returns
boolean
Boolean
public isBefore(milliseconds: number, margin?: number): boolean
Parameters
milliseconds: number
margin?: numberoptional
Returns
boolean
public isBefore(d: Date, margin?: number): boolean
Parameters
d: Date
margin?: numberoptional
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?: numberoptional
Returns
boolean
Boolean
public isBefore(start: number, end: string, margin?: number): boolean
Parameters
start: number
end: string
margin?: numberoptional
Returns
boolean
public isBefore(start: Date, end: Date, margin?: number): boolean
Date.create('yesterday').isLastWeek() -> true or false?
Date.create('yesterday').isLastMonth() -> probably not...
Date.create('yesterday').isLastYear() -> even less likely...
Date.create('tomorrow').isNextWeek() -> true or false?
Date.create('tomorrow').isNextMonth() -> probably not...
Date.create('tomorrow').isNextYear() -> even less likely...
Date.create('tomorrow').isThisWeek() -> true or false?
Date.create('tomorrow').isThisMonth() -> probably...
Date.create('tomorrow').isThisYear() -> signs point to yes...
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.
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.
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?: Dateoptional
locale?: stringoptional
Returns
number
Number
public millisecondsSince(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
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.
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?: Dateoptional
locale?: stringoptional
Returns
number
Number
public millisecondsUntil(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
Returns
number
public minutesAgo(): number
Returns
number
public minutesFromNow(): number
Returns
number
public minutesSince(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public minutesSince(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
Returns
number
public minutesUntil(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public minutesUntil(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
Returns
number
public monthsAgo(): number
Returns
number
public monthsFromNow(): number
Returns
number
public monthsSince(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public monthsSince(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
Returns
number
public monthsUntil(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public monthsUntil(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
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
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?: stringoptional
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?: booleanoptional
Returns
Date
Date
public rewind(year: number, month: number, day: number, reset?: boolean): Date
Parameters
year: number
month: number
day: number
reset?: booleanoptional
Returns
Date
public rewind(d: DateFields, reset?: boolean): Date
public secondsSince(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public secondsSince(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
Returns
number
public secondsUntil(date?: Date, locale?: string): number
Parameters
date?: Dateoptional
locale?: stringoptional
Returns
number
public secondsUntil(date: string, locale?: string): number
Parameters
date: string
locale?: stringoptional
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