Merge pull request #77164 from dalexeev/gds-re-add-ord

GDScript: Re-add `ord()` function

Author: akien-mga

core/variant/variant_call.cpp

@@ -1896,7 +1896,7 @@ static void _register_variant_builtin_methods_string() {
 	bind_static_method(String, num, sarray("number", "decimals"), varray(-1));
 	bind_static_method(String, num_int64, sarray("number", "base", "capitalize_hex"), varray(10, false));
 	bind_static_method(String, num_uint64, sarray("number", "base", "capitalize_hex"), varray(10, false));
-	bind_static_method(String, chr, sarray("char"), varray());
+	bind_static_method(String, chr, sarray("code"), varray());
 	bind_static_method(String, humanize_size, sarray("size"), varray());
 
 	/* StringName */

doc/classes/String.xml

@@ -118,13 +118,14 @@
 		</method>
 		<method name="chr" qualifiers="static">
 			<return type="String" />
-			<param index="0" name="char" type="int" />
+			<param index="0" name="code" type="int" />
 			<description>
-				Returns a single Unicode character from the decimal [param char]. You may use [url=https://unicodelookup.com/]unicodelookup.com[/url] or [url=https://www.unicode.org/charts/]unicode.org[/url] as points of reference.
+				Returns a single Unicode character from the integer [param code]. You may use [url=https://unicodelookup.com/]unicodelookup.com[/url] or [url=https://www.unicode.org/charts/]unicode.org[/url] as points of reference.
 				[codeblock]
 				print(String.chr(65))     # Prints "A"
 				print(String.chr(129302)) # Prints "🤖" (robot face emoji)
 				[/codeblock]
+				See also [method unicode_at], [method @GDScript.char], and [method @GDScript.ord].
 			</description>
 		</method>
 		<method name="contains" qualifiers="const">
@@ -1149,6 +1150,7 @@
 			<param index="0" name="at" type="int" />
 			<description>
 				Returns the character code at position [param at].
+				See also [method chr], [method @GDScript.char], and [method @GDScript.ord].
 			</description>
 		</method>
 		<method name="uri_decode" qualifiers="const">

doc/classes/StringName.xml

@@ -1057,6 +1057,7 @@
 			<param index="0" name="at" type="int" />
 			<description>
 				Returns the character code at position [param at].
+				See also [method String.chr], [method @GDScript.char], and [method @GDScript.ord].
 			</description>
 		</method>
 		<method name="uri_decode" qualifiers="const">

modules/gdscript/doc_classes/@GDScript.xml

@@ -48,14 +48,14 @@
 		</method>
 		<method name="char">
 			<return type="String" />
-			<param index="0" name="char" type="int" />
+			<param index="0" name="code" type="int" />
 			<description>
-				Returns a single character (as a [String]) of the given Unicode code point (which is compatible with ASCII code).
+				Returns a single character (as a [String] of length 1) of the given Unicode code point [param code].
 				[codeblock]
-				var upper = char(65)      # upper is "A"
-				var lower = char(65 + 32) # lower is "a"
-				var euro = char(8364)     # euro is "€"
+				print(char(65))     # Prints "A"
+				print(char(129302)) # Prints "🤖" (robot face emoji)
 				[/codeblock]
+				This is the inverse of [method ord]. See also [method String.chr] and [method String.unicode_at].
 			</description>
 		</method>
 		<method name="convert" deprecated="Use [method @GlobalScope.type_convert] instead.">
@@ -175,6 +175,18 @@
 				[b]Note:[/b] If [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @GDScript.load] will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set [member ProjectSettings.editor/export/convert_text_resources_to_binary] to [code]false[/code].
 			</description>
 		</method>
+		<method name="ord">
+			<return type="int" />
+			<param index="0" name="char" type="String" />
+			<description>
+				Returns an integer representing the Unicode code point of the given character [param char], which should be a string of length 1.
+				[codeblock]
+				print(ord("A")) # Prints 65
+				print(ord("🤖")) # Prints 129302
+				[/codeblock]
+				This is the inverse of [method char]. See also [method String.chr] and [method String.unicode_at].
+			</description>
+		</method>
 		<method name="preload">
 			<return type="Resource" />
 			<param index="0" name="path" type="String" />

modules/gdscript/gdscript_utility_functions.cpp

@@ -120,8 +120,17 @@ struct GDScriptUtilityFunctionsDefinitions {
 	static inline void _char(Variant *r_ret, const Variant **p_args, int p_arg_count, Callable::CallError &r_error) {
 		DEBUG_VALIDATE_ARG_COUNT(1, 1);
 		DEBUG_VALIDATE_ARG_TYPE(0, Variant::INT);
-		char32_t result[2] = { *p_args[0], 0 };
-		*r_ret = String(result);
+		const int64_t code = *p_args[0];
+		VALIDATE_ARG_CUSTOM(0, Variant::INT, code < 0 || code > UINT32_MAX, RTR("Expected an integer between 0 and 2^32 - 1."));
+		*r_ret = String::chr(code);
+	}
+
+	static inline void ord(Variant *r_ret, const Variant **p_args, int p_arg_count, Callable::CallError &r_error) {
+		DEBUG_VALIDATE_ARG_COUNT(1, 1);
+		DEBUG_VALIDATE_ARG_TYPE(0, Variant::STRING);
+		const String string = *p_args[0];
+		VALIDATE_ARG_CUSTOM(0, Variant::STRING, string.length() != 1, RTR("Expected a string of length 1 (a character)."));
+		*r_ret = string.get(0);
 	}
 
 	static inline void range(Variant *r_ret, const Variant **p_args, int p_arg_count, Callable::CallError &r_error) {
@@ -575,7 +584,8 @@ void GDScriptUtilityFunctions::register_functions() {
 	REGISTER_FUNC( convert,        true,  RETVAR,             ARGS( ARGVAR("what"), ARGTYPE("type") ), false, varray(     ));
 #endif // DISABLE_DEPRECATED
 	REGISTER_FUNC( type_exists,    true,  RET(BOOL),          ARGS( ARG("type", STRING_NAME)        ), false, varray(     ));
-	REGISTER_FUNC( _char,          true,  RET(STRING),        ARGS( ARG("char", INT)                ), false, varray(     ));
+	REGISTER_FUNC( _char,          true,  RET(STRING),        ARGS( ARG("code", INT)                ), false, varray(     ));
+	REGISTER_FUNC( ord,            true,  RET(INT),           ARGS( ARG("char", STRING)             ), false, varray(     ));
 	REGISTER_FUNC( range,          false, RET(ARRAY),         NOARGS,                                  true,  varray(     ));
 	REGISTER_FUNC( load,           false, RETCLS("Resource"), ARGS( ARG("path", STRING)             ), false, varray(     ));
 #ifndef DISABLE_DEPRECATED