Getting Started

Requirements

ProDate has no dependencies.

Browser Support

Instead of targeting an ever increasing plethora of specific browsers we simply craft thoroughly designed, meticulously developed products using the latest standards, best practices and progressive enhancements. Our products work best with modern browsers, but will accommodate older browsers to the most practical extent possible.

Installation

Load the ProDate library by adding the script to your page:

<script src="/prodate-1.0.x/js/prodate.js"></script>

ProDate is now ready to use.

Usage

The ProDate library consists of a prototype object ProDate and a global object proDate. The global object exposes several methods for customising the library, retrieving meta data and, most importantly, creating ProDate instances. A ProDate instance represents a specific moment in time and provides methods to query, manipulate and output its date and time.

Create

A ProDate is created by calling one of the global methods proDate(), proDate.utc() or proDate.invalid(). Optional arguments can be passed to set the initial date, control parsing and configure the resulting ProDate.

proDate()

Creates a ProDate in local mode representing the exact date and time the instance was created, i.e. "now".

Arguments

This method does not accept any arguments.

Return

Type: ProDate
"Now" in the client's local time.

proDate().toString(); // "2015-04-16T18:21:26+01:00"

proDate.utc()

Creates a ProDate in UTC mode representing the exact date and time the instance was created, i.e. "now".

Arguments

This method does not accept any arguments.

Return

Type: ProDate
"Now" in UTC.

proDate.utc().toString(); // "2015-04-04T13:12:34Z"

proDate.invalid()

Creates an invalidated ProDate. A ProDate created with invalid(), in addition to being isValid() false, will be isInvalidated() true. The distinction being that an invalidated ProDate is purposely invalid because it represents no date as opposed to a ProDate that is invalid because it was created with an input that could not be parsed. Purposely invalid ProDate instances can be essential in some situations and are made use of in ProDatePicker. When an invalidated ProDate is printed the output is an empty string.

Arguments

This method does not accept any arguments.

Return

Type: ProDate
A purposely invalid date.

proDate.invalid().toString(); // ""

Parse

To create a ProDate that represents a date other than "now" a date argument can be passed to both proDate() and proDate.utc(). For brevity the following documentation refers to both methods simultaneously by using square bracket notation on the method name, indicating the .utc part is optional.

proDate[.utc](string[, model[, locale[, format[, strict[, zone]]]]])

Parses a string to a date. If a date cannot be parsed the ProDate will be invalid. Omitted date parts are substituted with a corresponding value from the base date 01 Jan 1970 00:00:00.000Z (the UNIX epoch).

Arguments

string
Type: String
A string representation of a date that uses the defined model, locale and format.
model
Type: String
Default: "ISO_DATETIME"
A string literal (or preset) that uses predefined format elements as placeholders for data, used to map data from the string input to the internal Date. The value is retained and used as a default when the toString() method is called without a model argument.
locale
Type: String
Default: "en"
The Locale used to parse and month and day names along with region-specific attributes like radix points and meridiem indicators. The value is retained and used as a default when the toString() method is called without a locale argument.
format
Type: String
Default: "ProDate"
The Format defining the elements that can be used in the model. The value is retained and used as a default when the toString() method is called without a format argument.
strict
Type: Boolean
Default: false
Enables or disables Strict Mode. Can be passed last if omitting other arguments.
zone
Type: String | Number
An implicit time zone offset. If an explicit time zone offset cannot be included in the date string but the time zone offset is known, this argument can be used to inform the parser that the date should be parsed using the defined time zone offset instead of interpreting the date as local. This can be useful for back-end data models where time zone offsets are not stored because dates are normalised by design and/or the database data type cannot handle time zone offsets.

Return

Type: ProDate
The parsed date or an invalid date.

// Parse a string to local time using defaults
proDate("2013-04-23T02:53:12+02:00").toString(); // "2013-04-23T01:53:12+0100"
// Parse a string ton UTC with a custom model
proDate.utc("Monday, 30 March 2015", "dddd, D MMMM YYYY").toString(); // "Monday, 30 March 2015"

proDate[.utc](array[, model[, locale[, format[, strict[, zone]]]]])

Parses an array of numbers to a date. If a date cannot be parsed the ProDate will be invalid. Omitted date parts are substituted with a corresponding value from the base date 01 Jan 1970 00:00:00.000Z (the UNIX epoch).

Array values can be any number or omitted with null and map to the following date parts: [year, month, dayOfMonth, hour, minute, second, millisecond, offset].

Values that exceed the valid range for their date part will overflow. For example, parsing [2015, 1, 40] will result in a date of "2015-02-09" since there are only 31 days in January. Enable Strict Mode to prevent this behaviour and return an invalid date.

Months in ProDate always use the month numbers 1 - 12.

Arguments

array
Type: Array<Number>
An array representation of a date.
model
Type: String
Default: "ISO_DATETIME"
Although not used to parse an array date, the value is retained and used as a default when the toString() method is called without a model argument.
locale
Type: String
Default: "en"
Although not used to parse an array date, the value is retained and used as a default when the toString() method is called without a locale argument.
format
Type: String
Default: "ProDate"
Although not used to parse an array date, the value is retained and used as a default when the toString() method is called without a format argument.
strict
Type: Boolean
Default: false
Enables or disables Strict Mode. Can be passed last if omitting other arguments.
zone
Type: String | Number
An implicit time zone offset. If an explicit time zone offset cannot be included in the date array but the time zone offset is known, this argument can be used to inform the parser that the date should be parsed using the defined time zone offset instead of interpreting the date as local or UTC. This can be useful for back-end data models where time zone offsets are not stored because dates are normalised by design and/or the database data type cannot handle time zone offsets.

Return

Type: ProDate
The parsed date or an invalid date.

// Parse an array to local time using defaults
proDate([1997, 4]).toString(); // "1997-04-01T00:00:00+01:00"
// Parse an array to UTC with a custom model (for printing)
proDate.utc([2016, 6, 12, 15, 21, 56, 452, -300], "ddd, DD MMM YYYY HH:mm:ss.SSS Z").toString(); // "Sun, 12 Jun 2016 20:21:56.452 Z"
// Parse in Strict Mode - 31 Feb 2012 is not a real date
proDate([2012, 2, 31], true).toString(); // "Invalid date"

proDate[.utc](object[, model[, locale[, format[, strict[, zone]]]]])

Parses an object to a date. If a date cannot be parsed the ProDate will be invalid. Omitted date parts are substituted with a corresponding value from the base date 01 Jan 1970 00:00:00.000Z (the UNIX epoch).

Arguments

object
Type: Object
An object representation of a date that uses any of the following keys: ISODayOfWeek, ISOWeek, dayOfMonth, dayOfWeek, dayOfYear, epoch, hour, hour12, meridiem, decisecond, centisecond, millisecond, minute, month, offset, second, timestamp, year, quarter
model
Type: String
Default: "ISO_DATETIME"
Although not used to parse an object date, the value is retained and used as a default when the toString() method is called without a model argument.
locale
Type: String
Default: "en"
Although not used to parse an object date, the value is retained and used as a default when the toString() method is called without a locale argument.
format
Type: String
Default: "ProDate"
Although not used to parse an object date, the value is retained and used as a default when the toString() method is called without a format argument.
strict
Type: Boolean
Default: false
Enables or disables Strict Mode.
zone
Type: String | Number
An implicit time zone offset. If an explicit time zone offset cannot be included in the object but the time zone offset is known, this argument can be used to inform the parser that the date should be parsed using the defined time zone offset instead of interpreting the date as local. This can be useful for back-end data models where time zone offsets are not stored because dates are normalised by design and/or the database data type cannot handle time zone offsets.

Return

Type: ProDate
The parsed date or an invalid date.

// Parse an object to local time using defaults
proDate({"year": 2001, "month": 8, "dayOfMonth": 31}).toString(); // "2001-08-31T00:00:00+0100"
// Parse an object to UTC using a custom model and locale (for printing)
proDate.utc({"year": 2001, "month": 8, "dayOfMonth": 31}, "dddd, DD MMMM YYYY", "fr").toString(); // "vendredi, 31 août 2001"
// The first Wednesday in the second quarter of 2010
proDate({"year": 2010, "quarter": 2, "ISODayOfWeek": 3}, "dddd, DD MMMM YYYY").toString(); // "Wednesday, 07 April 2010"

proDate[.utc](date[, model[, locale[, format]]])

Converts a JavaScript Date to a ProDate. If the input date is invalid the returned ProDate will be invalid.

Arguments

date
Type: Date
A JavaScript Date.
model
Type: String
Default: "ISO_DATETIME"
Although not used to parse a native date, the value is retained and used as a default when the toString() method is called without a model argument.
locale
Type: String
Default: "en"
Although not used to parse a native date, the value is retained and used as a default when the toString() method is called without a locale argument.
format
Type: String
Default: "ProDate"
Although not used to parse a native date, the value is retained and used as a default when the toString() method is called without a format argument.

Return

Type: ProDate
The parsed date or an invalid date.

// Convert a native Date to local time using defaults
proDate(new Date(2011, 3, 17, 3, 12, 20)).toString(); // "2011-04-17T03:12:20+0100"
// Conver a JavaScript Date to UTC using a custom preset model
proDate.utc(new Date(2011, 3, 17, 3, 12, 20), "ISO_WEEKDATE").toString(); // "2011-W15-7"

proDate[.utc](number[, model[, locale[, format]]])

Creates a ProDate from timestamp representing the number of milliseconds since the UNIX epoch 01 Jan 1970 00:00:00.000Z. Results in exactly the same date created by proDate(new Date(Number)).

Arguments

number
Type: Number
A timestamp.
model
Type: String
Default: "ISO_DATETIME"
Although not used to parse a number, the value is retained and used as a default when the toString() method is called without a model argument.
locale
Type: String
Default: "en"
Although not used to parse a number, the value is retained and used as a default when the toString() method is called without a locale argument.
format
Type: String
Default: "ProDate"
Although not used to parse a number, the value is retained and used as a default when the toString() method is called without a format argument.

Return

Type: ProDate
The parsed date or an invalid date.

// Parse a timestamp in local time using defaults
proDate(475655675657).toString(); // "1985-01-27T06:34:35+0000"
// Parse a timestamp in UTC with custom model, locale and format
proDate.utc(475655675657, "l, j F Y", "fr", "PHP").toString(); // "dimanche, 27 janvier 1985"
// Use Date.UTC() to generate a timestamp
proDate(Date.UTC(2011, 3, 12, 5, 42)).toString(); // "2011-04-12T06:42:00+0100"

