Documentation

* Partially document timestamp class, still needs operators and maybe a couple other things.
* Completely documented thread_event class as well as concurrency enums.
* update datetime property examples to say "set thing" instead of "current thing," document julian_day property.
* Documents timestamp_from_UTC_time function.
* Documents thread_current_id and thread_yield.
* documents sound_global_pack property.
* Various minor polishing for a few functions in data manipulation, audio, and user interface.

doc/src/references/builtin/Audio/Global Properties/sound_default_pack.md

@@ -0,0 +1,4 @@
+# sound_default_pack
+The default value passed to the second argument of sound::load, in other words, a handle to an open pack object that all future sounds will load from unless otherwise specified individually.
+
+`pack@ sound_default_pack = null;`

doc/src/references/builtin/Audio/Global Properties/sound_global_hrtf.md

@@ -3,4 +3,4 @@ Controls weather to use steam audio's functionality. If this property is set to
 
 `bool sound_global_hrtf;`
 
-Changes take nearly instant effect from the time this property is changed.
+Changes take nearly instant effect from the time this property is modified.

doc/src/references/builtin/Concurrency/Classes/thread_event/!thread_event.nvgt

@@ -0,0 +1,36 @@
+/**
+	This concurrency primative implements a method by which one or more threads can safely wait on another thread for the event to become signaled.
+	thread_event(thread_event_type type = THREAD_EVENT_AUTO_RESET);
+	## Arguments:
+		thread_event_type type: The type of handling to perform when a waiting thread detects that the event has been set (see remarks).
+	## Remarks:
+		This primative can be used to make one thread inexpensively sleep until another thread wakes it up, or can more simply be used for some threads to monitor when a condition has been completed on another thread in a safe manner.
+		It is not a good idea to just use standard booleans in multithreaded situations where you want one thread to know when another thread has completed it's work because threads could be reading from the boolean as it is being written to by a worker thread, causing an undefined result. The thread_event object is one way around this issue, as it can signal when a standard boolean is safe to access or sometimes avoid their usage entirely.
+		Quite simply one thread can call the set() method on an event, and if another thread has previously called the wait() method on the same event, that wait method will return thus resuming the first thread. If the event was created with the THREAD_EVENT_AUTO_RESET type, the event will also be set to unsignaled as the waiting thread wakes up. Otherwise, the reset() method must be called manually.
+*/
+
+// Example:
+// Globals
+thread_event program_event;
+bool exit_program;
+string message;
+void message_thread() {
+	while (true) {
+		program_event.wait();
+		if (exit_program) return;
+		screen_reader_speak(message, true);
+	}
+}
+void main() {
+	show_window("press space to speak on another thread");
+	async<void>(message_thread);
+	while (!key_pressed(KEY_ESCAPE)) {
+		wait(5);
+		if (key_repeating(KEY_SPACE)) {
+			message = "the date and time is " + calendar().format(DATE_TIME_FORMAT_RFC1123);
+			program_event.set();
+		}
+	}
+	exit_program = true;
+	program_event.set();
+}

doc/src/references/builtin/Concurrency/Classes/thread_event/Methods/reset.md

@@ -0,0 +1,8 @@
+# reset
+Resets an event to an unsignaled state.
+`void reset();`
+
+## Remarks:
+This method is usually only needed if THREAD_EVENT_MANUAL_RESET was specified when the event was created, however you could also cancel the signaling of an event if another thread hasn't detected the signal yet.
+
+See the main event and mutex chapters for examples.

doc/src/references/builtin/Concurrency/Classes/thread_event/Methods/set.md

@@ -0,0 +1,6 @@
+# set
+Causes an event to become signaled, waking up any threads waiting for this condition.
+`void set();`
+
+## Remarks:
+All existing examples that use events must call this method, so it will not be demonstrated in this chapter.

doc/src/references/builtin/Concurrency/Classes/thread_event/Methods/try_wait.nvgt

