power info, calendar/datetime.reset, CLI fix, docs

* Registers the system_power_info function with documentation.

* The calendar and datetime classes now have a reset method, which is the same as assigning the calendar or datetime to a fresh instnace of it's type.

* Document array.find.

* Fix broken pack test case which used the now deprecated file_contents.nvgt include.

* fix is_console_available again.

doc/src/references/builtin/!Containers/array/Methods/find.nvgt

@@ -0,0 +1,22 @@
+/**
+	Search for an item in an array.
+	1. int find(const T&in value);
+	2. 	int find(uint start_at, const T&in value);
+	## Arguments:
+		* uint start_at: An optional index to begin searching from.
+		* const T&in value: The value to search for.
+	## Returns:
+		int: The index of the located item, or -1 if not found.
+	## Remarks:
+		Be ware that this method will start getting slower the larger your array is, this is because this find method must search through every item in the array until it finds an item that equals what you are looking for.
+		Be sure to never write code like `string value = array[array.find("testing")];` or anything else where you call array.find() directly within the array's indexing operator. This is because array.find() could return -1, meaning that an index out of bounds exception will be thrown if you use the value returned by this function without verifying it first.
+*/
+
+// Example:
+void main() {
+	string text = "this is a sentence made up of many words, sort of?";
+	string[]@ elements = text.split(" ,?.", false);
+	int word = elements.find("sort");
+	if (word < 0) alert("Oh no not found", "Someone should probably report this if they ever see it while running an unmodified version of this example...");
+	else alert("found", "The word sort is at index " + word);
+}

doc/src/references/builtin/Date and Time/Classes/datetime/Methods/reset.nvgt

@@ -0,0 +1,15 @@
+/**
+	Resets this datetime object to the current date and time.
+	void reset();
+	## Remarks:
+		The expression d.reset() is equivalent to the expression d = datetime(); this is only a convenience function.
+*/
+
+// Example:
+void main() {
+	datetime d;
+	d.set(2024, 3, 9, 1, 24, 49);
+	alert("The datetime object is currently set to", d.year + "/" + d.month + "/" + d.day + ", " + d.hour + ":" + d.minute + ":" + d.second);
+	d.reset();
+	alert("The datetime object is now set to", d.year + "/" + d.month + "/" + d.day + ", " + d.hour + ":" + d.minute + ":" + d.second);
+}

doc/src/references/builtin/Environment/Functions/system_power_info.nvgt

@@ -0,0 +1,41 @@
+/**
+	Determine the state of the system's battery.
+	system_power_state system_power_info(int&out seconds = void, int&out percent = void);
+	## Arguments:
+		* int&out seconds = void: Where to store the number of remaining charge time in seconds.
+		* int&out percent = void: Where to store the percentage of battery charge remaining.
+	## Returns:
+		system_power_state: One of POWER_STATE_ERROR, POWER_STATE_UNKNOWN, POWER_STATE_ON_BATTERY, POWER_STATE_NO_BATTERY, POWER_STATE_CHARGING or POWER_STATE_CHARGED.
+	## Remarks:
+		This could be useful for various reasons, such as backing up game data on low battery or showing extra mercy to online game players who run out of battery power who you might otherwise punish/tag for unlawful disconnection.
+		If the battery percentage or time remaining cannot be determined, that value will be set to -1.
+		Whether a time or percentage is available is up to the underlying operating system.
+*/
+
+// Example:
+// Utility function to convert a system_power_state to a string.
+string describe_power_state(system_power_state st) {
+	switch (st) {
+		case POWER_STATE_ERROR: return "error";
+		case POWER_STATE_ON_BATTERY: return "on battery";
+		case POWER_STATE_NO_BATTERY: return "no battery";
+		case POWER_STATE_CHARGING: return "charging";
+		case POWER_STATE_CHARGED: return "charged";
+		default: return "unknown";
+	}
+}
+void main() {
+	system_power_state old_state = system_power_info();
+	show_window(describe_power_state(old_state));
+	while (!key_pressed(KEY_ESCAPE) and !key_pressed(KEY_AC_BACK)) {
+		wait(5);
+		int seconds, percent;
+		system_power_state st = system_power_info(seconds, percent);
+		if (st != old_state) show_window(describe_power_state(st));
+		old_state = st;
+		if (key_pressed(KEY_SPACE)) {
+			string time_str = seconds > -1? " (" + timespan(seconds, 0).format() + ")" : "";
+			screen_reader_speak(percent > -1? percent + "%" + time_str : "unable to determine battery percent");
+		}
+	}
+}