proDate[.utc](proDate)

Clone an existing ProDate. Changes to the clone will not affect the original instance and vice versa. The result is exactly the same as calling clone() on the original ProDate.

Whether you use proDate() or proDate.utc() the returned ProDate will always be an exact clone of the original. It will not be changed from local mode to UTC mode or vice versa. To guarantee a local or UTC date call local() or utc() after cloning.

Arguments

proDate
Type: ProDate
An existing ProDate.

Return

Type: ProDate
An exact clone of the orignal ProDate.

var date1 = proDate();
var date2 = proDate(date1);
var date3 = date1.clone();
date2.isSame(date1); // true
date3.isSame(date1); // true
date2.isSame(date3); // true

Strict Mode

Strict mode can be enabled when parsing date inputs of type String, Array and Object by passing strict: true or by setting the default value of strict: true. When strict mode is disabled, self-contradictory, unrealistic and improperly formatted input dates are tolerated and will always resolve to a valid date. When strict mode is enabled such input dates result in invalid dates.

Strict mode enables the following restrictions based on input type:

String
  • Character literals in the input must match the exact character and letter case of the equivalent character in the model.
  • Numbers must be padded to the correct length for padded date parts.
  • Numbers must not be padded for unpadded date parts.
  • The input must not contain extra characters at the end.
  • The model must not contain extra characters at the end.
  • Names are case sensitive.
  • Time zone offsets must use the correct format (colon or no colon).
  • The input must represent a real date.
  • The input must be internally consistent, i.e. all date parts must be accurate for the date.
Array
  • The input must represent a real date.
Object
  • The input must represent a real date.
  • The input must be internally consistent, i.e. all date parts must be accurate for the date.

Get & Set

The core ProDate methods are overloaded and act as getters and setters of intrinsic date information. The individually named methods are essentially a layer of abstraction on top of the generic get() and set() methods, which themselves are a layer of abstraction on top of the JavaScript Date methods. Whilst the named methods are more intuitive to work with get() and set() both provide unique features that might be of use in some situations.

get()

See also: get(units)

Get a collection of intrinsic date information.

Arguments

This method does not accept any arguments.

Return

Type: Object
A collection of intrinsic date information.

proDate([2012, 4, 19, 3, 21, 10, 455]).get();
/*
{
    ISODayOfWeek: 4,
    ISOWeek: 16,
    ISOWeekYear: 2012,
    dayOfMonth: 19,
    dayOfWeek: 4,
    dayOfYear: 110,
    epoch: 1334802070,
    hour: 3,
    hour12: 3,
    isDST: true,
    isLeapYear: true,
    isUTC: false,
    isWeekend: false,
    meridiem: 0,
    millisecond: 455,
    minute: 21,
    month: 4,
    offset: 60,
    quarter: 2,
    second: 10,
    timestamp: 1334802070455,
    year: 2012
}
*/

get(units)

See also: get()

Get a specific date part.

Arguments

units
Type: String
The date part to get. Must be one of the following units: year[s], month[s], dayOfMonth, dayOfWeek, hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive and plural forms are optional.

Return

Type: Number
A specific date part, NaN if the date is invalid or undefined if the units aren't recognised.

var date = proDate([2012, 4, 19, 3, 21, 10, 455]);
date.get("year"); // 2012
date.get("month"); // 4
date.get("dayOfMonth"); // 19
date.get("dayOfWeek"); // 4
date.get("hour"); // 3
date.get("minute"); // 21
date.get("second"); // 10
date.get("millisecond"); // 455
date.get("week"); // 16
date.get("quarter"); // 2
date.get("unknown"); // undefined
proDate.invalid().get("month"); // NaN

set(units, value)

See also: set(values)

Set a specific date part.

Arguments

units
Type: String
The date part. Must be one of the following units: year[s], month[s], dayOfMonth, dayOfWeek, hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive and plural forms are optional.
value
Type: Number
The value to set. Values that exceed the normal range for a date part will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate().set("year", 2012);
proDate().set("month", 4);
proDate().set("dayOfMonth", 19);
proDate().set("dayOfWeek", 4);
proDate().set("hour", 3);
proDate().set("minute", 21);
proDate().set("second", 10);
proDate().set("millisecond", 455);
proDate().set("week", 15);
proDate().set("quarter", 2);

set(values)

See also: set(units, value)

Set multiple date parts using an array or object.

Arguments

values
Type: Array | Object
An array or object of values to set.
Array values can be any number or omitted with null and map to the following date parts: [year, month, dayOfMonth, hour, minute, second, millisecond, offset].
Objects can use the following keys to set values: year, month, dayOfMonth, dayOfWeek, ISODayOfWeek, hour, minute, second, decisecond, centisecond, millisecond,week, quarter, epoch, timestamp, meridiem, hour12, dayOfYear.

Return

Type: ProDate
The ProDate for chaining.

Using set() to set an offset has the same effect as calling offset() before setting date parts and results in a ProDate in offset mode. In contrast, the same values passed to proDate() or proDate.utc() would result in a date parsed with that offset then converted to local time or UTC respectively.
proDate.utc().set([2002, 2, 23, 4, 59, 20, 234, -600]).toString(); // "2002-02-23T04:59:20-1000"
proDate.utc().set({
    dayOfMonth: 19,
    hour: 3,
    millisecond: 455,
    minute: 21,
    month: 4,
    offset: 120,
    second: 10,
    year: 2012
}).toString(); // "2012-04-19T03:21:10+0200"

// Using get() and set() to clone a date
var date1 = proDate.utc([2002, 2, 23, 4, 59, 20, 234, -600]);
var date2 = proDate.utc().set(date1.get());
date2.isSame(date1); // true

year()

See also: year(value)

Get the year.

Arguments

This method does not accept any arguments.

Return

Type: Number
The year or NaN if the date is invalid.

proDate().year(); // 2015
proDate.invalid().year(); // NaN

year(value)

See also: year()

Set the year.

Arguments

value
Type: Number
The year.

Return

Type: ProDate
The ProDate for chaining.

proDate().year(2000);

month()

See also: month(value)

Get the month.

Months in ProDate always use the month numbers 1 - 12.

Arguments

This method does not accept any arguments.

Return

Type: Number
The month or NaN if the date is invalid.

proDate().month(); // 7
proDate.invalid().month(); // NaN

month(value)

See also: month()

Set the month.

Months in ProDate always use the month numbers 1 - 12.

Arguments

value
Type: Number
The month. Values that exceed the range 1 to 12 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4]).month(3).month(); // 3
proDate([2015, 4]).month(-2).toString("MMMM YYYY"); // "October 2014"
proDate([2015, 4]).month(14).toString("MMMM YYYY"); // "February 2016"

dayOfMonth()

See also: dayOfMonth(value)

Get the day of the month.

Arguments

This method does not accept any arguments.

Return

Type: Number
The day of the month or NaN if the date is invalid.

proDate().dayOfMonth(); // 15
proDate.invalid().dayOfMonth(); // NaN

dayOfMonth(value)

See also: dayOfMonth()

Set the day of the month.

Arguments

value
Type: Number
The day of the month. Values that exceed the number of days in the month will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6]).dayOfMonth(17).dayOfMonth(); // 17
proDate([2015, 4, 6]).dayOfMonth(-2).toString("DD MMM YYYY"); // "29 Mar 2015"
proDate([2015, 4, 6]).dayOfMonth(40).toString("DD MMM YYYY"); // "10 May 2015"

hour()

See also: hour(value)

Get the hour in the 24-hour clock.

Arguments

This method does not accept any arguments.

Return

Type: Number
The hour or NaN if the date is invalid.

proDate().hour(); // 19
proDate.invalid().hour(); // NaN

hour(value)

See also: hour()

Set the hour in the 24-hour clock.

Arguments

value
Type: Number
The hour. Values that exceed the range 0 to 23 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3]).hour(13).hour(); // 13
proDate([2015, 4, 6, 3]).hour(-2).toString("DD MMM YYYY HH:mm"); // "05 Apr 2015 22:00"
proDate([2015, 4, 6, 3]).hour(28).toString("DD MMM YYYY HH:mm"); // "07 Apr 2015 04:00"

minute()

See also: minute(value)

Get the minute.

Arguments

This method does not accept any arguments.

Return

Type: Number
The minute or NaN if the date is invalid.

proDate().minute(); // 54
proDate.invalid().minute(); // NaN

minute(value)

See also: minute()

Set the minute.

Arguments

value
Type: Number
The minute. Values that exceed the range 0 to 59 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3, 32]).minute(24).minute(); // 24
proDate([2015, 4, 6, 3, 32]).minute(-15).toString("HH:mm"); // "02:45"
proDate([2015, 4, 6, 3, 32]).minute(67).toString("HH:mm"); // "04:07"

second()

See also: second(value)

Get the second.

Arguments

This method does not accept any arguments.

Return

Type: Number
The second or NaN if the date is invalid.

proDate().second(); // 38
proDate.invalid().second(); // NaN

second(value)

See also: second()

Set the second.

Arguments

value
Type: Number
The second. Values that exceed the range 0 to 59 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3, 32, 12]).second(47).second(); // 47
proDate([2015, 4, 6, 3, 32, 12]).second(-20).toString("HH:mm:ss"); // "03:31:40"
proDate([2015, 4, 6, 3, 32, 12]).second(71).toString("HH:mm:ss"); // "03:33:11"

decisecond()

See also: decisecond(value)

Get the decisecond (tenths of a second).

Arguments

This method does not accept any arguments.

Return

Type: Number
The decisecond or NaN if the date is invalid.

proDate().decisecond(); // 3
proDate.invalid().decisecond(); // NaN

decisecond(value)

See also: decisecond()

Set the decisecond (tenths of a second).

Arguments

value
Type: Number
The decisecond. Values that exceed the range 0 to 9 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3, 32, 12, 838]).decisecond(3).decisecond(); // 3
proDate([2015, 4, 6, 3, 32, 12, 838]).decisecond(-2).toString("HH:mm:ss.S"); // "03:32:11.8"
proDate([2015, 4, 6, 3, 32, 12, 838]).decisecond(15).toString("HH:mm:ss.S"); // "03:32:13.5"

centisecond()

See also: centisecond(value)

Get the centisecond (hundredths of a second).

Arguments

This method does not accept any arguments.

Return

Type: Number
The centisecond or NaN if the date is invalid.

proDate().centisecond(); // 45
proDate.invalid().centisecond(); // NaN

centisecond(value)

