Trait AsArg 

pub trait AsArg<T>: Sized
where
    T: ToGodot,
{ }

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 also Copy.
• &T for by-ref built-ins: GString, Array, Dictionary, PackedArray, Variant…
  • These all implement ToGodot<Pass = ByRef>.
• &str, &String additionally for string types GString, StringName, NodePath, see String arguments.
• &Gd, Option<&Gd> for objects, see Object arguments.

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.

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.

String arguments

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.

Object arguments

This section treats AsArg<Gd<*>>. The trait is implemented for shared references in multiple ways:

• &Gd<T> to pass objects. Subclasses of T are explicitly supported.
• Option<&Gd<T>>, to pass optional objects. None is mapped to a null argument.
• Gd::null_arg(), to pass null arguments without using Option.

The following table lists the possible argument types and how you can pass them. Gd is short for Gd<T>.

Type	Closest accepted type	How to transform
Gd	&Gd	&arg
&Gd	&Gd	arg
&mut Gd	&Gd	&*arg
Option<Gd>	Option<&Gd>	arg.as_ref()
Option<&Gd>	Option<&Gd>	arg
Option<&mut Gd>	Option<&Gd>	arg.as_deref()
(null literal)		Gd::null_arg()

Nullability

The GDExtension API does not inform about nullability of its function parameters. It is up to you to verify that the arguments you pass are only null when this is allowed. Doing this wrong should be safe, but can lead to the function call failing.

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.

Implementations on Foreign Types

impl AsArg<GString> for &str

impl AsArg<GString> for &String

impl AsArg<NodePath> for &str

impl AsArg<NodePath> for &String

impl AsArg<StringName> for &str

impl AsArg<StringName> for &String

impl<T> AsArg<T> for &T

where T: ToGodot<Pass = ByRef>,

impl<T, Base> AsArg<Option<Gd<Base>>> for Option<&Gd<T>>

where T: Inherits<Base>, Base: GodotClass,

Convert Option<&Gd> -> Option<Gd> (with upcast).

impl<T, D, Base> AsArg<Option<DynGd<Base, D>>> for Option<&DynGd<T, D>>

where T: Inherits<Base>, Base: GodotClass, D: ?Sized,

Convert Option<&DynGd> -> Option<DynGd> (with upcast).

Implementors

impl<T> AsArg<T> for T

where T: ToGodot<Pass = ByValue>,

impl<T, Base> AsArg<Option<Gd<Base>>> for &Gd<T>

where T: Inherits<Base>, Base: GodotClass,

Convert &Gd -> Option<Gd> (with upcast).

impl<T, Base> AsArg<Gd<Base>> for &Gd<T>

where T: Inherits<Base>, Base: GodotClass,

impl<T, D, Base> AsArg<Option<DynGd<Base, D>>> for &DynGd<T, D>

where T: Inherits<Base>, Base: GodotClass, D: ?Sized,

Convert &DynGd -> Option<DynGd> (with upcast).

impl<T, D, Base> AsArg<Option<Gd<Base>>> for &DynGd<T, D>

where T: Inherits<Base>, Base: GodotClass, D: ?Sized,

Convert &DynGd -> Option<Gd> (with upcast).

impl<T, D, Base> AsArg<DynGd<Base, D>> for &DynGd<T, D>

where T: Inherits<Base>, Base: GodotClass, D: ?Sized,

Convert DynGd -> DynGd (with upcast).

impl<T, D, Base> AsArg<Gd<Base>> for &DynGd<T, D>

where T: Inherits<Base>, Base: GodotClass, D: ?Sized,

Convert DynGd -> Gd (with upcast).