## org.das2.datum.TimeParser

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. It should be given a time template (URI Time Template), which is then used to parse each string into a DatumRange or Datum. For example, in Jython:

    {@code
     tp= TimeParser.create('$-1d $b $Y at $-1H:$M:$S$p')
     d= tp.parse('3 Feb 2026 at 12:24:52am').getTimeDatum()
     print d
     }

This class is not thread-safe, so clients must make sure that only one thread accesses an instance of the class at a time.

## TIMEFORMAT_Z

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

## IGNORE_FIELD_HANDLER

handy FieldHandler that ignores the contents. For example,

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

## create

create( String formatString ) → org.das2.datum.TimeParser

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]()
      $[fieldLength](;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
      $N   9-digit nanoseconds
      $s   non-leap seconds since 1970-01-01T00:00Z
      $(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
      $p   am/pm field
      $z   RFC-822 numeric time zone
      $(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=
        delta=
        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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## create

create( String formatString, String fieldName, org.das2.datum.TimeParser.FieldHandler handler, Object[] moreHandler ) → org.das2.datum.TimeParser

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( DatumRange range ) → String

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

### Parameters

range - a DatumRange

### Returns:

a String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( Datum start ) → String

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

### Parameters

start - a Datum

### Returns:

formatted string.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( Datum start, Datum stop ) → String

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## format

format( Datum start, Datum stop, java.util.Map extra ) → String

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getEndTime

getEndTime( Units units ) → double

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

### Parameters

units - an Units

### Returns:

a double
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getExampleExtra

getExampleExtra( ) → java.util.Map

to get an example formatted time where there are nominal data fields, like enum, we need example values. This supports this.

### Returns:

a java.util.Map
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getExampleExtras

getExampleExtras( ) → java.util.Map

generate extras for fields like enum where only specific values are allowed.

### Returns:

map of extras which can be used with format.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getFieldHandlerByCode

getFieldHandlerByCode( String code ) → org.das2.datum.TimeParser.FieldHandler

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 - a String

### Returns:

the field handler.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getFieldHandlerById

getFieldHandlerById( String id ) → org.das2.datum.TimeParser.FieldHandler

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getPad

getPad( java.util.Map args ) → char

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 - a java.util.Map

### Returns:

the char, or (char)0.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getRegex

getRegex( ) → String

peek at the regular expression used.

### Returns:

a String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTime

getTime( Units units ) → double

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTimeDatum

getTimeDatum( ) → Datum

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getTimeRange

getTimeRange( ) → DatumRange

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
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getValidRange

getValidRange( ) → DatumRange

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:

a DatumRange
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## hasField

hasField( String field ) → boolean

return true if the parser has a field.

### Parameters

field - e.g. "x"

### Returns:

true if the parser has a field.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isIso8601String

isIso8601String( String exampleTime ) → boolean

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isNested

isNested( ) → boolean

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isSpec

isSpec( String spec ) → boolean

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

### Parameters

spec - a String

### Returns:

true if the string appears to be a spec.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isStartTimeOnly

isStartTimeOnly( ) → boolean

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:

a boolean
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## iso8601String

iso8601String( String exampleTime ) → String

must contain T or space to delimit date and time.

### Parameters

exampleTime - "1992-353T02:00"

### Returns:

"$Y-$jT$H$M" etc.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## main

main( String[] aa ) → void

### Parameters

aa - a java.lang.String[]

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( String timeString ) → org.das2.datum.TimeParser

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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## parse

parse( String timeString, java.util.Map extra ) → org.das2.datum.TimeParser

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 - a String
extra - map that is passed into field handlers

### Returns:

the TimeParser, call getTimeRange or getTime to get result.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setContext

setContext( DatumRange tr ) → void

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

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setDigit

setDigit( String format, double value ) → void

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 TODO: %s

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setDigit

setDigit( String format, int value ) → org.das2.datum.TimeParser

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:

TODO: %s
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setDigit

setDigit( int digitNumber, int digit ) → org.das2.datum.TimeParser

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 - an int
digit - an int

### Returns:

the time parser with the digit set.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## sloppyColumns

sloppyColumns( ) → void

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

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## testTimeParser

testTimeParser( ) → void

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.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toString

toString( ) → String

### Returns:

java.lang.String
[search for examples] [view on GitHub] [view on old javadoc] [view source]