See also: centisecond()

Set the centisecond (hundredths of a second).

Arguments

value
Type: Number
The centisecond. Values that exceed the range 0 to 99 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3, 32, 12, 838]).centisecond(12).centisecond(); // 12
proDate([2015, 4, 6, 3, 32, 12, 838]).centisecond(-35).toString("HH:mm:ss.SS"); // "03:32:11.65"
proDate([2015, 4, 6, 3, 32, 12, 838]).centisecond(131).toString("HH:mm:ss.SS"); // "03:32:13.31"

millisecond()

See also: millisecond(value)

Get the millisecond (thousanths of a second).

Arguments

This method does not accept any arguments.

Return

Type: Number
The millisecond or NaN if the date is invalid.

proDate().millisecond(); // 467
proDate.invalid().millisecond(); // NaN

millisecond(value)

See also: millisecond()

Set the millisecond (thousanths of a second).

Arguments

value
Type: Number
The millisecond. Values that exceed the range 0 to 999 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3, 32, 12, 838]).millisecond(324).millisecond(); // 324
proDate([2015, 4, 6, 3, 32, 12, 838]).millisecond(-124).toString("HH:mm:ss.SSS"); // "03:32:11.876"
proDate([2015, 4, 6, 3, 32, 12, 838]).millisecond(1329).toString("HH:mm:ss.SSS"); // "03:32:13.329"

offset()

See also: offset(value)

Get the time zone offset as a number of minutes from UTC.

Unlike the JavaScript Date.getTimezoneOffset() method which returns the number of minutes difference from local time to UTC, offset() returns the number of minutes difference from UTC to local time. The distinction is that the value returned from offset() is the opposite number of the value returned from Date.getTimezoneOffset(). The reason for this obvious if you frequently work with time zone offsets. For a date with a time zone offset of "+0100" the value returned from Date.getTimezoneOffset() is -60, which is counter-intuitive. Using offset() the value is 60 and this difference makes working with time zone offsets in both string and number form much simpler in ProDate.

ProDate handles negative zero, positive zero and null offsets as distinct values with the following meanings:

OffsetZoneMeaning
null "Z" UTC
0 "+00:00" GMT
-0 "-00:00" Local time, offset unknown

Arguments

This method does not accept any arguments.

Return

Type: Number
The offset minutes, null for UTC or NaN if the date is invalid.

proDate().offset(); // 60
proDate().offset(-120).offset(); // -120
proDate.utc().offset(); // null
proDate.invalid().offset(); // NaN

offset(value)

See also: offset()

Set the time zone offset as a number of minutes from UTC, putting the date in offset mode. Setting the time zone offset results in a date with a fixed number of minutes difference from UTC. A time zone offset is not the same as a time zone - the offset is not automatically adjusted for daylight savings time. ProDate does not currently support time zones in this sense.

ProDate handles negative zero, positive zero and null offsets as distinct values with the following meanings:

OffsetZoneMeaning
null "Z" UTC
0 "+00:00" GMT
-0 "-00:00" Local time, offset unknown

Passing null is equivalent to using the utc() method and sets UTC mode on the ProDate.

Arguments

value
Type: Number | String
The offset from UTC as:
  • A number of minutes or null for UTC
  • A string using one of the following formats: "±[hh]", "±[hh][mm]", "±[hh]:[mm]", or "Z" for UTC.
As a setter offset() is functionally equivalent to zone().

Return

Type: ProDate
The ProDate for chaining.

proDate().offset(120).zone(); // "+0200"
proDate().offset(-600).zone(); // "-1000"
proDate().offset(-0).zone(); // "-0000"
proDate().offset(0).zone(); // "+0000"
proDate().offset(null).zone(); // "Z"
proDate().offset(null).isUTC(); // true

zone([colon])

See also: zone(value)

Get the time zone offset as a string.

ProDate handles negative zero, positive zero and null offsets as distinct values with the following meanings:

OffsetZoneMeaning
null "Z" UTC
0 "+00:00" GMT
-0 "-00:00" Local time, offset unknown

Arguments

colon
Type: Boolean
If true hours and minutes are seperated by a colon.

Return

Type: String
The time zone offset or an empty string if the date is invalid.

proDate().zone(); // "+0100"
proDate().zone(true); // "+01:00"
proDate.utc().zone(); // "Z"
proDate.invalid().zone(); // ""

zone(value)

See also: zone([colon])

Set the time zone offset, putting the date in offset mode. Setting the time zone offset results in a date with a fixed number of minutes difference from UTC. A time zone offset is not the same as a time zone - the offset is not automatically adjusted for daylight savings time. ProDate does not currently support time zones in this sense.

ProDate handles negative zero, positive zero and null offsets as distinct values with the following meanings:

OffsetZoneMeaning
null "Z" UTC
0 "+00:00" GMT
-0 "-00:00" Local time, offset unknown

Passing "Z" is equivalent to using the utc() method and sets UTC mode on the ProDate.

Arguments

value
Type: Number | String
The offset from UTC as:
  • A number of minutes or null for UTC
  • A string using one of the following formats: "±[hh]", "±[hh][mm]", "±[hh]:[mm]", or "Z" for UTC.
As a setter zone() is functionally equivalent to offset().

Return

Type: ProDate
The ProDate for chaining.

proDate().zone("+0200").offset(); // 120
proDate().zone("-10:00").offset(); // -600
proDate().zone("-00").offset(); // -0
proDate().zone("+0000").offset(); // 0
proDate().zone("Z").offset(); // null
proDate().zone("Z").isUTC(); // true

hour12()

See also: hour12(value)

Get the hour in the 12-hour clock.

Arguments

This method does not accept any arguments.

Return

Type: Number
The hour or NaN if the date is invalid.

proDate().hour(19).hour12(); // 7
proDate.invalid().hour(); // NaN

hour12(value)

See also: hour12()

Set the hour in the 12-hour clock. The meridiem (AM or PM) is maintained.

The start of the day is 12AM in the 12-hour clock and 0 in the 24-hour clock. Midday is 12PM in the 12-hour clock and 12 in the 24-hour clock.

Arguments

value
Type: Number
The hour. Values that exceed the range 1 to 12 are ignored.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3]).hour12(2).hour(); // 2
proDate([2015, 4, 6, 15]).hour12(2).hour(); // 14
proDate([2015, 4, 6, 3]).hour12(14).hour(); // 3

meridiem()

See also: meridiem(value)

Get the meridiem indicator (whether the time is before midday (AM) or after midday (PM)).

Arguments

This method does not accept any arguments.

Return

Type: Number
The meridiem indicator as 0 (before midday) or 1 (after midday) or NaN if the date is invalid.

proDate().hour(3).meridiem(); // 0
proDate().hour(19).meridiem(); // 1
proDate.invalid().hour(); // NaN

meridiem(value)

See also: meridiem()

Set the period in the 12-hour clock. Times before midday gain 12 hours when set to 1 and times after midday lose 12 hours when set to 0.

Arguments

value
Type: Number
The meridiem indicator as 0 (before midday) or 1 (after midday). Values other than 0 or 1 are ignored.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015, 4, 6, 3]).meridiem(1).hour(); // 15
proDate([2015, 4, 6, 18]).meridiem(0).hour(); // 6
proDate([2015, 4, 6, 3]).meridiem(2).hour(); // 3

dayOfYear()

See also: dayOfYear(value)

Get the day of the year.

Arguments

This method does not accept any arguments.

Return

Type: Number
The day of the year or NaN if the date is invalid.

proDate().dayOfYear(); // 281
proDate.invalid().dayOfYear(); // NaN

dayOfYear(value)

See also: dayOfYear()

Set the day of the year.

Arguments

value
Type: Number
The day of the year. Values that exceed the number of days in the year will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate([2015]).dayOfYear(128).toString("DD MMM YYYY"); // "08 May 2015"
proDate([2015]).dayOfYear(-95).toString("DD MMM YYYY"); // "27 Sep 2014"
proDate([2015]).dayOfYear(473).toString("DD MMM YYYY"); // "17 Apr 2016"

dayOfWeek()

See also: dayOfWeek(value)

Get the day of the week using JavaScript day of the week numbers: 0 (Sunday) to 6 (Saturday).

Arguments

This method does not accept any arguments.

Return

Type: Number
The day of the week or NaN if the date is invalid.

proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").dayOfWeek(); // 3 (Wednesday)
proDate.invalid().dayOfYear(); // NaN

dayOfWeek(value)

See also: dayOfWeek()

Set the day of the week using JavaScript day of the week numbers: 0 (Sunday) through 6 (Saturday). When using dayOfWeek() as a setter, Sunday is implicitly the first day of the week, therefore setting dayOfWeek(0) will always result in an earlier date.

Due to the fact that dayOfWeek() implicitly uses Sunday as the first day of the week and the values 0 (Sunday) to 6 (Saturday) and ISODayOfWeek() implicitly uses Monday as the first day of the week and the values 1 (Monday) to 7 (Sunday) and because values are permitted to overflow, ISODayOfWeek() and dayOfWeek() are equivalent when used as setters.

Arguments

value
Type: Number
The day of the week. Values that exceed the range 0 to 6 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").dayOfWeek(5).toString(); // "Fri Aug 14 2015"
proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").dayOfWeek(15).toString(); // "Mon Aug 24 2015"
proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").dayOfWeek(0).toString(); // "Sun Aug 09 2015"
proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").ISODayOfWeek(0).toString(); // "Sun Aug 09 2015"

ISODayOfWeek()

See also: ISODayOfWeek(value)

Get the day of the week using ISO day of the week numbers: 1 (Monday) to 7 (Sunday).

Arguments

This method does not accept any arguments.

Return

Type: Number
The day of the week or NaN if the date is invalid.

proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").ISODayOfWeek(); // 3 (Wednesday)
proDate.invalid().dayOfYear(); // NaN

ISODayOfWeek(value)

See also: ISODayOfWeek()

Set the day of the week using ISO day of the week numbers: 1 (Monday) to 7 (Sunday). When using ISODayOfWeek() as a setter, Monday is implicitly the first day of the week, therefore setting ISODayOfWeek(1) will always result in an earlier date.

Due to the fact that dayOfWeek() implicitly uses Sunday as the first day of the week and the values 0 (Sunday) to 6 (Saturday) and ISODayOfWeek() implicitly uses Monday as the first day of the week and the values 1 (Monday) to 7 (Sunday) and because values are permitted to overflow, ISODayOfWeek() and dayOfWeek() are equivalent when used as setters.

