Add time and realtime clock functions

Adds functions to query the system's realtime clock, convert time intervals to/from a calendar date and time in either UTC or the local time, and perform time related calculations.

An SDL_Time type (a time interval represented in nanoseconds), and SDL_DateTime struct (broken down calendar date and time) were added to facilitate this functionality.

Querying the system time results in a value expressed in nanoseconds since the Unix epoch (Jan 1, 1970) in UTC +0000. Conversions to and from the various platform epochs and units are performed when required.

Any direct handling of timezones and DST were intentionally avoided. The offset from UTC is provided when converting from UTC to a local time by calculating the difference between the original UTC and the resulting local time, but no other timezone or DST information is used.

The preferred date formatting and 12/24 hour time for the system locale can be retrieved via global preferences.

Helper functions for obtaining the day of week or day or year for calendar date, and getting the number of days in a month in a given year are provided for convenience. These are simple, but useful for performing various time related calculations.

An automated test for time conversion is included, as is a simple standalone test to display the current system date and time onscreen along with a calendar, the rendering of which demonstrates the use of the utility functions (press up/down to increment or decrement the current month, and keys 1-5 to change the date and time formats).

src/time/windows/SDL_systime.c

@@ -0,0 +1,139 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+#include "SDL_internal.h"
+
+#ifdef SDL_TIME_WINDOWS
+
+#include "../../core/windows/SDL_windows.h"
+#include <minwinbase.h>
+#include <timezoneapi.h>
+
+#include "../SDL_time_c.h"
+
+#define NS_PER_WINDOWS_TICK   100ULL
+#define WINDOWS_TICK          10000000ULL
+#define UNIX_EPOCH_OFFSET_SEC 11644473600ULL
+
+void SDL_GetSystemTimeLocalePreferences(SDL_DATE_FORMAT *df, SDL_TIME_FORMAT *tf)
+{
+    WCHAR str[80]; /* Per the docs, the time and short date format strings can be a max of 80 characters. */
+
+    if (GetLocaleInfoW(LOCALE_USER_DEFAULT, LOCALE_SSHORTDATE, str, sizeof(str) / sizeof(WCHAR))) {
+        LPWSTR s = str;
+        while (*s) {
+            switch (*s++) {
+            case L'y':
+                *df = SDL_DATE_FORMAT_YYYYMMDD;
+                goto found_date;
+            case L'd':
+                *df = SDL_DATE_FORMAT_DDMMYYYY;
+                goto found_date;
+            case L'M':
+                *df = SDL_DATE_FORMAT_MMDDYYYY;
+                goto found_date;
+            default:
+                break;
+            }
+        }
+    }
+
+found_date:
+
+    /* Figure out the preferred system date format. */
+    if (GetLocaleInfoW(LOCALE_USER_DEFAULT, LOCALE_STIMEFORMAT, str, sizeof(str) / sizeof(WCHAR))) {
+        LPWSTR s = str;
+        while (*s) {
+            switch (*s++) {
+            case L'H':
+                *tf = SDL_TIME_FORMAT_24HR;
+                return;
+            case L'h':
+                *tf = SDL_TIME_FORMAT_12HR;
+                return;
+            default:
+                break;
+            }
+        }
+    }
+}
+
+int SDL_GetCurrentTime(SDL_Time *ticks)
+{
+    FILETIME ft;
+
+    if (!ticks) {
+        return SDL_InvalidParamError("ticks");
+    }
+
+    SDL_zero(ft);
+    GetSystemTimePreciseAsFileTime(&ft);
+    *ticks = SDL_TimeFromWindows(ft.dwLowDateTime, ft.dwHighDateTime);
+
+    return 0;
+}
+
+int SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime)
+{
+    FILETIME ft, local_ft;
+    SYSTEMTIME utc_st, local_st;
+    SYSTEMTIME *st = NULL;
+    Uint32 low, high;
+
+    if (!dt) {
+        return SDL_InvalidParamError("dt");
+    }
+
+    SDL_TimeToWindows(ticks, &low, &high);
+    ft.dwLowDateTime = (DWORD)low;
+    ft.dwHighDateTime = (DWORD)high;
+
+    if (FileTimeToSystemTime(&ft, &utc_st)) {
+        if (localTime) {
+            if (SystemTimeToTzSpecificLocalTime(NULL, &utc_st, &local_st)) {
+                /* Calculate the difference for the UTC offset. */
+                SystemTimeToFileTime(&local_st, &local_ft);
+                const SDL_Time local_ticks = SDL_TimeFromWindows(local_ft.dwLowDateTime, local_ft.dwHighDateTime);
+                dt->utc_offset = SDL_NS_TO_SECONDS(local_ticks - ticks);
+                st = &local_st;
+            }
+        } else {
+            dt->utc_offset = 0;
+            st = &utc_st;
+        }
+
+        if (st) {
+            dt->year = st->wYear;
+            dt->month = st->wMonth;
+            dt->day = st->wDay;
+            dt->hour = st->wHour;
+            dt->minute = st->wMinute;
+            dt->second = st->wSecond;
+            dt->nanosecond = ticks % SDL_NS_PER_SECOND;
+            dt->day_of_week = st->wDayOfWeek;
+
+            return 0;
+        }
+    }
+
+    return SDL_SetError("SDL_DateTime conversion failed (%lu)", GetLastError());
+}
+
+#endif /* SDL_TIME_WINDOWS */