Merge pull request #51044 from raulsntos/csharp-dictionary-doc

Reduce C# Dictionary internal calls, Add documentation to Dictionary in C#

modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs

@@ -3,6 +3,7 @@ using System.Collections.Generic;
 using System.Collections;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Godot.Collections
 {
@@ -25,6 +26,11 @@ namespace Godot.Collections
         }
     }
 
+    /// <summary>
+    /// Wrapper around Godot's Dictionary class, a dictionary of Variant
+    /// typed elements allocated in the engine in C++. Useful when
+    /// interfacing with the engine.
+    /// </summary>
     public class Dictionary :
         IDictionary,
         IDisposable
@@ -32,11 +38,19 @@ namespace Godot.Collections
         DictionarySafeHandle safeHandle;
         bool disposed = false;
 
+        /// <summary>
+        /// Constructs a new empty <see cref="Dictionary"/>.
+        /// </summary>
         public Dictionary()
         {
             safeHandle = new DictionarySafeHandle(godot_icall_Dictionary_Ctor());
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Dictionary"/> from the given dictionary's elements.
+        /// </summary>
+        /// <param name="dictionary">The dictionary to construct from.</param>
+        /// <returns>A new Godot Dictionary.</returns>
         public Dictionary(IDictionary dictionary) : this()
         {
             if (dictionary == null)
@@ -64,6 +78,9 @@ namespace Godot.Collections
             return safeHandle.DangerousGetHandle();
         }
 
+        /// <summary>
+        /// Disposes of this <see cref="Dictionary"/>.
+        /// </summary>
         public void Dispose()
         {
             if (disposed)
@@ -78,6 +95,11 @@ namespace Godot.Collections
             disposed = true;
         }
 
+        /// <summary>
+        /// Duplicates this <see cref="Dictionary"/>.
+        /// </summary>
+        /// <param name="deep">If <see langword="true"/>, performs a deep copy.</param>
+        /// <returns>A new Godot Dictionary.</returns>
         public Dictionary Duplicate(bool deep = false)
         {
             return new Dictionary(godot_icall_Dictionary_Duplicate(GetPtr(), deep));
@@ -85,6 +107,9 @@ namespace Godot.Collections
 
         // IDictionary
 
+        /// <summary>
+        /// Gets the collection of keys in this <see cref="Dictionary"/>.
+        /// </summary>
         public ICollection Keys
         {
             get
@@ -94,6 +119,9 @@ namespace Godot.Collections
             }
         }
 
+        /// <summary>
+        /// Gets the collection of elements in this <see cref="Dictionary"/>.
+        /// </summary>
         public ICollection Values
         {
             get
@@ -103,47 +131,88 @@ namespace Godot.Collections
             }
         }
 
-        public bool IsFixedSize => false;
+        private (Array keys, Array values, int count) GetKeyValuePairs()
+        {
+            int count = godot_icall_Dictionary_KeyValuePairs(GetPtr(), out IntPtr keysHandle, out IntPtr valuesHandle);
+            Array keys = new Array(new ArraySafeHandle(keysHandle));
+            Array values = new Array(new ArraySafeHandle(valuesHandle));
+            return (keys, values, count);
+        }
+
+        bool IDictionary.IsFixedSize => false;
 
-        public bool IsReadOnly => false;
+        bool IDictionary.IsReadOnly => false;
 
+        /// <summary>
+        /// Returns the object at the given <paramref name="key"/>.
+        /// </summary>
+        /// <value>The object at the given <paramref name="key"/>.</value>
         public object this[object key]
         {
             get => godot_icall_Dictionary_GetValue(GetPtr(), key);
             set => godot_icall_Dictionary_SetValue(GetPtr(), key, value);
         }
 
+        /// <summary>
+        /// Adds an object <paramref name="value"/> at key <paramref name="key"/>
+        /// to this <see cref="Dictionary"/>.
+        /// </summary>
+        /// <param name="key">The key at which to add the object.</param>
+        /// <param name="value">The object to add.</param>
         public void Add(object key, object value) => godot_icall_Dictionary_Add(GetPtr(), key, value);
 
+        /// <summary>
+        /// Erases all items from this <see cref="Dictionary"/>.
+        /// </summary>
         public void Clear() => godot_icall_Dictionary_Clear(GetPtr());
 
