Implement trait GodotRange, used to convert Rust ranges to values expected by Godot. Support negative indices for Array. Fix Array docs.

Author: Yarwin

godot-core/src/builtin/collections/array.rs

@@ -7,6 +7,7 @@
 
 use std::cell::OnceCell;
 use std::marker::PhantomData;
+use std::ops::RangeBounds;
 use std::{cmp, fmt};
 
 use godot_ffi as sys;
@@ -15,6 +16,7 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
 use crate::builtin::*;
 use crate::meta;
 use crate::meta::error::{ConvertError, FromGodotError, FromVariantError};
+use crate::meta::godot_range::GodotRange;
 use crate::meta::{
     element_godot_type_name, element_variant_type, ArrayElement, AsArg, ClassName, ElementType,
     ExtVariantType, FromGodot, GodotConvert, GodotFfiVariant, GodotType, PropertyHintInfo, RefArg,
@@ -526,57 +528,98 @@ impl<T: ArrayElement> Array<T> {
         result.with_cache(self)
     }
 
-    /// Returns a sub-range `begin..end`, as a new array.
+    /// Returns a sub-range `begin..end` as a new `Array`.
     ///
     /// The values of `begin` (inclusive) and `end` (exclusive) will be clamped to the array size.
     ///
+    /// If either `begin` or `end` are negative, their value is relative to the end of the array.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::array;
+    /// assert_eq!(array![0, 1, 2, 3, 4, 5].subarray_shallow(-1..-5, None), array![5, 3]);
+    /// ```
+    ///
+    /// If `end` is not specified, the range spans through whole array.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::array;
+    /// assert_eq!(array![0, 1, 2, 3, 4, 5].subarray_shallow(1.., None), array![1, 2, 3, 4, 5]);
+    /// ```
+    ///
     /// If specified, `step` is the relative index between source elements. It can be negative,
-    /// in which case `begin` must be higher than `end`. For example,
-    /// `Array::from(&[0, 1, 2, 3, 4, 5]).slice(5, 1, -2)` returns `[5, 3]`.
+    /// in which case `begin` must be higher than `end`.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::array;
+    /// assert_eq!(array![0, 1, 2, 3, 4, 5].subarray_shallow(-1..-5, Some(-2)), array![5, 3]);
+    /// ```
     ///
     /// Array elements are copied to the slice, but any reference types (such as `Array`,
     /// `Dictionary` and `Object`) will still refer to the same value. To create a deep copy, use
     /// [`subarray_deep()`][Self::subarray_deep] instead.
     ///
     /// _Godot equivalent: `slice`_
     #[doc(alias = "slice")]
-    // TODO(v0.3): change to i32 like NodePath::slice/subpath() and support+test negative indices.
-    pub fn subarray_shallow(&self, begin: usize, end: usize, step: Option<isize>) -> Self {
-        self.subarray_impl(begin, end, step, false)
+    pub fn subarray_shallow(&self, range: impl RangeBounds<i32>, step: Option<i32>) -> Self {
+        self.subarray_impl(range, step, false)
     }
 
-    /// Returns a sub-range `begin..end`, as a new `Array`.
+    /// Returns a sub-range `begin..end` as a new `Array`.
     ///
     /// The values of `begin` (inclusive) and `end` (exclusive) will be clamped to the array size.
     ///
+    /// If either `begin` or `end` are negative, their value is relative to the end of the array.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::array;
+    /// assert_eq!(array![0, 1, 2, 3, 4, 5].subarray_deep(-1..-5, None), array![5, 3]);
+    /// ```
+    ///
+    /// If `end` is not specified, the range spans through whole array.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::array;
+    /// assert_eq!(array![0, 1, 2, 3, 4, 5].subarray_deep(1.., None), array![1, 2, 3, 4, 5]);
+    /// ```
+    ///
     /// If specified, `step` is the relative index between source elements. It can be negative,
-    /// in which case `begin` must be higher than `end`. For example,
-    /// `Array::from(&[0, 1, 2, 3, 4, 5]).slice(5, 1, -2)` returns `[5, 3]`.
+    /// in which case `begin` must be higher than `end`.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::array;
+    /// assert_eq!(array![0, 1, 2, 3, 4, 5].subarray_deep(-1..-5, Some(-2)), array![5, 3]);
+    /// ```
     ///
     /// All nested arrays and dictionaries are duplicated and will not be shared with the original
     /// array. Note that any `Object`-derived elements will still be shallow copied. To create a
     /// shallow copy, use [`subarray_shallow()`][Self::subarray_shallow] instead.
     ///
     /// _Godot equivalent: `slice`_
     #[doc(alias = "slice")]
-    // TODO(v0.3): change to i32 like NodePath::slice/subpath() and support+test negative indices.
-    pub fn subarray_deep(&self, begin: usize, end: usize, step: Option<isize>) -> Self {
-        self.subarray_impl(begin, end, step, true)
+    pub fn subarray_deep(&self, range: impl RangeBounds<i32>, step: Option<i32>) -> Self {
+        self.subarray_impl(range, step, true)
     }
 
-    fn subarray_impl(&self, begin: usize, end: usize, step: Option<isize>, deep: bool) -> Self {
+    // Note: Godot will clamp values by itself.
+    fn subarray_impl(&self, range: impl GodotRange<i32>, step: Option<i32>, deep: bool) -> Self {
         assert_ne!(step, Some(0), "subarray: step cannot be zero");
 
-        let len = self.len();
-        let begin = begin.min(len);
-        let end = end.min(len);
         let step = step.unwrap_or(1);
+        let (begin, end) = range.to_godot_range_fromto();
+
+        // Unbounded upper bounds are represented by `i32::MAX` instead of `i64::MAX`,
+        // since Godot treats some indexes as 32-bit despite being declared `i64` in GDExtension API.
+        let end = end.unwrap_or(i32::MAX as i64);
 
         // SAFETY: The type of the array is `T` and we convert the returned array to an `Array<T>` immediately.
-        let subarray: VariantArray = unsafe {
-            self.as_inner()
-                .slice(to_i64(begin), to_i64(end), step.try_into().unwrap(), deep)
-        };
+        let subarray: VariantArray =
+            unsafe { self.as_inner().slice(begin, end, step as i64, deep) };
 
         // SAFETY: slice() returns a typed array with the same type as Self.
         let result = unsafe { subarray.assume_type() };

godot-core/src/builtin/collections/packed_array.rs

@@ -10,6 +10,7 @@
 #![allow(clippy::result_unit_err)]
 
 use std::iter::FromIterator;
+use std::ops::RangeBounds;
 use std::{fmt, ops, ptr};
 
 use godot_ffi as sys;
@@ -226,18 +227,33 @@ impl<T: PackedArrayElement> PackedArray<T> {
 
     /// Returns a sub-range `begin..end`, as a new packed array.
     ///
-    /// This method is called `slice()` in Godot.
     /// The values of `begin` (inclusive) and `end` (exclusive) will be clamped to the array size.
     ///
+    /// If either `begin` or `end` are negative, their value is relative to the end of the array.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::PackedArray;
+    /// let array = PackedArray::from([10, 20, 30, 40, 50]);
+    /// assert_eq!(array.subarray(-4..-2), PackedArray::from([20, 30]));
+    /// ```
+    ///
+    /// If `end` is not specified, the resulting subarray will span to the end of the array.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::PackedArray;
+    /// let array = PackedArray::from([10, 20, 30, 40, 50]);
+    /// assert_eq!(array.subarray(2..), PackedArray::from([30, 40, 50]));
+    /// ```
+    ///
     /// To obtain Rust slices, see [`as_slice`][Self::as_slice] and [`as_mut_slice`][Self::as_mut_slice].
+    ///
+    /// _Godot equivalent: `slice`_
     #[doc(alias = "slice")]
-    // TODO(v0.3): change to i32 like NodePath::slice/subpath() and support+test negative indices.
-    pub fn subarray(&self, begin: usize, end: usize) -> Self {
-        let len = self.len();
-        let begin = begin.min(len);
-        let end = end.min(len);
-
-        T::op_slice(self.as_inner(), to_i64(begin), to_i64(end))
+    // Note: Godot will clamp values by itself.
+    pub fn subarray(&self, range: impl RangeBounds<i32>) -> Self {
+        T::op_slice(self.as_inner(), range)
     }
 
     /// Returns a shared Rust slice of the array.

godot-core/src/builtin/collections/packed_array_element.rs

@@ -4,11 +4,13 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
+use std::ops::RangeBounds;
 
 use sys::{interface_fn, GodotFfi, SysPtr};
 
 use crate::builtin::collections::extend_buffer::{ExtendBuffer, ExtendBufferTrait};
 use crate::builtin::PackedArray;
+use crate::meta::godot_range::GodotRange;
 use crate::meta::{CowArg, FromGodot, GodotType, ToGodot};
 use crate::registry::property::builtin_type_string;
 use crate::{builtin, sys};
@@ -126,7 +128,7 @@ pub trait PackedArrayElement: GodotType + Clone + ToGodot + FromGodot {
     fn op_append_array(inner: Self::Inner<'_>, other: &PackedArray<Self>);
 
     #[doc(hidden)]
-    fn op_slice(inner: Self::Inner<'_>, begin: i64, end: i64) -> PackedArray<Self>;
+    fn op_slice(inner: Self::Inner<'_>, range: impl RangeBounds<i32>) -> PackedArray<Self>;
 
     #[doc(hidden)]
     fn op_find(inner: Self::Inner<'_>, value: CowArg<'_, Self>, from: i64) -> i64;
@@ -285,8 +287,9 @@ macro_rules! impl_packed_array_element {
                 inner.append_array(other);
             }
 
-            fn op_slice(inner: Self::Inner<'_>, begin: i64, end: i64) -> PackedArray<Self> {
-                inner.slice(begin, end)
+            fn op_slice(inner: Self::Inner<'_>, range: impl RangeBounds<i32>) -> PackedArray<Self> {
+                let (begin, end) = range.to_godot_range_fromto();
+                inner.slice(begin, end.unwrap_or(i32::MAX as i64))
             }
 
             fn op_find(inner: Self::Inner<'_>, value: CowArg<'_, Self>, from: i64) -> i64 {

godot-core/src/builtin/mod.rs

@@ -113,6 +113,9 @@ pub mod inner {
     pub use crate::gen::builtin_classes::*;
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Conversion functions
+
 pub(crate) fn to_i64(i: usize) -> i64 {
     i.try_into().unwrap()
 }

godot-core/src/builtin/string/mod.rs

@@ -13,8 +13,6 @@ mod node_path;
 mod string_macros;
 mod string_name;
 
-use std::ops;
-
 pub use gstring::*;
 pub use node_path::NodePath;
 pub use string_name::*;
@@ -69,71 +67,6 @@ pub enum Encoding {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// Returns a tuple of `(from, len)` from a Rust range.
-///
-/// Unbounded upper bounds are represented by `len = -1`.
-fn to_godot_fromlen_neg1<R>(range: R) -> (i64, i64)
-where
-    R: ops::RangeBounds<usize>,
-{
-    let from = match range.start_bound() {
-        ops::Bound::Included(&n) => n as i64,
-        ops::Bound::Excluded(&n) => (n as i64) + 1,
-        ops::Bound::Unbounded => 0,
-    };
-
-    let len = match range.end_bound() {
-        ops::Bound::Included(&n) => {
-            let to = (n + 1) as i64;
-            debug_assert!(
-                from <= to,
-                "range: start ({from}) > inclusive end ({n}) + 1"
-            );
-            to - from
-        }
-        ops::Bound::Excluded(&n) => {
-            let to = n as i64;
-            debug_assert!(from <= to, "range: start ({from}) > exclusive end ({to})");
-            to - from
-        }
-        ops::Bound::Unbounded => -1,
-    };
-
-    (from, len)
-}
-
-/// Returns a tuple of `(from, len)` from a Rust range.
-///
-/// Unbounded upper bounds are represented by `i32::MAX` (yes, not `i64::MAX` -- since Godot treats some indexes as 32-bit despite being
-/// declared `i64` in GDExtension API).
-fn to_godot_fromlen_i32max<R>(range: R) -> (i64, i64)
-where
-    R: ops::RangeBounds<usize>,
-{
-    let (from, len) = to_godot_fromlen_neg1(range);
-    if len == -1 {
-        // Use i32 here because Godot may wrap around larger values (see Rustdoc).
-        (from, i32::MAX as i64)
-    } else {
-        (from, len)
-    }
-}
-
-/// Returns a tuple of `(from, to)` from a Rust range.
-///
-/// Unbounded upper bounds are represented by `to = 0`.
-fn to_godot_fromto<R>(range: R) -> (i64, i64)
-where
-    R: ops::RangeBounds<usize>,
-{
-    let (from, len) = to_godot_fromlen_neg1(range);
-    if len == -1 {
-        (from, 0)
-    } else {
-        (from, from + len)
-    }
-}
-
 fn populated_or_none(s: GString) -> Option<GString> {
     if s.is_empty() {
         None

godot-core/src/builtin/string/node_path.rs

@@ -5,13 +5,14 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use std::fmt;
+use std::{fmt, ops};
 
 use godot_ffi as sys;
 use godot_ffi::{ffi_methods, ExtVariantType, GdextBuild, GodotFfi};
 
 use super::{GString, StringName};
 use crate::builtin::inner;
+use crate::meta::godot_range::GodotRange;
 
 /// A pre-parsed scene tree path.
 ///
@@ -127,10 +128,25 @@ impl NodePath {
     /// Returns the range `begin..exclusive_end` as a new `NodePath`.
     ///
     /// The absolute value of `begin` and `exclusive_end` will be clamped to [`get_total_count()`][Self::get_total_count].
-    /// So, to express "until the end", you can simply pass a large value for `exclusive_end`, such as `i32::MAX`.
+    /// If upper bound is not defined `exclusive_end` will span to the end of the `NodePath`.
     ///
-    /// If either `begin` or `exclusive_end` are negative, they will be relative to the end of the `NodePath`.  \
-    /// For example, `path.subpath(0, -2)` is a shorthand for `path.subpath(0, path.get_total_count() - 2)`.
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::NodePath;
+    /// assert_eq!(NodePath::from("path/to/Node:with:props").subpath(-1..), ":props".into());
+    /// ```
+    ///
+    /// If either `begin` or `exclusive_end` are negative, they will be relative to the end of the `NodePath`.
+    ///
+    /// # Example
+    /// ```no_run
+    /// # use godot::builtin::NodePath;
+    /// let path = NodePath::from("path/to/Node:with:props");
+    /// let total_count = path.get_total_count() as i32;
+    /// // Both are equal to "path/to/Node".
+    /// assert_eq!(path.subpath(0..-2), path.subpath(0..total_count - 2));
+    ///
+    /// ```
     ///
     /// _Godot equivalent: `slice`_
     ///
@@ -140,16 +156,17 @@ impl NodePath {
     // i32 used because it can be negative and many Godot APIs use this, see https://github.com/godot-rust/gdext/pull/982/files#r1893732978.
     #[cfg(since_api = "4.3")]
     #[doc(alias = "slice")]
-    pub fn subpath(&self, begin: i32, exclusive_end: i32) -> NodePath {
+    pub fn subpath(&self, range: impl ops::RangeBounds<i32>) -> NodePath {
+        let (from, exclusive_end) = range.to_godot_range_fromto();
         // Polyfill for bug https://github.com/godotengine/godot/pull/100954, fixed in 4.4.
         let begin = if GdextBuild::since_api("4.4") {
-            begin
+            from
         } else {
-            let name_count = self.get_name_count() as i32;
-            let subname_count = self.get_subname_count() as i32;
+            let name_count = self.get_name_count() as i64;
+            let subname_count = self.get_subname_count() as i64;
             let total_count = name_count + subname_count;
 
-            let mut begin = begin.clamp(-total_count, total_count);
+            let mut begin = from.clamp(-total_count, total_count);
             if begin < 0 {
                 begin += total_count;
             }
@@ -159,7 +176,8 @@ impl NodePath {
             begin
         };
 
-        self.as_inner().slice(begin as i64, exclusive_end as i64)
+        self.as_inner()
+            .slice(begin, exclusive_end.unwrap_or(i32::MAX as i64))
     }
 
     crate::meta::declare_arg_method! {