Move array/dict iterators to godot::builtin::iter

Author: Bromeon

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

@@ -5,19 +5,18 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use godot_ffi as sys;
-
-use crate::builtin::*;
-use crate::obj::EngineEnum;
-use crate::property::{builtin_type_string, Export, PropertyHintInfo, TypeStringHint, Var};
 use std::fmt;
 use std::marker::PhantomData;
-use sys::{ffi_methods, interface_fn, GodotFfi};
 
-use super::meta::{
+use crate::builtin::meta::{
     ArrayElement, ConvertError, FromGodot, FromGodotError, FromVariantError, GodotConvert,
     GodotFfiVariant, GodotType, ToGodot,
 };
+use crate::builtin::*;
+use crate::obj::EngineEnum;
+use crate::property::{builtin_type_string, Export, PropertyHintInfo, TypeStringHint, Var};
+use godot_ffi as sys;
+use sys::{ffi_methods, interface_fn, GodotFfi};
 
 /// Godot's `Array` type.
 ///
@@ -682,13 +681,13 @@ impl<T: ArrayElement> Array<T> {
     }
 
     /// Returns the runtime type info of this array.
-    fn type_info(&self) -> TypeInfo {
+    fn type_info(&self) -> ArrayTypeInfo {
         let variant_type = VariantType::from_sys(
             self.as_inner().get_typed_builtin() as sys::GDExtensionVariantType
         );
         let class_name = self.as_inner().get_typed_class_name();
 
-        TypeInfo {
+        ArrayTypeInfo {
             variant_type,
             class_name,
         }
@@ -697,7 +696,7 @@ impl<T: ArrayElement> Array<T> {
     /// Checks that the inner array has the correct type set on it for storing elements of type `T`.
     fn with_checked_type(self) -> Result<Self, ConvertError> {
         let self_ty = self.type_info();
-        let target_ty = TypeInfo::of::<T>();
+        let target_ty = ArrayTypeInfo::of::<T>();
 
         if self_ty == target_ty {
             Ok(self)
@@ -719,7 +718,7 @@ impl<T: ArrayElement> Array<T> {
         debug_assert!(self.is_empty());
         debug_assert!(!self.type_info().is_typed());
 
-        let type_info = TypeInfo::of::<T>();
+        let type_info = ArrayTypeInfo::of::<T>();
         if type_info.is_typed() {
             let script = Variant::nil();
 
@@ -1047,6 +1046,7 @@ impl<T: ArrayElement + FromGodot> From<&Array<T>> for Vec<T> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
+/// An iterator over typed elements of an [`Array`].
 pub struct Iter<'a, T: ArrayElement> {
     array: &'a Array<T>,
     next_idx: usize,
@@ -1180,14 +1180,14 @@ macro_rules! varray {
 ///
 /// We ignore the `script` parameter because it has no impact on typing in Godot.
 #[derive(Eq, PartialEq)]
-pub(crate) struct TypeInfo {
+pub(crate) struct ArrayTypeInfo {
     variant_type: VariantType,
 
     /// Not a `ClassName` because some values come from Godot engine API.
     class_name: StringName,
 }
 
-impl TypeInfo {
+impl ArrayTypeInfo {
     fn of<T: GodotType>() -> Self {
         Self {
             variant_type: <T::Via as GodotType>::Ffi::variant_type(),
@@ -1208,7 +1208,7 @@ impl TypeInfo {
     }
 }
 
-impl fmt::Debug for TypeInfo {
+impl fmt::Debug for ArrayTypeInfo {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let class = self.class_name.to_string();
         let class_str = if class.is_empty() {

godot-core/src/builtin/dictionary.rs renamed to godot-core/src/builtin/collections/dictionary.rs

@@ -7,7 +7,7 @@
 
 use godot_ffi as sys;
 
-use crate::builtin::meta::{FromGodot, ToGodot};
+use crate::builtin::meta::{impl_godot_as_self, FromGodot, ToGodot};
 use crate::builtin::{inner, Variant, VariantArray};
 use crate::property::{builtin_type_string, Export, PropertyHintInfo, TypeStringHint, Var};
 use sys::types::OpaqueDictionary;
@@ -16,8 +16,6 @@ use sys::{ffi_methods, interface_fn, GodotFfi};
 use std::marker::PhantomData;
 use std::{fmt, ptr};
 
-use super::meta::impl_godot_as_self;
-
 /// Godot's `Dictionary` type.
 ///
 /// The keys and values of the dictionary are all `Variant`s, so they can be of different types.
@@ -211,48 +209,54 @@ impl Dictionary {
         self.as_inner().merge(other, overwrite)
     }
 
-    /// Returns a deep copy of the dictionary. All nested arrays and dictionaries are duplicated and
-    /// will not be shared with the original dictionary. Note that any `Object`-derived elements will
-    /// still be shallow copied.
+    /// Deep copy, duplicating nested collections.
+    ///
+    /// All nested arrays and dictionaries are duplicated and will not be shared with the original dictionary.
+    /// Note that any `Object`-derived elements will still be shallow copied.
     ///
-    /// To create a shallow copy, use [`Self::duplicate_shallow()`] instead.
+    /// To create a shallow copy, use [`Self::duplicate_shallow()`] instead.  
     /// To create a new reference to the same dictionary data, use [`clone()`][Clone::clone].
     ///
     /// _Godot equivalent: `dict.duplicate(true)`_
     pub fn duplicate_deep(&self) -> Self {
         self.as_inner().duplicate(true)
     }
 
-    /// Returns a shallow copy of the dictionary. All dictionary keys and values are copied, but
-    /// any reference types (such as `Array`, `Dictionary` and `Object`) will still refer to the
-    /// same value.
+    /// Shallow copy, copying elements but sharing nested collections.
+    ///
+    /// All dictionary keys and values are copied, but any reference types (such as `Array`, `Dictionary` and `Gd<T>` objects)
+    /// will still refer to the same value.
     ///
-    /// To create a deep copy, use [`Self::duplicate_deep()`] instead.
+    /// To create a deep copy, use [`Self::duplicate_deep()`] instead.  
     /// To create a new reference to the same dictionary data, use [`clone()`][Clone::clone].
     ///
     /// _Godot equivalent: `dict.duplicate(false)`_
     pub fn duplicate_shallow(&self) -> Self {
         self.as_inner().duplicate(false)
     }
 
-    /// Returns an iterator over the key-value pairs of the `Dictionary`. The pairs are each of type `(Variant, Variant)`.
-    /// Each pair references the original `Dictionary`, but instead of a `&`-reference to key-value pairs as
-    /// you might expect, the iterator returns a (cheap, shallow) copy of each key-value pair.
+    /// Returns an iterator over the key-value pairs of the `Dictionary`.
     ///
-    /// Note that it's possible to modify the `Dictionary` through another reference while iterating
-    /// over it. This will not result in unsoundness or crashes, but will cause the iterator to
-    /// behave in an unspecified way.
+    /// The pairs are each of type `(Variant, Variant)`. Each pair references the original `Dictionary`, but instead of a `&`-reference
+    /// to key-value pairs as you might expect, the iterator returns a (cheap, shallow) copy of each key-value pair.
+    ///
+    /// Note that it's possible to modify the `Dictionary` through another reference while iterating over it. This will not result in
+    /// unsoundness or crashes, but will cause the iterator to behave in an unspecified way.
+    ///
+    /// Use `iter_shared().typed::<K, V>()` to iterate over `(K, V)` pairs instead.
     pub fn iter_shared(&self) -> Iter<'_> {
         Iter::new(self)
     }
 
-    /// Returns an iterator over the keys `Dictionary`. The keys are each of type `Variant`. Each key references
-    /// the original `Dictionary`, but instead of a `&`-reference to keys pairs as you might expect, the
-    /// iterator returns a (cheap, shallow) copy of each key pair.
+    /// Returns an iterator over the keys in a `Dictionary`.
+    ///
+    /// The keys are each of type `Variant`. Each key references the original `Dictionary`, but instead of a `&`-reference to keys pairs
+    /// as you might expect, the iterator returns a (cheap, shallow) copy of each key pair.
     ///
-    /// Note that it's possible to modify the `Dictionary` through another reference while iterating
-    /// over it. This will not result in unsoundness or crashes, but will cause the iterator to
-    /// behave in an unspecified way.
+    /// Note that it's possible to modify the `Dictionary` through another reference while iterating over it. This will not result in
+    /// unsoundness or crashes, but will cause the iterator to behave in an unspecified way.
+    ///
+    /// Use `.keys_shared.typed::<K>()` to iterate over `K` keys instead.
     pub fn keys_shared(&self) -> Keys<'_> {
         Keys::new(self)
     }
@@ -504,8 +508,8 @@ impl<'a> DictionaryIter<'a> {
                 ptr::addr_of_mut!(valid_u8),
             )
         };
-        let valid = super::u8_to_bool(valid_u8);
-        let has_next = super::u8_to_bool(has_next);
+        let valid = u8_to_bool(valid_u8);
+        let has_next = u8_to_bool(has_next);
 
         if has_next {
             assert!(valid);
@@ -518,9 +522,9 @@ impl<'a> DictionaryIter<'a> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// An iterator over key-value pairs from a `Dictionary`.
+/// Iterator over key-value pairs in a [`Dictionary`].
 ///
-/// See [Dictionary::iter_shared()] for more information about iteration over dictionaries.
+/// See [`Dictionary::iter_shared()`] for more information about iteration over dictionaries.
 pub struct Iter<'a> {
     iter: DictionaryIter<'a>,
 }
@@ -553,9 +557,9 @@ impl<'a> Iterator for Iter<'a> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// An iterator over keys from a `Dictionary`.
+/// Iterator over keys in a [`Dictionary`].
 ///
-/// See [Dictionary::keys_shared()] for more information about iteration over dictionaries.
+/// See [`Dictionary::keys_shared()`] for more information about iteration over dictionaries.
 pub struct Keys<'a> {
     iter: DictionaryIter<'a>,
 }
@@ -595,10 +599,9 @@ impl<'a> Iterator for Keys<'a> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// An iterator over key-value pairs from a `Dictionary` that will attempt to convert each
-/// key-value pair into a typed `(K, V)`.
+/// [`Dictionary`] iterator that converts each key-value pair into a typed `(K, V)`.
 ///
-/// See [Dictionary::iter_shared()] for more information about iteration over dictionaries.
+/// See [`Dictionary::iter_shared()`] for more information about iteration over dictionaries.
 pub struct TypedIter<'a, K, V> {
     iter: DictionaryIter<'a>,
     _k: PhantomData<K>,
@@ -631,9 +634,9 @@ impl<'a, K: FromGodot, V: FromGodot> Iterator for TypedIter<'a, K, V> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// An iterator over keys from a `Dictionary` that will attempt to convert each key into a `K`.
+/// [`Dictionary`] iterator that converts each key into a typed `K`.
 ///
-/// See [Dictionary::iter_shared()] for more information about iteration over dictionaries.
+/// See [`Dictionary::iter_shared()`] for more information about iteration over dictionaries.
 pub struct TypedKeys<'a, K> {
     iter: DictionaryIter<'a>,
     _k: PhantomData<K>,
@@ -660,6 +663,17 @@ impl<'a, K: FromGodot> Iterator for TypedKeys<'a, K> {
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Helper functions
+
+fn u8_to_bool(u: u8) -> bool {
+    match u {
+        0 => false,
+        1 => true,
+        _ => panic!("Invalid boolean value {u}"),
+    }
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
 /// Constructs [`Dictionary`] literals, close to Godot's own syntax.

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

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * 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/.
+ */
+
+mod array;
+mod dictionary;
+mod packed_array;
+
+// Re-export in godot::builtin.
+pub(crate) mod containers {
+    pub use super::array::{Array, VariantArray};
+    pub use super::dictionary::Dictionary;
+    pub use super::packed_array::*;
+}
+
+// Re-export in godot::builtin::iter.
+pub(crate) mod iterators {
+    pub use super::array::Iter as ArrayIter;
+    pub use super::dictionary::Iter as DictIter;
+    pub use super::dictionary::Keys as DictKeys;
+    pub use super::dictionary::TypedIter as DictTypedIter;
+    pub use super::dictionary::TypedKeys as DictTypedKeys;
+}
+
+// Crate-local re-exports.
+pub(crate) use array::ArrayTypeInfo;

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

@@ -10,11 +10,9 @@ use std::fmt;
 
 use godot_ffi::VariantType;
 
-use crate::builtin::{
-    array_inner,
-    meta::{ClassName, ToGodot},
-    Variant,
-};
+use crate::builtin::collections::ArrayTypeInfo;
+use crate::builtin::meta::{ClassName, ToGodot};
+use crate::builtin::Variant;
 
 type Cause = Box<dyn Error + Send + Sync>;
 
@@ -173,8 +171,8 @@ impl fmt::Display for ErrorKind {
 #[derive(Eq, PartialEq, Debug)]
 pub(crate) enum FromGodotError {
     BadArrayType {
-        expected: array_inner::TypeInfo,
-        actual: array_inner::TypeInfo,
+        expected: ArrayTypeInfo,
+        actual: ArrayTypeInfo,
     },
     /// InvalidEnum is also used by bitfields.
     InvalidEnum,