+        /// <summary>
+        /// Checks if this <see cref="Dictionary"/> contains the given key.
+        /// </summary>
+        /// <param name="key">The key to look for.</param>
+        /// <returns>Whether or not this dictionary contains the given key.</returns>
         public bool Contains(object key) => godot_icall_Dictionary_ContainsKey(GetPtr(), key);
 
+        /// <summary>
+        /// Gets an enumerator for this <see cref="Dictionary"/>.
+        /// </summary>
+        /// <returns>An enumerator.</returns>
         public IDictionaryEnumerator GetEnumerator() => new DictionaryEnumerator(this);
 
+        /// <summary>
+        /// Removes an element from this <see cref="Dictionary"/> by key.
+        /// </summary>
+        /// <param name="key">The key of the element to remove.</param>
         public void Remove(object key) => godot_icall_Dictionary_RemoveKey(GetPtr(), key);
 
         // ICollection
 
-        public object SyncRoot => this;
+        object ICollection.SyncRoot => this;
 
-        public bool IsSynchronized => false;
+        bool ICollection.IsSynchronized => false;
 
+        /// <summary>
+        /// Returns the number of elements in this <see cref="Dictionary"/>.
+        /// This is also known as the size or length of the dictionary.
+        /// </summary>
+        /// <returns>The number of elements.</returns>
         public int Count => godot_icall_Dictionary_Count(GetPtr());
 
