JsSimpleDateFormat   v1.0
Author: AT Mulyana                          9 May 2008

Table of Contents

• Description
• Date and Time Patterns
• Class JsSimpleDateFormat
• Class JsDateFormatSymbols
• Bugs Report

Description

JsSimpleDateFormat is for formatting Date object to be a string as the pattern we define and also for parsing a string to be a Date object based on the defined pattern. JsSimpleDateFormat works similar with Java SimpleDateFormat class which uses the same pattern letters with similar rules. If you have been familiar with Java SimpleDateFormat class, you should be able to use JsSimpleDateFormat easily.

This library contains two main classes, those are JsSimpleDateFormat and JsDateFormatSymbols. (We still use Class term, even if in the fact, Javascript doesn't have class in its grammar).

Date and Time Patterns

As mentioned above, JsSimpleDateFormat uses the same pattern letters with similar rules as used by Java SimpleDateFormat class. To make the same comprehension, the explanation about the pattern letters here is copied from Java (TM) 2 Platform Standard Edition 5.0 API Specification with some modifications and additions. Java (TM) 2 Platform Standard Edition 5.0 API Specification is copyrighted by Sun Microsystems, Inc.

Note: There are some differences between JsSimpleDateFormat and Java SimpleDateFormat class:

• If there is a letter ('a' to 'z' or 'A' to 'Z') in the pattern which doesn't have a representation (not listed in the list below), such as B, Java SimpleDateFormat class will raise error. JsSimpleDateFormat, however, will not interpret that letter but will show that letter as is. Single quote (') is still be used to avoid interpretation. "''" represents a single quote.
• Letter z and Z are not implemented yet by JsSimpleDateFormat.
• JsSimpleDateFormat always uses strict parser. If using Java SimpleDateFormat class, you must invoke setLenient method by passing false as parameter. In the fact, JsSimpleDateFormat is more strict. With pattern "EEE, MMM d, yyyy", Java SimpleDateFormat class will parse "Mon, Feb 1, 2008" successfully. But in the fact, it's Friday. JsSimpleDateFormat will not allow it. I think, it's better to force the users to be aware about their fault.
• JsSimpleDateFormat has a new property, that is flexWhiteSpace. By this property, the user may type any number of space even if in the pattern, there is only one (or another number) space for that position. If this property is set to false (by default), the user must type the exact number of spaces as written in the pattern.

The list of the pattern letters:

Letter	Date or Time Component	Presentation	Examples
G	Era designator	Text	AD
y	Year	Year	1996; 96
M	Month in year	Month	July; Jul; 07
w	Week in year	Number	27
W	Week in month	Number	2
D	Day in year	Number	189
d	Day in month	Number	10
F	Day of week in month	Number	2
E	Day in week	Text	Tuesday; Tue
a	Am/pm marker	Text	PM
H	Hour in day (0-23)	Number	0
k	Hour in day (1-24)	Number	24
K	Hour in am/pm (0-11)	Number	0
h	Hour in am/pm (1-12)	Number	12
m	Minute in hour	Number	30
s	Second in minute	Number	55
S	Millisecond	Number	978

Pattern letters are usually repeated, as their number determines the exact presentation:

• Text: For formatting, if the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available.
  For parsing, both forms are accepted, independent of the number of pattern letters.
• Number: For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this amount.
  For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields.
• Year: For formatting, if the number of pattern letters is less than 4, the year is truncated to 2 digits; otherwise it is interpreted as a Number.
  NOTE: year 0 means 1 BC, year -1 means 2 BC and so on. So if you set year to 0 then it will be shown as 1, -1 will be shown as 2 and so on. Perhaps, it's better to show era designator field.

  For parsing, if the number of pattern letters is more than 2, the year is interpreted literally, regardless of the number of digits. So using the pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.

  For parsing with the abbreviated year pattern ("y" or "yy"), JsSimpleDateFormat must interpret the abbreviated year relative to some century. The begin of century is set by set2DigitYearStart method. By default, it's 80 years before the JsSimpleDateFormat instance is created. For example, using a pattern of "MM/dd/yy" and the begin of century is 1917, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two characters string that isn't all digits (for example, "-1"), is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC.

