Allow overriding how scripted objects are converted to strings

solves #26796

- ADD `String to_string()` method to Object which can be overriden by `String _to_string()` in scripts
- ADD `String to_string(r_valid)` method to ScriptInstance to allow langauges to control how scripted objects are converted to strings
- IMPLEMENT to_string for GDScriptInstance, VisualScriptInstance, and NativeScriptInstance
- ADD Documentation about `Object.to_string` and `Object._to_string`
- Changed `Variant::operator String` to use `obj->to_string()`

2 files changed, 23 insertions, 0 deletions

diff --git a/modules/gdnative/nativescript/nativescript.cpp b/modules/gdnative/nativescript/nativescript.cpp
index 5cf144d4fe..b743768783 100644
--- a/modules/gdnative/nativescript/nativescript.cpp
+++ b/modules/gdnative/nativescript/nativescript.cpp
@@ -32,6 +32,7 @@
 
 #include "gdnative/gdnative.h"
 
+#include "core/core_string_names.h"
 #include "core/global_constants.h"
 #include "core/io/file_access_encrypted.h"
 #include "core/os/file_access.h"
@@ -771,6 +772,27 @@ void NativeScriptInstance::notification(int p_notification) {
 	call_multilevel("_notification", args, 1);
 }
 
+String NativeScriptInstance::to_string(bool *r_valid) {
+	if (has_method(CoreStringNames::get_singleton()->_to_string)) {
+		Variant::CallError ce;
+		Variant ret = call(CoreStringNames::get_singleton()->_to_string, NULL, 0, ce);
+		if (ce.error == Variant::CallError::CALL_OK) {
+			if (ret.get_type() != Variant::STRING) {
+				if (r_valid)
+					*r_valid = false;
+				ERR_EXPLAIN("Wrong type for " + CoreStringNames::get_singleton()->_to_string + ", must be a String.");
+				ERR_FAIL_V(String());
+			}
+			if (r_valid)
+				*r_valid = true;
+			return ret.operator String();
+		}
+	}
+	if (r_valid)
+		*r_valid = false;
+	return String();
+}
+
 void NativeScriptInstance::refcount_incremented() {
 	Variant::CallError err;
 	call("_refcount_incremented", NULL, 0, err);
diff --git a/modules/gdnative/nativescript/nativescript.h b/modules/gdnative/nativescript/nativescript.h
index a6865c6243..be1c499714 100644
--- a/modules/gdnative/nativescript/nativescript.h
+++ b/modules/gdnative/nativescript/nativescript.h
@@ -208,6 +208,7 @@ public:
 	virtual bool has_method(const StringName &p_method) const;
 	virtual Variant call(const StringName &p_method, const Variant **p_args, int p_argcount, Variant::CallError &r_error);
 	virtual void notification(int p_notification);
+	String to_string(bool *r_valid);
 	virtual Ref<Script> get_script() const;
 	virtual MultiplayerAPI::RPCMode get_rpc_mode(const StringName &p_method) const;
 	virtual MultiplayerAPI::RPCMode get_rset_mode(const StringName &p_variable) const;