+        /// <summary>
+        /// Copies the elements of this <see cref="Dictionary"/> to the given
+        /// untyped C# array, starting at the given index.
+        /// </summary>
+        /// <param name="array">The array to copy to.</param>
+        /// <param name="index">The index to start at.</param>
         public void CopyTo(System.Array array, int index)
         {
-            // TODO Can be done with single internal call
-
             if (array == null)
                 throw new ArgumentNullException(nameof(array), "Value cannot be null.");
 
             if (index < 0)
                 throw new ArgumentOutOfRangeException(nameof(index), "Number was less than the array's lower bound in the first dimension.");
 
-            Array keys = (Array)Keys;
-            Array values = (Array)Values;
-            int count = Count;
+            var (keys, values, count) = GetKeyValuePairs();
 
             if (array.Length < (index + count))
                 throw new ArgumentException("Destination array was not long enough. Check destIndex and length, and the array's lower bounds.");
@@ -161,24 +230,39 @@ namespace Godot.Collections
 
         private class DictionaryEnumerator : IDictionaryEnumerator
         {
-            Array keys;
-            Array values;
-            int count;
-            int index = -1;
+            private readonly Dictionary dictionary;
+            private readonly int count;
+            private int index = -1;
+            private bool dirty = true;
+
+            private DictionaryEntry entry;
 
             public DictionaryEnumerator(Dictionary dictionary)
             {
-                // TODO 3 internal calls, can reduce to 1
-                keys = (Array)dictionary.Keys;
-                values = (Array)dictionary.Values;
+                this.dictionary = dictionary;
                 count = dictionary.Count;
             }
 
             public object Current => Entry;
 
-            public DictionaryEntry Entry =>
-                // TODO 2 internal calls, can reduce to 1
-                new DictionaryEntry(keys[index], values[index]);
+            public DictionaryEntry Entry
+            {
+                get
+                {
+                    if (dirty)
+                    {
+                        UpdateEntry();
+                    }
+                    return entry;
+                }
+            }
+
+            private void UpdateEntry()
+            {
+                dirty = false;
+                godot_icall_Dictionary_KeyValuePairAt(dictionary.GetPtr(), index, out object key, out object value);
+                entry = new DictionaryEntry(key, value);
+            }
 
             public object Key => Entry.Key;
 
@@ -187,15 +271,21 @@ namespace Godot.Collections
             public bool MoveNext()
             {
                 index++;
+                dirty = true;
                 return index < count;
             }
 
             public void Reset()
             {
                 index = -1;
+                dirty = true;
             }
         }
 
+        /// <summary>
+        /// Converts this <see cref="Dictionary"/> to a string.
+        /// </summary>
+        /// <returns>A string representation of this dictionary.</returns>
         public override string ToString()
         {
             return godot_icall_Dictionary_ToString(GetPtr());
@@ -225,6 +315,12 @@ namespace Godot.Collections
         [MethodImpl(MethodImplOptions.InternalCall)]
         internal extern static int godot_icall_Dictionary_Count(IntPtr ptr);
 
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        internal extern static int godot_icall_Dictionary_KeyValuePairs(IntPtr ptr, out IntPtr keys, out IntPtr values);
+
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        internal extern static void godot_icall_Dictionary_KeyValuePairAt(IntPtr ptr, int index, out object key, out object value);
+
         [MethodImpl(MethodImplOptions.InternalCall)]
         internal extern static void godot_icall_Dictionary_Add(IntPtr ptr, object key, object value);
 
@@ -259,10 +355,18 @@ namespace Godot.Collections
         internal extern static string godot_icall_Dictionary_ToString(IntPtr ptr);
     }
 
+    /// <summary>
+    /// Typed wrapper around Godot's Dictionary class, a dictionary of Variant
+    /// typed elements allocated in the engine in C++. Useful when
+    /// interfacing with the engine. Otherwise prefer .NET collections
+    /// such as <see cref="System.Collections.Generic.Dictionary{TKey, TValue}"/>.
+    /// </summary>
+    /// <typeparam name="TKey">The type of the dictionary's keys.</typeparam>
+    /// <typeparam name="TValue">The type of the dictionary's values.</typeparam>
     public class Dictionary<TKey, TValue> :
         IDictionary<TKey, TValue>
     {
-        Dictionary objectDict;
+        private readonly Dictionary objectDict;
 
         internal static int valTypeEncoding;
         internal static IntPtr valTypeClass;
@@ -272,11 +376,19 @@ namespace Godot.Collections
             Dictionary.godot_icall_Dictionary_Generic_GetValueTypeInfo(typeof(TValue), out valTypeEncoding, out valTypeClass);
         }
 
+        /// <summary>
+        /// Constructs a new empty <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
         public Dictionary()
         {
             objectDict = new Dictionary();
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Dictionary{TKey, TValue}"/> from the given dictionary's elements.
+        /// </summary>
+        /// <param name="dictionary">The dictionary to construct from.</param>
+        /// <returns>A new Godot Dictionary.</returns>
         public Dictionary(IDictionary<TKey, TValue> dictionary)
         {
             objectDict = new Dictionary();
@@ -294,6 +406,11 @@ namespace Godot.Collections
             }
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Dictionary{TKey, TValue}"/> from the given dictionary's elements.
+        /// </summary>
+        /// <param name="dictionary">The dictionary to construct from.</param>
+        /// <returns>A new Godot Dictionary.</returns>
         public Dictionary(Dictionary dictionary)
         {
             objectDict = dictionary;
@@ -309,6 +426,10 @@ namespace Godot.Collections
             objectDict = new Dictionary(handle);
         }
 
+        /// <summary>
+        /// Converts this typed <see cref="Dictionary{TKey, TValue}"/> to an untyped <see cref="Dictionary"/>.
+        /// </summary>
+        /// <param name="from">The typed dictionary to convert.</param>
         public static explicit operator Dictionary(Dictionary<TKey, TValue> from)
         {
             return from.objectDict;
@@ -319,6 +440,11 @@ namespace Godot.Collections
             return objectDict.GetPtr();
         }
 
+        /// <summary>
+        /// Duplicates this <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
+        /// <param name="deep">If <see langword="true"/>, performs a deep copy.</param>
+        /// <returns>A new Godot Dictionary.</returns>
         public Dictionary<TKey, TValue> Duplicate(bool deep = false)
         {
             return new Dictionary<TKey, TValue>(objectDict.Duplicate(deep));
@@ -326,12 +452,19 @@ namespace Godot.Collections
 
         // IDictionary<TKey, TValue>
 
+        /// <summary>
+        /// Returns the value at the given <paramref name="key"/>.
+        /// </summary>
+        /// <value>The value at the given <paramref name="key"/>.</value>
         public TValue this[TKey key]
         {
             get { return (TValue)Dictionary.godot_icall_Dictionary_GetValue_Generic(objectDict.GetPtr(), key, valTypeEncoding, valTypeClass); }
             set { objectDict[key] = value; }
         }
 
+        /// <summary>
+        /// Gets the collection of keys in this <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
         public ICollection<TKey> Keys
         {
             get
@@ -341,6 +474,9 @@ namespace Godot.Collections
             }
         }
 
+        /// <summary>
+        /// Gets the collection of elements in this <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
         public ICollection<TValue> Values
         {
             get
@@ -350,56 +486,93 @@ namespace Godot.Collections
             }
         }
 
+        private KeyValuePair<TKey, TValue> GetKeyValuePair(int index)
+        {
+            Dictionary.godot_icall_Dictionary_KeyValuePairAt(GetPtr(), index, out object key, out object value);
+            return new KeyValuePair<TKey, TValue>((TKey)key, (TValue)value);
+        }
+
+        /// <summary>
+        /// Adds an object <paramref name="value"/> at key <paramref name="key"/>
+        /// to this <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
+        /// <param name="key">The key at which to add the object.</param>
+        /// <param name="value">The object to add.</param>
         public void Add(TKey key, TValue value)
         {
             objectDict.Add(key, value);
         }
 
+        /// <summary>
+        /// Checks if this <see cref="Dictionary{TKey, TValue}"/> contains the given key.
+        /// </summary>
+        /// <param name="key">The key to look for.</param>
+        /// <returns>Whether or not this dictionary contains the given key.</returns>
         public bool ContainsKey(TKey key)
         {
             return objectDict.Contains(key);
         }
 
+        /// <summary>
+        /// Removes an element from this <see cref="Dictionary{TKey, TValue}"/> by key.
+        /// </summary>
+        /// <param name="key">The key of the element to remove.</param>
         public bool Remove(TKey key)
         {
             return Dictionary.godot_icall_Dictionary_RemoveKey(GetPtr(), key);
         }
 
-        public bool TryGetValue(TKey key, out TValue value)
+        /// <summary>
+        /// Gets the object at the given <paramref name="key"/>.
+        /// </summary>
+        /// <param name="key">The key of the element to get.</param>
+        /// <param name="value">The value at the given <paramref name="key"/>.</param>
+        /// <returns>If an object was found for the given <paramref name="key"/>.</returns>
+        public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value)
         {
-            object retValue;
-            bool found = Dictionary.godot_icall_Dictionary_TryGetValue_Generic(GetPtr(), key, out retValue, valTypeEncoding, valTypeClass);
-            value = found ? (TValue)retValue : default(TValue);
+            bool found = Dictionary.godot_icall_Dictionary_TryGetValue_Generic(GetPtr(), key, out object retValue, valTypeEncoding, valTypeClass);
+            value = found ? (TValue)retValue : default;
             return found;
         }
 
         // ICollection<KeyValuePair<TKey, TValue>>
 