• Month: If the number of pattern letters is 3 or more, the month is interpreted as Text; otherwise, it is interpreted as a Number.

Class JsSimpleDateFormat

Constructor

• JsSimpleDateFormat()
  Creates a JsSimpleDateFormat object using default pattern and default locale. Default pattern is "dd MMMM yyyy hh:mm a" and default locale is English. If you want to change the default pattern, you may create your own class which inherits JsSimpleDateFormat and then overwrite _getDefaultPattern method, like the below one. Suppose the default pattern you want is "MMM dd, yyyy HH:mm a":

  		function MyJsSimpleDateFormat() {
  			JsSimpleDateFormat.apply(this,arguments);
  		}
  		MyJsSimpleDateFormat.__extends__(JsSimpleDateFormat, {
  		_getDefaultPattern: function() {
  			return "MMM dd, yyyy HH:mm a";
  		}
  		});
  	  

  __extends__ method is written in JsSimpleDateFormat.js. If using usual way, we write like this:

  		function MyJsSimpleDateFormat() {
  			JsSimpleDateFormat.apply(this,arguments);
  		}
  		MyJsSimpleDateFormat.prototype = new JsSimpleDateFormat();
  		MyJsSimpleDateFormat.prototype._getDefaultPattern = function() {
  			return "MMM dd, yyyy HH:mm a";
  		}
  	  

• JsSimpleDateFormat(sPattern)
  Creates a JsSimpleDateFormat object using the pattern as written in parameter and using default locale that is English.
  Parameters:
  • sPattern is the pattern for formatting date time that will be used by this object.
• JsSimpleDateFormat(sPattern,sLocale)
  Creates a JsSimpleDateFormat object using the pattern and the locale as defined by parameter.
  Parameters:
  • sPattern is the pattern for formatting date time that will be used by this object.
  • sLocale is the locale code which defines the language that will be used. There are two codes provided by this library, those are en (English) and id (Indonesian). But you can define the new one. For further information, see JsDateFormatSymbols.
• JsSimpleDateFormat(sPattern,oSymbols)
  Creates a JsSimpleDateFormat object using the pattern and the locale as defined by parameter.
  Parameters:
  • sPattern is the pattern for formatting date time that will be used by this object.
  • oSymbols is a JsDateFormatSymbols object which defines the name of days, months etc, which are usually shown in date time information.

Property

• flexWhiteSpace
  It defines the flexibility of white space (space, tab and new line). If set to true then the users can type any number of spaces regardless the number of spaces defined in the pattern for that position. This flexibility makes easier for the users so that they don't need to remember how many spaces they have typed. This setting also ignores the kind of white space (space, tab or new line). By default, the value of this property is false that will parse strictly, the number and the kind of white space. This property must be set before invoking parse method.

Method

• applyPattern(sPattern)
  Applies new pattern for this object. All formatting and parsing hereafter will use the new pattern.
  Parameters:
  • sPattern is the new pattern will be applied.
• format(oDate)
  Formats a Date object using the pattern applied to this object.
  Parameters:
  • oDate is the Date object will be formatted.
  Returns:
  The string representing date time which is the result of formatting.
• get2DigitYearStart()
  Returns the Date object that have been set by set2DigitYearStart method. If set2DigitYearStart method has not been invoked yet, it will return the Date object representing the date time 80 years before this JsSimpleDateFormat object is created.
  Returns:
  The Date object which its year is the begin of century.
• getDateFormatSymbols()
  Returns the JsDateFormatSymbols object used by this object. See setDateFormatSymbols
  Returns:
  The JsDateFormatSymbols object used by this object.