@@ -0,0 +1,25 @@
+/**
+	Wait a given number of milliseconds for an event to become signaled.
+	bool try_wait(uint milliseconds);
+	## Arguments:
+		* uint milliseconds: The amount of time to wait, may be 0 to not wait at all.
+	## Returns:
+		bool: True if another thread has signaled the event, or false if the event is still unsignaled after the given number of milliseconds has elapsed.
+	## Remarks:
+		The semantics of this function are exactly the same as mutex::try_wait(), accept that this function waits on an event instead of a mutex.
+*/
+
+// Example:
+thread_event g_wait;
+void test_thread() {
+	screen_reader_speak("started", true);
+	while (!g_wait.try_wait(1000)) screen_reader_speak("waiting...", true);
+	screen_reader_speak("ah!", true);
+	g_wait.set();
+}
+void main() {
+	async<void>(test_thread);
+	wait(3500);
+	g_wait.set();
+	g_wait.wait(); // So we'll know the other thread has finished speaking it's final message.
+}

doc/src/references/builtin/Concurrency/Classes/thread_event/Methods/wait.md

@@ -0,0 +1,11 @@
+# wait
+waits for the event to become signaled, blocking indefinitely or for a given duration if required.
+
+1. `void wait();`
+2. `void wait(uint milliseconds);`
+
+## Arguments (2):
+* uint milliseconds: How long to wait for the event to become signaled before throwing an exception
+
+## Remarks:
+Beware that if you use the version of the wait function that takes a timeout argument, an exception will be thrown if the timeout expires without the event having become signaled. The version of the function taking 0 arguments waits forever for the event's set() method to be called.

doc/src/references/builtin/Concurrency/Enums/thread_event_type.md

@@ -0,0 +1,4 @@
+# thread_event_type
+These are the possible event types that can be used to successfully construct thread_event objects.
+* THREAD_EVENT_MANUAL_RESET: Many threads can wait on this event because the `thread_event::reset()` method must be manually called.
+* THREAD_EVENT_AUTO_RESET: Only one thread can wait on this event because it will be automatically reset as soon as the waiting thread detects that the event has become signaled.

doc/src/references/builtin/Concurrency/Enums/thread_priority.md

@@ -0,0 +1,7 @@
+# thread_priority
+It is possible to set a thread's priority to the following values in NVGT:
+* THREAD_PRIORITY_LOWEST
+* THREAD_PRIORITY_LOW
+* THREAD_PRIORITY_NORMAL
+* THREAD_PRIORITY_HIGH
+* THREAD_PRIORITY_HIGHEST

doc/src/references/builtin/Concurrency/Functions/thread_current_id.nvgt

@@ -0,0 +1,11 @@
+/**
+	Determine the operating system specific ID of the currently executing thread.
+	uint thread_current_id();
+	## Returns:
+		uint: The ID of the thread that this function was called on.
+*/
+
+// Example
+void main() {
+	alert("Current thread ID is", thread_current_id());
+}

doc/src/references/builtin/Concurrency/Functions/thread_yield.md

@@ -0,0 +1,6 @@
+# thread_yield
+Yields CPU to other threads.
+void thread_yield();
+
+## Remarks:
+This is a little bit like executing `wait(0);` accept that it doesn't pull the window, and there is absolutely no sleeping. It will temporarily yield code execution to the next scheduled thread that is of the same or higher priority as the one that called this function.

doc/src/references/builtin/Data Manipulation/Functions/character_to_ascii.nvgt

@@ -5,6 +5,9 @@
 		* string character: the character to convert.
 	## Returns:
 		uint8: the ascii value for the given character.
+	## Remarks:
+		If a string containing more than one character is passed as input to this function, only the left-most character is checked.
+		If an empty string is passed, the function returns 0.
 */
 
 // Example:

doc/src/references/builtin/Data Manipulation/Functions/pack_set_global_identifier.md

@@ -12,3 +12,4 @@ bool: true if the identifier was properly set, false otherwise.
 ## Remarks:
 * The default pack identifier is "NVPK" followed by 4 NULL bytes.
 * Your pack identifier should be 8 characters or less. If it's less than 8 characters, 0s will be added as padding on the end. If it's larger than 8, the first 8 characters will be used.
+* NVGT will refuse to open any pack files that do not match this identifier.

doc/src/references/builtin/Data Manipulation/Functions/regexp_match.nvgt

@@ -7,6 +7,7 @@
 	## Returns:
 		bool: true if the text matches the given regular expression, false otherwise.
 	## Remarks:
+		If you would like a lower level interface to regular_expressions in NVGT, check out the regexp class which this function more or less wraps.
 		To learn more about regular expressions, visit: https://en.wikipedia.org/wiki/Regular_expression
 */
 

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/AM.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8, 14, 18);
-	alert("The datetime's AM value is", d.AM);
+	alert("The datetime's AM value was set to", d.AM);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/PM.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8, 14, 18);
-	alert("The datetime's PM value is", d.PM);
+	alert("The datetime's set PM value is", d.PM);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/day.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8);
-	alert("The datetime's current day is", d.day);
+	alert("The datetime's set day is", d.day);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/hour.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(d.year, d.month, d.day, 13, 47, 19);
-	alert("The current hour of the datetime object is", d.hour);
+	alert("The set hour of the datetime object is", d.hour);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/hour12.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(d.year, d.month, d.day, 13, 47, 19);
-	alert("In 12 hour time, the current hour of the datetime object is", d.hour12);
+	alert("In 12 hour time, the set hour of the datetime object is", d.hour12);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/julian_day.nvgt

@@ -0,0 +1,13 @@
+/**
+	Represents the current timestamp held by the datetime object in julian days.
+	const double julian_day;
+	## Remarks:
+		The [julian day](http://en.wikipedia.org/wiki/Julian_day) measures, including decimal fractions, the amount of time that has passed (in years) since Monday, January 1st, 4713 BC at 12 PM Universal Time.
+*/
+
+// Example:
+void main() {
+	datetime d;
+	d.set(2024, 5, 8, 16, 17, 18);
+	alert("The julian day represented by this datetime object is", d.julian_day);
+}

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/microsecond.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(d.year, d.month, d.day, 12, 47, 19, 217, 962);
-	alert("The current microsecond value of the datetime object is", d.microsecond);
+	alert("The set microsecond value of the datetime object is", d.microsecond);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/millisecond.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(d.year, d.month, d.day, 12, 47, 19, 217);
-	alert("The current millisecond value of the datetime object is", d.millisecond);
+	alert("The set millisecond value of the datetime object is", d.millisecond);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/minute.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(d.year, d.month, d.day, 12, 47, 19);
-	alert("The current minute of the datetime object is", d.minute);
+	alert("The set minute of the datetime object is", d.minute);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/month.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8);
-	alert("The datetime's current month is", d.month);
+	alert("The datetime's set month is", d.month);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/second.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(d.year, d.month, d.day, 12, 47, 19);
-	alert("The current second of the datetime object is", d.second);
+	alert("The set second of the datetime object is", d.second);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/weekday.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8);
-	alert("The datetime's current day of the week is", d.weekday);
+	alert("The datetime's set day of the week is", d.weekday);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/year.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8);
-	alert("The datetime's current year is", d.year);
+	alert("The datetime's set year is", d.year);
 }

doc/src/references/builtin/Date and Time/Classes/datetime/Properties/yearday.nvgt

@@ -7,5 +7,5 @@
 void main() {
 	datetime d;
 	d.set(2024, 5, 8);
-	alert("The datetime's current day of the year is", d.yearday);
+	alert("The datetime's set day of the year is", d.yearday);
 }

doc/src/references/builtin/Date and Time/Classes/timestamp/!timestamp.md

@@ -0,0 +1,11 @@
+# timestamp
+Stores a unix timestamp with microsecond accuracy and provides methods for comparing them.
+1. timestamp();
+2. timestamp(int64 epoch_microseconds);
+
+## Arguments 2:
+* int64 epoch_microseconds: the initial value of the timestamp
+
+## Remarks:
+If a timestamp object is initialize with the default constructor, it will be set to the system's current date and time.
+The unix epoch began on January 1st, 1970 at 12 AM UTC.

doc/src/references/builtin/Date and Time/Classes/timestamp/Methods/has_elapsed.nvgt

@@ -0,0 +1,18 @@
+/**
+	determine whether the given number of microseconds has elapsed since the time point stored in this timestamp.
+	bool has_elapsed(int64 microseconds);
+	## Arguments:
+		* int64 microseconds: the number of microseconds to check elapsed status of
+	## Returns:
+		bool: Whether the given number of milliseconds has elapsed
+	## Remarks:
+		This method serves as a shorthand version of executing `bool has_elapsed = timestamp() - this >= microseconds;`
+*/
+
+// Example:
+void main() {
+	timestamp ts;
+	alert("test", "will you keep the alert box opened for 10 seconds?");
+	if (ts.has_elapsed(10 * SECONDS)) alert("good job", "You kept the alert box opened for 10 seconds!");
+	else alert("oh no", "looks like a bit of character development in regards to the trait of patience is in order...");
+}

