Vector conversion functions from/to tuples and arrays

Author: Bromeon

godot-core/src/builtin/vectors/vector2.rs

@@ -24,6 +24,8 @@ use std::fmt;
 /// is always 64-bit. The engine can be compiled with the option `precision=double` to use 64-bit
 /// vectors; use the gdext library with the `double-precision` feature in that case.
 ///
+#[doc = shared_vector_docs!()]
+///
 /// ### Navigation to `impl` blocks within this page
 ///
 /// - [Constants](#constants)

godot-core/src/builtin/vectors/vector2i.rs

@@ -19,11 +19,13 @@ use std::fmt;
 /// 2-element structure that can be used to represent discrete positions or directions in 2D space,
 /// as well as any other pair of numeric values.
 ///
-/// It uses integer coordinates and is therefore preferable to [`Vector2`] when exact precision is
+/// `Vector2i` uses integer coordinates and is therefore preferable to [`Vector2`] when exact precision is
 /// required. Note that the values are limited to 32 bits, and unlike `Vector2` this cannot be
 /// configured with an engine build option. Use `i64` or [`PackedInt64Array`][crate::builtin::PackedInt64Array]
 /// if 64-bit values are needed.
 ///
+#[doc = shared_vector_docs!()]
+///
 /// ### Navigation to `impl` blocks within this page
 ///
 /// - [Constants](#constants)

godot-core/src/builtin/vectors/vector3.rs

@@ -24,6 +24,8 @@ use std::fmt;
 /// is always 64-bit. The engine can be compiled with the option `precision=double` to use 64-bit
 /// vectors instead; use the gdext library with the `double-precision` feature in that case.
 ///
+#[doc = shared_vector_docs!()]
+///
 /// ### Navigation to `impl` blocks within this page
 ///
 /// - [Constants](#constants)

godot-core/src/builtin/vectors/vector3i.rs

@@ -19,11 +19,13 @@ use crate::builtin::{inner, real, RVec3, Vector3, Vector3Axis};
 /// 3-element structure that can be used to represent discrete positions or directions in 3D space,
 /// as well as any other triple of numeric values.
 ///
-/// It uses integer coordinates and is therefore preferable to [`Vector3`] when exact precision is
+/// `Vector3i` uses integer coordinates and is therefore preferable to [`Vector3`] when exact precision is
 /// required. Note that the values are limited to 32 bits, and unlike `Vector3` this cannot be
 /// configured with an engine build option. Use `i64` or [`PackedInt64Array`][crate::builtin::PackedInt64Array]
 /// if 64-bit values are needed.
 ///
+#[doc = shared_vector_docs!()]
+///
 /// ### Navigation to `impl` blocks within this page
 ///
 /// - [Constants](#constants)

godot-core/src/builtin/vectors/vector4.rs

@@ -22,6 +22,8 @@ use std::fmt;
 /// is always 64-bit. The engine can be compiled with the option `precision=double` to use 64-bit
 /// vectors; use the gdext library with the `double-precision` feature in that case.
 ///
+#[doc = shared_vector_docs!()]
+///
 /// ### Navigation to `impl` blocks within this page
 ///
 /// - [Constants](#constants)

godot-core/src/builtin/vectors/vector4i.rs

@@ -18,11 +18,13 @@ use std::fmt;
 ///
 /// 4-element structure that can be used to represent 4D grid coordinates or sets of integers.
 ///
-/// It uses integer coordinates and is therefore preferable to [`Vector4`] when exact precision is
+/// `Vector4i` uses integer coordinates and is therefore preferable to [`Vector4`] when exact precision is
 /// required. Note that the values are limited to 32 bits, and unlike `Vector4` this cannot be
 /// configured with an engine build option. Use `i64` or [`PackedInt64Array`][crate::builtin::PackedInt64Array]
 /// if 64-bit values are needed.
 ///
+#[doc = shared_vector_docs!()]
+///
 /// ### Navigation to `impl` blocks within this page
 ///
 /// - [Constants](#constants)

godot-core/src/builtin/vectors/vector_macros.rs

@@ -330,6 +330,37 @@ macro_rules! impl_vector3x_consts {
     };
 }
 
+macro_rules! shared_vector_docs {
+    () => {
+        "Conversions are provided via various `from_*` and `to_*` functions, not via the `From` trait. This encourages `new()` as the main \
+         way to construct vectors, is explicit about the conversion taking place, needs no type inference, and works in `const` contexts."
+    };
+}
+
+macro_rules! tuple_type {
+    ($Scalar:ty; $x:ident, $y:ident) => {
+        ($Scalar, $Scalar)
+    };
+    ($Scalar:ty; $x:ident, $y:ident, $z:ident) => {
+        ($Scalar, $Scalar, $Scalar)
+    };
+    ($Scalar:ty; $x:ident, $y:ident, $z:ident, $w:ident) => {
+        ($Scalar, $Scalar, $Scalar, $Scalar)
+    };
+}
+
+macro_rules! array_type {
+    ($Scalar:ty; $x:ident, $y:ident) => {
+        [$Scalar; 2]
+    };
+    ($Scalar:ty; $x:ident, $y:ident, $z:ident) => {
+        [$Scalar; 3]
+    };
+    ($Scalar:ty; $x:ident, $y:ident, $z:ident, $w:ident) => {
+        [$Scalar; 4]
+    };
+}
+
 /// Implements functions that are present on floating-point and integer vectors.
 macro_rules! impl_vector_fns {
     (
@@ -345,20 +376,48 @@ macro_rules! impl_vector_fns {
         /// # Constructors and general vector functions
         /// The following associated functions and methods are available on all vectors (2D, 3D, 4D; float and int).
         impl $Vector {
-            /// Returns a vector with the given components.
+            /// Creates a vector with the given components.
+            #[inline]
             pub const fn new($($comp: $Scalar),*) -> Self {
                 Self {
                     $( $comp ),*
                 }
             }
 
-            /// Returns a new vector with all components set to `v`.
+            /// Creates a vector with all components set to `v`.
+            #[inline]
             pub const fn splat(v: $Scalar) -> Self {
                 Self {
                     $( $comp: v ),*
                 }
             }
 
+            /// Creates a vector from the given tuple.
+            #[inline]
+            pub const fn from_tuple(tuple: tuple_type!($Scalar; $($comp),*)) -> Self {
+                let ( $($comp,)* ) = tuple;
+                Self::new( $($comp),* )
+            }
+
+            /// Creates a vector from the given array.
+            #[inline]
+            pub const fn from_array(array: array_type!($Scalar; $($comp),*)) -> Self {
+                let [ $($comp,)* ] = array;
+                Self::new( $($comp),* )
+            }
+
+            /// Returns a tuple with the components of the vector.
+            #[inline]
+            pub const fn to_tuple(&self) -> tuple_type!($Scalar; $($comp),*) {
+                ( $(self.$comp,)* )
+            }
+
+            /// Returns an array with the components of the vector.
+            #[inline]
+            pub const fn to_array(&self) -> array_type!($Scalar; $($comp),*) {
+                [ $(self.$comp,)* ]
+            }
+
             /// Converts the corresponding `glam` type to `Self`.
             fn from_glam(v: $GlamVector) -> Self {
                 Self::new(