Arguments

value
Type: Number
The day of the week. Values that exceed the range 1 to 7 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").ISODayOfWeek(5).toString(); // "Fri Aug 14 2015"
proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").ISODayOfWeek(15).toString(); // "Mon Aug 24 2015"
proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").ISODayOfWeek(0).toString(); // "Sun Aug 09 2015"
proDate("Wed Aug 12 2015", "ddd MMM DD YYYY").dayOfWeek(0).toString(); // "Sun Aug 09 2015"

ISOWeek()

See also: ISOWeek(value)

Get the ISO week number.

Arguments

This method does not accept any arguments.

Return

Type: Number
The ISO week number or NaN if the date is invalid.

proDate("Sun Jun 23 2013", "ddd MMM DD YYYY").ISOWeek(); // 25
proDate.invalid().ISOWeek(); // NaN

ISOWeek(value)

See also: ISOWeek()

Set the date representing the same day of the week in the specified ISO week of the year. The day of the week is always maintained.

Arguments

value
Type: Number
The ISO week number. Values less than 1 or greater than the number of ISOWeeksInYear() are ignored.

Return

Type: ProDate
The ProDate for chaining.

proDate("Sun Jun 23 2013", "ddd MMM DD YYYY").ISOWeek(6).toString(); // "Sun Feb 10 2013"
proDate("Sun Jun 23 2013", "ddd MMM DD YYYY").ISOWeek(53).toString(); // "Sun Jun 23 2013"

ISOWeekYear()

See also: ISOWeekYear(value)

Get the ISO week year. The ISO week year relates to ISO week numbers and can differ from the calendar year for dates at the start and end of the year that fall into the last or first weeks of the previous or next year.

Arguments

This method does not accept any arguments.

Return

Type: Number
The ISO week year or NaN if invalid.

proDate([2011, 1, 1]).ISOWeekYear(); // 2010 (ISO week 52 of 2010)

ISOWeekYear(value)

See also: ISOWeekYear()

Set the ISO week year. When setting the ISO week year the ISO week number and ISO day of the week are maintained, resulting in the exact same ISO weekdate in a different year. This differs from setting the calendar year since the day of the month and month might be changed. This is the only logical result of setting the ISO week year. For example, consider the date "2011-01-01" for which the ISO week year is 2010 since this date falls into week 52 of the previous year. Setting ISOWeekYear(2011) should result in some change, because the ISO week year is changing from 2010 to 2011, but if the calendar year was set to 2011 the date wouldn't change at all.

Arguments

value
Type: Number
The ISO week year.

Return

Type: ProDate
The ProDate for chaining.

var date = proDate([2011, 1, 1]);
date.toString("ISO_WEEKDATE"); // "2010-W52-6"
date.toString("ISO_DATE"); // "2011-01-01"
date.ISOWeekYear(2011).toString("ISO_WEEKDATE"); // "2011-W52-6"
date.toString("ISO_DATE"); // "2011-12-31"

quarter()

See also: quarter(value)

Get the quarter of the year.

Arguments

This method does not accept any arguments.

Return

Type: Number
The quarter or NaN if the date is invalid.

proDate("Thu Jul 21 2016", "ddd MMM DD YYYY").quarter(); // 3
proDate.invalid().quarter(); // NaN

quarter(value)

See also: quarter()

Set the date representing the equivalent day of the specified quarter. The resulting date follows the same logic used when manipulating years and months, i.e. if the day of the month exceeds the number of days in the month, the day of the month becomes the last day of the month.

Arguments

value
Type: Number
The quarter. Values that exceed the range 1 to 4 will overflow.

Return

Type: ProDate
The ProDate for chaining.

proDate("Thu Jul 21 2016", "ddd MMM DD YYYY").quarter(1).toString(); // "Thu Jan 21 2016"
proDate("Tue Jan 31 2012", "ddd MMM DD YYYY").quarter(2).toString(); // "Mon Apr 30 2012"

epoch()

See also: epoch(value)

Get the number of seconds since the UNIX epoch 01 Jan 1970 00:00:00.000Z.

Arguments

This method does not accept any arguments.

Return

Type: Number
The number of seconds or NaN if the date is invalid.

proDate([2009, 12, 12, 3, 53, 29, 343]).epoch(); // 1260590009
proDate.invalid().epoch(); // NaN

epoch(value)

See also: epoch()

Set the number of seconds since the UNIX epoch 01 Jan 1970 00:00:00.000Z.

Arguments

value
Type: Number
The number of seconds. Fractional seconds become milliseconds.

Return

Type: ProDate
The ProDate for chaining.

proDate().epoch(1260590009).toString("ISO_FULL"); // "2009-12-12T03:53:29.000+0000"
proDate().epoch(1260590009.324844).toString("ISO_FULL"); // "2009-12-12T03:53:29.324+0000"

timestamp()

See also: timestamp(value)

Get the number of milliseconds since the UNIX epoch 01 Jan 1970 00:00:00.000Z.

Arguments

This method does not accept any arguments.

Return

Type: Number
The number of milliseconds or NaN if the date is invalid.

proDate([2015, 2, 14, 12, 30, 25, 294]).timestamp(); // 1423917025294
proDate.invalid().timestamp(); // NaN

timestamp(value)

See also: timestamp()

Set the number of milliseconds since the UNIX epoch 01 Jan 1970 00:00:00.000Z.

Arguments

value
Type: Number
The number of milliseconds. Fractional milliseconds are truncated.

Return

Type: ProDate
The ProDate instance for chaining.

proDate().timestamp(1423917025294).toString("ISO_FULL"); // "2015-02-14T12:30:25.294+0000"

locale()

See also: locale(value)

Get the locale ID.

Arguments

This method does not accept any arguments.

Return

Type: String
The locale ID.

proDate().locale(); // "en"

locale(value)

See also: locale()

Set the locale.

Arguments

value
Type: String
A valid locale ID or null for the default locale. If the specified locale is not loaded the locale is not changed.

Return

Type: ProDate
The ProDate for chaining.

var date = proDate();

date.toString("dddd, DD MMMM YYYY"); // "Monday, 13 April 2015"
date.locale("fr").toString("dddd, DD MMMM YYYY"); // lundi, 13 avril 2015"
date.locale(null).toString("dddd, DD MMMM YYYY"); // "Monday, 13 April 2015"

Manipulate

Manipulating dates and times is easy with ProDate. The self-explanatory add() and subtract() methods are the cornerstones of most date manipulation tasks and can handle any unit of time.

add(amount[, units])

Add time.

When adding years, quarters, months or weeks, if the day of the month exceeds the number of days in the month, the day of the month is adjusted to be the last day of the month.

When crossing daylight savings boundaries by adding years, quarters, months, weeks or days, the time will be maintained. However, when adding hours, minutes, seconds or milliseconds the time will change so that the missing or extra hour introduced by DST is properly accounted for.

Arguments

amount
Type: Number
The amount of time to add. Values are permitted to overflow. Negative values subtract time.
units
Type: String
The unit of time. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional. If units are not passed or the value is not recognised milliseconds are used.

Return

Type: ProDate
The ProDate instance for chaining.

proDate().add(5, "years");
proDate().add(1, "month");
proDate().add(45, "days");
proDate().add(12, "hours");
proDate().add(200, "minutes");
proDate().add(1000, "seconds");
proDate().add(50, "milliseconds");
proDate().add(2, "weeks");
proDate().add(1, "quarter");

proDate().add(-1, "day"); // Subtract 1 day

subtract(amount[, units])

Subtract time.

When subtracting years, quarters, months or weeks if the day of the month exceeds the number of days in the month, the day of the month is adjusted to be the last day of the month.

When crossing daylight savings boundaries by subtracting years, quarters, months, weeks or days, the time will be maintained. However, when subtracting hours, minutes, seconds or milliseconds the time will change so that the missing or extra hour introduced by DST is properly accounted for.

Arguments

amount
Type: Number
The amount of time to subtract. Values are permitted to overflow. Negative values add time.
units
Type: String
The unit of time. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional. If units are not passed or the value is not recognised milliseconds are used.

Return

Type: ProDate
The ProDate instance for chaining.

proDate().subtract(5, "years");
proDate().subtract(1, "month");
proDate().subtract(45, "days");
proDate().subtract(12, "hours");
proDate().subtract(200, "minutes");
proDate().subtract(1000, "seconds");
proDate().subtract(50, "milliseconds");
proDate().subtract(2, "weeks");
proDate().subtract(1, "quarter");

proDate().subtract(-1, "day"); // Add 1 day

startOf(units)

Change the date and time to the start of the specified period.

Arguments

units
Type: String
The period. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.

Return

Type: ProDate
The ProDate instance for chaining.

proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("year").toString(); // "2013-01-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("quarter").toString(); // "2013-07-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("month").toString(); // "2013-09-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("week").toString(); // "2013-09-16T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("day").toString(); // "2013-09-17T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("hour").toString(); // "2013-09-17T15:00:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("minute").toString(); // "2013-09-17T15:29:00.000+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").startOf("second").toString(); // "2013-09-17T15:29:41.000+01:00"

endOf(units)

Change the date and time to the end of the specified period.

Arguments

units
Type: String
The period. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.

Return

Type: ProDate
The ProDate instance for chaining.

proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("year").toString(); // "2013-12-31T23:59:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("quarter").toString(); // "2013-09-30T23:59:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("month").toString(); // "2013-09-30T23:59:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("week").toString(); // "2013-09-22T23:59:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("day").toString(); // "2013-09-17T23:59:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("hour").toString(); // "2013-09-17T15:59:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("minute").toString(); // "2013-09-17T15:29:59.999+01:00"
proDate("2013-09-17T15:29:41.210", "ISO_FULL").endOf("second").toString(); // "2013-09-17T15:29:41.999+01:00"

roundUp(roundTo[, units])

Change the date and time to the start of the nearest ceilinged multiple of the specified period. This method is most useful when you need to round a time up to the nearest n minutes, but can take other units.

Arguments

units
Type: String
The period. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s]. Units are case-insensitive, plural forms are optional.

Return

Type: ProDate
The ProDate instance for chaining.

proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "years").toString(); // "2015-01-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "months").toString(); // "2013-10-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "days").toString(); // "2013-09-20T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "hours").toString(); // "2013-09-17T15:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "minutes").toString(); // "2013-09-17T15:30:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "seconds").toString(); // "2013-09-17T15:29:45.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundUp(5, "milliseconds").toString(); // "2013-09-17T15:29:41.215+01:00"

