HomeThere are three classes for handling wallclock time: Time, Date and DateTime.
Time
A time instance stores the time since midnight. It provides functions to compare times and for adding a certain amount of time.
A new instance is created by calling clock.currentTime(), which initializes the object from the system clock, or by calling clock.newTime() with an arbitrary time value. Note that the system clock runs on UTC, not local time. To handle local time, use a datetime object.
The time:hour(), time:minute(), time:second() and time:msec() functions provide access to the stored time. The same information can be formatted into a string by calling time:format().
Two times can be compared, a time is considered smaller than another if it is earlier than the other.
You can add a specific amount of time using time:addSecs() or time:addMSecs(). In addition, the distance between two times can be calculated using time:secsTo() or time:msecsTo().
Date
A date instance stores a calendar date. It provides functions to compare dates and for adding a certain amount of days to a date.
A new instance is created by calling clock.currentDate(), which initializes the object from the system clock, or by calling clock.newDate() with an arbitrary date value. Note that the system clock runs on UTC, not local time. To handle local time, use a datetime object.
The date:year(), date:month() and date:day() functions provide access to the stored date. The same information can be formatted into a string by calling date:format().
Two dates can be compared, a date is considered smaller than another if it is earlier than the other.
You can add (or subtract) a specific amount of time using date:addDays(), date:addMonths() or date:addYears(). In addition, the distance between two dates can be calculated using date:daysTo().
Further information can be queried using date:dayOfWeek(), date:dayOfYear().
The function date:weekNumber() returns the ISO8601 conformant week number and its corresponding year. (The standard says weeks start on Monday and the first Thursday of a year is always in week 1 of that year. This might not be what US american citicens expect...)
Older Teratronik systems often handle dates as an offset from 1990, Jan. 1st. Use date:setDays90() and date:days90() to set and query this encoding.
A date object is able to handle dates between the beginning of the gregorian calandar and somewhere around 8000 A.D., which should be sufficient for the scope of embedded systems.
DateTime
A datetime is the combination of a date and a time. It provides the same initialization and query functions as the previous classes. In addition, it knows about timezones and daylight saving rules.
A new instance is created by calling clock.currentDateTime(), which initializes the object from the system clock, or by calling clock.newDateTime() with an arbitrary date value.
Note that the system clock runs on UTC, not local time. The function datetime:toLocal() converts a date/time storing UTC time into the current local date/time. Correspondingly, datetime:toUTC() converts back to UTC.
Older Teratronik systems often handle dates as an offset from 1990, Jan. 1st and times as minutes since midnight. Use datetime:setBase90() and datetime:base90() to set and query this encoding.
The function datetime:isdst() returns true if the stored value lies within a range where daylight saving rules apply. Use datetime:zone() to get the name of the stored timezone, which might differ depending if daylight saving is in effect or not (e.g. CET vs. CEST). Finally, datetime:offset() returns the difference in seconds between the stored value and UTC, again, taking daylight saving rules into account.
Timezones
The system clock always runs on UTC time and does not know anything about local time zones.
To use local time, the datetime class provides the conversion functions datetime:toLocal() and datetime:toUTC(). It is recommended to do all internal date/time processing using UTC and only convert to local time when displaying a date/time to a user. That way, the software almost never needs to care about timezones and daylight saving rules.
Information about the local time zone is stored in the global kconfig configuration area and passed to processes in the TZ environment variable by the init process.
To set up a different timezone, call clock.tzset(). Usually there is no need to call this however, as long as the proper timezone has been configured into the global kconfig area. Query the currently configured timezone information by calling clock.tzget().
Local/UTC time conversion is done using the public domain zoneinfo codebase.