com.metsci.glimpse.util.units.time.format

Class TimeStampFormatStandard

java.lang.Object

com.metsci.glimpse.util.units.time.format.TimeStampFormatStandard

All Implemented Interfaces:

TimeStampFormat, Cloneable

public class TimeStampFormatStandard
extends Object
implements TimeStampFormat

Formats and parses TimeStamps according to a specified format string, in the spirit of trusty old printf. This is similar to SimpleDateFormat, but with a few improvements:

• Instances are thread-safe
• Fractional seconds are handled more intuitively
• Time-zone is associated with the format, not with the date/time object
• Formatting options are specified printf-style (e.g. %3S instead of SSS)

The following format terms are defined:

Letter	Description
y	Year
M	Month number (1-12)
N	Month name
d	Day of month (1-31)
j	Day of year (1-366)
H	Hour in day (0-23)
m	Minute in hour (0-59)
S	Second in minute (includes fractional part)
s	Whole second in minute (floored toward zero)
z	Timezone name

A good basic example is TimeStampFormat.iso8601:

Format	Output
%y-%M-%dT%H:%m:%SZ	2008-06-11T13:40:12.5439231Z

Any characters not inside a format term -- such as the "T", "Z", dashes, and colons in the above example -- will simply show up in as literals in the output string. Just like printf. So if you want date and time separated by a space, and "UTC" instead of "Z":

Format	Output
%y-%M-%d %H:%m:%S UTC	2008-06-11 13:40:12.5439231 UTC

To make text fields all uppercase or all lowercase, use ^ or /:

Format	Output
%N	January
%^N	JANUARY
%/N	january

For a two-digit year (see note below), use 2:

Format	Output
%y	2008
%2y	08

To abbreviate the text month, use 3:

Format	Output
%N	January
%3N	Jan

To change padding of numeric fields, use <, >, or !:

Format	Output
%H:%m	04:10
%<H:%m	4 :10
%>H:%m	4:10
%!H:%m	4:10

Specify the number of decimal places used by %S with a digit:

Format	Output
%S	12.5439231
%3S	12.544

Other features that would be nice:

• text day of week (%E --> Tuesday, %3E --> Tue)
• hour in am/pm (1-12)
• am/pm

Two-Digit Years

When parsing a two-digit year, the result is shifted to fall between baseYear and baseYear+99. The default base year is 1970. To explicitly specify a base year, use one of the constructors that take a base-year argument.

Rollover and the %S Field

The %S field is special: its precision affects when other fields (potentially all of them) roll over to the next value. For instance, for the time 1999/12/31 23:59:59.999, note how every field can change, solely because of a change in the precision of the %S field.

Format	Output
%y-%M-%d %H:%m:%S	1999/12/31 23:59:59.999
%y-%M-%d %H:%m:%0S	2000/01/01 00:00:00

If a format string does not contain a %S field, other fields will behave as though there were a full-precision %S.

If (for some strange reason) a format string contains multiple %S fields, the precision of the rightmost one is used for figuring rollover.

Field Summary

Fields inherited from interface com.metsci.glimpse.util.units.time.format.TimeStampFormat

iso8601

Constructor Summary

Constructors

Constructor and Description
TimeStampFormatStandard(String format, String timeZoneName)
TimeStampFormatStandard(String format, String timeZoneName, int baseForTwoDigitYears)
TimeStampFormatStandard(String format, TimeZone timeZone)
TimeStampFormatStandard(String format, TimeZone timeZone, int baseForTwoDigitYears)

Method Summary

Modifier and Type	Method and Description
String	format(BigDecimal posixSeconds)
com.metsci.glimpse.util.units.time.format.TimeStampFormatStandard.Field	newField(char code, String flags)
BigDecimal	parse(String string)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeStampFormatStandard

public TimeStampFormatStandard(String format,
                               String timeZoneName)

TimeStampFormatStandard

public TimeStampFormatStandard(String format,
                               String timeZoneName,
                               int baseForTwoDigitYears)

TimeStampFormatStandard

public TimeStampFormatStandard(String format,
                               TimeZone timeZone)

TimeStampFormatStandard

public TimeStampFormatStandard(String format,
                               TimeZone timeZone,
                               int baseForTwoDigitYears)

Method Detail

newField

public com.metsci.glimpse.util.units.time.format.TimeStampFormatStandard.Field newField(char code,
                                                                                        String flags)

parse

public BigDecimal parse(String string)

Specified by:

parse in interface TimeStampFormat

Returns:

seconds since the epoch

format

public String format(BigDecimal posixSeconds)

Specified by:

format in interface TimeStampFormat

Returns:

a date-time string, formatted according to this format