NSTimestampFormatter

Inherits from:
java.text.Format : Object

Package:
com.webobjects.foundation

Class Description

Instances of NSTimestampFormatter format NSTimestamps into their textual representations and convert textual representations of dates and times into NSTimestamps. You can express the representation of dates and times very flexibly: "Thu 22 Dec 1994" is just as acceptable as "12/22/94".

You can associate an date pattern with a WOString or WOTextField dynamic element. WebObjects uses an NSTimestampFormatter object to perform the appropriate conversions.

You can also create an NSTimestampFormatter with the constructor, provide a date pattern string, and use java.text.Format's format and parseObject methods to convert between NSTimestamps and their textual representations:


NSTimestampFormatter formatter = new NSTimestampFormatter("%m/%d/%y");
String description = formatter.format(myNSTimestamp);


NSTimestampFormatter formatter = new NSTimestampFormatter("%m/%d/%y");
NSTimestamp myNSTimestamp = formatter.parseObject(myTimestampString);

Instances of NSTimestampFormatter are immutable.

The Calendar Pattern

You must specify a pattern whenever you create a NSTimestampFormatter. This pattern is a string that contains specifiers that are very similar to those used in the standard C library function strftime(). When NSTimestampFormatter converts a date to a string, it uses this pattern.

The date conversion specifiers cover a range of date conventions:

Specifier	Description
`%%`	a `'%'` character
`%a`	abbreviated weekday name
`%A`	full weekday name
`%b`	abbreviated month name
`%B`	full month name
`%c`	shorthand for "`%X %x`", the locale format for date and time
`%d`	day of the month as a decimal number (01-31)
`%e`	same as `%d` but does not print the leading 0 for days 1 through 9
`%F`	milliseconds as a decimal number (000-999)
`%H`	hour based on a 24-hour clock as a decimal number (00-23)
`%I`	hour based on a 12-hour clock as a decimal number (01-12)
`%j`	day of the year as a decimal number (001-366)
`%m`	month as a decimal number (01-12)
`%M`	minute as a decimal number (00-59)
`%p`	AM/PM designation for the locale
`%S`	second as a decimal number (00-59)
`%w`	weekday as a decimal number (0-6), where Sunday is 0
`%x`	date using the date representation for the locale
`%X`	time using the time representation for the locale
`%y`	year without century (00-99)
`%Y`	year with century (such as 1990)
`%Z`	time zone name (such as Pacific Daylight Time)
`%z`	time zone offset in hours and minutes from GMT (HHMM)

Alternatively, you can specify the pattern using Sun's date pattern specifiers. See Sun's documentation for the java.text.SimpleDateFormat class for more information.

Converting Date Strings Without Time Zones

When you convert a string without a time zone specification to an NSTimestamp, the formatter assumes the time zone is the default parse time zone (see the defaultParseTimeZone and setDefaultParseTimeZone methods). An analogous time zone, called the default format time zone, is used when converting an NSTimestamp without a time zone to a string.

Sometimes you need to give the user a choice of time zones. For example, you might put the time zones in a pull-down list. In such cases, you can use the parseObjectInUTC method to parse a date string for the UTC time zone. The following code shows how you can compute the offset from UTC for the particular time zone the user chooses and add it to the parsed timestamp:


NSTimestamp date = (NSTimestamp)myFormatter.parseInUTC(myString);
NSTimeZone tz = NSTimeZone.timeZoneWithName(myTimeZoneName);
int offset = tz.secondsFromGMTForTimestamp(date);
long milliseconds = date.getTime() - offset * 1000;
NSTimestamp dateWithTimeZone = new NSTimestamp(milliseconds);

Constructors

NSTimestampFormatter

public NSTimestampFormatter()

Creates a NSTimestampFormatter with the default pattern (%m/%d/%y).

public NSTimestampFormatter(String pattern)

Creates an NSTimestampFormatter with the pattern string pattern. If pattern is null, this constructor uses the default pattern (%m/%d/%y). See "The Calendar Pattern" (page 300) for more information on specifying the pattern string.

public NSTimestampFormatter(String pattern, java.text.DateFormatSymbols formatSymbols)

Creates an NSTimestampFormatter with the specified pattern using the specified date format symbols. If pattern is null, this constructor uses the default pattern (%m/%d/%y) with the slashes replaced by the appropriate date symbol. See "The Calendar Pattern" (page 300) for more information on specifying the pattern string.

public NSTimestampFormatter(String pattern, java.util.Locale locale)

Creates an NSTimestampFormatter with the specified pattern using the date symbols for the specified locale. If pattern is null, this constructor uses the default pattern (%m/%d/%y) with the slashes ("/") replaced by the appropriate date symbol. See "The Calendar Pattern" (page 300) for more information on specifying the pattern string.

Instance Methods

defaultFormatTimeZone

public NSTimeZone defaultFormatTimeZone()

Returns the default time zone the receiver uses for formatting (converting an NSTimestamp into a string). If the default format time zone is not null, the receiver uses the default format time zone when it performs the conversion. Otherwise the receiver uses the time zone of the NSTimestamp that it is converting. The default format time zone itself defaults to null.

See Also: defaultParseTimeZone

defaultParseTimeZone

public synchronized NSTimeZone defaultParseTimeZone()

Returns the default time zone the receiver uses for parsing (converting a string to an NSTimestamp). During the conversion, if the NSTimestamp has a time zone (its timeZone method returns something other than null), the receiver uses the NSTimestamp's time zone. Otherwise the receiver uses the default parse time zone. The default parse time zone itself defaults to the time zone specified by the user.timezone system property.

See Also: defaultFormatTimeZone

format

public StringBuffer format( Object object, StringBuffer toAppendTo, java.text.FieldPosition position)

Formats object to produce a string, appends the string to toAppendTo, and returns the resulting StringBuffer. The position parameter specifies an alignment field to place the formatted object. When the method returns, this parameter contains the position of the alignment field. See Sun's java.text.Format documentation for more information.

parseObjectInUTC

public Object parseObjectInUTC( String source, java.text.ParsePosition status)

Parses a string to produce an object using UTC as the time zone. This method ignores the time zone specified by the string and the value of the parse time zone. For parameter definitions, see Sun's java.text.Format documentation for the parseObject method.

See Also: parseObject

parseObject

public Object parseObject( String source, java.text.ParsePosition status)

Parses a string to produce an object. If the string does not specify a time zone, uses the default parse time zone. See Sun's java.text.Format documentation for more information.

See Also: setDefaultParseTimeZone

pattern

public String pattern()

Returns the receiver's pattern. See "The Calendar Pattern" (page 300) for more information about the pattern.

setDefaultFormatTimeZone

public synchronized void setDefaultFormatTimeZone(NSTimeZone timeZone)

Sets the default time zone the receiver uses for formatting (converting an NSTimestamp into a string) to timeZone.

See Also: setDefaultParseTimeZone

setDefaultParseTimeZone

public synchronized void setDefaultParseTimeZone(NSTimeZone timeZone)

Sets the default time zone the receiver uses for parsing (converting a string to an NSTimestamp) to timeZone.

See Also: setDefaultFormatTimeZone

setPattern

public synchronized void setPattern(String pattern)

Sets the receiver's pattern to pattern. See "The Calendar Pattern" (page 300) for more information about the pattern.

toString

public String toString()

Returns a string representation of the receiver that includes the default format time zone, the default parse time zone, and the pattern.