roundDown(roundTo[, units])

Change the date and time to the start of the nearest floored multiple of the specified period. This method is most useful when you need to round a time down to the nearest n minutes, but can take other units.

Arguments

units
Type: String
The period. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s]. Units are case-insensitive, plural forms are optional.

Return

Type: ProDate
The ProDate instance for chaining.

proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "years").toString(); // "2010-01-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "months").toString(); // "2013-05-01T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "days").toString(); // "2013-09-15T00:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "hours").toString(); // "2013-09-17T15:00:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "minutes").toString(); // "2013-09-17T15:25:00.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "seconds").toString(); // "2013-09-17T15:29:40.000+01:00"
proDate("2013-09-17T15:29:41.211", "ISO_FULL").roundDown(5, "milliseconds").toString(); // "2013-09-17T15:29:41.210+01:00"

today()

Change the year, month and day of the month to the date "today" but leave the hours, minutes, seconds and milliseconds unchanged.

Arguments

This method does not accept any arguments.

Return

Type: ProDate
The ProDate instance for chaining.

proDate("05 Jan 2014 15:23:51", "DD MMM YYYY HH:mm:ss").today().toString(); // e.g. "13 Apr 2015 15:23:51"

now()

Change the hours, minutes, seconds and milliseconds to the time "now" but leave the year, month and day of the month unchanged.

Arguments

This method does not accept any arguments.

Return

Type: ProDate
The ProDate instance for chaining.

proDate("05 Jan 2014 15:23:51", "DD MMM YYYY HH:mm:ss").now().toString(); // e.g. "05 Jan 2014 08:16:32"

clone()

Create a new ProDate instance as an exact copy. Changes to the copy have no effect on the original and vice versa.

Arguments

This method does not accept any arguments.

Return

Type: ProDate
The ProDate instance for chaining.

var date1 = proDate([2015, 2, 12]);
var date2 = date1.clone().add(8, "days");

date1.toString(); // "2015-02-12T00:00:00+0000
date2.toString(); // "2015-02-20T00:00:00+0000

local([local])

Set local mode. In local mode the internal Date is interpreted using the client's local time. In local mode an instant is represented by different times in different locales. Not all instants exist in all locales due to Daylight Savings Time. Compare with the utc() method.

Arguments

units
Type: Boolean
If true sets local mode and if false sets UTC mode. This argument is useful if setting local or UTC mode is dependant on a variable, and eliminates the need for a separate if statement. If this argument is omitted local mode is set.

Return

Type: ProDate
The ProDate instance for chaining.

var date = proDate.utc("05 May 2015 14:00Z", "DD MMM YYYY HH:mmZZ");

date.toString(); // "05 May 2015 14:00Z"
date.local().toString(); // "05 May 2015 15:00+0100"
date.local(false).toString(); // "05 May 2015 14:00Z"
date.local(true).toString(); // "05 May 2015 15:00+0100"

utc([utc])

Set UTC mode. In UTC mode the internal Date is interpreted in UTC. In UTC mode an instant is represented by the exact same time in all locales. All instants exist in all locales as Daylight Savings Time does not apply in UTC. Compare with the local() method.

Arguments

units
Type: Boolean
If true sets UTC mode and if false sets local mode. This argument is useful if setting local or UTC mode is dependant on a variable, and eliminates the need for a separate if statement. If this argument is omitted UTC mode is set.

Return

Type: ProDate
The ProDate instance for chaining.

var date = proDate("05 May 2015 14:00+01:00", "DD MMM YYYY HH:mmZZ");

date.toString(); // "05 May 2015 14:00+01:00"
date.utc().toString(); // "05 May 2015 13:00Z"
date.utc(false).toString(); // "05 May 2015 14:00+01:00"
date.utc(true).toString(); // "05 May 2015 13:00Z"

until(end[, callback[, units[, step]]])

Change the date iteratively until the end date is reached but not met or exceeded. At each iteration a callback is executed and passed the current date and iteration count. The callback can manipulate the date or cancel the operation entirely by returning false. End dates after the start date cause each iteration to step forward in time and vice versa.

Arguments

end
Type: Any
A representation of a date in any form. See Parse for more information on date parsing and supported date types. Iteration will continue only whilst the current date isBefore() or isAfter() the end date (depending on whether the date is incrementing or decrementing). This means the end date is not included in the set of dates that can be generated by until().
callback
Type: Function
A function to execute on each iteration. The following arguments are passed to the callback:
date
Type: ProDate
The date at the current iteration. This is the original mutated ProDate, not a clone. Changes to the date will affect subsequent iterations. Care should be taken not to create an endless loop!
count
Type: Number
The iteration count.
If the callback function returns false the operation will be cancelled and the date will remain.
units
Type: String
The units to increment or decrement. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.
step
Type: Number
Must be a number greater than 0. The absolute value will be used if a negative number is passed. If omitted a value of 1 is used.

Return

Type: ProDate
The ProDate instance for chaining.

var start = proDate([2014, 4, 1]);
var callback = function (date, count) {
    console.log(count, date.toString("DD MMM YYYY"));
};

start.until([2014, 5, 1], callback, "day", 1);
// 1 "01 Apr 2014"
// ...
// 30 "30 Apr 2014"

start.toString("DD MMM YYYY"); // "30 Apr 2014"

invalidate()

Purposely invalidates a ProDate. Invalidated ProDate instances are safe to call all methods on and can be useful as placeholders when a date isn't known.

Arguments

This method does not accept any arguments.

Return

Type: ProDate
The ProDate instance for chaining.

var date = proDate();

date.isValid(); // true
date.invalidate().isValid(); // false
date.isInvalidated(); // true

Output

ProDate provides a variety of methods to get your dates in different formats, including strings, numbers and arrays.

valueOf()

Get the primitive value of the internal Date, i.e. the number of milliseconds since the UNIX epoch 01 Jan 1970 00:00:00.000Z.

Arguments

This method does not accept any arguments.

Return

Type: Number
The timestamp or NaN if the date is invalid.

proDate("Mon, 13 Apr 2015", "ddd, 05 MMM YYYY").valueOf(); // 1428274800000
proDate.invalid().valueOf(); // NaN

toString([model[, locale[, format]]])

Get a string representation of the date, optionally overriding the internal model, locale and format.

Arguments

model
Type: String
A string literal that uses predefined format elements as placeholders for data, used to map data from the internal Date to the string output. If omitted, the model used to create the ProDate is used.
locale
Type: String
The Locale used to print month and day names along with region-specific attributes like radix points and meridiem indicators. If omitted, the locale set when the ProDate was created, or last set with the locale() method, is used.
format
Type: String
The Format defining the elements that can be used in the model. If omitted, the format used to create the ProDate is used.

Return

Type: String
A string representation of the date and time, a localised "Invalid date" string if invalid or an empty string if invalidated.

var date = proDate("Mon, 13 Apr 2015", "ddd, 05 MMM YYYY", "en", "ProDate");

date.toString(); // "Mon, 13 Apr 2015"
date.toString("dddd MMMM DD YYYY"); // "Monday April 13 2015"
date.toString("dddd MMMM DD YYYY", "fr"); // "lundi avril 06 2015"
date.toString("l F d Y", "fr", "PHP"); // "lundi avril 06 2015"

proDate("13 Apr 2015", "ddd, 05 MMM YYYY").toString(); // "Invalid date" (parse error)
proDate.invalid().toString(); // "" (empty string)

toDate()

Get a clone of the internal Date. Changes to the returned Date object will not affect the original ProDate.

Arguments

This method does not accept any arguments.

Return

Type: Date
The internal Date.

proDate().toDate(); // Date

toArray()

Get an array of date parts.

Arguments

This method does not accept any arguments.

Return

Type: Array
An array of date parts in the following order: [year, month, dayOfMonth, hour, minute, second, millisecond, offset].

Months in ProDate always use the month numbers 1 - 12.
proDate("2014-06-12T13:41:29.954Z", "ISO_FULL").toArray(); // [2014, 6, 12, 14, 41, 29, 954, 60]
proDate.utc("2014-06-12T13:41:29.954Z", "ISO_FULL").toArray(); // [2014, 6, 12, 13, 41, 29, 954, null]

toJSON()

Get a string representation of the date and time in UTC using the ISO_FULL model. The toJSON() method is called automatically when an object containing a ProDate is serialised to JSON, e.g. when using JSON.stringify(). The same output can be achieved using the toString("ISO_FULL") method on a ProDate in UTC mode.

Arguments

This method does not accept any arguments.

Return

Type: String
A string representation of the date and time in UTC.

JSON.stringify({
    date: proDate()
}); // "{"date": "2015-04-19T18:31:25.492Z"}"

Query

isSame([input[, units]])

Check if the date is the same as another date by comparing timestamps to a specified precision. If input is omitted the date will be compared to "now". If units are omitted the full timestamps will be compared, i.e. millisecond precision.

Arguments

input
Type: Any
A representation of a date in any form. See Parse for more information on date parsing and supported date types.
units
Type: String
The precision at which to compare timestamps. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.

Return

Type: Boolean
If the date is the same as the input date the result will be true. If the date is before or after the input date the result will be false. If either date is invalid the result is undefined.

proDate([2015, 10, 15]).isSame([2015, 10, 25]); // false
proDate([2015, 10, 15]).isSame([2015, 10, 25], "month"); // true
proDate([2015, 10, 15]).isSame([2013, 8, 30]); // false
proDate.invalid().isSame([2013, 8, 30]); // undefined
proDate().isSame(NaN); // undefined

isBefore([input[, units]])

Check if the date is before another date by comparing timestamps to a specified precision. If input is omitted the date will be compared to "now". If units are omitted the full timestamps will be compared, i.e. millisecond precision.

Arguments

input
Type: Any
A representation of a date in any form. See Parse for more information on date parsing and supported date types.
units
Type: String
The precision at which to compare timestamps. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.

Return

Type: Boolean
If the date is before the input date the result will be true. If the date is the same as or after the input date the result will be false. If either date is invalid the result is undefined.

proDate([2015, 10, 15]).isBefore([2015, 10, 25]); // true
proDate([2015, 10, 15]).isBefore([2015, 10, 25], "month"); // false
proDate([2015, 10, 15]).isBefore([2013, 8, 30]); // false
proDate.invalid().isBefore([2013, 8, 30]); // undefined
proDate().isBefore(NaN); // undefined

isAfter([input[, units]])

Check if the date is after another date by comparing timestamps to a specified precision. If input is omitted the date will be compared to "now". If units are omitted the full timestamps will be compared, i.e. millisecond precision.

