Merge pull request #54056 from aaronfranke/3.x-time

godotengine · Nov 29, 2021 · 5120c67 · 5120c67
2 parents 964c6ec + 035a84f
commit 5120c67
Show file tree

Hide file tree

Showing 7 changed files with 798 additions and 0 deletions.
diff --git a/core/os/time.cpp b/core/os/time.cpp
diff --git a/core/os/time.h b/core/os/time.h
@@ -0,0 +1,109 @@
+/*************************************************************************/
+/*  time.h                                                               */
+/*************************************************************************/
+/*                       This file is part of:                           */
+/*                           GODOT ENGINE                                */
+/*                      https://godotengine.org                          */
+/*************************************************************************/
+/* Copyright (c) 2007-2021 Juan Linietsky, Ariel Manzur.                 */
+/* Copyright (c) 2014-2021 Godot Engine contributors (cf. AUTHORS.md).   */
+/*                                                                       */
+/* Permission is hereby granted, free of charge, to any person obtaining */
+/* a copy of this software and associated documentation files (the       */
+/* "Software"), to deal in the Software without restriction, including   */
+/* without limitation the rights to use, copy, modify, merge, publish,   */
+/* distribute, sublicense, and/or sell copies of the Software, and to    */
+/* permit persons to whom the Software is furnished to do so, subject to */
+/* the following conditions:                                             */
+/*                                                                       */
+/* The above copyright notice and this permission notice shall be        */
+/* included in all copies or substantial portions of the Software.       */
+/*                                                                       */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY  */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,  */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE     */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
+/*************************************************************************/
+
+#ifndef TIME_H
+#define TIME_H
+
+#include "core/class_db.h"
+
+// This Time class conforms with as many of the ISO 8601 standards as possible.
+// * As per ISO 8601:2004 4.3.2.1, all dates follow the Proleptic Gregorian
+//   calendar. As such, the day before 1582-10-15 is 1582-10-14, not 1582-10-04.
+//   See: https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
+// * As per ISO 8601:2004 3.4.2 and 4.1.2.4, the year before 1 AD (aka 1 BC)
+//   is number "0", with the year before that (2 BC) being "-1", etc.
+// Conversion methods assume "the same timezone", and do not handle DST.
+// Leap seconds are not handled, they must be done manually if desired.
+// Suffixes such as "Z" are not handled, you need to strip them away manually.
+
+class Time : public Object {
+	GDCLASS(Time, Object);
+	static void _bind_methods();
+	static Time *singleton;
+
+public:
+	static Time *get_singleton();
+
+	enum Month : uint8_t {
+		/// Start at 1 to follow Windows SYSTEMTIME structure
+		/// https://msdn.microsoft.com/en-us/library/windows/desktop/ms724950(v=vs.85).aspx
+		MONTH_JANUARY = 1,
+		MONTH_FEBRUARY,
+		MONTH_MARCH,
+		MONTH_APRIL,
+		MONTH_MAY,
+		MONTH_JUNE,
+		MONTH_JULY,
+		MONTH_AUGUST,
+		MONTH_SEPTEMBER,
+		MONTH_OCTOBER,
+		MONTH_NOVEMBER,
+		MONTH_DECEMBER,
+	};
+
+	enum Weekday : uint8_t {
+		WEEKDAY_SUNDAY,
+		WEEKDAY_MONDAY,
+		WEEKDAY_TUESDAY,
+		WEEKDAY_WEDNESDAY,
+		WEEKDAY_THURSDAY,
+		WEEKDAY_FRIDAY,
+		WEEKDAY_SATURDAY,
+	};
+
+	// Methods that convert times.
+	Dictionary get_datetime_dict_from_unix_time(int64_t p_unix_time_val) const;
+	Dictionary get_date_dict_from_unix_time(int64_t p_unix_time_val) const;
+	Dictionary get_time_dict_from_unix_time(int64_t p_unix_time_val) const;
+	String get_datetime_string_from_unix_time(int64_t p_unix_time_val, bool p_use_space = false) const;
+	String get_date_string_from_unix_time(int64_t p_unix_time_val) const;
+	String get_time_string_from_unix_time(int64_t p_unix_time_val) const;
+	Dictionary get_datetime_dict_from_string(String p_datetime, bool p_weekday = true) const;
+	String get_datetime_string_from_dict(Dictionary p_datetime, bool p_use_space = false) const;
+	int64_t get_unix_time_from_datetime_dict(Dictionary p_datetime) const;
+	int64_t get_unix_time_from_datetime_string(String p_datetime) const;
+
+	// Methods that get information from OS.
+	Dictionary get_datetime_dict_from_system(bool p_utc = false) const;
+	Dictionary get_date_dict_from_system(bool p_utc = false) const;
+	Dictionary get_time_dict_from_system(bool p_utc = false) const;
+	String get_datetime_string_from_system(bool p_utc = false, bool p_use_space = false) const;
+	String get_date_string_from_system(bool p_utc = false) const;
+	String get_time_string_from_system(bool p_utc = false) const;
+	Dictionary get_time_zone_from_system() const;
+	double get_unix_time_from_system() const;
+	uint64_t get_ticks_msec() const;
+	uint64_t get_ticks_usec() const;
+
+	Time();
+	virtual ~Time();
+};
+
+#endif // TIME_H
diff --git a/core/register_core_types.cpp b/core/register_core_types.cpp
@@ -65,6 +65,7 @@
 #include "core/math/triangle_mesh.h"
 #include "core/os/input.h"
 #include "core/os/main_loop.h"
