org.das2.datum

Class TimeParser

java.lang.Object

org.das2.datum.TimeParser

public class TimeParser
extends java.lang.Object

TimeParser designed to quickly parse strings with a known format. This parser has been shown to perform around 20 times faster than the discovery parser. This class is not thread-safe, so clients must make sure that only one thread accesses the class at a time.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TimeParser.EnumFieldHandler "$Y$m$d-$(enum;values=a,b,c,d)", "20130202-a", "2013-02-02/2013-02-03"
static interface	TimeParser.FieldHandler Interface to add custom handlers for strings with unique formats.
static class	TimeParser.HrintervalFieldHandler $(hrinterval;names=a,b,c,d) "b" → "06:00/12:00"
static class	TimeParser.IgnoreFieldHandler Just skip the field.
static class	TimeParser.PeriodicFieldHandler regular intervals are numbered.
static class	TimeParser.SubsecFieldHandler $(subsec;places=6) "36" → "36 microseconds"

Field Summary

Fields

Modifier and Type	Field and Description
static TimeParser.FieldHandler	IGNORE_FIELD_HANDLER handy FieldHandler that ignores the contents.
static java.lang.String	TIMEFORMAT_Z $Y-$m-$dT$H:$M:$S.$(subsec;places=3)Z

Method Summary

Modifier and Type	Method and Description
static TimeParser	create(java.lang.String formatString) Create a TimeParser object, which is the fast time parser for use when a known format specification is used to parse many instances of a formatted string.
static TimeParser	create(java.lang.String formatString, java.lang.String fieldName, TimeParser.FieldHandler handler, java.lang.Object... moreHandler) create the time parser, and add specialized handlers.
java.lang.String	format(Datum start) The TimeParser can be used to format times as well.
java.lang.String	format(Datum start, Datum stop) The TimeParser can be used to format times as well.
java.lang.String	format(Datum start, Datum stop, java.util.Map<java.lang.String,java.lang.String> extra) The TimeParser can be used to format times as well.
java.lang.String	format(DatumRange range) return the formatted range.
double	getEndTime(Units units) return the end time of the range in units, e.g.
TimeParser.FieldHandler	getFieldHandlerByCode(java.lang.String code) return the field handler for the id.
TimeParser.FieldHandler	getFieldHandlerById(java.lang.String id) return the field handler for the id.
static char	getPad(java.util.Map<java.lang.String,java.lang.String> args) return the pad for the spec, like "underscore" "space" "zero" or "none" For "none", space is returned, and clients allowing special behavior should check for this.
java.lang.String	getRegex() peek at the regular expression used.
double	getTime(Units units) return the parsed time in the given units.
Datum	getTimeDatum() return the parsed time as a Datum.
DatumRange	getTimeRange() Returns the implicit interval as a DatumRange.
DatumRange	getValidRange() return the limits of the range we can parse.
boolean	hasField(java.lang.String field) return true if the parser has a field.
static boolean	isIso8601String(java.lang.String exampleTime) return true if the string appears to be an ISO8601 time.
boolean	isNested() return true if each successive field is nested within the previous, e.g.
static java.lang.String	iso8601String(java.lang.String exampleTime) must contain T or space to delimit date and time.
static boolean	isSpec(java.lang.String spec) Provide standard means of indicating this appears to be a spec by looking for something that would assert the year.
boolean	isStartTimeOnly() true if the flag (startTimeOnly) was set in the spec.
static void	main(java.lang.String[] aa)
TimeParser	parse(java.lang.String timeString) parse the string, which presumably contains a time matching the spec.
TimeParser	parse(java.lang.String timeString, java.util.Map<java.lang.String,java.lang.String> extra) attempt to parse the string.
void	setContext(DatumRange tr) explicitly set the context for time parsing.
TimeParser	setDigit(int digitNumber, int digit) This allows for string split into elements to be interpreted here.
void	setDigit(java.lang.String format, double value) set the digit with the integer part, and move the fractional part to the less significant digits.
TimeParser	setDigit(java.lang.String format, int value) Set the digit using the format code.
void	sloppyColumns() force the parser to look for delimiters.
static void	testTimeParser() test time parsing when the format is known.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TIMEFORMAT_Z

public static final java.lang.String TIMEFORMAT_Z

$Y-$m-$dT$H:$M:$S.$(subsec;places=3)Z

See Also:

Constant Field Values

IGNORE_FIELD_HANDLER

public static final TimeParser.FieldHandler IGNORE_FIELD_HANDLER

handy FieldHandler that ignores the contents. For example,

tp= TimeParser.create(sagg,"v", TimeParser.IGNORE_FIELD_HANDLER );

Method Detail

hasField

public boolean hasField(java.lang.String field)

return true if the parser has a field.

Parameters:

field - e.g. "x"

Returns:

true if the parser has a field.

isIso8601String

public static boolean isIso8601String(java.lang.String exampleTime)

return true if the string appears to be an ISO8601 time. This requires that the string contain a "T" or space and the hours and minutes components.

Parameters:

exampleTime - string like "1992-353T02:00"

Returns:

true if the string appears to be an ISO8601 time.

iso8601String

public static java.lang.String iso8601String(java.lang.String exampleTime)

must contain T or space to delimit date and time.

Parameters:

exampleTime - "1992-353T02:00"

Returns:

"$Y-$jT$H$M" etc.

Throws:

java.lang.IllegalArgumentException - if the time does not appear to be ISO8601.

isNested

public boolean isNested()

return true if each successive field is nested within the previous, e.g. $Y$m/$d is nested, but $Y$m/$Y$m$d is not because of the second $Y.

Returns:

true if the spec is nested.

isStartTimeOnly

public boolean isStartTimeOnly()

true if the flag (startTimeOnly) was set in the spec. This is a hint to clients (FileStorageModel) using the time that it shouldn't infer that the time is bounded.

Returns:

isSpec

public static boolean isSpec(java.lang.String spec)

Provide standard means of indicating this appears to be a spec by looking for something that would assert the year.

Parameters:

spec -

Returns:

true if the string appears to be a spec.

create

public static TimeParser create(java.lang.String formatString)

Create a TimeParser object, which is the fast time parser for use when a known format specification is used to parse many instances of a formatted string. For example, this would be used to interpret the times in an text file, but not times entered in a time range GUI to control an axis. This can also be and is used for filenames, for example omni2_h0_mrg1hr_$Y$(m,span=6)01_v01.cdf. Note field lengths are used when formatting the data, but when parsing often fractional components are accepted. For example, the format might be "%Y %j %H", and "2012 365 12.003" is accepted. Note also that often $(Y) is used where %{Y} is used. These are equivalent, and useful when $() interferes with parsing elsewhere. URI_Templates is a public project with translations to Java, JavaScript, and Python, and provides an specification for this. See https://github.com/hapi-server/uri-templates/wiki/Specification .

  $[fieldLength]<1-char code>  or
  $[fieldLength](<code>)
  $[fieldLength](<code>;qualifiers)

  fieldLength=0 --> makes field length indeterminate, deliminator must follow.

  $Y   4-digit year
  $y   2-digit year
  $j   3-digit day of year
  $m   2-digit month
  $b   3-char month name (jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec.  Sorry, rest of world...)
  $d   2-digit day
  $H   2-digit hour
  $M   2-digit minute
  $S   2-digit second
  $(milli)  3-digit milliseconds
  $(ignore) skip this field
  $x   skip this field
  $(enum)  skip this field.  If id is specified, then id can be retrieved.
  $v   skip this field
  $(hrinterval;values=0,1,2,3)  enumeration of part of day
  $(subsec;places=6)  fractional seconds (6->microseconds)
  $(periodic;offset=0;start=2000-001;period=P1D)

 Qualifiers:
    span=<int>
    delta=<int>
    Y=2004  Also for Y,m,d,H,M,S

   For example:
      $(j;Y=2004) means the day-of-year, within the year 2004.
      $(H;Y=2004;j=117) means the hour of day 2004-117
      $(m;span=6) means the 6-month interval starting at the given month.

  

Parameters:

formatString - the format string.

Returns:

the time parser.

create

public static TimeParser create(java.lang.String formatString,
                                java.lang.String fieldName,
                                TimeParser.FieldHandler handler,
                                java.lang.Object... moreHandler)

create the time parser, and add specialized handlers. Note the typical route create(formatString) adds handlers for orbits ($o) and version numbers ($v).

Parameters:

formatString - like $Y$m$dT$H

fieldName - name for the special field, like "o"

handler - handler for the special field, like OrbitFieldHandler

moreHandler - additional name/handler pairs.

Returns:

the configured TimeParser, ready to use.

sloppyColumns

public void sloppyColumns()

force the parser to look for delimiters. This should be called immediately after

parse

public TimeParser parse(java.lang.String timeString)
                 throws java.text.ParseException

parse the string, which presumably contains a time matching the spec. A reference to the TimeParser is returned so operations can be chained together: tp.parse("2014-01-06T02").getTime( Units.us2000 ) Since this the TimeParser has a state, it is not safe to use simultaneously by multiple threads. Each thread should create its own parser.

Parameters:

timeString - string containing a time

Returns:

a reference to this TimeParser object, which now contains the time.

Throws:

java.text.ParseException - if the string cannot be parsed.

parse

public TimeParser parse(java.lang.String timeString,
                        java.util.Map<java.lang.String,java.lang.String> extra)
                 throws java.text.ParseException

attempt to parse the string. The parser itself is returned so that so expressions can be chained like so: parser.parse("2009-jan").getTimeRange()

Parameters:

timeString -

extra - map that is passed into field handlers

Returns:

the TimeParser, call getTimeRange or getTime to get result.

Throws:

java.text.ParseException

getPad

public static char getPad(java.util.Map<java.lang.String,java.lang.String> args)

return the pad for the spec, like "underscore" "space" "zero" or "none" For "none", space is returned, and clients allowing special behavior should check for this.

Parameters:

args -

Returns:

the char, or (char)0.

setDigit

public void setDigit(java.lang.String format,
                     double value)

set the digit with the integer part, and move the fractional part to the less significant digits. Format should contain just one field, see setDigit( String format, int value ) to break up fields.

Parameters:

format - like "Y"

value - like 2014

setDigit

public TimeParser setDigit(java.lang.String format,
                           int value)

Set the digit using the format code. If multiple digits are found, then the integer provided should be the misinterpreted integer. For example, if the format is "%Y%m%d", the integer 20080830 is split apart into 2008,08,30.

Parameters:

format - spec like "%Y%m%d"

value - integer like 20080830.

Returns:

setDigit

public TimeParser setDigit(int digitNumber,
                           int digit)

This allows for string split into elements to be interpreted here. This is to add flexibility to external parsers that have partially parsed the number already. examples: TimeParser p= TimeParser.create("%Y %m %d"); p.setDigit(0,2007).setDigit(1,12).setDigit(2,5).getTime( Units.us2000 ); p.format(); // maybe in the future

Parameters:

digitNumber, - the digit to set (starting with 0).

digit, - value to set the digit.

Returns:

the time parser with the digit set.

Throws:

java.lang.IllegalArgumentException - if the digit has a custom field handler

java.lang.IllegalArgumentException - if the digit does not exist.

setContext

public void setContext(DatumRange tr)

explicitly set the context for time parsing. For example, filenames are just $H$M$S.dat, and the context is "Jan 17th, 2015" Note that the context is stored internally as just a start time, so spans (e.g. 3-day) are not supported.

Parameters:

tr - the range

getTime

public double getTime(Units units)

return the parsed time in the given units. Here Autoplot Jython code shows how this is used: from org.virbo.dataset import SemanticOps tp= TimeParser.create("$Y-$m-$dT$H") u= SemanticOps.lookupTimeUnits("seconds since 2014-01-01T00:00") print tp.parse("2014-01-06T02").getTime( u )

Parameters:

units - as in Units.us2000

Returns:

the value in the given units.

getTimeDatum

public Datum getTimeDatum()

return the parsed time as a Datum. For years less than 1990, Units.us1980 is used, otherwise Units.us2000 is used.

Returns:

a datum representing the parsed time.

getValidRange

public DatumRange getValidRange()

return the limits of the range we can parse. These limits come from orbit files like "$(o,sc=rbspa-pp)" or from explicit fields like "$(M,Y=1999)"

Returns:

getTimeRange

public DatumRange getTimeRange()

Returns the implicit interval as a DatumRange. For example, "Jan 1, 2003" would have a getTimeDatum of "Jan 1, 2003 00:00:00", and getDatumRange() would go from midnight to midnight. This will try to create MonthDatumRanges when possible, to keep it abstract, so for example,

tr= tp.getTimeRange()  // "Jan 2015"
tr= tr.next()          // "Feb 2015", not 31 days starting Feb 1

This accesses time, timeWidth, orbitDatumRange, startTime.

Returns:

the DatumRange

getEndTime

public double getEndTime(Units units)

return the end time of the range in units, e.g. Units.us2000

Parameters:

units -

Returns:

getRegex

public java.lang.String getRegex()

peek at the regular expression used.

Returns:

format

public java.lang.String format(DatumRange range)

return the formatted range. This actually returns the range that contains the min of the given range.

Parameters:

range -

Returns:

format

public java.lang.String format(Datum start)

The TimeParser can be used to format times as well. The resolution or span implicitly defines the end time.

Parameters:

start -

Returns:

formatted string.

format

public java.lang.String format(Datum start,
                               Datum stop)

The TimeParser can be used to format times as well.

Parameters:

start - beginning of the interval

stop - null if not needed or implicit.

Returns:

formatted string.

format

public java.lang.String format(Datum start,
                               Datum stop,
                               java.util.Map<java.lang.String,java.lang.String> extra)

The TimeParser can be used to format times as well.

Parameters:

start - beginning of the interval

stop - null if not needed or implicit.

extra - null or a map of additional identifiers, see enum and x.

Returns:

formatted string.

getFieldHandlerByCode

public TimeParser.FieldHandler getFieldHandlerByCode(java.lang.String code)

return the field handler for the id. For example, enum returns the field handler handling enumerations. Note there is currently only one field handler for each type, so for example two enumerations are not allowed.

Parameters:

code -

Returns:

the field handler.

getFieldHandlerById

public TimeParser.FieldHandler getFieldHandlerById(java.lang.String id)

return the field handler for the id. For example, enum returns the field handler handling enumerations. Note there is currently only one field handler for each type, so for example two enumerations are not allowed.

Parameters:

id - the field handler id

Returns:

the field handler.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

main

public static void main(java.lang.String[] aa)
                 throws java.lang.Exception

Throws:

java.lang.Exception

testTimeParser

public static void testTimeParser()
                           throws java.lang.Exception

test time parsing when the format is known. This time parser is much faster than the time parser of Test009, which must infer the format as it parses.

Throws:

java.lang.Exception