Trait AsArg
pub trait AsArg<T>: Sizedwhere
T: ToGodot,{ }
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 built-ins:i32
,bool
,Vector3
,Transform2D
…- These all implement
ToGodot<Pass = ByValue>
and typically alsoCopy
.
- These all implement
&T
for by-ref built-ins:GString
,Array
,Dictionary
,PackedArray
,Variant
…- These all implement
ToGodot<Pass = ByRef>
.
- These all implement
&str
,&String
additionally for string typesGString
,StringName
,NodePath
.
See also the AsObjectArg
trait which is specialized for object arguments. It may be merged with AsArg
in the future.
§Owned values vs. references
Implicitly converting from T
for by-ref built-ins is explicitly not supported, i.e. you need to pass &variant
instead of variant
.
This emphasizes that there is no need to consume the object, thus discourages unnecessary cloning. Similarly, you cannot pass by-value
types like i32
by reference.
Sometimes, you need exactly that for generic programming though: consistently pass T
or &T
. For this purpose, the global functions
owned_into_arg()
and ref_to_arg()
are provided.
§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.
The blanket implementations of AsArg
for T
(in case of Pass = ByValue
) and &T
(Pass = ByRef
) should readily enable most use
cases, as long as your type already supports ToGodot
. In the majority of cases, you’ll simply use by-value passing, e.g. for enums.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.