tsc_DateTime

Description

tsc_DateTime is a basic class for date and time calculation. Internally it uses Survey Core time, a double value which is the number of seconds since 00:00:00 on the 1st of January 1980.  Times in this format are also available from the tsc_SurveyCore class. 

Note that the tsc_SurveyCore::LinearTime() method also returns a time in seconds, however the start time for LinearTime is the time the device was last started (booted), rather than some fixed date in the past.  The LinearTime will increment predictably during the lifetime of a program, whereas tsc_DateTime::Now() will jump in value when the user changes the clock or daylight saving time starts or ends.  For this reason, always use tsc_SurveyCore::LinearTime() rather than tsc_DateTime for computing timeouts.

tsc_DateTime also supplies the basic functions for date and time calculation, and conversion between Local, UTC, and GPS times. The default time zone is the local time as configured in the Operating System. 

It is possible to store a UTC value in a tsc_DateTime which, for instance, allows you to convert a UTC time to string format.  When a tsc_DateTime is used in this way it is important not to use methods like AsUTC() or AsGPS(), since they assume local time and will return incorrect values.  Other methods such as GetDetails() will return correct values, but in UTC rather than local.

Because tsc_DateTime is based on a simple type (double) it is possible to perform arithmetic on the raw value, by adding or subtracting seconds or calculating the difference between two times. A number of arithmetic operator overrides have been supplied for this purpose.

Public constructors

tsc_DateTime ();
Constructs an empty instance.

tsc_DateTime (double datetime);
Constructs from a local date/time value.  Note that a UTC time may be passed to this constructor; this means the instance will contain a UTC value, and functions will also return UTC values.  Do not to use methods like AsUTC() or AsGPS() on a UTC instance.

tsc_DateTime (const tsc_DateTime & datetime);
Copy constructor - constructs by copying another tsc_DateTime.

tsc_DateTime (int year, int monthOfYyear, int dayOfMonth,
              int hourOfDday = 0, int minuteOfHour = 0, int secondOfMinute = 0);
Constructs from date and time details.  If any date parameter is invalid, the constructed date will be "empty".  The time parameters may exceed the maximums; this will cause higher-order fields to be incremented, such as an hour of 25 which will resolve to hour 1 on the following day.

Public methods  

static tsc_DateTime  Now();
Returns the current local date/time value.  The resolution of this value varies with the hardware platform and operating system, but should not be relied upon to provide anything better than a one-second resolution.  For higher resolutions consider using tsc_SurveyCore::LinearTime().  The value returned by Now() is subject to changes to the device's clock, such as daylight saving time ending.  This may cause the returned value to jump in value between subsequent calls, or even go backwards.  To calculate timeouts, use LinearTime() instead.

static const double  EmptyValue;
Contains the "null" value, which is used to denote emptiness or an error condition. It is an infinitely distant date.  Some constructors may result in an empty value if the supplied parameter(s) were invalid, such as a month of zero.

static tsc_DateTime ParseDate(tsc_String dateString);
Returns the date/time value after parsing the date components in the supplied string. Returns double_Null if the parsing was unsuccessful.  The parser will accept three fields with any separator, with the order dependent upon the date format set in the operating system options. The year should be four digits, but two digits are accepted and refer to the previous century if more than 10 years in the future. Some valid dates might be 12/31/2020, 31/12/20, 2020/12/31, or 1-1-20. Android does not appear to support formats starting with the year.

static tsc_DateTime ParseTime(tsc_String timeString);
Returns the date/time value after parsing the time components in the supplied string. Returns double_Null if the parsing was unsuccessful. The parser will accept three fields with any separator, representing hour, minute, second.

bool    IsEmpty () const;
Returns true if the value indicates the date/time is empty or was constructed from bad values.

void    FromGPS (int gpsWeeks, double gpsSeconds);
Replaces the date/time value with a local time computed from the supplied GPS time.

void    AsGPS (int& gpsWeeks, double& gpsSeconds) const;
Returns, in the two parameters, the GPS time converted from the local date/time.

void    FromUTC (double UTC);
Replaces the date/time value with a local time computed from the supplied UTC time.

double  AsUTC () const;
Returns a UTC time computed from the local date/time.

void    GetDetails (int& year, int& monthOfYear, int& dayOfMonth,
                    int& hourOfDay, int& minuteOfHour, int& secondOfMinute) const;
Returns details from the date/time value.  Year is 1980-, month is 1-12, day is 1-31, hour is 0-23, minute is 0-59, and second is 0-59.

int     GetDayOfWeek () const;
Returns the day of the week, Sunday (0) to Saturday (6).

tsc_DateTime GetDate () const;
Returns only the date portion, with a time of 00:00:00.

tsc_DateTime GetTime () const;
Returns only the time portion, with the date set to 1980-01-01. In other words, the date is zero and the value contains just a time in seconds.

virtual tsc_String ToString () const;
Formats the date/time into a string containing the date and the time.  The conversion is locale-aware.

tsc_String tsc_ToDateString () const;
Formats the date part of the date/time into a string. The time is ignored.

tsc_String tsc_ToTimeString () const;
Formats the time part of the date/time into a string. The date is ignored.

double Value () const;
Returns the date/time as a value in seconds.

void Value (double value);
Sets the time from the supplied value in seconds.  If the supplied time is a UTC value then tsc_DateTime will not be aware of this fact, however all methods will continue to work correctly except for those (such as AsGPS and AsUTC) which make an implicit assumption that the value is local and will apply the wrong conversion.