Trait AsArg

pub trait AsArg<T>: Sizedwhere
    T: ApiParam,
{ }

Expand description

Implicit conversions for arguments passed to Godot APIs.

An impl AsArg<T> parameter allows values to be passed which can be represented in the target type T. Note that unlike From<T>, this trait is implemented more conservatively.

As a result, AsArg<T> is currently only implemented for certain argument types:

T for by-value builtins (typically Copy): i32, bool, Vector3, Transform2D, …
&T for by-ref builtins: GString, Array, Dictionary, Packed*Array, Variant…
&str, &String additionally for string types GString, StringName, NodePath.

§Pass by value

Implicitly converting from T for by-ref builtins is explicitly not supported. This emphasizes that there is no need to consume the object, thus discourages unnecessary cloning.

If you need to pass owned values in generic code, you can use ApiParam::owned_to_arg().

§Performance for strings

Godot has three string types: GString, StringName and NodePath. Conversions between those three, as well as between String and them, is generally expensive because of allocations, re-encoding, validations, hashing, etc. While this doesn’t matter for a few strings passed to engine APIs, it can become a problematic when passing long strings in a hot loop.

In the case of strings, we allow implicit conversion from Rust types &str, &String and &'static CStr (StringName only). While these conversions are not free, those are either explicit because a string literal is used, or they are unsurprising, because Godot cannot deal with raw Rust types. On the other hand, GString and StringName are sometimes used almost interchangeably (example: Node::set_name takes GString but Node::get_name returns StringName).

If you want to convert between Godot’s string types for the sake of argument passing, each type provides an arg() method, such as GString::arg(). You cannot use this method in other contexts.

§Using the trait

AsArg is meant to be used from the function call site, not the declaration site. If you declare a parameter as impl AsArg<...> yourself, you can only forward it as-is to a Godot API – there are no stable APIs to access the inner object yet.

Furthermore, there is currently no benefit in implementing AsArg for your own types, as it’s only used by Godot APIs which don’t accept custom types. Classes are already supported through upcasting and AsObjectArg.