doc/src/references/builtin/Date and Time/Classes/timestamp/Methods/update.nvgt

@@ -0,0 +1,13 @@
+/**
+	Reset this timestamp to the system's current date and time.
+	void update();
+*/
+
+// Example:
+void main() {
+	timestamp ts;
+	ts -= 60 * SECONDS;
+	alert("timestamp before reset", ts / SECONDS);
+	ts.update();
+	alert("current timestamp", ts / SECONDS);
+}

doc/src/references/builtin/Date and Time/Classes/timestamp/Operators/opImplConv.md

@@ -0,0 +1,3 @@
+# opImplConv
+Implicitly convert the timestamp to a 64 bit integer containing a raw microsecond accuracy unix epoch.
+int64 opImplConv();

doc/src/references/builtin/Date and Time/Classes/timestamp/Properties/UTC_time.nvgt

@@ -0,0 +1,12 @@
+/**
+	Determines a UTC based time point based on the value stored in the timestamp object.
+	const int64 UTC_time;
+	## Remarks:
+		UTC based time begins on October 15, 1582 at 12 AM and uses an accuracy of 100 nanoseconds.
+*/
+
+// Example:
+void main() {
+	timestamp ts;
+	alert("example", "The current UTC time value is " + ts.UTC_time);
+}

doc/src/references/builtin/Date and Time/Classes/timestamp/Properties/elapsed.nvgt

@@ -0,0 +1,12 @@
+/**
+	Determine the difference of time in microseconds between this timestamp's value and now.
+	const int64 elapsed;
+	## Remarks:
+		This property is a shorthand version of the expression `int64 elapsed = timestamp() - this;`
+*/
+
+// Example:
+void main() {
+	datetime dt(2013, 11, 29, 1, 2, 3);
+	alert("example", dt.format(DATE_TIME_FORMAT_RFC850) + " was " + (dt.timestamp.elapsed / DAYS) + " days ago");
+}

doc/src/references/builtin/Date and Time/Functions/timestamp_from_UTC_time.nvgt

@@ -0,0 +1,19 @@
+/**
+	Create a timestamp object from a UTC time point.
+	timestamp timestamp_from_UTC_time(int64 UTC_time);
+	## Arguments:
+		* int64 UTC_time: The UTC time point (see remarks).
+	## Returns:
+		timestamp: A timestamp derived from the given value.
+	## Remarks:
+		UTC based time begins on October 15, 1582 at 12 AM and uses an accuracy of 100 nanoseconds.
+*/
+
+// Example:
+void main() {
+	calendar c(2017, 2, 3, 4, 5, 6);
+	alert("initial calendar", c.format(DATE_TIME_FORMAT_RFC1123));
+	timestamp ts = timestamp_from_UTC_time(c.UTC_time);
+	calendar c2 = ts;
+	alert("new calendar", c2.format(DATE_TIME_FORMAT_RFC1123));
+}

doc/src/references/builtin/User Interface/Functions/install_keyhook.nvgt

@@ -7,6 +7,7 @@
 		bool: true if the keyhook was successfully installed, false otherwise.
 	## Remarks:
 		This keyhook allows NVGT games to properly capture keyboard input while the JAWS for Windows screen reader is running.
+		Note that installing it when JAWS is not running may yield unintended consequences, such as functionality of other screen readers being slightly limited while in your game window.
 */
 
 // Example:

doc/src/references/builtin/User Interface/Functions/is_console_available.nvgt

@@ -0,0 +1,14 @@
+/**
+	Determine if your application has access to a console window or not.
+	bool is_console_available();
+	## Returns:
+		bool: true if your application has access to a console window, false otherwise.
+	## Remarks:
+		If this function returns false, it is very likely that any output passed to the print or println functions or the cout/cerr datastreams will be silently dropped.
+*/
+
+// Example:
+void main() {
+	if (is_console_available()) println("hello from the console!");
+	else alert("console unavailable", "hello from the user interface!");
+}