TOTimestampFormat is a concrete class for formatting and
* parsing dates in a locale-sensitive manner. It allows for formatting
* (date -> text), parsing (text -> date), and normalization.
*
*
* TOTimestampFormat allows you to start by choosing
* any user-defined patterns for date-time formatting. However, you
* are encouraged to create a date-time formatter with either
* getTimeInstance, getDateInstance, or
* getDateTimeInstance in DateFormat. Each
* of these class methods can return a date/time formatter initialized
* with a default format pattern. You may modify the format pattern
* using the applyPattern methods as desired.
* For more information on using these methods, see
* {@link DateFormat}.
*
*
* Date and time formats are specified by date and time pattern
* strings.
* Within date and time pattern strings, unquoted letters from
* 'A' to 'Z' and from 'a' to
* 'z' are interpreted as pattern letters representing the
* components of a date or time string.
* Text can be quoted using single quotes (') to avoid
* interpretation.
* "''" represents a single quote.
* All other characters are not interpreted; they're simply copied into the
* output string during formatting or matched against the input string
* during parsing.
*
* The following pattern letters are defined (all other characters from
* 'A' to 'Z' and from 'a' to
* 'z' are reserved):
*
** Pattern letters are usually repeated, as their number determines the * exact presentation: **
** 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** z*Time zone * General time zone * Pacific Standard Time;PST;GMT-08:00** Z*Time zone * RFC 822 time zone * -0800*
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"),
* TOTimestampFormat must interpret the abbreviated year
* relative to some century. It does this by adjusting dates to be
* within 80 years before and 20 years after the time the TOTimestampFormat
* instance is created. For example, using a pattern of "MM/dd/yy" and a
* TOTimestampFormat instance created on Jan 1, 1997, 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, as defined by
* {@link Character#isDigit(char)}, 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 digit 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.
*
* GMTOffsetTimeZone: ** Hours must be between 0 and 23, and Minutes must be between * 00 and 59. The format is locale independent and digits must be taken * from the Basic Latin block of the Unicode standard. *GMTSign Hours:Minutes * Sign: one of *+ -* Hours: * Digit * Digit Digit * Minutes: * Digit Digit * Digit: one of *0 1 2 3 4 5 6 7 8 9
For parsing, RFC 822 time zones are also * accepted. *
* RFC822TimeZone: * Sign TwoDigitHours Minutes * TwoDigitHours: * Digit Digit* TwoDigitHours must be between 00 and 23. Other definitions * are as for general time zones. *
For parsing, general time zones are also * accepted. *
TOTimestampFormat also supports localized date and time
* pattern strings. In these strings, the pattern letters described above
* may be replaced with other, locale dependent, pattern letters.
* TOTimestampFormat does not deal with the localization of text
* other than the pattern letters; that's up to the client of the class.
* * *
** **
** Date and Time Pattern * Result * * "yyyy.MM.dd G 'at' HH:mm:ss z"*2001.07.04 AD at 12:08:56 PDT** "EEE, MMM d, ''yy"*Wed, Jul 4, '01** "h:mm a"*12:08 PM** "hh 'o''clock' a, zzzz"*12 o'clock PM, Pacific Daylight Time** "K:mm a, z"*0:08 PM, PDT** "yyyyy.MMMMM.dd GGG hh:mm aaa"*02001.July.04 AD 12:08 PM** "EEE, d MMM yyyy HH:mm:ss Z"*Wed, 4 Jul 2001 12:08:56 -0700** "yyMMddHHmmssZ"*010704120856-0700** "yyyy-MM-dd'T'HH:mm:ss.SSSZ"*2001-07-04T12:08:56.235-0700*
* Date formats are not synchronized.
* It is recommended to create separate format instances for each thread.
* If multiple threads access a format concurrently, it must be synchronized
* externally.
*
* @see Java Tutorial
* @see java.util.Calendar
* @see java.util.TimeZone
* @see DateFormat
* @see DateFormatSymbols
* @version 1.77, 01/22/04
* @author Mark Davis, Chen-Lieh Huang, Alan Liu
*/
public class TOTimestampFormat extends java.text.SimpleDateFormat {
/** COPIED FROM SimpleDateFormat!
* Constructs a TOTimestampFormat using the default pattern and
* date format symbols for the default locale.
* Note: This constructor may not support all locales.
* For full coverage, use the factory methods in the {@link DateFormat}
* class.
*/
public TOTimestampFormat() {
super();
}
/** COPIED FROM SimpleDateFormat!
* Constructs a TOTimestampFormat using the given pattern and
* the default date format symbols for the default locale.
* Note: This constructor may not support all locales.
* For full coverage, use the factory methods in the {@link DateFormat}
* class.
*
* @param pattern the pattern describing the date and time format
* @exception NullPointerException if the given pattern is null
* @exception IllegalArgumentException if the given pattern is invalid
*/
public TOTimestampFormat(String pattern) {
super(pattern);
}
/** COPIED FROM SimpleDateFormat!
* Constructs a TOTimestampFormat using the given pattern and
* the default date format symbols for the given locale.
* Note: This constructor may not support all locales.
* For full coverage, use the factory methods in the {@link DateFormat}
* class.
*
* @param pattern the pattern describing the date and time format
* @param locale the locale whose date format symbols should be used
* @exception NullPointerException if the given pattern is null
* @exception IllegalArgumentException if the given pattern is invalid
*/
public TOTimestampFormat(String pattern, Locale locale) {
super(pattern, locale);
}
/** COPIED FROM SimpleDateFormat!
* Constructs a TOTimestampFormat using the given pattern and
* date format symbols.
*
* @param pattern the pattern describing the date and time format
* @param formatSymbols the date format symbols to be used for formatting
* @exception NullPointerException if the given pattern or formatSymbols is null
* @exception IllegalArgumentException if the given pattern is invalid
*/
public TOTimestampFormat(String pattern, DateFormatSymbols formatSymbols) {
super(pattern, formatSymbols);
}
/** COPIED FROM SimpleDateFormat!
* Parses text from a string to produce a NSTimestamp.
*
* The method attempts to parse text starting at the index given by
* pos.
* If parsing succeeds, then the index of pos is updated
* to the index after the last character used (parsing does not necessarily
* use all characters up to the end of the string), and the parsed
* date is returned. The updated pos can be used to
* indicate the starting point for the next call to this method.
* If an error occurs, then the index of pos is not
* changed, the error index of pos is set to the index of
* the character where the error occurred, and null is returned.
*
* See the {@link #parse(String, ParsePosition)} method for more information
* on date parsing.
*
* @param source A String, part of which should be parsed.
* @param pos A ParsePosition object with index and error
* index information as described above.
* @return A Date parsed from the string. In case of
* error, returns null.
* @exception NullPointerException if pos is null.
*/
public Object parseObject(String source, ParsePosition pos) {
return new NSTimestamp((Date)super.parseObject(source, pos));
}
/**
* Parses text from the beginning of the given string to produce a date.
* The method may not use the entire text of the given string.
*
* See the {@link #parse(String, ParsePosition)} method for more information
* on date parsing.
*
* @param source A String whose beginning should be parsed.
* @return A Date parsed from the string.
* @exception ParseException if the beginning of the specified string
* cannot be parsed.
*/
public NSTimestamp parse(String source) throws ParseException
{
return new NSTimestamp(super.parse(source));
}
}