Added XML standard in-code documentation, also GatsList and GatsDictionary

helpers.

1 files changed, 129 insertions, 0 deletions

diff --git a/cs-dotnet/src/gatsdictionary.cs b/cs-dotnet/src/gatsdictionary.cs
index af7f72a..77d088c 100644
--- a/cs-dotnet/src/gatsdictionary.cs
+++ b/cs-dotnet/src/gatsdictionary.cs
@@ -13,6 +13,26 @@ using System.Collections.Generic;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Encapsulates a single dictionary of GatsObjects.
+    /// </summary>
+    /// <remarks>
+    /// All keys are strings, and are encoded UTF-8.  At the moment it is
+    /// advisable to stick to 7-bit ASCII or LATIN-1 compatible strings for
+    /// interoperability.  If you want full unicode for keys, be sure you
+    /// handle it correctly with all libraries.
+    ///
+    /// Values can be any valid GatsObject.
+    ///
+    /// Just like dictionaries in memory, order is not important and is
+    /// considered random in encoded GATS.  This means that dictionary items
+    /// may be in a different order after writing them and reading them back
+    /// again.  Do not rely on a specific order, if you need ordered data use
+    /// a GatsList.
+    ///
+    /// All standard dictionary interface methods are implemented, so you can
+    /// use a GatsDictionary just like the .NET standard Dictionary.
+    /// </remarks>
     public class GatsDictionary : GatsObject, IDictionary<string, GatsObject>
 //          ICollection<KeyValuePair<string, GatsObject>>,
 //      IEnumerable<KeyValuePair<string, GatsObject>>
@@ -68,6 +88,115 @@ namespace Com.Xagasoft.Gats
         }
 
         //
+        // Extra helper functions for making life with GATS easier
+        //
+
+        /// <summary>
+        /// Helper function to add a new GatsString to the dictionary from a
+        /// byte array.
+        /// </summary>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <param name="val">The byte array to be inserted as a string</param>
+        public void Add( string key, byte[] val )
+        {
+            Add( key, new GatsString( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsString to the dictionary from a
+        /// string.
+        /// </summary>
+        /// <remarks>
+        /// The string is encoded UTF-8 by .NETs internal facilities.
+        /// </remarks>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <param name="val">The string to be inserted as a string</param>
+        public void Add( string key, string val )
+        {
+            Add( key, new GatsString( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsInteger to the dictionary.
+        /// </summary>
+        /// <remarks>
+        /// Implicit upcasting should allow all integer types (byte, short,
+        /// int, long), and automatic unboxing should allow all object variants
+        /// to be passed into this method without problem.
+        /// </remarks>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <param name="val">The long to be inserted</param>
+        public void Add( string key, long val )
+        {
+            Add( key, new GatsInteger( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsFloat to the dictionary.
+        /// </summary>
+        /// <remarks>
+        /// Implicit upcasting should allow floats and doubles to both be
+        /// accepted by this method.  Please note that decimal types are not
+        /// strictly compatible, please see GatsFloat for more details.
+        /// </remarks>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <param name="val">The double to be inserted</param>
+        public void Add( string key, double val )
+        {
+            Add( key, new GatsFloat( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsBoolean to the dictionary.
+        /// </summary>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <param name="val">The boolean value to be inserted</param>
+        public void Add( string key, bool val )
+        {
+            Add( key, new GatsBoolean( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsNull to the dictionary.
+        /// </summary>
+        /// <param name="key">The key to insert the new null value with</param>
+        public void AddNull( string key )
+        {
+            Add( key, new GatsNull() );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsDictionary to the dictionary.
+        /// </summary>
+        /// <remarks>
+        /// A new GatsDictionary is created, added to the dictionary, and
+        /// returned.
+        /// </remarks>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <returns>A new, empty dictionary that is already added</returns>
+        public GatsDictionary AddDict( string key )
+        {
+            GatsDictionary dict = new GatsDictionary();
+            Add( key, dict );
+            return dict;
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsList to the dictionary.
+        /// </summary>
+        /// <remarks>
+        /// A new GatsList is created, added to the dictionary, and returned.
+        /// </remarks>
+        /// <param name="key">The key to insert the new value with</param>
+        /// <returns>A new, empty list that is already added</returns>
+        public GatsList AddList( string key )
+        {
+            GatsList list = new GatsList();
+            Add( key, list );
+            return list;
+        }
+
+        //
         // List interface overrides under here.
         //
         public void Add( string key, GatsObject obj )