/MEng/Time

ClassPath:MEng.Time
Parent ClassPath:MEng.Formattable
Copyable:Yes
Final:Yes

MEng.Time provides basic time related services, e.g. getting or representing the current time or date, comparing times, timing events, and so forth. This class is not designed for highly accurate timing of events, since it's accuracy and granularity is not guaranteed to be extremely high on any particular hardware. 

Months and days of the week are represented by nested enumerated types of this class, but the other fields are numeric values, which are defined like this:

  • c4Year - The full year value, with the base year (1970) being the smallest legal value.
  • c4Day - A zero based day of month, which must be valid for the month in question.
  • c4Hours - A zero based hour value, from 0 to 23.
  • c4Minutes - A zero based minutes value, from 0 to 59.
  • c4Seconds - A zero based seconds value, from 0 to 59.

Time objects can be formatted to text in a number of flexible ways, because there are often needs to display only the time info or only the date info or to use certain well known standard formats. So each time objects has a format string, which uses the standard token replacement scheme of the MEng.String class. You can set a default format string on the time object, which contains replacement tokens, and when you format it, each token is replaced by the indicated field. The tokens are:

  • ':' - The localized time separator character
  • '/' - The localized date separator character
  • 'a' - The localized abbreviated day of the week
  • 'D' - The day of the month as a number
  • 'd' - The localized name of the day of the week
  • 'e' - Total elapsed seconds
  • 'E' - Total elapsed minutes
  • 'H' - The hour in 24 hour terms
  • 'h' - The hour in 12 hour terms
  • 'l' - The milliseconds
  • 'M' - The month as a number
  • 'm' - The localized abbreviated month name
  • 'n' - The localized full month name
  • 'P' - The localized AM/PM designation
  • 'p' - The single letter AM/PM designation
  • 's' - The seconds
  • 'S' - The raw time stamp value (elapsed 100ns intervals)
  • 'T' - The localized time zone name
  • 't' - The local time zone offset from UTC, in minutes
  • 'u' - The minutes
  • 'Y' - The year as a 4 digit value
  • 'y' - The trailing two digits of the year

So, "%(h,2,0):%(u,2,0) %(P)" would turn the time 2:35am, into "02:35 am", assuming that am is the localized representation of a 12 hour am time. This class provides some prefab format strings, as literals, so that you can use them without having to figure them out yourself.

The raw form of a time object, called a 'stamp' here, can be gotten out of a time object and set on a time object. The raw form is a Card8 value which holds the number of 100 nano-seconds since the base time of midnight January 1st, 1970. So if you set a time object via a raw stamp set to zero, you will get that base time.

Though it is a 'time stamp', these objects can be used as elapsed time values as well. If you just look at the hours, minutes and seconds fields, then the date doesn't matter. So if you set a stamp value that represents 10 seconds, it will be 10 seconds into the based day mentioned above. But it doesn't really matter what the day is for that purpose. So if you want to use it to represent elapsed time that a music track has been playing, just treat is as a zero based count of 100ns intervals.

 

Literals:

kFmt24HHMM("%(H,2,0):%(u,2,0)");
kFmtCTime("%(a), %(m) %(D,2,0) %(H,2,0):%(u,2,0):%(s,2,0) %(Y,4,0) %(t)");
kFmtFullDate("%(a) %(n) %(M,2,0), %(Y,4,0)");
kFmtHHMMSS("%(H,2,0):%(u,2,0):%(s,2,0)");
kFmtMMDDYYYY("%(M,2,0)/%(D,2,0)/%(Y,4,0)");
kFmtMMDDYY("%(M,2,0)/%(D,2,0)/%(y,2,0)");

These are format strings used by the SetDefFmt() method below. See the main class documentation above for the format of these strings. You can make up your own, these are just for your convenience.

kOneMilliSec
kOneSecond
kOneMinute
kOneHour
kOneDay

These values are conveniences that represent various amounts of time in terms of the 100-nanosecond intervals that the Card8 style timestamps provided by this class are in terms of.

 

Nested Classes:

