JavaScript Date Instance Methods (v3.3 December 2011)

Looking for version 2?

Contents

1. Introduction
2. Demo
3. Github Repository
4. Download
5. Examples
6. Method Reference
7. Parsable Formats
8. Format Codes
9. Customization and I18n
10. Unit Tests

contents ^

Introduction

This script provides JavaScript Date instance methods for parsing, formatting, and calculating dates. It leverages the existing functionality of the native Date.parse method and uses a concise and configurable algorithm for interpreting format codes.

Contributions are welcome through my Github Repository

Features include:

1. Parse various formats with ability to register custom format parsing.
2. Format dates using the well-known percent-letter formatting options with the ability to register custom formating.
3. Add and subtract years, months, days, hours, minutes or seconds.
4. Calculate differences between dates in the given unit.
5. Methods are available on all Date Objects.

contents ^

Demo

contents ^

Download

• Date.js (source)
• Date.min.js (minified)

contents ^

Examples

$D('2006-09-20').strftime('%m/%d/%Y'); // "09/20/2006"
$D('Sep 20 2006').add(3).strftime('%Y-%m-%d'); // "2006-09-23"
$D('09/20/2006').add(4, 'years').strftime('%Y-%m-%d'); // "2010-09-20"
$D('09/20/2006 20:15:00').add(4, 'hours').format('%Y-%m-%d %H:%M:%S'); // "2006-09-21 00:15:00"
$D('2006-09-20').format('m/d/Y'); // "09/20/2006"
$D('2006.09.28').diff('20 Sep, 2006', 'days'); // 8

contents ^

Full Reference

contents ^

Parsable Formats

• 5/29/2007
• 05/29/2007
• 5-29-2007
• 05-29-2007
• Oct 29, 2007
• October 29, 2007
• October the 29th
• October 29th
• 29 Oct 2007
• 29-Oct-2007
• 29 October 2007
• 29-October-2007
• 2007-10-29
• 29.10.2007
• 29/10/2007
• date 02:30:59.005
• date 02:30:59
• date 02:30
• date 2:30:59am
• date 2:30am
• date 2am
• 2:30:59am
• 2:30am
• 2am
• 2010-03-15T12:34:56.005
• Thu, 21 Dec 2000 16:01:07 +0200 (RFC 2822 format)
• 2010-03-15T12:34:56+01:00 (full ISO 8601)
• @1312132465 (Unix Timestamp)
• 2 weeks before date
• 2 years after date
• 2 days ago
• in 2 months
• yesterday
• today
• tomorrow
• last Thursday
• this Thursday
• last month
• now

Note: all formats are case insensitive.

contents ^

Format Codes

*Note: formatSql() codes may be uppercase or lowercase.

contents ^

Customization

This library allows you to customize month/day names, parsing patterns and format characters.

Parsing patterns

Add new pattern strings or functions to the array defined in Data.create.patterns. See source for more examples.

Date.addPattern(['month-year', /^(\d{1,2})-(\d{4})$/, '$1/01/$2']); // match month-year
Date.addPattern(['hoy', /^hoy$/i, function(match) { return new Date(); }], 'iso_8601'); // match Spanish word for `today`

Remove a pattern

Date.removePattern('us'); // us-style m/d/Y dates no longer recognized

var us = Date.removePattern('us');
Date.addPattern(us, 'world'); // prefer world-style d/m/Y dates over us-style dates

Internationalize Month/day names

Simply set the static members of the Date object.

Date.MONTHNAMES = 'Enero Febrero Marzo Abril Mayo Junio Julio Agosto Septiembre Octubre Noviembre Diciembre'.split(' '),
Date.DAYNAMES   = 'Domingo Lunes Martes Miércoles Jueves Viernes Sábado'.split(' '),

Format characters

Add new characters and character patterns and a method to call them. Here is a snippet from the source.

Date.addFormat('formatPhp', {
//
// 2-part regex matcher for format codes
//
// first match must be the character before the code (to account for escaping)
// second match must be the format code character(s)
//
matcher: /(\\)?([a-z])/i,
defaultFormat: 'Y-m-d H:i:s',
codes: {
	// year
	Y: 'FullYear',
	// ...
	O: 'UTCOffsetNumber'
},
//
// shortcuts that will be translated into their longer version
//
// be sure that format shortcuts do not refer to themselves: this will cause an infinite loop
//
shortcuts: {
	// iso
	c: 'Y-m-d\\TH:i:sP',
	// rfc 2822
	r: 'D, j M Y H:i:s O'
}
});