Allow returning Dictionary after merging

core/variant/dictionary.cpp

@@ -249,6 +249,7 @@ void Dictionary::clear() {
 }
 
 void Dictionary::merge(const Dictionary &p_dictionary, bool p_overwrite) {
+	ERR_FAIL_COND_MSG(_p->read_only, "Dictionary is in read-only state.");
 	for (const KeyValue<Variant, Variant> &E : p_dictionary._p->variant_map) {
 		if (p_overwrite || !has(E.key)) {
 			operator[](E.key) = E.value;
@@ -256,6 +257,12 @@ void Dictionary::merge(const Dictionary &p_dictionary, bool p_overwrite) {
 	}
 }
 
+Dictionary Dictionary::merged(const Dictionary &p_dictionary, bool p_overwrite) const {
+	Dictionary ret = duplicate();
+	ret.merge(p_dictionary, p_overwrite);
+	return ret;
+}
+
 void Dictionary::_unref() const {
 	ERR_FAIL_NULL(_p);
 	if (_p->refcount.unref()) {

core/variant/dictionary.h

@@ -64,6 +64,7 @@ public:
 	bool is_empty() const;
 	void clear();
 	void merge(const Dictionary &p_dictionary, bool p_overwrite = false);
+	Dictionary merged(const Dictionary &p_dictionary, bool p_overwrite = false) const;
 
 	bool has(const Variant &p_key) const;
 	bool has_all(const Array &p_keys) const;

core/variant/variant_call.cpp

@@ -2205,6 +2205,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Dictionary, is_empty, sarray(), varray());
 	bind_method(Dictionary, clear, sarray(), varray());
 	bind_method(Dictionary, merge, sarray("dictionary", "overwrite"), varray(false));
+	bind_method(Dictionary, merged, sarray("dictionary", "overwrite"), varray(false));
 	bind_method(Dictionary, has, sarray("key"), varray());
 	bind_method(Dictionary, has_all, sarray("keys"), varray());
 	bind_method(Dictionary, find_key, sarray("value"), varray());

doc/classes/Dictionary.xml

@@ -340,6 +340,24 @@
 				[b]Note:[/b] [method merge] is [i]not[/i] recursive. Nested dictionaries are considered as keys that can be overwritten or not depending on the value of [param overwrite], but they will never be merged together.
 			</description>
 		</method>
+		<method name="merged" qualifiers="const">
+			<return type="Dictionary" />
+			<param index="0" name="dictionary" type="Dictionary" />
+			<param index="1" name="overwrite" type="bool" default="false" />
+			<description>
+				Returns a copy of this dictionary merged with the other [param dictionary]. By default, duplicate keys are not copied over, unless [param overwrite] is [code]true[/code]. See also [method merge].
+				This method is useful for quickly making dictionaries with default values:
+				[codeblock]
+				var base = { "fruit": "apple", "vegetable": "potato" }
+				var extra = { "fruit": "orange", "dressing": "vinegar" }
+				# Prints { "fruit": "orange", "vegetable": "potato", "dressing": "vinegar" }
+				print(extra.merged(base))
+				# Prints { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" }
+				print(extra.merged(base, true))
+				[/codeblock]
+				See also [method merge].
+			</description>
+		</method>
 		<method name="size" qualifiers="const">
 			<return type="int" />
 			<description>