documentation and removed dead code from TimePoint

Author: jkalias

include/reflection.h

@@ -35,8 +35,6 @@
 #include <stddef.h>
 #endif
 
-// todo: saving/retrieving dates (get/set local/utc time functions)
-// todo: cpp+20 for date type
 // todo: template specialization for int64_t and wchar_t*
 
 // todo: bool member type

include/time_point.h

@@ -30,17 +30,33 @@
 typedef std::chrono::time_point<std::chrono::system_clock, std::chrono::seconds> sys_seconds;
 
 namespace sqlite_reflection {
+/// A wrapper for expressing points in time based on system time.
+/// The epoch is by convention the Unix epoch of 1 January 1970 at midnight (1970-01-01T00:00:00Z)
+/// System time is a very good approximation of UTC time, the only difference being the management of leap seconds
+/// (system time ignores leap seconds)
+/// https://en.wikipedia.org/wiki/Coordinated_Universal_Time
 	class REFLECTION_EXPORT TimePoint
 	{
 	public:
+        /// Defaults to start of system time (Unix epoch)
 		TimePoint();
+        
+        // Creates a time representation based on the elapsed seconds from the Unix epoch.
+        // Negative valules represent time points before 1970-01-01T00:00:00Z,
+        // whereas positive values after 1970-01-01 00:00:00 UTC
 		explicit TimePoint(const int64_t& seconds_since_unix_epoch);
+        
+        // Creates a time representation based on the elapsed seconds from the Unix epoch.
+        // Negative valules represent time points before 1970-01-01T00:00:00Z,
+        // whereas positive values after 1970-01-01 00:00:00 UTC
 		explicit TimePoint(const sys_seconds& time_since_unix_epoch);
+        
+        /// Creates a time point instance from its equivalent ISO 8601 UTC format
 		static TimePoint FromSystemTime(const std::wstring& iso_8601_string);
-		//static TimePoint FromLocalTime(const std::wstring& timestamp);
-
+        
+        /// Returns a string representation of this  instance, expressed in ISO 8601 UTC format
+        /// https://en.wikipedia.org/wiki/ISO_8601
 		std::wstring SystemTime() const;
-		//std::wstring LocalTimestamp() const;
 
 	private:
         sys_seconds time_stamp_;

src/time_point.cc

@@ -22,6 +22,8 @@
 
 #include "time_point.h"
 #include "internal/string_utilities.h"
+
+// This would not have been at all possible without this amazing library
 #include "internal/date.h"
 
 #include <sstream>
@@ -30,20 +32,20 @@
 using namespace sqlite_reflection;
 
 #if __cplusplus < 201907L
-    #define LEGACY_CHRONO
+#define LEGACY_CHRONO
+#else
+#ifdef _WIN32
+#define MODERN_WIN_CHRONO
 #else
-    #ifdef _WIN32
-        #define MODERN_WIN_CHRONO
-    #else
-        #define MODERN_UNIX_CHRONO
-    #endif
+#define MODERN_UNIX_CHRONO
+#endif
 #endif
 
 #if defined(LEGACY_CHRONO) || !defined(MODERN_WIN_CHRONO)
 using namespace date;
 #endif
 
-static std::wstring iso_format = L"%FT%T";
+static std::wstring iso_format = L"%FT%TZ";
 
 TimePoint::TimePoint() {}
 
@@ -68,9 +70,9 @@ std::wstring TimePoint::SystemTime() const {
 #endif
 	std::stringstream ss;
 #if defined(LEGACY_CHRONO) || !defined(MODERN_WIN_CHRONO)
-	ss << tp << "T" << make_time(time_stamp_ - tp) << " UTC";
+	ss << tp << "T" << make_time(time_stamp_ - tp) << "Z";
 #else
-	ss << tp << "T" << std::chrono::hh_mm_ss(time_stamp_ - tp) << " UTC";
+	ss << tp << "T" << std::chrono::hh_mm_ss(time_stamp_ - tp) << "Z";
 #endif
 	return StringUtilities::FromUtf8(ss.str().c_str());
 }

tests/date_time_test.cc

@@ -66,25 +66,25 @@ void ControlRoundTrip(const int64_t& time_point, const wchar_t* sys_time) {
 }
 
 TEST_F(DateTimeTest, UnixEpoch) {
-	ControlRoundTrip(0, L"1970-01-01T00:00:00 UTC");
+	ControlRoundTrip(0, L"1970-01-01T00:00:00Z");
 }
 
 TEST_F(DateTimeTest, RoundtripBefore1000) {
-    ControlRoundTrip(-32350628573LL, L"944-11-06T10:17:07 UTC");
+    ControlRoundTrip(-32350628573LL, L"944-11-06T10:17:07Z");
 }
 
 TEST_F(DateTimeTest, RoundtripBefore1900) {
-	ControlRoundTrip(-2359097130LL, L"1895-03-30T15:14:30 UTC");
+	ControlRoundTrip(-2359097130LL, L"1895-03-30T15:14:30Z");
 }
 
 TEST_F(DateTimeTest, RoundtripBefore1970) {
-	ControlRoundTrip(-1508726294, L"1922-03-11T21:21:46 UTC");
+	ControlRoundTrip(-1508726294, L"1922-03-11T21:21:46Z");
 }
 
 TEST_F(DateTimeTest, RoundtripAfter2000) {
-	ControlRoundTrip(1688842924, L"2023-07-08T19:02:04 UTC");
+	ControlRoundTrip(1688842924, L"2023-07-08T19:02:04Z");
 }
 
 TEST_F(DateTimeTest, RoundtripAfter2038) {
-	ControlRoundTrip(2333089535, L"2043-12-07T08:25:35 UTC");
+	ControlRoundTrip(2333089535, L"2043-12-07T08:25:35Z");
 }