Difference between revisions of "SHIP:Data Types:Time"

From Serious Documentation
Jump to: navigation, search
(Created page with "{{DataType|Time}} type variables are a unique complex data type with several {{DataType|Integer}} subfields: * timevar.year -- the year, for example, 2016; this should be >=...")
 
 
Line 1: Line 1:
 +
== {{DataType|Time}} Type Variables ==
 +
 
{{DataType|Time}} type variables are a unique complex data type with several {{DataType|Integer}} subfields:
 
{{DataType|Time}} type variables are a unique complex data type with several {{DataType|Integer}} subfields:
  
Line 23: Line 25:
 
== Auto-Rollover on Subfields ==
 
== Auto-Rollover on Subfields ==
  
−
The subfields can be assigned values outside their natural ranges, which will cause a rebalancing of the various fields to make them in compliance if possible.  For example, it is obvious you could do "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 of course the .value field.
+
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 one from the month causes an 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.
+
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.
 
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 do date/time adjusters in the GUI, with the + and - buttons on each subfield simply doing a -- or ++ on the subfield.   
+
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 ==
 
== Events ==
Line 35: Line 37:
 
All subfields of {{DataType|Time}} variables can cause events. For example, changing timevar.minute will cause any {{Node|listener}} {{Prop|listener|listeningto}} timevar.minute to wake up and run its associated {{Node|script}}(s).
 
All subfields of {{DataType|Time}} variables can cause events. For example, changing timevar.minute will cause any {{Node|listener}} {{Prop|listener|listeningto}} timevar.minute to wake up and run its associated {{Node|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.).
+
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, during auto-rollover can cause multiple events.  For example, doing 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.   
+
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 {{DataType|Time}} Variables ==
 
== Copying {{DataType|Time}} Variables ==
  
−
If you have two {{DataType|Time}} variables, generally you will 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 {{DataType|Time}}  variables named "foo" and "bar", you can do foo.value = bar.value, which will assign the time from bar to foo.
+
If you have two {{DataType|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 {{DataType|Time}}  variables named "foo" and "bar", you can use foo.value = bar.value, which will assign the time from bar to foo.
  
 
== The {{SysVar|shiptime}} System Variable ==
 
== The {{SysVar|shiptime}} System Variable ==
  
 
The {{SysVar|shiptime}} system variable tracks the current system date/time and changes once per second during operation. For more information see {{SysVar|shiptime}}.
 
The {{SysVar|shiptime}} system variable tracks the current system date/time and changes once per second during operation. For more information see {{SysVar|shiptime}}.

Latest revision as of 08:44, 18 August 2016

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.

Retrieved from "https://techref.myserious.com/index.php?title=SHIP:Data_Types:Time&oldid=5594"