+        /// <summary>
+        /// Returns the number of elements in this <see cref="Dictionary{TKey, TValue}"/>.
+        /// This is also known as the size or length of the dictionary.
+        /// </summary>
+        /// <returns>The number of elements.</returns>
         public int Count
         {
             get { return objectDict.Count; }
         }
 
-        public bool IsReadOnly
-        {
-            get { return objectDict.IsReadOnly; }
-        }
+        bool ICollection<KeyValuePair<TKey, TValue>>.IsReadOnly => false;
 
-        public void Add(KeyValuePair<TKey, TValue> item)
+        void ICollection<KeyValuePair<TKey, TValue>>.Add(KeyValuePair<TKey, TValue> item)
         {
             objectDict.Add(item.Key, item.Value);
         }
 
+        /// <summary>
+        /// Erases all the items from this <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
         public void Clear()
         {
             objectDict.Clear();
         }
 
-        public bool Contains(KeyValuePair<TKey, TValue> item)
+        bool ICollection<KeyValuePair<TKey, TValue>>.Contains(KeyValuePair<TKey, TValue> item)
         {
             return objectDict.Contains(new KeyValuePair<object, object>(item.Key, item.Value));
         }
 
+        /// <summary>
+        /// Copies the elements of this <see cref="Dictionary{TKey, TValue}"/> to the given
+        /// untyped C# array, starting at the given index.
+        /// </summary>
+        /// <param name="array">The array to copy to.</param>
+        /// <param name="arrayIndex">The index to start at.</param>
         public void CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex)
         {
             if (array == null)
@@ -408,9 +581,6 @@ namespace Godot.Collections
             if (arrayIndex < 0)
                 throw new ArgumentOutOfRangeException(nameof(arrayIndex), "Number was less than the array's lower bound in the first dimension.");
 
-            // TODO 3 internal calls, can reduce to 1
-            Array<TKey> keys = (Array<TKey>)Keys;
-            Array<TValue> values = (Array<TValue>)Values;
             int count = Count;
 
             if (array.Length < (arrayIndex + count))
@@ -418,13 +588,12 @@ namespace Godot.Collections
 
             for (int i = 0; i < count; i++)
             {
-                // TODO 2 internal calls, can reduce to 1
-                array[arrayIndex] = new KeyValuePair<TKey, TValue>(keys[i], values[i]);
+                array[arrayIndex] = GetKeyValuePair(i);
                 arrayIndex++;
             }
         }
 