Enum=TimeErrors
    CvtFailed   : "";
    SetFailed   : "";
EndEnum;

This enumerated type defines the time specific exceptions that this class might throw. Note though that other exceptions might be thrown from other classes used by this class or passed in as exceptions. Also note that they don't have any text defined, since they will actually get their text from the underlying C++ exception that occurs in the process of doing the operation.

Enum=Months
    January     : "Jan";
    February    : "Feb";
    March       : "Mar";
    April       : "Apr";
    May         : "May";
    June        : "Jun";
    July        : "Jul";
    August      : "Aug";
    September   : "Sep";
    October     : "Oct";
    November    : "Nov";
    December    : "Dec";
EndEnum;

This enumerated type defines the months of the year, which are used in this class instead of numerical month values, because it is more self documenting and you cannot use an invalid month value.

Enum=WeekDays
    Sunday      : "Sun";
    Monday      : "Mon";
    Tuesday     : "Tues";
    Wednesday   : "Wed";
    Thursday    : "Thu";
    Friday      : "Fri";
    Saturday    : "Sat";
EndEnum;

This enumerated type defines the days of the week, which are used in this class instead of numerical weekday values, because it is more self documenting and you cannot use an invalid weekday value.

Enum=SpecialTimes
    Base         : "Base time";
    CurDate      : "Midnight today, local time";
    CurTime      : "Current local time";
    Noon         : "Noon today, local time";
    UTC          : "Current UTC time";
EndEnum;

This enumerated type is used by a couple methods, to allow you to set the time to one of a set of special times. UTC is 'universal coordinated time', and represents the time at the 0th meridian. Time zones are relative, added or subtracted from UTC time to get local time.

 

Constructors:

Constructor();
Constructor([In] SpecialTimes InitVal);

There is a constructor, which will set the initial value to the current time on the current day. And there is a constructor that sets it to one of the special times.

 

Final, Const Methods:

GetCurMillis() Returns MEng.Card4;

Returns the value of a running millisecond timer, which can be used to time events, by getting a starting timer value, and then getting subsequent timer values and subtracting the original one, to calculate the expired milliseconds.

Be careful of this field as a delay value, i.e. get it once and then keep getting it until the new value equals the first plus some count. This counter will wrap around in to zero after about 49 days of system running time (it starts over if the system is rebooted), so though it is unlikely, you could use it to time something and it could wrap around while you are waiting and you would wait for 49 days. It is much preferred that you use GetCurStamp(), which returns a time stamp that will not wrap in your lifetime.

GetCurStamp() Returns MEng.Card8;
GetCurStampPlusMSs([In] Card4 Millis) Returns MEng.Card8;
GetCurStampPlusSecs([In] Card4 Seconds) Returns MEng.Card8;

Returns the number of 100-nanosecond intervals since the base time of midnight, January 1st, 1970. This value is in the form of a Card8 value (64 bits) so it will not wrap around within any length of time that your application will in reality ever run. There are also helper versions that will return the current system time plus some number of milliseconds or seconds. Since it is very common to want to generate such 'some time from now' type of stamps, these are very convenient.

Note that this is returning the system time stamp, not the value of the time stamp in this object. Use GetStamp() to get this object's time stamp value.

GetDateFlds
(
    [Out] MEng.Card4 YearToFill
    , [Out] Months MonthToFill
    , [Out] MEng.Card4 DayToFill
);

Gets the date fields out of this time stamp object, i.e. the year, month, and the day of the month. If the values cannot be converted and extracted for any reason, you will get a CvtError.

GetJulianDate() Returns MEng.Card4;

Gets the Julian date for today.

GetStamp() Returns MEng.Card8;

Returns the raw time stamp value from this object. the number of 100-nanosecond intervals since the base time of midnight, January 1st, 1970. This value is in the form of a Card8 value (64 bits) so it will not wrap around within any length of time that your application will in reality ever run.

Note that this is returning this object's time, not the system time. Use GetCurStamp() to get the system (local) time.