Arguments

input
Type: Any
A representation of a date in any form. See Parse for more information on date parsing and supported date types.
units
Type: String
The precision at which to compare timestamps. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.

Return

Type: Boolean
If the date is after the input date the result will be true. If the date is the same as or before the input date the result will be false. If either date is invalid the result is undefined.

proDate([2015, 10, 15]).isAfter([2015, 10, 25]); // false
proDate([2015, 10, 15]).isAfter([2015, 10, 25], "month"); // false
proDate([2015, 10, 15]).isAfter([2013, 8, 30]); // true
proDate.invalid().isAfter([2013, 8, 30]); // undefined
proDate().isAfter(NaN); // undefined

isBetween([input1[, input2[, units]]])

Check if the date is between two other dates by comparing timestamps to a specified precision. If either input1 or input2 is omitted they will each default to "now". If units are omitted the full timestamps will be compared, i.e. millisecond precision. The range defined by input1 and input2 is start inclusive, end exclusive. This means that the date will be considered to be in between if it is exactly the same as input1 but not if it is exactly the same as input2.

Arguments

input1
Type: Any
A representation of a date in any form. See Parse for more information on date parsing and supported date types.
input2
Type: Any
A representation of a date in any form. See Parse for more information on date parsing and supported date types.
units
Type: String
The precision at which to compare timestamps. Must be one of the following units: year[s], month[s], day[s], hour[s], minute[s], second[s], millisecond[s],week[s], quarter[s]. Units are case-insensitive, plural forms are optional.

Return

Type: Boolean
If the date is the same as or after the input1 date and before the input2 date the result will be true. If the date is before the input1 date or is the same as or after the input2 date the result will be false. If any of the dates are invalid the result is undefined.

proDate([2014, 6, 15]).isBetween([2014, 6, 7], [2014, 6, 23]); // true
proDate([2014, 6, 15]).isBetween([2014, 6, 7], [2014, 6, 23], "month"); // true
proDate([2014, 6, 15]).isBetween([2014, 6, 21], [2014, 6, 23], "day"); // false
proDate.invalid().isBetween([2014, 6, 21], [2014, 6, 23]); // undefined
proDate().isBetween(NaN, NaN); // undefined

isValid()

Check if the ProDate is valid. A ProDate is valid if the internal Date is valid. Invalid ProDate instances can be created by using the invalid() method or by parsing invalid input, or can be invalidated using the invalidate() method.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is valid true, else false.

proDate().isValid(); // true
proDate(NaN).isValid(); // false
proDate.invalid().isValid(); // false

isLocal()

Check if the ProDate is in local mode. In local mode the internal Date is interpreted in the client's local time.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is in local mode true, else if the date is in UTC or offset mode false.

proDate().isLocal(); // true
proDate.utc().isLocal(); // false
proDate().offset(180).isLocal(); // false

isUTC()

Check if the ProDate is in UTC mode. In UTC mode the internal Date is interpreted in UTC.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is in UTC mode true, else if the date is in local or offset mode false.

proDate().isUTC(); // false
proDate.utc().isUTC(); // true
proDate().offset(180).isUTC(); // false

isOffset()

Check if the ProDate is in offset mode. In offset mode the internal Date is interpreted with a fixed offset from UTC.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is in offset mode true, else if the date is in local or UTC mode false.

proDate().isOffset(); // false
proDate.utc().isOffset(); // false
proDate().offset(180).isOffset(); // true

isDST()

Check if the date is in Daylight Savings Time. For local dates in some locales DST might be in affect for dates in the summer months in which case the time zone offset will usually be one hour ahead of standard time.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is in Daylight Savings Time true, else if the date is in Standard Time false. A ProDate in UTC or offset mode will always return false.

proDate([2015, 1, 1]).isDST(); // false
proDate([2015, 7, 1]).isDST(); // true

isWeekend()

Check if the date is a weekend day, i.e. Saturday or Sunday.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is Saturday or Sunday true, else false.

proDate("Thu, 09 Apr 2015", "ddd, DD MMM YYYY").isWeekend(); // false
proDate("Sat, 18 Apr 2015", "ddd, DD MMM YYYY").isWeekend(); // true

isLeapYear()

Check if the date is in a leap year.

Arguments

This method does not accept any arguments.

Return

Type: Boolean
If the date is in a leap year true, else false.

proDate("09 Aug 2015", "DD MMM YYYY").isLeapYear(); // false
proDate("09 Aug 2016", "DD MMM YYYY").isLeapYear(); // true

daysInMonth()

Get the number of days in the month.

Arguments

This method does not accept any arguments.

Return

Type: Number
The number of days in the month or NaN if invalid.

proDate([2016, 2]).daysInMonth(); // 29 (leap year)
proDate([2016, 3]).daysInMonth(); // 31
proDate.invalid().daysInMonth(); // NaN

daysInYear()

Get the number of days in the year.

Arguments

This method does not accept any arguments.

Return

Type: Number
The number of days in the year or NaN if invalid.

proDate([2015]).daysInYear(); // 365
proDate([2016]).daysInYear(); // 366 (leap year)
proDate.invalid().daysInYear(); // NaN

ISOWeeksInYear()

Get the number of ISO weeks in the year. An ISO week year has 52 or 53 full weeks.

Arguments

This method does not accept any arguments.

Return

Type: Number
The number of ISO weeks in the year or NaN if invalid.

proDate([2012]).ISOWeeksInYear(); // 52
proDate([2015]).ISOWeeksInYear(); // 53
proDate.invalid().ISOWeeksInYear(); // NaN

min([input1[, input2[, ...[, inputN]]]])

Get the earliest ProDate from all the input dates.

Arguments

inputN
Type: Any
Any number of representations of dates in any form. See Parse for more information on date parsing and supported date types. Inputs are passed to prodate(). Existing ProDate instances will be cloned.

Return

Type: ProDate
If one or more arguments are passed the return will always be the earliest valid ProDate or an invalid ProDate if all inputs are invalid. If no arguments are passed an invalidated ProDate is returned.

proDate.min([2012, 4, 3], "2013-07-06T19:12:51+0100", [2012, 7, 14, 2, 54]).toString(); // "2012-04-03T00:00:00+0100"

max([input1[, input2[, ...[, inputN]]]])

Get the latest ProDate from all the input dates.

Arguments

inputN
Type: Any
Any number of representations of dates in any form. See Parse for more information on date parsing and supported date types. Inputs are passed to prodate(). Existing ProDate instances will be cloned.

Return

Type: ProDate
If one or more arguments are passed the return will always be the latest valid ProDate or an invalid ProDate if all inputs are invalid. If no arguments are passed an invalidated ProDate is returned.

proDate.min([2012, 4, 3], "2013-07-06T19:12:51+0100", [2012, 7, 14, 2, 54]).toString(); // "2013-07-06T19:12:51+0100"

isProDate(input)

Check if the input is a ProDate.

Arguments

input
Type: Any
Anything.

Return

Type: Boolean
If the input is a ProDate returns true, else false.

proDate.isProDate(proDate()); // true
proDate.isProDate(null); // false

isValidProDate(input)

Check if the input is a ProDate and isValid() is true.

Arguments

input
Type: Any
Anything.

Return

Type: Boolean
If the input is a valid ProDate returns true, else false.

proDate.isValidProDate(proDate()); // true
proDate.isValidProDate(proDate(NaN)); // false

format()

Get the name of the format used to parse and print models.

Arguments

This method does not accept any arguments.

Return

Type: String
The format name.

proDate().format(); // "ProDate"
proDate("Tuesday, 14 April 2015", "l, j F Y", null, "PHP").format(); // "PHP"
]

queryModel([model[, format]])

Get meta data about a format model. The following information is returned:

  • An array of character literals in the order they appear.
  • The date parts present with an array of corresponding format elements.
  • hasDate, hasTime, hasMeridiem and hasTimeZone flags.

Arguments

model
Type: String
A string literal that uses predefined format elements as placeholders for data, used to map data from the string input to the internal Date. If this argument is omitted the default model is used.
units
Type: String
The Format defining the elements that can be used in the model. If this argument is omitted the default format is used.

Return

Type: Object
An object containing model meta data.

// Query the default model using the default format
proDate.queryModel();
/*
{
    year: ["YYYY"],
    hasDate: true,
    character: ["-", "-", "T", ":", ":"],
    monthPadded: ["MM"],
    dayOfMonthPadded: ["DD"],
    hourPadded: ["HH"],
    hasTime: true,
    minutePadded: ["mm"],
    secondPadded: ["ss"],
    timezone: ["ZZ"],
    hasTimeZone: true
}
*/
// Query a PHP model
proDate.queryModel("l, d F Y", "PHP");
/*
{
    dayName: ["l"],
    hasDate: true,
    character: [","],
    dayOfMonthPadded: ["d"],
    monthName: ["F"],
    year: ["Y"]
}
*/

Names

monthName([letterCase])

Get the full month name in the current locale, optionally converted to lower case or upper case.

Arguments

letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The month name or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate("Thu, 09 Apr 2015", "ddd, DD MMM YYYY").monthName(); // April
proDate("Sat, 18 Apr 2015", "ddd, DD MMM YYYY").locale("fr").monthName("upper"); // "AVRIL"
proDate(NaN).monthName(); // "Invalid date"
proDate.invalid().monthName(); // ""

monthNameShort([letterCase])

Get the shortened month name in the current locale, optionally converted to lower case or upper case.

Arguments

letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The month name or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate("Thu, 09 Apr 2015", "ddd, DD MMM YYYY").monthNameShort(); // Apr
proDate("Sat, 18 Apr 2015", "ddd, DD MMM YYYY").locale("fr").monthNameShort("upper"); // "AVR"
proDate(NaN).monthNameShort(); // "Invalid date"
proDate.invalid().monthNameShort(); // ""

dayName([letterCase])

Get the full day name in the current locale, optionally converted to lower case or upper case.

Arguments

letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The day name or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate("Thu, 09 Apr 2015", "ddd, DD MMM YYYY").dayName(); // Thursday
proDate("Sat, 18 Apr 2015", "ddd, DD MMM YYYY").locale("fr").dayName("upper"); // "SAMEDI"
proDate(NaN).dayName(); // "Invalid date"
proDate.invalid().dayName(); // ""

dayNameShort([letterCase])

Get the shortened day name in the current locale, optionally converted to lower case or upper case.

Arguments

letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The shortened day name or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate("Thu, 09 Apr 2015", "ddd, DD MMM YYYY").dayNameShort(); // Thu
proDate("Sat, 18 Apr 2015", "ddd, DD MMM YYYY").locale("fr").dayNameShort("upper"); // "SAM"
proDate(NaN).dayNameShort(); // "Invalid date"
proDate.invalid().dayNameShort(); // ""

dayNameMin([letterCase])

Get the two letter day name in the current locale, optionally converted to lower case or upper case.

Arguments

letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The shortened day name or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate("Thu, 09 Apr 2015", "ddd, DD MMM YYYY").dayNameMin(); // Th
proDate("Sat, 18 Apr 2015", "ddd, DD MMM YYYY").locale("fr").dayNameMin("upper"); // "SA"
proDate(NaN).dayNameMin(); // "Invalid date"
proDate.invalid().dayNameMin(); // ""

meridiemLower([punc])

Get the meridiem indicator in lower case (am or pm), optionally with punctuation.

Arguments

punc
Type: Boolean
If true the meridiem indicator uses punctuation, e.g. "a.m.", "p.m.".

Return

Type: String
The meridiem indicator in lower case or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate([2012, 2, 18, 14, 26]).meridiemLower(); // "pm"
proDate([2012, 2, 18, 7, 26]).meridiemLower(true); // "a.m."
proDate(NaN).meridiemLower(); // "Invalid date"
proDate.invalid().meridiemLower(); // ""

meridiemUpper([punc])

Get the meridiem indicator in upper case (AM or PM), optionally with punctuation.

Arguments

punc
Type: Boolean
If true the meridiem indicator uses punctuation, e.g. "A.M.", "P.M.".

Return

Type: String
The meridiem indicator in upper case or a localised "Invalid date" string if invalid or an empty string if invalidated.

proDate([2012, 2, 18, 14, 26]).meridiemUpper(); // "PM"
proDate([2012, 2, 18, 7, 26]).meridiemUpper(true); // "A.M."
proDate(NaN).meridiemUpper(); // "Invalid date"
proDate.invalid().meridiemUpper(); // ""

Customise

prototype

The ProDate prototype is exposed through proDate.fn. The methods and properties of the prototype, even those you add yourself, are shared by all ProDate instances, even those that have already been created. This feature is useful if you need to add your own functionality.

// Create a custom method that adds 1 week to the date
proDate.fn.nextWeek = function () {
    return this.add(1, "week");
};
proDate("2015-04-03", "ISO_DATE").nextWeek().toString(); // "2015-04-10"

defaults

Default values for model, locale, format and strict are exposed through proDate.defaults. These default values are used when creating ProDate instances with omitted arguments.

// Get default values
proDate.defaults;
/*
{
    model: "ISO_DATETIME",
    locale: "en",
    format: "ProDate",
    strict: false
}
*/
// Set new default locale
proDate.defaults.locale = "fr";
proDate().dayName(); // "mercredi"

debug

Debug logging can be enabled for parsing, printing and querying models using the proDate.debug property. Debug messages will be output to the console. By default debug logging is disabled.

proDate.debug = true;

presets

Preset models are stored in the proDate.presets object. These models can be used as shortcuts to avoid having to remember complex models that you use frequently. You can update the existing models or add your own. Preset models always use the ProDate format, regardless of the instance format. When a preset model name is passed as a model argument, the parser uses the preset model in its place as long as the model argument matches the preset model name exactly.

// Get presets
proDate.presets;
/*
{
    ISO_FULL: "YYYY-MM-DDTHH:mm:ss.SSSZ",
    ISO_DATETIME: "YYYY-MM-DDTHH:mm:ssZ",
    ISO_DATE: "YYYY-MM-DD",
    ISO_TIME: "HH:mm:ssZ",
    ISO_WEEK: "GGGG-^WWW",
    ISO_WEEKDATE: "GGGG-^WWW-E",
    ISO_ORDINAL: "YYYY-DDDD",
    ATOM: "YYYY-MM-DDTHH:mm:ssZ",
    W3C: "YYYY-MM-DDTHH:mm:ssZ",
    RSS: "ddd, DD MMM YYYY HH:mm:ss Z",
    COOKIE: "ddd, DD-MMM-YYYY HH:mm:ss Z"
}
*/
// Using a preset as a substitution string
proDate().toString("ISO_DATE"); // "2015-04-27"

Locales

A Locale defines the set of strings required by ProDate in a given language. Locales are identified by language[-country] keys and have integral methods for retrieving sets of strings or individual strings. The default language for the Locale object is English - any string not present in another Locale will be in English.

locale()

See also: locale(id), locale(id, data)

Get the default locale object.

Arguments

This method does not accept any arguments.

Return

Type: Locale
A locale object or undefined if the default locale does not exist.

proDate.locale(); // The default locale

locale(id)

See also: locale(), locale(id, data)

Get a locale object.

Arguments

id
Type: String
A locale ID using the same syntax used by the HTTP Accept-Language header, i.e. an ISO 639-1 language code optionally followed by a hyphen separated ISO 3166-1 alpha-2 country code. Examples: en-gb English (United Kingdom), es-ar Spanish (Argentina), fi Finnish.

Return

Type: Locale
A locale object or undefined if a locale with the defined id does not exist.

proDate.locale("en"); // The English Locale
proDate.locale("fr"); // The French Locale
proDate.locale("unknown"); // undefined

locale(id, data)

See also: locale(), locale(id)

Create a new locale.

Arguments

id
Type: String
The locale ID using the same syntax used by the HTTP Accept-Language header, i.e. an ISO 639-1 language code optionally followed by a hyphen separated ISO 3166-1 alpha-2 country code. Examples: en-gb English (United Kingdom), es-ar Spanish (Argentina), fi Finnish. If a locale with the same ID already exists it will be overwritten.
data
Type: Object
An object containing localised versions of the following strings:
  • Month names "January", "February" etc.
  • Short month names "Jan", "Feb" etc.
  • Day names "Monday", "Tuesday" etc.
  • Short day names "Mon", "Tue" etc.
  • Minimum day names "Mo", "Tu" etc.
  • Meridiem indicator variants "A.M.", "pm" etc.
  • Radix point typically comma "," or dot "."
  • Invalid date
Omitted strings will be substituted with English equivalents.

Return

Type: Locale
The created locale object.

// Create a French locale, defaulting to English for omitted meridiem, radix point and invalid date strings
proDate.locale("fr", {
    monthName: ["janvier", "février", "mars", "avril", "mai", "juin", "juillet", "août", "septembre", "octobre", "novembre", "décembre"],
    monthNameShort: ["jan", "fév", "mar", "avr", "mai", "jun", "jul", "aoû", "sep", "oct", "nov", "déc"],
    dayName: ["dimanche", "lundi", "mardi", "mercredi", "jeudi", "vendredi", "samedi"],
    dayNameShort: ["dim", "lun", "mar", "mer", "jeu", "ven", "sam"],
    dayNameMin: ["di", "lu", "ma", "me", "je", "ve", "sa"]
});

monthName()

See also: monthName(index [, letterCase])

Get the set of full month names.

Arguments

This method does not accept any arguments.

Return

Type: Array
The set of full month names.

proDate.locale("en").monthName(); // ["January", "February", ...]

monthName(index[, letterCase])

See also: monthName()

Get the full month name for a specific month, optionally in lower or upper case.

Arguments

index
Type: Number
A month number between 1 and 12.
letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The full month name or undefined if index exceeds the permitted range.

proDate.locale("en").monthName(4); // "April"
proDate.locale("en").monthName(6, "lower"); // "june"
proDate.locale("en").monthName(10, "upper"); // "OCTOBER"
proDate.locale("en").monthName(0); // undefined

monthNameShort()

See also: monthNameShort(index [, letterCase])

Get the set of shortened month names.

Arguments

This method does not accept any arguments.

Return

Type: Array
The set of shortened month names.

proDate.locale("en").monthNameShort(); // ["Jan", "Feb", ...]

monthNameShort(index[, letterCase])

See also: monthNameShort()

Get the shortened month name for a specific month, optionally in lower or upper case.

Arguments

index
Type: Number
A month number between 1 and 12.
letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The shortened month name or undefined if index exceeds the permitted range.

proDate.locale("en").monthNameShort(4); // "Apr"
proDate.locale("en").monthNameShort(6, "lower"); // "jun"
proDate.locale("en").monthNameShort(10, "upper"); // "OCT"
proDate.locale("en").monthNameShort(0); // undefined

dayName()

See also: dayName(index [, letterCase])

Get the set of full day names.

Arguments

This method does not accept any arguments.

Return

Type: Array
The set of full day names.

proDate.locale("en").dayName(); // ["Monday", "Tuesday", ...]

dayName(index[, letterCase])

See also: dayName()

Get the full day name for a specific day of the week using JavaScript or ISO indexing, optionally in lower or upper case.

Arguments

index
Type: Number
A day of the week number between 0 and 7. Because both JavaScript and ISO day of the week numbers are supported 0 and 7 both represent Sunday.
letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The full day name or undefined if index exceeds the permitted range.

proDate.locale("en").dayName(3); // "Wednesday"
proDate.locale("en").dayName(0, "lower"); // "sunday"
proDate.locale("en").dayName(7, "upper"); // "SUNDAY"
proDate.locale("en").dayName(8); // undefined

dayNameShort()

See also: dayNameShort(index [, letterCase])

Get the set of shortened day names.

Arguments

This method does not accept any arguments.

Return

Type: Array
The set of shortened day names.

proDate.locale("en").dayNameShort(); // ["Mon", "Tue", ...]

dayNameShort(index[, letterCase])

See also: dayNameShort()

Get the shortened day name for a specific day of the week using JavaScript or ISO day of the week numbers, optionally in lower or upper case.

Arguments

index
Type: Number
A day of the week number between 0 and 7. Because both JavaScript and ISO day of the week numbers are supported 0 and 7 both represent Sunday.
letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The shortened day name or undefined if index exceeds the permitted range.

proDate.locale("en").dayNameShort(3); // "Wed"
proDate.locale("en").dayNameShort(0, "lower"); // "sun"
proDate.locale("en").dayNameShort(7, "upper"); // "SUN"
proDate.locale("en").dayNameShort(8); // undefined

dayNameMin()

See also: dayNameMin(index [, letterCase])

Get the set of two-letter day names.

Arguments

This method does not accept any arguments.

Return

Type: Array
The set of two-letter day names.

proDate.locale("en").dayNameMin(); // ["Mo", "Tu", ...]