-        public bool Remove(KeyValuePair<TKey, TValue> item)
+        bool ICollection<KeyValuePair<TKey, TValue>>.Remove(KeyValuePair<TKey, TValue> item)
         {
             return Dictionary.godot_icall_Dictionary_Remove(GetPtr(), item.Key, item.Value);
             ;
@@ -432,17 +601,15 @@ namespace Godot.Collections
 
         // IEnumerable<KeyValuePair<TKey, TValue>>
 
+        /// <summary>
+        /// Gets an enumerator for this <see cref="Dictionary{TKey, TValue}"/>.
+        /// </summary>
+        /// <returns>An enumerator.</returns>
         public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
         {
-            // TODO 3 internal calls, can reduce to 1
-            Array<TKey> keys = (Array<TKey>)Keys;
-            Array<TValue> values = (Array<TValue>)Values;
-            int count = Count;
-
-            for (int i = 0; i < count; i++)
+            for (int i = 0; i < Count; i++)
             {
-                // TODO 2 internal calls, can reduce to 1
-                yield return new KeyValuePair<TKey, TValue>(keys[i], values[i]);
+                yield return GetKeyValuePair(i);
             }
         }
 
@@ -451,6 +618,10 @@ namespace Godot.Collections
             return GetEnumerator();
         }
 
+        /// <summary>
+        /// Converts this <see cref="Dictionary{TKey, TValue}"/> to a string.
+        /// </summary>
+        /// <returns>A string representation of this dictionary.</returns>
         public override string ToString() => objectDict.ToString();
     }
 }

modules/mono/glue/collections_glue.cpp

@@ -230,6 +230,19 @@ int32_t godot_icall_Dictionary_Count(Dictionary *ptr) {
 	return ptr->size();
 }
 
+int32_t godot_icall_Dictionary_KeyValuePairs(Dictionary *ptr, Array **keys, Array **values) {
+	*keys = godot_icall_Dictionary_Keys(ptr);
+	*values = godot_icall_Dictionary_Values(ptr);
+	return godot_icall_Dictionary_Count(ptr);
+}
+
+void godot_icall_Dictionary_KeyValuePairAt(Dictionary *ptr, int index, MonoObject **key, MonoObject **value) {
+	Array *keys = godot_icall_Dictionary_Keys(ptr);
+	Array *values = godot_icall_Dictionary_Values(ptr);
+	*key = GDMonoMarshal::variant_to_mono_object(keys->get(index));
+	*value = GDMonoMarshal::variant_to_mono_object(values->get(index));
+}
+
 void godot_icall_Dictionary_Add(Dictionary *ptr, MonoObject *key, MonoObject *value) {
 	Variant varKey = GDMonoMarshal::mono_object_to_variant(key);
 	Variant *ret = ptr->getptr(varKey);
@@ -338,6 +351,8 @@ void godot_register_collections_icalls() {
 	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_Keys", godot_icall_Dictionary_Keys);
 	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_Values", godot_icall_Dictionary_Values);
 	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_Count", godot_icall_Dictionary_Count);
+	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_KeyValuePairs", godot_icall_Dictionary_KeyValuePairs);
+	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_KeyValuePairAt", godot_icall_Dictionary_KeyValuePairAt);
 	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_Add", godot_icall_Dictionary_Add);
 	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_Clear", godot_icall_Dictionary_Clear);
 	GDMonoUtils::add_internal_call("Godot.Collections.Dictionary::godot_icall_Dictionary_Contains", godot_icall_Dictionary_Contains);