src/UI.cpp

@@ -391,11 +391,7 @@ uint64_t idle_ticks() {
 
 bool is_console_available() {
 	#if defined (_WIN32)
-		#ifdef NVGT_WIN_APP
-		return GetConsoleWindow() != nullptr;
-		#else
-		return true;
-		#endif
+		return Poco::Util::Application::instance().config().hasOption("application.gui")? GetConsoleWindow() != nullptr : true;
 	#else
 		return isatty(fileno(stdin)) || isatty(fileno(stdout)) || isatty(fileno(stderr));
 	#endif

src/misc_functions.cpp

@@ -343,4 +343,12 @@ void RegisterMiscFunctions(asIScriptEngine* engine) {
 	engine->RegisterGlobalFunction(_O("void memory_free(uint64 ptr)"), asFUNCTION(free), asCALL_CDECL);
 	engine->RegisterGlobalFunction("float parse_float(const string &in number)", asFUNCTION(parse_float), asCALL_CDECL);
 	engine->RegisterGlobalFunction("double parse_double(const string &in number)", asFUNCTION(parse_double), asCALL_CDECL);
+	engine->RegisterEnum("system_power_state");
+	engine->RegisterEnumValue("system_power_state", "POWER_STATE_ERROR", SDL_POWERSTATE_ERROR);
+	engine->RegisterEnumValue("system_power_state", "POWER_STATE_UNKNOWN", SDL_POWERSTATE_UNKNOWN);
+	engine->RegisterEnumValue("system_power_state", "POWER_STATE_ON_BATTERY", SDL_POWERSTATE_ON_BATTERY);
+	engine->RegisterEnumValue("system_power_state", "POWER_STATE_NO_BATTERY", SDL_POWERSTATE_NO_BATTERY);
+	engine->RegisterEnumValue("system_power_state", "POWER_STATE_CHARGING", SDL_POWERSTATE_CHARGING);
+	engine->RegisterEnumValue("system_power_state", "POWER_STATE_CHARGED", SDL_POWERSTATE_CHARGED);
+	engine->RegisterGlobalFunction("system_power_state system_power_info(int&out seconds = void, int&out percent = void)", asFUNCTION(SDL_GetPowerInfo), asCALL_CDECL);
 }

src/timestuff.cpp

@@ -308,6 +308,8 @@ template <class T, typename O> int timestuff_opCmp(T* self, O other) {
 	else if (*self > other) return 1;
 	else return 0;
 }
+// Assigns one of the datetime types to a new version of itself E. the current date and time.
+template <class T> void timestuff_reset(T* obj) { (*obj) = T(); }
 
 void RegisterScriptTimestuff(asIScriptEngine* engine) {
 	engine->SetDefaultAccessMask(NVGT_SUBSYSTEM_DATETIME);
@@ -326,7 +328,7 @@ void RegisterScriptTimestuff(asIScriptEngine* engine) {
 	engine->RegisterGlobalFunction(_O("uint64 nanoticks()"), asFUNCTION(SDL_GetTicksNS), asCALL_CDECL);
 	engine->RegisterGlobalFunction(_O("uint64 get_SYSTEM_PERFORMANCE_COUNTER() property"), asFUNCTION(SDL_GetPerformanceCounter), asCALL_CDECL);
 	engine->RegisterGlobalFunction(_O("uint64 get_SYSTEM_PERFORMANCE_FREQUENCY() property"), asFUNCTION(SDL_GetPerformanceFrequency), asCALL_CDECL);
-	engine->RegisterGlobalFunction(_O("void nanosleep(uint64 ns)"), asFUNCTION(SDL_GetTicksNS), asCALL_CDECL);
+	engine->RegisterGlobalFunction(_O("void nanosleep(uint64 ns)"), asFUNCTION(SDL_DelayNS), asCALL_CDECL);
 	engine->SetDefaultAccessMask(NVGT_SUBSYSTEM_OS);
 	engine->RegisterGlobalFunction(_O("uint64 get_TIME_SYSTEM_RUNNING_MILLISECONDS() property"), asFUNCTION(system_running_milliseconds), asCALL_CDECL);
 	engine->RegisterGlobalFunction("int get_TIMEZONE_BASE_OFFSET() property", asFUNCTION(Poco::Timezone::utcOffset), asCALL_CDECL);
@@ -483,6 +485,7 @@ void RegisterScriptTimestuff(asIScriptEngine* engine) {
 	engine->RegisterObjectMethod("datetime", "datetime& opSubAssign(const timespan&in)", asMETHODPR(DateTime, operator-=, (const Timespan&), DateTime&), asCALL_THISCALL);
 	engine->RegisterObjectMethod("datetime", "void make_UTC(int timezone_offset)", asMETHOD(DateTime, makeUTC), asCALL_THISCALL);
 	engine->RegisterObjectMethod("datetime", "void make_local(int timezone_offset)", asMETHOD(DateTime, makeLocal), asCALL_THISCALL);
+	engine->RegisterObjectMethod("datetime", "void reset()", asFUNCTION(timestuff_reset<DateTime>), asCALL_CDECL_OBJFIRST);
 	engine->RegisterGlobalFunction("bool datetime_is_leap_year(int year)", asFUNCTION(DateTime::isLeapYear), asCALL_CDECL);
 	engine->RegisterGlobalFunction("int datetime_days_of_month(int year, int month)", asFUNCTION(DateTime::daysOfMonth), asCALL_CDECL);
 	engine->RegisterGlobalFunction("bool datetime_is_valid(int year, int month, int day, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0)", asFUNCTION(DateTime::isValid), asCALL_CDECL);
@@ -522,6 +525,7 @@ void RegisterScriptTimestuff(asIScriptEngine* engine) {
 	engine->RegisterObjectMethod("calendar", "timespan opSub(const calendar&in) const", asMETHODPR(LocalDateTime, operator-, (const LocalDateTime&) const, Timespan), asCALL_THISCALL);
 	engine->RegisterObjectMethod("calendar", "calendar& opAddAssign(const timespan&in)", asMETHODPR(LocalDateTime, operator+=, (const Timespan&), LocalDateTime&), asCALL_THISCALL);
 	engine->RegisterObjectMethod("calendar", "calendar& opSubAssign(const timespan&in)", asMETHODPR(LocalDateTime, operator-=, (const Timespan&), LocalDateTime&), asCALL_THISCALL);
+	engine->RegisterObjectMethod("calendar", "void reset()", asFUNCTION(timestuff_reset<LocalDateTime>), asCALL_CDECL_OBJFIRST);
 
 	engine->RegisterObjectMethod("timestamp", "string format(const string&in fmt, int tzd = 0xffff)", asFUNCTIONPR(DateTimeFormatter::format, (const Timestamp&, const std::string&, int), std::string), asCALL_CDECL_OBJFIRST);
 	engine->RegisterObjectMethod("datetime", "string format(const string&in fmt, int tzd = 0xffff)", asFUNCTIONPR(DateTimeFormatter::format, (const DateTime&, const std::string&, int), std::string), asCALL_CDECL_OBJFIRST);

test/case/pack.nvgt

@@ -1,13 +1,11 @@
-#include "file_contents.nvgt"
-
 void test_pack() {
-	put_file_contents("tmp/pack.dat", "test overwrite: lets start with bogus data");
+	file_put_contents("tmp/pack.dat", "test overwrite: lets start with bogus data");
 	dictionary cases;
 	pack p;
 	assert(p.open("tmp/pack.dat", PACK_OPEN_MODE_CREATE));
 	string[]@ case_list = find_files("case/*.nvgt");
 	for (uint i = 0; i < case_list.length(); i++) {
-		string case_data = get_file_contents("case/" + case_list[i]);
+		string case_data = file_get_contents("case/" + case_list[i]);
 		if (case_data.empty()) {
 			case_list.remove_at(i);
 			i--;