Simple types

SCAPI uses, as far as possible, the predefined types available with C++.

Boolean

All boolean values use the bool type.  The correct values to use are true and false.  Avoid TRUE and FALSE except for use with the Windows API.

Characters and strings

Characters and strings use UTF-8 encoding in a char.  UTF-8 expresses Unicode values in one or more 8-bit bytes.

Where necessary, UTF-16 character values use the type wchar_t.  This format expresses unicode values in one or more 16-bit words. On Android we used the native format, UTF-32.

Integers

All signed and unsigned integer values use the int type, except in the small number of cases where the sign bit is used (such as a bit-encoded field or a possible value greater than (2^32)-1) where unsigned int is used instead.

Floating point

All calculations requiring floating-point numbers use double.  Note that the 'NaN' value is generally not used; instead the very large value double_Null is defined to mean "no value".  Many API functions will accept double_Null as input and may return double_Null.

The function:
bool double_IsNull(double& value);
returns true if the value passed is equal to double_Null.  It is significantly faster than using value == double_Null.

Because the C runtime does not have a nice definition of NaN (Not a Number), SCAPI defines the macro double_NaN. This value is useful for setting a double variable to NaN, but cannot be used to test for NaN since all comparisons with NaN return false (except for NaN != NaN, which returns true).  To test for NaN, use the function _isnan(x) in float.h.

A small number of methods use float.  These are typically screen or image positions used within the UI system.

Date and time

Within Survey Core, all dates and times are stored as floating point (double) values.  The value represents seconds.  For small or accurate time intervals, the fractional part is relevant, such as 1.25 which is equivalent to 1250 milliseconds.  

For intervals containing fractional seconds, the linear time should be used.  This can be obtained from tsc_SurveyCore::LinearTime(), which returns the same value as the windows API call GetTickCount(), but avoids the 32-bit wrap-around problems inherent in that function.  Linear times are always expressed in seconds.

The tsc_DateTime class is useful for creating and dissecting dates, and performing date calculations.  It uses the same internal format in a double.

For dates, the value represents the number of seconds since 00:00:00 on the 1st of January 1980, local time.  Negative values can be used to represent dates before this.  A date also contains a time component, with a platform-dependent resolution of 1 second or better.  The term local time means the time zone that has been configured in the Windows date and time configuration, which may automatically change when daylight saving time begins or ends.

The time-of-day component of the value contains the number of seconds since midnight, and can be calculated as the value modulus 86400.

The tsc_SurveyCore class contains methods for obtaining the time and date as a local time, UTC time, or a time since startup (linear time).  The linear time is useful for calculating timeouts and other uses where a time that will not jump is required.  UTC and Local times will change if the user alters the clock, or daylight saving begins or ends.

Dates and times may be formatted into readable strings using functions in the tsc_Format and tsc_DateTime classes.

Some arithmetic with dates and times is possible.  Subtraction provides a time difference between dates, times, and intervals.  Addition is also possible except adding two dates is not useful.