Create SignedRange trait.

Add `wrapped` utility function to handle signed ranges.

Author: Yarwin

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

@@ -7,7 +7,6 @@
 
 use std::cell::OnceCell;
 use std::marker::PhantomData;
-use std::ops::RangeBounds;
 use std::{cmp, fmt};
 
 use godot_ffi as sys;
@@ -16,7 +15,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::signed_range::SignedRange;
 use crate::meta::{
     element_godot_type_name, element_variant_type, ArrayElement, AsArg, ClassName, ElementType,
     ExtVariantType, FromGodot, GodotConvert, GodotFfiVariant, GodotType, PropertyHintInfo, RefArg,
@@ -110,6 +109,35 @@ use crate::registry::property::{BuiltinExport, Export, Var};
 /// // ...and so on.
 /// ```
 ///
+/// # Working with signed ranges and steps
+///
+/// For negative indices, use [`wrapped()`](crate::meta::wrapped).
+///
+/// ```no_run
+/// # use godot::builtin::array;
+/// # use godot::meta::wrapped;
+/// let arr = array![0, 1, 2, 3, 4, 5];
+///
+/// // The values of `begin` (inclusive) and `end` (exclusive) will be clamped to the array size.
+/// let clamped_array = arr.subarray_deep(999..99999, None);
+/// assert_eq!(clamped_array, array![]);
+///
+/// // If either `begin` or `end` is negative, its value is relative to the end of the array.
+/// let sub = arr.subarray_shallow(wrapped(-1..-5), None);
+/// assert_eq!(sub, array![5, 3]);
+///
+/// // If `end` is not specified, the range spans through whole array.
+/// let sub = arr.subarray_deep(1.., None);
+/// assert_eq!(sub, array![1, 2, 3, 4, 5]);
+/// let other_clamped_array = arr.subarray_shallow(5.., Some(2));
+/// assert_eq!(other_clamped_array, array![5]);
+///
+/// // If specified, `step` is the relative index between source elements. It can be negative,
+/// // in which case `begin` must be higher than `end`.
+/// let sub = arr.subarray_shallow(wrapped(-1..-5), Some(-2));
+/// assert_eq!(sub, array![5, 3]);
+/// ```
+///
 /// # Thread safety
 ///
 /// Usage is safe if the `Array` is used on a single thread only. Concurrent reads on
@@ -530,91 +558,34 @@ impl<T: ArrayElement> Array<T> {
 
     /// 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`.
-    ///
-    /// # 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")]
-    pub fn subarray_shallow(&self, range: impl RangeBounds<i32>, step: Option<i32>) -> Self {
+    pub fn subarray_shallow(&self, range: impl SignedRange, step: Option<i32>) -> Self {
         self.subarray_impl(range, step, false)
     }
 
     /// 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`.
-    ///
-    /// # 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")]
-    pub fn subarray_deep(&self, range: impl RangeBounds<i32>, step: Option<i32>) -> Self {
+    pub fn subarray_deep(&self, range: impl SignedRange, step: Option<i32>) -> Self {
         self.subarray_impl(range, step, true)
     }
 
     // Note: Godot will clamp values by itself.
-    fn subarray_impl(&self, range: impl GodotRange<i32>, step: Option<i32>, deep: bool) -> Self {
+    fn subarray_impl(&self, range: impl SignedRange, step: Option<i32>, deep: bool) -> Self {
         assert_ne!(step, Some(0), "subarray: step cannot be zero");
 
         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 (begin, end) = range.signed();
         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.

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

@@ -10,7 +10,6 @@
 #![allow(clippy::result_unit_err)]
 
 use std::iter::FromIterator;
-use std::ops::RangeBounds;
 use std::{fmt, ops, ptr};
 
 use godot_ffi as sys;
@@ -20,6 +19,7 @@ use crate::builtin::collections::extend_buffer::ExtendBufferTrait;
 use crate::builtin::*;
 use crate::classes::file_access::CompressionMode;
 use crate::meta;
+use crate::meta::signed_range::SignedRange;
 use crate::meta::{AsArg, FromGodot, GodotConvert, PackedArrayElement, ToGodot};
 use crate::obj::EngineEnum;
 use crate::registry::property::{Export, Var};
@@ -228,31 +228,29 @@ impl<T: PackedArrayElement> PackedArray<T> {
     /// Returns a sub-range `begin..end`, as a new packed array.
     ///
     /// The values of `begin` (inclusive) and `end` (exclusive) will be clamped to the array size.
+    /// To obtain Rust slices, see [`as_slice`][Self::as_slice] and [`as_mut_slice`][Self::as_mut_slice].
     ///
-    /// If either `begin` or `end` are negative, their value is relative to the end of the array.
+    /// # Usage
+    /// For negative indices, use [`wrapped()`](crate::meta::wrapped).
     ///
-    /// # Example
     /// ```no_run
     /// # use godot::builtin::PackedArray;
+    /// # use godot::meta::wrapped;
     /// 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.
+    /// // If either `begin` or `end` is negative, its value is relative to the end of the array.
+    /// let sub = array.subarray(wrapped(-4..-2));
+    /// assert_eq!(sub, PackedArray::from([20, 30]));
     ///
-    /// # 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]));
+    /// // If `end` is not specified, the resulting subarray will span to the end of the array.
+    /// let sub = array.subarray(2..);
+    /// assert_eq!(sub, 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")]
     // Note: Godot will clamp values by itself.
-    pub fn subarray(&self, range: impl RangeBounds<i32>) -> Self {
+    pub fn subarray(&self, range: impl SignedRange) -> Self {
         T::op_slice(self.as_inner(), range)
     }
 

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

@@ -4,13 +4,12 @@
  * 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::signed_range::SignedRange;
 use crate::meta::{CowArg, FromGodot, GodotType, ToGodot};
 use crate::registry::property::builtin_type_string;
 use crate::{builtin, sys};
@@ -128,7 +127,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<'_>, range: impl RangeBounds<i32>) -> PackedArray<Self>;
+    fn op_slice(inner: Self::Inner<'_>, range: impl SignedRange) -> PackedArray<Self>;
 
     #[doc(hidden)]
     fn op_find(inner: Self::Inner<'_>, value: CowArg<'_, Self>, from: i64) -> i64;
@@ -287,8 +286,8 @@ macro_rules! impl_packed_array_element {
                 inner.append_array(other);
             }
 
-            fn op_slice(inner: Self::Inner<'_>, range: impl RangeBounds<i32>) -> PackedArray<Self> {
-                let (begin, end) = range.to_godot_range_fromto();
+            fn op_slice(inner: Self::Inner<'_>, range: impl $crate::meta::signed_range::SignedRange) -> PackedArray<Self> {
+                let (begin, end) = range.signed();
                 inner.slice(begin, end.unwrap_or(i32::MAX as i64))
             }
 

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

@@ -5,14 +5,14 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use std::{fmt, ops};
+use std::fmt;
 
 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;
+use crate::meta::signed_range::SignedRange;
 
 /// A pre-parsed scene tree path.
 ///
@@ -128,36 +128,37 @@ 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].
-    /// If upper bound is not defined `exclusive_end` will span to the end of the `NodePath`.
     ///
-    /// # 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`.
+    /// # Usage
+    /// For negative indices, use [`wrapped()`](crate::meta::wrapped).
     ///
-    /// # Example
     /// ```no_run
     /// # use godot::builtin::NodePath;
+    /// # use godot::meta::wrapped;
     /// 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));
     ///
+    /// // If upper bound is not defined, `exclusive_end` will span to the end of the `NodePath`.
+    /// let sub = path.subpath(2..);
+    /// assert_eq!(sub, ":props".into());
+    ///
+    /// // If either `begin` or `exclusive_end` are negative, they will be relative to the end of the `NodePath`.
+    /// let total_count = path.get_total_count();
+    /// let wrapped_sub = path.subpath(wrapped(0..-2));
+    /// let normal_sub = path.subpath(0..total_count - 2);
+    /// // Both are equal to "path/to/Node".
+    /// assert_eq!(wrapped_sub, normal_sub);
     /// ```
     ///
     /// _Godot equivalent: `slice`_
     ///
     /// # Compatibility
-    /// The `slice()` behavior for Godot <= 4.3 is unintuitive, see [#100954](https://github.com/godotengine/godot/pull/100954). godot-rust
+    /// The `slice()` behavior for Godot <= 4.3 is unintuitive, see [#100954](https://github.com/godotengine/godot/pull/100954). Godot-rust
     /// automatically changes this to the fixed version for Godot 4.4+, even when used in older versions. So, the behavior is always the same.
     // 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, range: impl ops::RangeBounds<i32>) -> NodePath {
-        let (from, exclusive_end) = range.to_godot_range_fromto();
+    pub fn subpath(&self, range: impl SignedRange) -> NodePath {
+        let (from, exclusive_end) = range.signed();
         // Polyfill for bug https://github.com/godotengine/godot/pull/100954, fixed in 4.4.
         let begin = if GdextBuild::since_api("4.4") {
             from

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

@@ -81,15 +81,13 @@ macro_rules! impl_shared_string_api {
 
             /// Count how many times `what` appears within `range`. Use `..` for full string search.
             pub fn count(&self, what: impl AsArg<GString>, range: impl std::ops::RangeBounds<usize>) -> usize {
-                use $crate::meta::godot_range::GodotRange;
-                let (from, to) = range.to_godot_range_fromto_checked(0);
+                let (from, to) = $crate::meta::signed_range::to_godot_range_fromto(range);
                 self.as_inner().count(what, from, to) as usize
             }
 
             /// Count how many times `what` appears within `range`, case-insensitively. Use `..` for full string search.
             pub fn countn(&self, what: impl AsArg<GString>, range: impl std::ops::RangeBounds<usize>) -> usize {
-                use $crate::meta::godot_range::GodotRange;
-                let (from, to) = range.to_godot_range_fromto_checked(0);
+                let (from, to) = $crate::meta::signed_range::to_godot_range_fromto(range);
                 self.as_inner().countn(what, from, to) as usize
             }
 
@@ -123,8 +121,7 @@ macro_rules! impl_shared_string_api {
             /// Returns a substring of this, as another `GString`.
             // TODO is there no efficient way to implement this for StringName by interning?
             pub fn substr(&self, range: impl std::ops::RangeBounds<usize>) -> GString {
-                use $crate::meta::godot_range::GodotRange;
-                let (from, len) = range.to_godot_range_fromlen(-1);
+                let (from, len) = $crate::meta::signed_range::to_godot_range_fromlen(range, -1);
 
                 self.as_inner().substr(from, len)
             }
@@ -166,11 +163,7 @@ macro_rules! impl_shared_string_api {
 
             /// Returns a copy of the string without the specified index range.
             pub fn erase(&self, range: impl std::ops::RangeBounds<usize>) -> GString {
-                use $crate::meta::godot_range::GodotRange;
-                // 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 (from, len) = range.to_godot_range_fromlen(i32::MAX as i64);
-
+                let (from, len) = $crate::meta::signed_range::to_godot_range_fromlen(range, i32::MAX as i64);
                 self.as_inner().erase(from, len)
             }