org.das2.datum.TimeUtil

Various time utilities

YEAR

MONTH

DAY

HOUR

MINUTE

SECOND

MILLI

MICRO

NANO

WEEK

QUARTER

HALF_YEAR

TD_YEAR

TD_MONTH

TD_DAY

TD_HOUR

TD_MINUTE

TD_SECOND

TD_MILLI

TD_MICRO

TD_NANO

add

add( org.das2.datum.TimeUtil.TimeStruct a, org.das2.datum.TimeUtil.TimeStruct b ) → TimeStruct

Parameters

a - a TimeUtil.TimeStruct
b - a TimeUtil.TimeStruct

Returns:

org.das2.datum.TimeUtil.TimeStruct

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

borrow

borrow( org.das2.datum.TimeUtil.TimeStruct t ) → TimeStruct

Normalize the TimeStruct by decrementing higher digits.

Parameters

t - the time.

Returns:

the normalized TimeStruct

See Also:

normalize(org.das2.datum.TimeUtil.TimeStruct)


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

carry

carry( org.das2.datum.TimeUtil.TimeStruct t ) → TimeStruct

Normalize the TimeStruct by incrementing higher digits. For example, 2002-01-01T24:00 → 2002-01-02T00:00. This will only carry one to the next higher place, so 70 seconds is handled but not 130. 2015-09-08: this now supports leap seconds.

Parameters

t - a time structure

Returns:

a time structure where extra minutes are moved into hours, etc.

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

ceil

ceil( int step, Datum datum ) → Datum

return the next ordinal boundary if we aren't at one already.

Parameters

step - the ordinal location, such as TimeUtil.DAY or TimeUtil.HALF_YEAR
datum - the location.

Returns:

the next ordinal boundary if we aren't at one already.

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

convert

convert( int year, int month, int day, int hour, int minute, double second, org.das2.datum.TimeLocationUnits units ) → double

convert the month components to a double in the given units.

Parameters

year - the year, which must be greater than 1582
month - the month
day - the day of month, unless month==0, then day is day of year.
hour - additional hours
minute - additional minutes
second - additional seconds
units - the Units in which to return the result.

Returns:

a double in the given units.

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

create

create( String s ) → Datum

Creates a datum from a string

Parameters

s - a String

Returns:

a Datum

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

createTimeDatum

createTimeDatum( int year, int month, int day, int hour, int minute, int second, int nano ) → Datum

creates a Datum representing the time given in integer years, months, ..., seconds, nanoseconds. The year must be at least 1000, and must be a four-digit year. A double in Units.us2000 is used to represent the Datum, so resolution will drop as the year drops away from 2000.

Parameters

year - four digit year >= 1060.
month - integer month, 1..12.
day - integer day of month.
hour - additional hours
minute - additional minutes
second - additional seconds
nano - additional nanoseconds

Returns:

a Datum with units Units.us2000.

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

createValid

createValid( String validString ) → Datum

creates a Datum from a string which is known to contain a valid time format. Throws a RuntimeException if the string is not valid.

Parameters

validString - a String

Returns:

a Datum

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

dayContaining

dayContaining( Datum t ) → DatumRange

return a DatumRange for the day containing the given time. Midnight is contained within the following day.

Parameters

t - a time.

Returns:

the day containing the time.

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

dayOfYear

dayOfYear( int month, int day, int year ) → int

return the day of year for the month and day, for the given year

Parameters

month - the month, january=1, february=2, etc.
day - day of month
year - four-digit year

Returns:

the day of year

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

daysInMonth

daysInMonth( int month, int year ) → int

Parameters

month - an int
year - an int

Returns:

int

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

floor

floor( int step, Datum datum ) → Datum

return the previous ordinal boundary if we aren't at one already.

Parameters

step - the ordinal location, such as TimeUtil.DAY or TimeUtil.HALF_YEAR
datum - the location.

Returns:

the previous ordinal boundary if we aren't at one already.

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

fromDatum

fromDatum( Datum time ) → int[]

returns the 7-element array of components from the time location datum: 0:year, 1:month, 2:day, 3:hour, 4:minute, 5:second, 6:nanoseconds Note special care is taken to not use units conversions which introduce noise into the numbers, so the following units are handled directly: cdfTT2000, cdfEpoch, us2000, and mj1958. Also, a separate leap seconds table provides the leap seconds, since these are easily managed within code, removing the external dependence on a file.

Parameters

time - a Datum

Returns:

seven-element int array.

See Also:

fromJulianDayAndOffset(int, int, int)
lastLeapSecond(org.das2.datum.Datum) which uses similar code and is not used because Java doesn't have tuple results.


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

getJulianDay

getJulianDay( Datum datum ) → int

return the the integer number of days that have elapsed since roughly Monday, January 1, 4713 BC. Julian Day is defined as starting at noon UT, here is is defined starting at midnight.

Parameters

datum - a Datum

Returns:

an int

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

getJulianDay( long val, Units units ) → int

getMicroSecondsSinceMidnight

getMicroSecondsSinceMidnight( Datum datum ) → double

return the number of microseconds elapsed since the last midnight.

Parameters

datum - a Datum

Returns:

a double

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

getSecondsSinceMidnight

getSecondsSinceMidnight( Datum datum ) → double

return the number of seconds elapsed since the last midnight.

Parameters

datum - a Datum

Returns:

a double

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

isLeapYear

isLeapYear( int year ) → boolean

return the leap year for years 1901-2099.

Parameters

year - an int

Returns:

a boolean

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

isValidTime

isValidTime( String string ) → boolean

check to see if the string is parseable as a time.

Parameters

string - any string

Returns:

true if the string is clearly a time.

See Also:

create(java.lang.String)


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

julianDay

julianDay( int year, int month, int day ) → int

return the julianDay for the year month and day. This was verified against another calculation (julianDayWP, commented out above) from http://en.wikipedia.org/wiki/Julian_day. Both calculations have 20 operations. Note this does not match

Parameters

year - calendar year greater than 1582.
month - an int
day - day of month. For day of year, use month=1 and doy for day.

Returns:

the Julian day

See Also:

julianToGregorian


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

julianDayIMCCE

julianDayIMCCE( int YY, int MM, int DD ) → int

calculation of julianDay based on http://www.imcce.fr/en/grandpublic/temps/jour_julien.php This is slightly slower because of a cusp at 1582, but is accurate before these times.

Parameters

YY - Gregorian year
MM - Gregorian month
DD - Gregorian day

Returns:

an int

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

julianToGregorian

julianToGregorian( int julian ) → TimeStruct

Break the Julian day apart into month, day year. This is based on http://en.wikipedia.org/wiki/Julian_day (GNU Public License), and was introduced when toTimeStruct failed when the year was 1886.

Parameters

julian - the (integer) number of days that have elapsed since the initial epoch at noon Universal Time (UT) Monday, January 1, 4713 BC

Returns:

a TimeStruct with the month, day and year fields set.

See Also:

julianDay( int year, int mon, int day )


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

lastLeapSecond

lastLeapSecond( Datum t ) → Datum

returns the instant after the last leap second. So for example, lastLeapSecond(datum('2020-01-01T00:00')) → datum('2017-01-01T00:00Z') This code is introduced only to provide some transparency to leap second handling. Note that leap seconds before 1970-01-01 are not supported. Note that most time units do not include leap seconds, so TimeUtil.lastLeapSecond(datum('2016-12-31T23:60Z')) uses us2000 internally and the result is 2017-01-01T00:00Z, not 2015-01-01T00:00Z as one might expect.

Parameters

t - a time after 1970-01-01

Returns:

the instant after the last leap second.

See Also:

fromDatum which uses similar code. which uses similar code.


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

main

main( java.lang.String[][] args ) → void

Parameters

args - a java.lang.String[]

Returns:

void (returns nothing)

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

monthNameAbbrev

monthNameAbbrev( int mon ) → String

returns "Jan", "Feb", ... for month number (1..12).

Parameters

mon - integer from 1 to 12.

Returns:

three character English month name.

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

monthNumber

monthNumber( String s ) → int

returns 1..12 for the English month name. (Sorry, rest of world...)

Parameters

s - the three-letter month name, jan,feb,...,nov,dec

Returns:

1,2,...,11,12 for the English month name

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

next

next( org.das2.datum.TimeUtil.TimeDigit td, int count, Datum datum ) → Datum

return the next boundary

Parameters

td - the boundary, e.g. TimeUtil.TD_HALF_YEAR
count - the number of boundaries
datum - the starting point.

Returns:

the boundary

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

next( int step, Datum datum ) → Datum

nextMidnight

nextMidnight( Datum datum ) → Datum

provide the next midnight, similar to the ceil function, noting that if the datum provided is midnight already then it is simply returned.

Parameters

datum - a Datum

Returns:

the Datum for the next day boundary.

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

nextMonth

Deprecated: Use next(MONTH,datum) instead

normalize

normalize( org.das2.datum.TimeUtil.TimeStruct t ) → TimeStruct

convert times like "2000-01-01T24:00" to "2000-01-02T00:00" and "2000-002T00:00" to "2000-01-02T00:00". This will only carry one to the next higher place, so 70 seconds is handled but not 130.

Parameters

t - a TimeUtil.TimeStruct

Returns:

an org.das2.datum.TimeUtil.TimeStruct

See Also:

borrow(org.das2.datum.TimeUtil.TimeStruct)


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

now

now( ) → Datum

return the current time as a Datum.

Returns:

the current time as a Datum.

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

parseTime

parseTime( String s ) → TimeStruct

parse the time into a timestruct.

Parameters

s - a String

Returns:

an org.das2.datum.TimeUtil.TimeStruct

See Also:

createValid(java.lang.String) createValid which creates a Datum.


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

prev

prev( int step, Datum datum ) → Datum

step down the previous ordinal. If the datum is already at an ordinal boundary, then step down by one ordinal.

Parameters

step - the ordinal location, such as TimeUtil.DAY or TimeUtil.HALF_YEAR
datum - the location.

Returns:

the prev boundary location.

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

prevMidnight

prevMidnight( Datum datum ) → Datum

provide the previous midnight, similar to the floor function, noting that if the datum provided is midnight exactly then it is simply returned.

Parameters

datum - a Datum

Returns:

the Datum for the next day boundary.

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

prevWeek

prevWeek( Datum datum ) → Datum

decrement by 7 days.

Parameters

datum - a Datum

Returns:

the datum

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

rangeContaining

rangeContaining( int count, int step, DatumRange tr ) → DatumRange

return the hours or minutes or days interval containing the time range, or multiple spans of this when the given range spans boundaries. For example, rangeContaining(1,TimeUtil.DAY,datumRange('2024-07-17T23:30/2024-07-18T00:30')) would be '2024-07-17/2024-07-19'.

Parameters

count - an int
step - the ordinal unit, such as TimeUtil.DAY or TimeUtil.HALF_YEAR
tr - the timerange

Returns:

the range containing the interval.

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

rangeContaining( int count, int step, Datum t ) → DatumRange

roundNDigits

roundNDigits( org.das2.datum.TimeUtil.TimeStruct ts, int n ) → TimeStruct

round seconds to N decimal places. For example, n=3 means round to the millisecond.

Parameters

ts - a time structure
n - number of digits, 3 is millis, 6 is micros.

Returns:

rounded and normalized TimeStruct.

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

subtract

subtract( org.das2.datum.TimeUtil.TimeStruct a, org.das2.datum.TimeUtil.TimeStruct b ) → TimeStruct

Parameters

a - a TimeUtil.TimeStruct
b - a TimeUtil.TimeStruct

Returns:

org.das2.datum.TimeUtil.TimeStruct

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

toDatum

toDatum( org.das2.datum.TimeUtil.TimeStruct d ) → Datum

convert to Datum without regard to the type of unit used to represent time. This will use the canonical Units.us2000 for time locations, which does not represent leap seconds.

Parameters

d - the decomposed time or time width.

Returns:

the Datum.

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

toDatum( org.das2.datum.TimeUtil.TimeStruct d, Units u ) → Datum
toDatum( int[][] timeArray ) → Datum
toDatum( int[][] timeArray, Units u ) → Datum

toDatumDuration

toDatumDuration( int[][] timeArray ) → Datum

return approximate duration in Units.seconds or in Units.days. This is assuming a year is 365 days, a month is 30 days, and a day is 86400 seconds.

Parameters

timeArray - 6 or 7 element array [ yrs, months, days, hours, minutes, seconds, nanos ]

Returns:

a Datum

See Also:

DatumRangeUtil#parseISO8601Duration(java.lang.String)


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

toTimeArray

Deprecated: use 7-element fromDatum instead, which is consistent with toDatum. Note the array elements are different!

toTimeStruct

toTimeStruct( org.das2.datum.Datum.Long datum ) → TimeStruct

splits the time location datum into y,m,d,etc components, using the full precision of the Long backing the Datum. The datum can have the units of ms1970 or cdf_tt2000, and

Parameters

datum - with time location units.

Returns:

TimeStruct containing the time components.

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

toTimeStruct( Datum datum ) → TimeStruct