dayNameMin(index[, letterCase])

See also: dayNameMin()

Get the two-letter day name for a specific day of the week using JavaScript or ISO day of the week numbers, optionally in lower or upper case.

Arguments

index
Type: Number
A day of the week number between 0 and 7. Because both JavaScript and ISO day of the week numbers are supported 0 and 7 both represent Sunday.
letterCase
Type: String
Either "lower" or "upper". Defines if the string should be lower case or upper case. If omitted the string is not modified.

Return

Type: String
The two-letter day name or undefined if index exceeds the permitted range.

proDate.locale("en").dayNameMin(3); // "We"
proDate.locale("en").dayNameMin(0, "lower"); // "su"
proDate.locale("en").dayNameMin(7, "upper"); // "SU"
proDate.locale("en").dayNameMin(8); // undefined

meridiem()

See also: meridiem(index [, upper] [, punc])

Get the set of meridiem indicator variants, including upper and lower case, with and without punctuation.

Arguments

This method does not accept any arguments.

Return

Type: Array
The set of meridiem indicator variants.

proDate.locale("en").meridiem(); // ["am", "pm", "AM", "PM", "a.m.", "p.m.", "A.M.", "P.M."]

meridiem(index[, upper[, punc]])

See also: meridiem()

Get a reduced set of meridiem indicators or a specific one.

Arguments

index
Type: Number
A meridiem number, either 0 (AM) or 1 (PM). If this argument is null both strings will be returned.
upper
Type: Boolean
If true returns upper case variants.
punc
Type: Boolean
If true returns punctuated variants.

Return

Type: String | Array
If index is not null the meridiem indicator or undefined if index exceeds the permitted range. If index is null an array containing both meridiem indicators.

proDate.locale("en").meridiem(null); // ["am", "pm"]
proDate.locale("en").meridiem(null, true); // ["AM", "PM"]
proDate.locale("en").meridiem(null, false, true); // ["a.m.", "p.m."]
proDate.locale("en").meridiem(null, true, true); // ["A.M.", "P.M."]
proDate.locale("en").meridiem(0); // "am"
proDate.locale("en").meridiem(0, true); // "AM"
proDate.locale("en").meridiem(1, false, true); // "p.m."
proDate.locale("en").meridiem(1, true, true); // "P.M."

radixPoint()

Get the radix point. The radix point (or radix character) is the symbol used in numerical representations to separate the integer part of a number (to the left of the radix point) from its fractional part (to the right of the radix point). In most cases this is either a comma "," or dot ".". When working with dates the radix point is useful for printing fractional seconds.

Arguments

This method does not accept any arguments.

Return

Type: String
The radix point.

proDate.locale("en").radixPoint(); // "."
proDate.locale("fr").radixPoint(); // ","

invalidDate()

Get the text displayed for invalid dates.

Arguments

This method does not accept any arguments.

Return

Type: String
The text displayed for invalid dates.

proDate.locale("en").invalidDate(); // "Invalid date"

Formats

The primary purpose of a Format is to define the special character sequences that can be used in a model to map data between strings and dates. A ProDate format consists of a dictionary of such mappings plus preset models, special characters used for escaping literal characters and other settings that can configure the parser. The ProDate parser has been created specifically to handle different formats, so that ProDate end-users can use the format with which they are most familiar and/or integrates best with their existing codebase.

format()

See also: format(id), format(id, data)

Get the default format object.

Arguments

This method does not accept any arguments.

Return

Type: Format
A format object or undefined if the default format does not exist.

proDate.format(); // The default format

format(id)

See also: format(), format(id, data)

Get a format object.

Arguments

id
Type: String
A format name.

Return

Type: Format
A format object or undefined if a format with the defined id does not exist.

proDate.format("PHP"); // The PHP format
proDate.format("unknown"); // undefined

format(id, data)

See also: format(), format(id)

Create a new format for parsing and printing.

Arguments

id
Type: String
The format name.
data
Type: Object
An object containing format elements and settings:
  • Dictionary a mapping of format elements to date parts
  • Presets predefined models
  • Escape characters for escaping literal characters
  • Other settings for controlling parsing

Return

Type: Format
The created format object.

// Create a custom format for parsing and printing dates
// The following is a copy of the ProDate format
proDate.format("MyFormat", {
    // The dictionary defines mappings from format elements (special character sequences) to date parts
    // Any characters or sequence of characters not found in the dictionary are considered literal
    dictionary: {
        D: "dayOfMonth",
        DD: "dayOfMonthPadded",
        dddd: "dayName",
        ddd: "dayNameShort",
        dd: "dayNameMin",
        M: "month",
        MM: "monthPadded",
        MMMM: "monthName",
        MMM: "monthNameShort",
        YYYY: "year",
        DDD: "dayOfYear",
        DDDD: "dayOfYearPadded",
        a: "meridiemLower",
        A: "meridiemUpper",
        h: "hour12",
        hh: "hour12Padded",
        H: "hour",
        HH: "hourPadded",
        m: "minute",
        mm: "minutePadded",
        s: "second",
        ss: "secondPadded",
        S: "decisecond",
        SS: "centisecond",
        SSS: "millisecond",
        X: "epoch",
        Z: "timeZoneColon",
        ZZ: "timeZone",
        GGGG: "ISOWeekYear",
        W: "ISOWeek",
        WW: "ISOWeekPadded",
        E: "ISODayOfWeek",
        e: "dayOfWeek",
        Q: "quarter"
    },
    // Special characters used for escaping character and string literals
    literal: {
        start "[", // Marks the start of a string literal
        end "]", // Marks the end of a string literal
        escape "^" // Escapes any single character including itself
    }
});

ProDate

The default format, loosely based on LDML syntax. To use the ProDate (if not set as the default format) format pass "ProDate" as the format argument or set as the default format.

Elements

Format elements are characters or sequences of characters, used in models, that are substituted with values when dates are parsed or output. The ProDate format uses the following elements:

ElementMeaningValues
DDay of month1...31
DDDay of month (padded)01...31
DDDDay of year1...366
DDDDDay of year (padded)001...366
ddDay name (minimum)Su...Sa
dddDay name (short)Sun...Sat
ddddDay nameSunday...Saturday
MMonth1...12
MMMonth (padded)01...12
MMMMonth name (short)Jan...Dec
MMMMMonth nameJanuary...December
YYYYYear1000...9999
aMeridiem (lowercase)am or pm
aaMeridiem (lowercase with punctuation)a.m. or p.m.
AMeridiem (uppercase)AM or PM
AAMeridiem (uppercase with punctuation)A.M. or P.M.
hHour (12 hour clock)1...12
hhHour (12 hour clock, padded)01...12
HHour (24 hour clock)0...23
HHHour (24 hour clock, padded)00...23
mMinute0..59
mmMinute (padded)00...59
sSecond0...59
ssSecond (padded)00...59
SDecisecond0...9
SSCentisecond0...99
SSSMillisecond0...999
XUnix epoch (seconds)-999999999999...999999999999
ZTime zone±HHmm or Z
ZZTime zone (with colon)±HH:mm or Z
eDay of week0...6 (0 = Sunday)
EISO day of week1...7 (1 = Monday)
WISO week0...53
WWISO week (padded)00...53
GGGGISO week year1000...9999
QQuarter1...4

Literals

Any character or sequence of characters that is not an element or escape sequence will be parsed literally. To escape characters or sequences of characters that are elements or escape sequences but should be parsed literally, use the following escape sequences:

ElementMeaning
[Literal start
]Literal end
^Escape single character

Oracle

A format based on the Oracle Datetime Format. To use the Oracle format pass "Oracle" as the format argument or set as the default format.

Elements

Format elements are characters or sequences of characters, used in models, that are substituted with values when dates are parsed or output. The Oracle format uses the following elements:

ElementMeaningValues
Case-sensitive The letter case of the element will be used by the parser to modify or match string values.
DYDay name (short)Sun...Sat
DAYDay nameSunday...Saturday
MONMonth name (short)Jan...Dec
MONTHMonth nameJanuary...December
AM
PM
Meridiemam or pm
A.M.
P.M.
Meridiem (with punctuation)a.m. or p.m.
Case-insensitive The letter case of the element will be ignored by the parser.
DDDay of month1...31
DDDDay of year1...366
MMMonth1...12
YYYYYear1000...9999
HH
HH12
Hour (12 hour clock)1...12
HH24Hour (24 hour clock)0...23
MIMinute0..59
SSSecond0...59
FF1Decisecond0...9
FF2Centisecond0...99
FF, FF3Millisecond0...999
TZHTime zone hours±HH24
TZMTime zone minutesMI
DISO day of week1...7 (1 = Monday)
IWISO week (padded)00...53
IYYYISO week year1000...9999
QQuarter1...4
XRadix point. or ,
FMFormat modifierToggles padding of numeric fields
FXFormat exactToggles strict mode

Literals

Any character or sequence of characters that is not an element or escape sequence will be parsed literally. To escape characters or sequences of characters that are elements or escape sequences but should be parsed literally, use the following escape sequences:

ElementMeaning
"Literal start
"Literal end

PHP

A format based on PHP date functions. To use the PHP format pass "PHP" as the format argument or set as the default format.

Elements

Format elements are characters or sequences of characters, used in models, that are substituted with values when dates are parsed or output. The PHP format uses the following elements:

ElementMeaningValues
jDay of month1...31
dDay of month (padded)01...31
zDay of year1...366
doyDay of year (padded)001...366
DDay name (short)Sun...Sat
lDay nameSunday...Saturday
nMonth1...12
mMonth (padded)01...12
MMonth name (short)Jan...Dec
FMonth nameJanuary...December
YYear1000...9999
aMeridiem (lowercase)am or pm
AMeridiem (uppercase)AM or PM
gHour (12 hour clock)1...12
hHour (12 hour clock, padded)01...12
GHour (24 hour clock)0...23
HHour (24 hour clock, padded)00...23
iMinute (padded)00...59
sSecond (padded)00...59
UUnix epoch (seconds)-999999999999...999999999999
OTime zone±HHmm or Z
PTime zone (with colon)±HH:mm or Z
wDay of week0...6 (0 = Sunday)
NISO day of week1...7 (1 = Monday)
WISO week (padded)00...53
oISO week year1000...9999

Literals

Any character or sequence of characters that is not an element or escape sequence will be parsed literally. To escape characters or sequences of characters that are elements or escape sequences but should be parsed literally, use the following escape sequences:

ElementMeaning
\Escape single character (backslash must be escaped in JavaScript, i.e. \\