HecTime

HecTime is one of the most frequently used classes with HEC-DSS.   It holds a date and time value, and performs various functions with those, such as incrementing a date/time or returning a date/time in a formatted string in a specific style.

HecTime holds a date component, which is Julian days (day count) since 01Jan1900, and a time component, which is seconds past midnight (for the specified Julian day.)  In addition, the date/time “granularity” may be set to specify the precision of the date/time.  The granularity says to work with and return the date/time to the nearest second or minute or hour or day.  For example, if you were to set the granularity to “hour”, the time would always be displayed with no, or in this case, zero, minutes; you would have 0800 or 0900 for the time, but not 0830.  Since DSS generally identifies values to the minute, the default granularity is “minute”.  DSS-7 supports data to the nearest second, so “second” granularity may be used for that type of data.  HecTime does not support a time granularity of less than one second.

Most data in DSS is reported as end-of-period; for example, a daily average data value cannot be computed until the end of the day.  The default reporting for HecTime is end-of-period, meaning that midnight occurs at the end of the day, not at the beginning.  A midnight time will be returned as “2400”.  Be aware of this, as some other commercial programs (such as Excel) use only beginning of day time for midnight.  However, there are some instances where a beginning of period time should be used, for example, the beginning time of the measurement of a data set obtained from radar.  HecTime contains a function to return times as beginning of period (“0000” for midnight).  See the following for that function.

The methods listed below are not comprehensive; they are functions that are more commonly used.  Please refer to the class Java Doc for reference and documentation for all functions.



  • Public Static Members


HecTime.SECOND_GRANULARITY

HecTime.MINUTE_GRANULARITY        (default)

HecTime.HOUR_GRANULARITY

HecTime.DAY_GRANULARITY

  • Constructors

           

HecTime ()

HecTime (String date, String time)

HecTime (int timeGranularity)

HecTime (int value, int timeGranularity)

HecTime (Date javaDate, int minutesTimezoneOffset)

HecTime (HecTime hecTime)


  • Set Methods (common)


int set (String date, String time)

Sets the date from a string in a variety of formats (see below), and the time in a hours:minutes:seconds (colons not necessary) format.  Returns zero (0) for success. 

Example:  hecTime.set("20Jan2002”, “1330");


int set (String dateAndTime)

Parses a combined date/time string, then sets the date and time.  Returns zero (0) for success. 

Example:  hecTime.set("20Jan2002 1330");


int setDate (String date)

