mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-04-05 07:09:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add time and realtime clock functions

Browse Source 
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).
This commit is contained in:
Frank Praznik
2024-02-29 13:06:26 -05:00
committed by Sam Lantinga
parent b6c9a72740
commit a6fbf0488c
41 changed files with 1862 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
test/CMakeLists.txt
View File

@@ -413,6 +413,7 @@ add_sdl_test_executable(testvulkan NO_C90 SOURCES testvulkan.c)
add_sdl_test_executable(testoffscreen SOURCES testoffscreen.c)
add_sdl_test_executable(testpopup SOURCES testpopup.c)
add_sdl_test_executable(testdialog SOURCES testdialog.c)
add_sdl_test_executable(testtime SOURCES testtime.c)
if (HAVE_WAYLAND)
# Set the GENERATED property on the protocol file, since it is first created at build time

1
test/testautomation.c
View File

@@ -44,6 +44,7 @@ static SDLTest_TestSuiteReference *testSuites[] = {
&sdltestTestSuite,
&stdlibTestSuite,
&surfaceTestSuite,
&timeTestSuite,
&timerTestSuite,
&videoTestSuite,
&subsystemsTestSuite, /* run last, not interfere with other test enviroment */

1
test/testautomation_suites.h
View File

@@ -32,6 +32,7 @@ extern SDLTest_TestSuiteReference sdltestTestSuite;
extern SDLTest_TestSuiteReference stdlibTestSuite;
extern SDLTest_TestSuiteReference subsystemsTestSuite;
extern SDLTest_TestSuiteReference surfaceTestSuite;
extern SDLTest_TestSuiteReference timeTestSuite;
extern SDLTest_TestSuiteReference timerTestSuite;
extern SDLTest_TestSuiteReference videoTestSuite;

201
test/testautomation_time.c Normal file
View File

@@ -0,0 +1,201 @@
/**
* Timer test suite
*/
#include "testautomation_suites.h"
#include <SDL3/SDL.h>
#include <SDL3/SDL_test.h>
/* 2000-01-01T16:35:42 UTC */
#define JAN_1_2000_NS SDL_SECONDS_TO_NS(946744542)
/* Test case functions */
/**
* Call to SDL_GetRealtimeClock
*/
static int time_getRealtimeClock(void *arg)
{
int result;
SDL_Time ticks;
result = SDL_GetCurrentTime(&ticks);
SDLTest_AssertPass("Call to SDL_GetRealtimeClockTicks()");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
return TEST_COMPLETED;
}
/**
* Test bidirectional SDL_DateTime conversions.
*/
static int time_dateTimeConversion(void *arg)
{
int result;
SDL_Time ticks[2];
SDL_DateTime dt;
ticks[0] = JAN_1_2000_NS;
result = SDL_TimeToDateTime(ticks[0], &dt, SDL_FALSE);
SDLTest_AssertPass("Call to SDL_TimeToUTCDateTime()");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
SDLTest_AssertCheck(dt.year == 2000, "Check year value, expected 2000, got: %i", dt.year);
SDLTest_AssertCheck(dt.month == 1, "Check month value, expected 1, got: %i", dt.month);
SDLTest_AssertCheck(dt.day == 1, "Check day value, expected 1, got: %i", dt.day);
SDLTest_AssertCheck(dt.hour == 16, "Check hour value, expected 16, got: %i", dt.hour);
SDLTest_AssertCheck(dt.minute == 35, "Check hour value, expected 35, got: %i", dt.minute);
SDLTest_AssertCheck(dt.second == 42, "Check hour value, expected 42, got: %i", dt.second);
result = SDL_DateTimeToTime(&dt, &ticks[1]);
SDLTest_AssertPass("Call to SDL_DateTimeToTime()");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
result = ticks[0] == ticks[1];
SDLTest_AssertCheck(result, "Check that original and converted SDL_Time values match: ticks0 = %" SDL_PRIs64 ", ticks1 = %" SDL_PRIs64, ticks[0], ticks[1]);
/* Local time unknown, so just verify success. */
result = SDL_TimeToDateTime(ticks[0], &dt, SDL_TRUE);
SDLTest_AssertPass("Call to SDL_TimeToLocalDateTime()");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
/* Convert back and verify result. */
result = SDL_DateTimeToTime(&dt, &ticks[1]);
SDLTest_AssertPass("Call to SDL_DateTimeToTime()");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
result = ticks[0] == ticks[1];
SDLTest_AssertCheck(result, "Check that original and converted SDL_Time values match: ticks0 = %" SDL_PRIs64 ", ticks1 = %" SDL_PRIs64, ticks[0], ticks[1]);
/* Advance the time one day. */
++dt.day;
if (dt.day > SDL_GetDaysInMonth(dt.year, dt.month)) {
dt.day = 1;
++dt.month;
}
if (dt.month > 12) {
dt.month = 1;
++dt.year;
}
result = SDL_DateTimeToTime(&dt, &ticks[1]);
SDLTest_AssertPass("Call to SDL_DateTimeToTime() (one day advanced)");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
result = (ticks[0] + SDL_SECONDS_TO_NS(86400)) == ticks[1];
SDLTest_AssertCheck(result, "Check that the difference is exactly 86400 seconds, got: %" SDL_PRIs64, (Sint64)SDL_NS_TO_SECONDS(ticks[1] - ticks[0]));
/* Check dates that overflow/underflow an SDL_Time */
dt.year = 2400;
dt.month = 1;
dt.day = 1;
result = SDL_DateTimeToTime(&dt, &ticks[0]);
SDLTest_AssertPass("Call to SDL_DateTimeToTime() (year overflows an SDL_Time)");
SDLTest_AssertCheck(result == -1, "Check result value, expected -1, got: %i", result);
dt.year = 1601;
result = SDL_DateTimeToTime(&dt, &ticks[0]);
SDLTest_AssertPass("Call to SDL_DateTimeToTime() (year underflows an SDL_Time)");
SDLTest_AssertCheck(result == -1, "Check result value, expected -1, got: %i", result);
return TEST_COMPLETED;
}
/**
* Test time utility functions.
*/
static int time_dateTimeUtilities(void *arg)
{
int result;
/* Leap-year */
result = SDL_GetDaysInMonth(2000, 2);
SDLTest_AssertPass("Call to SDL_GetDaysInMonth(2000, 2)");
SDLTest_AssertCheck(result == 29, "Check result value, expected 29, got: %i", result);
result = SDL_GetDaysInMonth(2001, 2);
SDLTest_AssertPass("Call to SDL_GetDaysInMonth(2001, 2)");
SDLTest_AssertCheck(result == 28, "Check result value, expected 28, got: %i", result);
result = SDL_GetDaysInMonth(2001, 13);
SDLTest_AssertPass("Call to SDL_GetDaysInMonth(2001, 13)");
SDLTest_AssertCheck(result == -1, "Check result value, expected -1, got: %i", result);
result = SDL_GetDaysInMonth(2001, -1);
SDLTest_AssertPass("Call to SDL_GetDaysInMonth(2001, 13)");
SDLTest_AssertCheck(result == -1, "Check result value, expected -1, got: %i", result);
/* 2000-02-29 was a Tuesday */
result = SDL_GetDayOfWeek(2000, 2, 29);
SDLTest_AssertPass("Call to SDL_GetDayOfWeek(2000, 2, 29)");
SDLTest_AssertCheck(result == 2, "Check result value, expected %i, got: %i", 2, result);
/* Nonexistent day */
result = SDL_GetDayOfWeek(2001, 2, 29);
SDLTest_AssertPass("Call to SDL_GetDayOfWeek(2001, 2, 29)");
SDLTest_AssertCheck(result == -1, "Check result value, expected -1, got: %i", result);
result = SDL_GetDayOfYear(2000, 1, 1);
SDLTest_AssertPass("Call to SDL_GetDayOfWeek(2001, 1, 1)");
SDLTest_AssertCheck(result == 0, "Check result value, expected 0, got: %i", result);
/* Leap-year */
result = SDL_GetDayOfYear(2000, 12, 31);
SDLTest_AssertPass("Call to SDL_GetDayOfYear(2000, 12, 31)");
SDLTest_AssertCheck(result == 365, "Check result value, expected 365, got: %i", result);
result = SDL_GetDayOfYear(2001, 12, 31);
SDLTest_AssertPass("Call to SDL_GetDayOfYear(2000, 12, 31)");
SDLTest_AssertCheck(result == 364, "Check result value, expected 364, got: %i", result);
/* Nonexistent day */
result = SDL_GetDayOfYear(2001, 2, 29);
SDLTest_AssertPass("Call to SDL_GetDayOfYear(2001, 2, 29)");
SDLTest_AssertCheck(result == -1, "Check result value, expected -1, got: %i", result);
/* Test Win32 time conversion */
Uint64 wintime = 11644473600LL * 10000000LL; /* The epoch */
SDL_Time ticks = SDL_TimeFromWindows((Uint32)(wintime & 0xFFFFFFFF), (Uint32)(wintime >> 32));
SDLTest_AssertPass("Call to SDL_TimeFromWindows()");
SDLTest_AssertCheck(ticks == 0, "Check result value, expected 0, got: %" SDL_PRIs64, ticks);
/* Out of range times should be clamped instead of rolling over */
wintime = 0;
ticks = SDL_TimeFromWindows((Uint32)(wintime & 0xFFFFFFFF), (Uint32)(wintime >> 32));
SDLTest_AssertPass("Call to SDL_TimeFromWindows()");
SDLTest_AssertCheck(ticks < 0 && ticks >= SDL_MIN_TIME, "Check result value, expected <0 && >=%" SDL_PRIs64 ", got: %" SDL_PRIs64, SDL_MIN_TIME, ticks);
wintime = 0xFFFFFFFFFFFFFFFFULL;
ticks = SDL_TimeFromWindows((Uint32)(wintime & 0xFFFFFFFF), (Uint32)(wintime >> 32));
SDLTest_AssertPass("Call to SDL_TimeFromWindows()");
SDLTest_AssertCheck(ticks > 0 && ticks <= SDL_MAX_TIME, "Check result value, expected >0 && <=%" SDL_PRIs64 ", got: %" SDL_PRIs64, SDL_MAX_TIME, ticks);
return TEST_COMPLETED;
}
/* ================= Test References ================== */
/* Time test cases */
static const SDLTest_TestCaseReference timeTest1 = {
(SDLTest_TestCaseFp)time_getRealtimeClock, "time_getRealtimeClock", "Call to SDL_GetRealtimeClockTicks", TEST_ENABLED
};
static const SDLTest_TestCaseReference timeTest2 = {
(SDLTest_TestCaseFp)time_dateTimeConversion, "time_dateTimeConversion", "Call to SDL_TimeToDateTime/SDL_DateTimeToTime", TEST_ENABLED
};
static const SDLTest_TestCaseReference timeTest3 = {
(SDLTest_TestCaseFp)time_dateTimeUtilities, "time_dateTimeUtilities", "Call to SDL_TimeToDateTime/SDL_DateTimeToTime", TEST_ENABLED
};
/* Sequence of Timer test cases */
static const SDLTest_TestCaseReference *timeTests[] = {
&timeTest1, &timeTest2, &timeTest3, NULL
};
/* Time test suite (global) */
SDLTest_TestSuiteReference timeTestSuite = {
"Time",
NULL,
timeTests,
NULL
};

214
test/testtime.c Normal file
View File

@@ -0,0 +1,214 @@
/*
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.
*/
/* Test program to check the resolution of the SDL timer on the current
platform
*/
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>
#include <SDL3/SDL_test.h>
#define CAL_Y_OFF 100
#define CAL_X_OFF 19
#define CELL_WIDTH 86
#define CELL_HEIGHT 60
static int cal_year;
static int cal_month;
static SDL_TIME_FORMAT time_format;
static SDL_DATE_FORMAT date_format;
static void RenderDateTime(SDL_Renderer *r)
{
const char *const WDAY[] = { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" };
const char *const MNAME[] = { "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul",
"Aug", "Sep", "Oct", "Nov", "Dec" };
const char *const TIMEPOST[] = { "", " AM", " PM" };
int x, y, day, len;
const char *postfix = TIMEPOST[0];
const int x_max = CAL_X_OFF + (CELL_WIDTH * 7);
const int y_max = CAL_Y_OFF + (CELL_HEIGHT * 6);
char str[256];
char short_date[128];
SDL_Time ticks;
SDL_DateTime dt;
SDL_SetRenderDrawColor(r, 0xFF, 0xFF, 0xFF, 0xFF);
/* Query the current time and print it. */
SDL_GetCurrentTime(&ticks);
SDL_TimeToDateTime(ticks, &dt, SDL_FALSE);
switch (date_format) {
case SDL_DATE_FORMAT_YYYYMMDD:
SDL_snprintf(short_date, sizeof(short_date), "%04d-%02d-%02d", dt.year, dt.month, dt.day);
break;
case SDL_DATE_FORMAT_DDMMYYYY:
SDL_snprintf(short_date, sizeof(short_date), "%02d.%02d.%04d", dt.day, dt.month, dt.year);
break;
case SDL_DATE_FORMAT_MMDDYYYY:
SDL_snprintf(short_date, sizeof(short_date), "%02d/%02d/%04d", dt.month, dt.day, dt.year);
break;
}
if (time_format) {
if (dt.hour > 12) { /* PM */
dt.hour -= 12;
postfix = TIMEPOST[2];
} else {
if (!dt.hour) { /* AM */
dt.hour = 12; /* Midnight */
}
postfix = TIMEPOST[1];
}
}
SDL_snprintf(str, sizeof(str), "UTC: %s %02d %s %04d (%s) %02d:%02d:%02d.%09d%s %+05d",
WDAY[dt.day_of_week], dt.day, MNAME[dt.month - 1], dt.year, short_date,
dt.hour, dt.minute, dt.second, dt.nanosecond, postfix, ((dt.utc_offset / 3600) * 100) + (dt.utc_offset % 3600));
SDLTest_DrawString(r, 10, 15, str);
SDL_TimeToDateTime(ticks, &dt, SDL_TRUE);
SDL_snprintf(str, sizeof(str), "Local: %s %02d %s %04d (%s) %02d:%02d:%02d.%09d%s %+05d",
WDAY[dt.day_of_week], dt.day, MNAME[dt.month - 1], dt.year, short_date,
dt.hour, dt.minute, dt.second, dt.nanosecond, postfix,
((dt.utc_offset / 3600) * 100) + (dt.utc_offset % 3600));
SDLTest_DrawString(r, 10, 30, str);
/* Draw a calendar. */
if (!cal_month) {
cal_month = dt.month;
cal_year = dt.year;
}
for (y = CAL_Y_OFF; y <= CAL_Y_OFF + (CELL_HEIGHT * 6); y += CELL_HEIGHT) {
SDL_RenderLine(r, CAL_X_OFF, y, x_max, y);
}
for (x = CAL_X_OFF; x <= CAL_X_OFF + (CELL_WIDTH * 7); x += CELL_WIDTH) {
SDL_RenderLine(r, x, CAL_Y_OFF, x, y_max);
}
/* Draw the month and year. */
len = SDL_snprintf(str, sizeof(str), "%s %04d", MNAME[cal_month - 1], cal_year);
SDLTest_DrawString(r, (CAL_X_OFF + ((x_max - CAL_X_OFF) / 2)) - ((FONT_CHARACTER_SIZE * len) / 2), CAL_Y_OFF - (FONT_LINE_HEIGHT * 3), str);
/* Draw day names */
for (x = 0; x < 7; ++x) {
int offset = ((CAL_X_OFF + (CELL_WIDTH * x)) + (CELL_WIDTH / 2)) - ((FONT_CHARACTER_SIZE * 3) / 2);
SDLTest_DrawString(r, offset, CAL_Y_OFF - FONT_LINE_HEIGHT, WDAY[x]);
}
day = SDL_GetDayOfWeek(cal_year, cal_month, 1);
x = CAL_X_OFF + (day * CELL_WIDTH + (CELL_WIDTH - (FONT_CHARACTER_SIZE * 3)));
day = 0;
y = CAL_Y_OFF + FONT_LINE_HEIGHT;
while (++day <= SDL_GetDaysInMonth(cal_year, cal_month)) {
SDL_snprintf(str, sizeof(str), "%02d", day);
/* Highlight the current day in red. */
if (cal_year == dt.year && cal_month == dt.month && day == dt.day) {
SDL_SetRenderDrawColor(r, 0xFF, 0, 0, 0xFF);
}
SDLTest_DrawString(r, x, y, str);
SDL_SetRenderDrawColor(r, 0xFF, 0xFF, 0xFF, 0xFF);
x += CELL_WIDTH;
if (x >= x_max) {
x = CAL_X_OFF + (CELL_WIDTH - (FONT_CHARACTER_SIZE * 3));
y += CELL_HEIGHT;
}
}
}
int main(int argc, char *argv[])
{
SDLTest_CommonState *state;
SDL_Event event;
int done;
/* Initialize test framework */
state = SDLTest_CommonCreateState(argv, SDL_INIT_VIDEO);
if (!state) {
return 1;
}
/* Enable standard application logging */
SDL_LogSetPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_INFO);
/* Parse commandline */
if (!SDLTest_CommonDefaultArgs(state, argc, argv)) {
return 1;
}
if (!SDLTest_CommonInit(state)) {
goto quit;
}
time_format = SDL_GetNumberProperty(SDL_GetGlobalProperties(), SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER, SDL_TIME_FORMAT_24HR);
date_format = SDL_GetNumberProperty(SDL_GetGlobalProperties(), SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER, SDL_DATE_FORMAT_YYYYMMDD);
/* Main render loop */
done = 0;
while (!done) {
/* Check for events */
while (SDL_PollEvent(&event)) {
SDLTest_CommonEvent(state, &event, &done);
if (event.type == SDL_EVENT_KEY_DOWN) {
switch (event.key.keysym.sym) {
case SDLK_UP:
if (++cal_month > 12) {
cal_month = 1;
++cal_year;
}
break;
case SDLK_DOWN:
if (--cal_month < 1) {
cal_month = 12;
--cal_year;
}
break;
case SDLK_1:
time_format = SDL_TIME_FORMAT_24HR;
break;
case SDLK_2:
time_format = SDL_TIME_FORMAT_12HR;
break;
case SDLK_3:
date_format = SDL_DATE_FORMAT_YYYYMMDD;
break;
case SDLK_4:
date_format = SDL_DATE_FORMAT_DDMMYYYY;
break;
case SDLK_5:
date_format = SDL_DATE_FORMAT_MMDDYYYY;
break;
default:
break;
}
}
}
SDL_SetRenderDrawColor(state->renderers[0], 0x00, 0x00, 0x00, 0xFF);
SDL_RenderClear(state->renderers[0]);
RenderDateTime(state->renderers[0]);
SDL_RenderPresent(state->renderers[0]);
}
quit:
SDLTest_CommonQuit(state);
return 0;
}