GetTimeFlds
(
    [Out] MEng.Card4 Hours
    , [Out] MEng.Card4 Minutes
    , [Out] MEng.Card4 Seconds
);

Gets the time fields out of this time stamp object, i.e. the hours, minute and seconds values. Their possible values are documented above in the main documentation for this class. If the values cannot be converted and extracted for any reason, you will get a CvtError.

GetTZOffset() Returns Int4;

Returns the number of minutes (positive or negative) that the local time zone differs from UTC time. So, for instance, California is -480, because it is 8 hours behind UTC time.

GetWeekday() Returns WeekDays;

Returns the day of the week represented by this time stamp.

IsLeapYear([In] MEng.Card4 ToCheck) Returns Boolean;

Returns True if the passed year is a leap year, else it returns False.

Sleep([In] MEng.Card4 MilliSecs);

Your macro will sleep for the indicated number of seconds.  You should be careful of using this method in certain applications, such as CQC drivers, since it will cause everything to back up. But for your own macros, it is often very useful.

 

Final, Non-Const Methods:

LocalToUTC();

Assumes that this object's current time is a local time, and converts it to UTC time (by removing the local time zone offset from it.)

SetDate
(
    [In] MEng.Card4 YearToSet
    , [In] Months MonthToSet
    , [In] MEng.Card4 DayToSet
);

Sets this object to the indicated date. The time will be set to midnight on this date. The day of the month must be valid for the particular month, which varies by month and by leap year in some cases. If not, you will get a SetFailed exception.

SetDateTime
(
    [In] MEng.Card4 YearToSet
    , [In] Months MonthToSet
    , [In] MEng.Card4 DayToSet
    , [In] MEng.Card4 Hours
    , [In] MEng.Card4 Minutes
    , [In] MEng.Card4 Seconds
);

Sets this object to the indicated date and time. This is a combination of the SetDate and SetTime methods. The passed values  must comprise a  valid date and time or you will get a SetFailed exception.

SetDefFmt([In] MEng.String FmtToSet);

Sets the format string for this object. If you format a time object to an output text stream, it will use this format string to format itself, which allows you to control what information it displays and i what order. The format of this string is documented in the main class documentation above.

SetFromJulian([In] MEng.Card4 ToSet);

Sets this object to midnight on the Julian date indicated.

SetFromStamp([In] MEng.Card8 ToSet);

Sets the value of this object from a raw time stamp value. If the stamp is not valid, then the SetFailed except is thrown.

SetSpecial([In] SpecialTimes ToSet);

Sets the value of this object to the indicated special time. See the class comments at the top of this page for the list of special times that can be set.

SetTime
(
    [In] MEng.Card4 Hours
    , [In] MEng.Card4 Minutes
    , [In] MEng.Card4 Seconds
    , [In] MEng.Card4 Millis
);

Sets this object to the indicated time. The date will be the base date, i.e. 1/1/1970. This is often used to do time difference operations, since the date is irrelevant in this case. The values must comprise a valid time value, or you will get a SetFailed exception.

SetToSunrise
(
    [In] MEng.Float4 Latitude
    , [In] MEng.Float4 Longitude
    , [In] MEng.Int4 TZOffset
);
SetToSunset
(
    [In] MEng.Float4 Latitude
    , [In] MEng.Float4 Longitude
    , [In] MEng.Int4 TZOffset
);

Sets the value of this object to the sunrise or sunset time for the current date set in this object, at the passed location. You must provide the target latitude and longitude and time zone offset for the location whose sunrise/sunset you want to set. You must also provide the time zone offset for the location. For your own location, just call GetTZOffset() above to get this value.

  • Note that you must provide the correct sign on longitudes and latitudes! Latitudes in the southern hemisphere are negative and longitudes west of the 0th meridian (e.g. north and south America) are negative. So San Francisco is 37.4/-122.26, while Melbourne Australia is -37.47/144.58. If you fail to get the sign right, you will get an error or incorrect results.
UTCToLocal();

Assumes that this object's current time is a UTC time, and converts it to the local time (by applying the local time zone offset to it.)