• parse(s)
  Parses a string to be a Date object based on the pattern used by this object. It's possible there will be a missing field in the pattern to construct a complete date time. Perhaps, there is no year or month or day etc. To avoid that, in the beginning of parsing, this method will get the initial date time and then parse and set the appropriate field as found in the string. The initial date time is "January 1, 1970 00:00:00.000" based on your local time. If you want change the initial date time, you may create your own class inherited from JsSimpleDateFormat and overwrite _getInitDate method as below (suppose you want the iniatial date time is the current date time):
  

  		function MyJsSimpleDateFormat() {
  			JsSimpleDateFormat.apply(this,arguments);
  		}
  		MyJsSimpleDateFormat.__extends__(JsSimpleDateFormat, {
  		_getInitDate: function() {
  			return new Date();
  		}
  		});
  	  

  __extends__ method is written in JsSimpleDateFormat.js. If using usual way, we write like this:

  		function MyJsSimpleDateFormat() {
  			JsSimpleDateFormat.apply(this,arguments);
  		}
  		MyJsSimpleDateFormat.prototype = new JsSimpleDateFormat();
  		MyJsSimpleDateFormat.prototype._getInitDate = function() {
  			return new Date();
  		}
  	  

  This method will return null if the string cannot be parsed to be a valid date time. Note, the method may not use the entire text, only a substring positioned at index 0. For example, "Jan 3, 2008 is Thursday" will be parsed successfully using pattern "MMM d, yyyy" even if the remaining string " is Thursday" doesn't match the pattern.

  Parameters:
  • s is a string to be parsed.
  Returns:
  The Date object as the result of parsing or null if the parsing failed.
• parse(s,oPos)
  To parse a string starting at index defined by oPos. If the parsing is successful, this index will be updated to the index after the last character parsed successfully (this method may not parse until the end of string) and the Date object which is the result of parsing is returned. The updated index is useful to determine the starting index for the next parsing. Paramerter oPos is an object whose properties: index and errorIndex. The index property is the starting index as explained before. The errorIndex property will be used if the parsing failed. It notes the index when the error begins to happen. If an error occurs, the index property will not be updated but the errorIndex property will be updated. Example:

  		var oDf = new JsSimpleDateFormat("MMM d, yyyy");
  		var s = "The date of Jan 3, 2008 is Thursday";
  		var oPos = {index: 12, errorIndex: -1};
  		var oDate = oDf.parse(s, oPos);
  	  

  After parsing, index property will be updated become 23. As example above, initiate the value of errorIndex property to -1 because if an error occurs, it will be updated to the non negative value. Negative value will differentiate from the index where the error occurs. So if errorIndex property becomes 0 or higher after parsing then an error occurs. Another clue, this method will return null if the string cannot be parsed to be a valid date time.
  
  If you don't need the return back about index but only want to determine the starting index, you may do it like this:

  		var oDate = oDf.parse(s, {index:3});
  	  

  For further information, see another parse method.

  Parameters:
  • s is a string to be parsed.
  • oPos is an object whose index and error index information as explained above.
  Returns:
  The Date object as the result of parsing or null if parsing is failed.
• set2DigitYearStart(oStartDate)
  Sets the begin of century. It's for parsing two digits year. To get the full year, two digits year must be added to a number that is multiplication of a hundred. This full year will be between the begin of century and 100 years after that. Note, the parameter of this method is not an integer but a Date object. What you must do is to create a Date object and set its year by invoking setFullYear method. Then pass this Date object as parameter.
  Parameters:
  • oStartDate is a Date object which its year is the begin of century.
• setDateFormatSymbols(oFormatSymbols)
  Sets JsDateFormatSymbols object that will be used by this object. JsDateFormatSymbols object determines the name of days, months etc, which are usually shown in date time information. You can create your own JsDateFormatSymbols object and set your own name of days and months. Pass that JsDateFormatSymbols object as the parameter of this method. When a JsSimpleDateFormat object is created, it will create a JsDateFormatSymbols object for it, based on the parameter of constructor.
  Parameters:
  • oFormatSymbols is a JsDateFormatSymbols object to be set.