Sets the date from a string in a variety of formats (see below.  Returns zero (0) for success. 


int setTime (String time)

Sets the time in a hours:minutes:seconds (colons not necessary) format.  Returns zero (0) for success.


void set (int value, int valueGranularitySeconds, int julianBaseDate)

Sets the date/time relative to a julian base date.  valueGranularitySeconds is what value is given in, and can be 1 (seconds), 60 (minutes), 3600 (hours) or 86400 (days).  For example, if value is 1000 and x is 3600, then the date/time is 1000 hours after julianBaseDate.  valueGranularitySeconds does not set the object’s time granularity, it just indicates what the value represents.


void set (Date javaDate, int minutesTimezoneOffset)

Sets the date/time from a Java Date class.  Since the Date class is intended to represent time in UTC, the minutesTimezoneOffset parameter allows this to be adjusted to local (or other) time.


void set(Calendar cal)

Sets the date/time from a Java Calendar class. 


void set (HecTime hecTime)

Copies a HecTime object, including granularity value. 


void setCurrent ()

   Sets the object to the current (machine) local date/time.


void setJulian (int julian)

Sets the Julian date to the day count passed.


void setJulian (int julian, int minutesSinceMidnight)

Sets the Julian date and the time.


void setJulian (int julian, int minutesSinceMidnight,

int secondsSinceMinute)

When the granularity is set to seconds, this provides a means of setting seconds along with the date and time in minutes.


void setTimeInMillis (long milliseconds)

Sets the date and the time from milliseconds since January 01, 1970; what the system clock uses.


void setYearMonthDay(int year, int month, int day)

Sets the date according to the year, month and day (common usage).  Example,

setYearMonthDay(2002, 1, 20); is the same as setDate("20Jan2002");


void setYearMonthDay (int year, int month, int day,

int minutesSinceMidnight)

Allows the time to be set in the same call.



  • Time as Beginning of Period

HecTime defaults to use end-of-period conventions for time, meaning that midnight occurs at the end of the day, not at the beginning.  A midnight time will be returned as “2400”.  This can be changed to use beginning -of-period conventions, where midnight is returned as “0000” (of the next day.)  The following calls are available for this

void showTimeAsBeginningOfDay(boolean showBeginning)

If showBeginning is true, the HecTime object uses beginning-of-period conventions.  (Note that is at an object level, not a global level.)  If false, then the standard end-of-period convention is used.


boolean getShowsTimeAsBeginningOfDay()

Returns a boolean set to true if the object uses beginning-of-period conventions, false if end-of-period conventions are used.

 

  • Date Style Table

The following table shows examples of the different formats to return or show a date as, based on an integer style.  These styles are used by various methods.


  • Get Methods (common)


String date (int style)

Returns the date portion as a Stirng using the style format in the table above.  If the date is not defined, a blank String “” is returned.


String date()

   Returns the date portion using style 2 in the table above (2 June 1985)


String getTime (boolean withColons)

Returns the time portion as a Stirng, with or without colons, in the standard time format.  What the string contains depends on the granularity.  For example, second granularity returns “08:30:00”, minute granularity “08:30”, hour granularity “08:00” (note – follows standard format, but minutes are truncated.)  Without colons the String would be “0830” for minute granularity.  If the time is not defined, a blank String “” is returned.


String time ()

   Returns the time portion as a Stirng with colons, as described above.


String dateAndTime (int style)

Returns the date and time as a Stirng using the style format in the table above for the date, and colons in the time.  The date is separated from the time by a comma followed by a space.


String dateAndTime ()

Returns the date and time as a Stirng using style 2 in the table above for the date, and colons in the time.  For example “2 June 1985, 08:30”.


int value ()

Returns an int representation of the date/time.  The default for minute granularity is the number of minutes since 01Jan1900.  For hour or day granularity, this is the number of hours or days since 01Jan1900.  For second granularity, this is the number of seconds since 01Jan1970.


int julian ()

Returns the Julian (day count) value in days since 01Jan1900 (with 01Jan1900 being day 1.)


int minutesSinceMidnight ()

Returns the time portion in minutes since midnight (ignores the date.)


int secondsSinceMidnight ()

Returns the time portion in seconds since midnight (ignores the date.)


int getTimeInMillis ()

Returns the date and time in milliseconds since 01 Jan 1970 UTC (same units that Java uses.)


int getTimeInMillis (Calendar cal)

Returns the date and time in milliseconds since 01 Jan 1970 using the Calendar object and its time zone to compute the value.


int dayOfWeek ()

Returns an int representing the day of the week for the date, where Sunday is “1” and Saturday is “7”.


String dayOfWeekName ()

Returns a string with the name of the day of the week for the date, such as “Sunday”, “Monday”, etc.


int dayOfYear ()

Returns an int with the day of the year, where Jan 1 is “1”, Feb 1 is “32”.


static boolean isLeap(int year)

Returns true if the year passed in is a leap year.


int timeGranularity ()

Returns the time granularity set for this object.


  • Is Defined Methods

boolean isDefined()

Returns true if both the date and time are defined.  If the granularity is Day, only the date is checked to be defined.


boolean isDateDefined ()

Returns true if the date portion is defined.


boolean isTimeDefined ()

Returns true if the time portion is defined.


void setUndefined ()

Sets both the date and time portions to Undefined.


  • Date / Time Components

The following calls return the various parts of the date and time, using standard date conventions (for example, 01Jan1985 has day 1, month 1, and year 1985).  -1 is returned for an undefined date/time (but do not rely on this, as -1 is a valid year.

int year ()

int month ()

int day ()

int hour ()

int minute ()

int second ()

int yearMonthDay (intContainer year, intContainer month,

                        intContainer day)

int hoursMinutesSeconds (intContainer hours,

                        intContainer minutes, intContainer seconds)

Where intContainer is a simple class with one variable named “value”.


  • Arithmetic Functions

The following calls add a value to the date/time parameters.  The value added does not need to be within the normal limits, and can be negative or positive.  For example, you can add 10,000 hours and the date and time would be adjusted accordingly (you do not have to limit the call to a 24 hour period.)

void addSeconds(int seconds)

void addMinutes (int minutes)

void addHours (int hours)

void addDays (int hours)

void add (HecTime days)

void subtract (HecTime time)


  • Comparison Functions

The following calls return a boolean indicating if the expression is true or not.  The HecTime passed in is compared to the object’s values (e.g., is the HecTime passed in greater than the object’s date/time.)

boolean equalTo (HecTime time)

boolean notEqualTo (HecTime time)

boolean greaterThan (HecTime time)

boolean greaterThanEqualTo (HecTime time)

boolean lessThan (HecTime time)

boolean lessThanEqualTo (HecTime time)


  • Interval Functions

The following calls deal with time intervals used frequently with time series data.  These functions handle time intervals that vary, such as monthly data where the number of days varies depending on the month.  A time offset is the number of minutes from the “Standard Time” to the specified time.  For example, if the interval is hourly (60 minutes) and the object has a time of “12:34”, then the offset is 34 minutes (because “12:00” is a standard time for hourly data.)  The functions also handle leap years.

Time intervals are given in minutes.  Most intervals are obvious (1 day is 1440 minutes), but a monthly interval is 43,200 minutes (default of 30 days) and a yearly interval is 525,600 (365 days).

void increment(int numberPeriods, int intervalInMins)

Increments the object by numberPeriods periods, each intervalInMins minutes long.  The number of periods may be positive or negative.  The interval should be a standard interval, but will work for any interval less than a month (e.g., you could use an interval of 6 day, 4 hours and 3 minutes, although not recommended.)  For monthly intervals, use 43200 minutes.  For example, incrementing a HecTime object set to 04Jan1985 by 2 months will set it to 04March1985.  Incrementing a HecTime object set to 31Jan1985 by 3 months will set it to 30April1985, the end of the month, while dealing with 28 or 29 days for February.


int computeNumberIntervals(HecTime otherTime, int intervalInMins)

Returns the number of intervals between the current object and the HecTime object passed in.  The number of intervals can be positive or negative.


int getIntervalOffset(int intervalMinutes)

Returns the number minutes from the “standard time” to the current object’s time, given the interval specified.  For example, if the object is set to “12:34” and the interval passed in was 60 minutes, then this would return 34.  If the interval passed in was 1440 minutes, then this would return 754 (12 hours * 60 minutes + 34).


void adjustToIntervalOffset(int intervalMinutes, int offset)

Changes the object to the (next) standard time.  For example, if the object is set to “12:34” and the interval is 60 minutes, then the time would be set to “13:00”.  (For 1 hour data, the valid times for this interval are from 12:01 to 13:00, so the adjustment will not be to 12:00.)  If the offset passed in was 30 minutes, then the object would be set to “12:30”.



  • Utility Functions

Two static utility functions are available to do common date/time processing:

static int getTimeWindow (String userLine, HecTime startTime,

HecTime endTime)

Takes a user date/time string time window and converts it to a start time and end time.  The date/times can be in a variety of formats and can be an offset from the current time or just an offset from the HecTime.  Returns -1 if the string cannot be parsed correctly.  Example user strings are

 "20May95 1200 13Jan97 0500"

"t-5d, t"  //  Current time mines 5 days to current time

"-5D +2H"  //  Take the start time and subtract 5 days; add 2 hours to the end time.


static void convertTimeZone(HecTime hecTime, TimeZone fromTimeZone,

                                                            TimeZone toTimeZone, boolean respectDST)

Takes an HecTime object and adjusts it from one time zone to another time zone.  If daylight savings time is to be observed in the computation, set respectDST to true.  For example, if the from time zone is PST and the to time zone is EST, this will essentially subtract 3 hours from the HecTIme object.