Checked cpp and commented detailing why all godot hashes are hash_u32. Renamed and added tests

[markogalevski]

Aiming to fix issue #505

• Checked Godot's cpp implementation. Only the following function was an i64 hash, which was just casting Variant's u32 hash: https://github.com/godotengine/godot/blob/cb7cd815eeeb11aaa1f68453a515c76bec5ba73d/core/variant/variant_utility.cpp#L1120
• All other hashes (e.g. array.h, callable.h) are explicit uint32_t return types (https://github.com/godotengine/godot/blob/cb7cd815eeeb11aaa1f68453a515c76bec5ba73d/core/variant/callable.h)
• Therefore renamed all Godot hashes to hash_u32()
• Updated tests to ensure they always check for hash_u32() equality (Most tests were there, some needed some extension)

[GodotRust]

API docs are being generated and will be shortly available at: https://godot-rust.github.io/docs/gdext/pr-1366

[Yarwin]

This method is public thus included in docs and IDE tips. IMO user doesn't need to know about safety guarantees – especially if they are always held. I would just use the same docs as for everything else:

Suggested change

	/// @GlobalScope.hash() actually calls the VariantUtilityFunctions::hash(&Variant) function (cpp).
	/// This function calls the passed reference's `hash` method, which returns a uint32_t.
	/// Therefore, casting this function to u32 is always safe
	pub fn hash_u32(&self) -> u32 {
	unsafe { interface_fn!(variant_hash)(self.var_sys()) }
	.try_into()
	.expect("Godot hashes are uint32_t")
	/// Returns a 32-bit unsigned integer hash value representing the Variant.
	///
	/// _Godot equivalent : `@GlobalScope.hash()`_
	pub fn hash_u32(&self) -> u32 {
	// Note: Calls the passed reference's underlying `hash` method which returns an uint32_t.
	// SAFETY: we pass in the valid pointer.
	unsafe { interface_fn!(variant_hash)(self.var_sys()) }
	.try_into()
	.expect("Godot hashes are uint32_t")

idk if we should keep info about VariantUtilityFunctions::hash(&Variant), your call 😅

[Bromeon]

Agree that this should be in comment rather than RustDoc.

Note that the int conversion isn't safety relevant, so shouldn't be part of // SAFETY:. Making a mistake here will result in a worse hash function, not UB.

[markogalevski]

Okay, I'll move it into a non-safety dev comment.

[Yarwin]

true true, I updated my suggestion

to elaborate – the only way to cause an UB here is by passing invalid GDExtensionConstVariantPtr.

static GDExtensionInt gdextension_variant_hash(GDExtensionConstVariantPtr p_self) {
	const Variant *self = (const Variant *)p_self;
	return self->hash();
}

[Yarwin]

Note: I wondered if it would be worth it to put it into same macro (or even covering it directly in builtin), such as

macro_rules! impl_hash_32 {
    (
        $( #[$maybe_docs:meta] )*
        $Type:ty
    ) => {
        impl $Type {
            #[doc=concat!("Returns a 32-bit integer hash value representing the ", stringify!($Type), " and its contents.")]
            $( #[$maybe_docs] )*
            pub fn hash_u32(&self) -> u32 {
                self.as_inner()
                    .hash()
                    .try_into()
                    .expect("Godot hashes are uint32_t")
            }
        }
    }
}

and called as

impl_hash_32!(
    ///
    /// Note: Arrays with equal content will always produce identical hash values. However, the
    /// reverse is not true. Returning identical hash values does not imply the arrays are equal,
    /// because different arrays can have identical hash values due to hash collisions.
    Array<T>
);

(...)
impl_hash_32!(StringName);

Since having one source for multiple instances of same code would be nice – but IMO it is not worth it getting into consideration all the differences (impl<T:ArrayElement> Array<T> vs. concrete Type). Ctrl+c ctrl+v ftw

[markogalevski]

I'll give that a crack too.

[Yarwin]

I would cut out this comment and move it to builtin Hash macro.

[Yarwin]

LGTM, outside of this one SAFETY comment exposed in public docs

and just to confirm, in my view hash_u32 shortcut (avoiding conflict with Hash::hash) is fine too

[Bromeon]

Renames of public functions are breaking changes, as such it would have to wait for v0.5. We can merge it sooner if you provide the old methods with a deprecation (no docs, just "renamed to xy" in deprecation notice).

[Bromeon]

Agree that this should be in comment rather than RustDoc.

Note that the int conversion isn't safety relevant, so shouldn't be part of // SAFETY:. Making a mistake here will result in a worse hash function, not UB.