## 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 ) → org.das2.datum.TimeUtil.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 ) → org.das2.datum.TimeUtil.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 ) → org.das2.datum.TimeUtil.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

getJulianDay( long val, Units units ) → 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

val - the magnitude
units - Units object identifying the units of the val, such as Units.us2000.

### Returns:

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

## 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 ) → org.das2.datum.TimeUtil.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.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## main

main( 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

next( int step, Datum datum ) → Datum

step to the next ordinal. If the datum is already at an ordinal boundary, then step to the next by one ordinal.

### Parameters

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

### Returns:

the next boundary location.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## 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 ) → org.das2.datum.TimeUtil.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 ) → org.das2.datum.TimeUtil.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

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

return the hour or minute or day

### Parameters

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

### Returns:

the range containing the interval.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## roundNDigits

roundNDigits( org.das2.datum.TimeUtil.TimeStruct ts, int n ) → org.das2.datum.TimeUtil.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 ) → org.das2.datum.TimeUtil.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

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

convert to a Datum with the given units.

### Parameters

d - the decomposed time
u - the target units.

### Returns:

the Datum in the units specified.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toDatum

toDatum( int[] timeArray ) → Datum

get the datum from the 6 or 7 element timeArray. The elements are: 0:year, 1:month, 2:day, 3:hour, 4:minute, 5:second, [ 6:nanoseconds ]

### Parameters

timeArray - an int[]

### Returns:

a datum representing the time.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## toDatum

toDatum( int[] timeArray, Units u ) → Datum

get the time datum from the 6 or 7 element decomposed timeArray. The elements are: 0:year, 1:month, 2:day, 3:hour, 4:minute, 5:second, [ 6:nanoseconds ]

### Parameters

timeArray - an int[]
u - target units.

### Returns:

a datum representing the time.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## 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 ) → org.das2.datum.TimeUtil.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

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

splits the time location datum into y,m,d,etc components. Note that if seconds is a double, and micros will be 0.

### Parameters

datum - with time location units.

### Returns:

TimeStruct containing the time components.
[search for examples] [view on GitHub] [view on old javadoc] [view source]