SHIP:Data Types:Time

Time Type Variables

Time type variables are a unique complex data type with several Integer subfields:

• timevar.year -- the year, for example, 2016; this should be >= 2000

• timevar.month -- the month 1..12 for Jan...Dec

• timevar.day -- the day of the month 1..31

• timevar.hour -- the hour in the day 0..23

• timevar.minute -- the minute of the hour 0..59

• timevar.second -- the second of the minute 0..59

In addition, there is an aggregate subfield:

• timevar.value -- the number of seconds since 0:00:00 on January 1, 2000.

Auto-Translation Between .value and the other Subfields

When you assign the .value field with a number, the system will automatically translate this value to the other fields and vice versa. For example, assigning timevar.value = 10 will automatically set the year subfield to 2000, month to 1, day to 1, hour to 0, minute to 0, and seconds to 10. Subsequently changing the timevar.minute to 1 will then add 60 seconds to the value field which would then be 70.

Auto-Rollover on Subfields

The subfields can be assigned values outside their natural ranges. This will cause a rebalancing of the various fields to put them in compliance (if possible). For example, it is obvious you could set "timevar.month -= 1;" to go back one month in time. If, say, you were starting at February 20, timevar.month-- would change the time to January 20. The rest of the subfields would be unchanged except for the .value field.

However, subsequently subtracting 1 from the month causes a rollback to the prior year (December) as expected. You do not have to manually (e.g. if timevar == 1 <handle underrun> else <normal>). SHIP handles this automatically. So if you do a timevar.month-- when .month is 1, it will subtract one from the year and timevar.month will now be 12 as expected.

Similarly, assigning timevar.month to 13, for example, will cause the rebalance to timevar.month as 1 in the incremented year.

This capability makes it extremely easy to make date/time adjustments in the GUI, with the + and - buttons on each subfield simply implementing a -- or ++ on the subfield.

Events

All subfields of Time variables can cause events. For example, changing timevar.minute will cause any listener listeningto timevar.minute to wake up and run its associated script(s).

Multiple events are often generated simultaneously when subfields are adjusted. For example, changing the .value field will often fire multiple events across the other subfields because of the auto-translation from the .value field to the other subfields (.minute, etc.).

Similarly, auto-rollover can cause multiple events. For example, using a timevar.second-- when the date is Jan 1, 2001 at 00:00 will cause every subfield to change as the date is rolled back to the very last second of the year 2000.

Copying Time Variables

If you have two Time variables, you will generally want to copy the .value property. This atomically copies all the ingredients of the complex type at one time. For example if you have two Time variables named "foo" and "bar", you can use foo.value = bar.value, which will assign the time from bar to foo.

The shiptime System Variable

The shiptime system variable tracks the current system date/time and changes once per second during operation. For more information see shiptime.