+#include "core/os/time.h"
 #include "core/packed_data_container.h"
 #include "core/path_remap.h"
 #include "core/project_settings.h"
@@ -250,6 +251,7 @@ void register_core_singletons() {
 	ClassDB::register_class<InputMap>();
 	ClassDB::register_class<_JSON>();
 	ClassDB::register_class<Expression>();
+	ClassDB::register_class<Time>();
 
 	Engine::get_singleton()->add_singleton(Engine::Singleton("ProjectSettings", ProjectSettings::get_singleton()));
 	Engine::get_singleton()->add_singleton(Engine::Singleton("IP", IP::get_singleton()));
@@ -264,6 +266,7 @@ void register_core_singletons() {
 	Engine::get_singleton()->add_singleton(Engine::Singleton("Input", Input::get_singleton()));
 	Engine::get_singleton()->add_singleton(Engine::Singleton("InputMap", InputMap::get_singleton()));
 	Engine::get_singleton()->add_singleton(Engine::Singleton("JSON", _JSON::get_singleton()));
+	Engine::get_singleton()->add_singleton(Engine::Singleton("Time", Time::get_singleton()));
 }
 
 void unregister_core_types() {

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
@@ -77,6 +77,9 @@
 		<member name="ResourceSaver" type="ResourceSaver" setter="" getter="">
 			The [ResourceSaver] singleton.
 		</member>
+		<member name="Time" type="Time" setter="" getter="">
+			The [Time] singleton.
+		</member>
 		<member name="TranslationServer" type="TranslationServer" setter="" getter="">
 			The [TranslationServer] singleton.
 		</member>

diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml
@@ -184,20 +184,23 @@
 			<return type="Dictionary" />
 			<argument index="0" name="utc" type="bool" default="false" />
 			<description>
+				Deprecated, use [method Time.get_date_dict_from_system] instead.
 				Returns current date as a dictionary of keys: [code]year[/code], [code]month[/code], [code]day[/code], [code]weekday[/code], [code]dst[/code] (Daylight Savings Time).
 			</description>
 		</method>
 		<method name="get_datetime" qualifiers="const">
 			<return type="Dictionary" />
 			<argument index="0" name="utc" type="bool" default="false" />
 			<description>
+				Deprecated, use [method Time.get_datetime_dict_from_system] instead.
 				Returns current datetime as a dictionary of keys: [code]year[/code], [code]month[/code], [code]day[/code], [code]weekday[/code], [code]dst[/code] (Daylight Savings Time), [code]hour[/code], [code]minute[/code], [code]second[/code].
 			</description>
 		</method>
 		<method name="get_datetime_from_unix_time" qualifiers="const">
 			<return type="Dictionary" />
 			<argument index="0" name="unix_time_val" type="int" />
 			<description>
+				Deprecated, use [method Time.get_datetime_dict_from_unix_time] instead.
 				Gets a dictionary of time values corresponding to the given UNIX epoch time (in seconds).
 				The returned Dictionary's values will be the same as [method get_datetime], with the exception of Daylight Savings Time as it cannot be determined from the epoch.
 			</description>
@@ -467,19 +470,22 @@
 		<method name="get_ticks_msec" qualifiers="const">
 			<return type="int" />
 			<description>
+				Deprecated, use [method Time.get_ticks_msec] instead.
 				Returns the amount of time passed in milliseconds since the engine started.
 			</description>
 		</method>
 		<method name="get_ticks_usec" qualifiers="const">
 			<return type="int" />
 			<description>
+				Deprecated, use [method Time.get_ticks_usec] instead.
 				Returns the amount of time passed in microseconds since the engine started.
 			</description>
 		</method>
 		<method name="get_time" qualifiers="const">
 			<return type="Dictionary" />
 			<argument index="0" name="utc" type="bool" default="false" />
 			<description>
+				Deprecated, use [method Time.get_time_dict_from_system] instead.
 				Returns current time as a dictionary of keys: hour, minute, second.
 			</description>
 		</method>