• toPattern()
  Returns the pattern string used by this object.
  Returns:
  The pattern string used by this object.

Class JsDateFormatSymbols

The objects of this class is to specify the name of days, months and the other keywords which are usually shown in date time information. The JsSimpleDateFormat object uses an object of JsDateFormatSymbols to get all keywords needed either for formatting or for parsing. All JsSimpleDateFormat objects always have a JsDateFormatSymbols object associated to it. When JsSimpleDateFormat object is created, it will also create JsDateFormatSymbols object based on the parameters passed to constructor. This JsDateFormatSymbols object can be obtained by getDateFormatSymbols method. You may also create a new JsDateFormatSymbols object and set it via setDateFormatSymbols method. In other words, you can set the new keywords according to your languange.

Below is an example how to change the keywords:

		var oDf = new JsSimpleDateFormat("MMM d, yyyy");
		var oSymbols = new JsDateFormatSymbols();
		oSymbols.setAmPmStrings(['AM','PM']);
		oSymbols.setEras(['AD','BC']);
		oSymbols.setMonths(['January','February','March','April','May','June','July','August','September','October','November','December']);
		oSymbols.setShortMonths(['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']);
		oSymbols.setShortWeekdays(['Sun','Mon','Tue','Wed','Thu','Fri','Sat']);
		oSymbols.setWeekdays(['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday']);
		oDf.setDateFormatSymbols(oSymbols);
		alert(oDf.format(new Date()));
	

Of course, you should change the words in the example above to be the appropriate words according to your language.

Another Trick
If you want set a code for your language like "en" for English and can pass this code whenever creating JsSimpleDateFormat object, do these steps. Specify the code for you language, suppose you want the code "xx". It should be two letters as specified in http://www.loc.gov/standards/iso639-2/php/English_list.php, but you may choose what you like. Nevermind if for your own. Create a JavaScript file and write the code like the below one inside this JavaScript file.

		JsDateFormatSymbols.__symbols__.xx = {
			amPmStrings: ['AM','PM'],
			eras: ['AD','BC'],
			months: ['January','February','March','April','May','June','July','August','September','October','November','December'],
			shortMonths: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'],
			shortWeekdays: ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'],
			weekdays: ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday']
		};
	

Alter the words in the example above to be the appropriate words according to your language. Insert that JavaScript file in your HTML document after inserting JsSimpleDateFormat.js.

Method

• getAmPmStrings()
  Returns:
  Array of "AM" and "PM" text.
• getEras()
  Returns:
  Array of era designators (English: "AD" and "BC").
• getMonths()
  Returns:
  Array of month names.
• getShortMonths()
  Returns:
  Array of abbreviated month names.
• getShortWeekdays()
  Returns:
  Array of abbreviated day names.
• getWeekdays()
  Returns:
  Array of day names.
• setAmPmStrings(arAmPmStrings)
  Sets "AM" and "PM" text.
  Parameters:
  • arAmPmStrings is an array of "AM" and "PM" text. "AM" is the first elements.
• setEras(arEras)
  Sets era designators (English: "AD" and "BC").
  Parameters:
  • arEras is an array of era designators. The first element is the designator which is the same as "AD".
• setMonths(arMonths)
  Sets the month names.
  Parameters:
  • arMonths is an array of the month names, the first until the twelfth month.
• setShortMonths(arShortMonths)
  Sets the abbreviated month names.
  Parameters:
  • arShortMonths is an array of the abbreviated month names, the first until the twelfth month. The abbreviated month name usually consists of three letters.
• setShortWeekdays(arShortWeekdays)
  Sets the abbreviated day names.
  Parameters:
  • arShortWeekdays is an array of the abbreviated day names. Sunday is the first element. The abbreviated day name usually consists of three letters.
• setWeekdays(arWeekdays)
  Sets the day names.
  Parameters:
  • arWeekdays an array of the day names. Sunday is the first element.

Bugs Report

You may send bug reports to [email protected].