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

helpers.

1 files changed, 108 insertions, 0 deletions

diff --git a/cs-dotnet/src/gatslist.cs b/cs-dotnet/src/gatslist.cs
index 7d57035..0f93d1e 100644
--- a/cs-dotnet/src/gatslist.cs
+++ b/cs-dotnet/src/gatslist.cs
@@ -13,6 +13,15 @@ using System.Collections.Generic;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Encapsulates a single list of GatsObjects.
+    /// </summary>
+    /// <remarks>
+    /// A list of arbitrary size containing ordered GatsObjects.  All standard
+    /// .NET IList, ICollection, and IEnumerable interfaces are implemented,
+    /// so a GatsList should work just like a standard List, but with a few
+    /// extras.
+    /// </remarks>
     public class GatsList : GatsObject, IList<GatsObject>,
         ICollection<GatsObject>, IEnumerable<GatsObject>
 //        IReadOnlyList<GatsObject>, IReadOnlyCollection<GatsObject>,
@@ -60,6 +69,105 @@ namespace Com.Xagasoft.Gats
         }
 
         //
+        // Helper functions
+        //
+
+        /// <summary>
+        /// Helper function to add a new GatsString to the list.
+        /// </summary>
+        /// <param name="val">The byte array to be added as a GatsString</param>
+        public void Add( byte[] val )
+        {
+            Add( new GatsString( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsString to the list.
+        /// </summary>
+        /// <remarks>
+        /// The string is encoded UTF-8 by .NETs internal facilities.
+        /// </remarks>
+        /// <param name="val">The string to be added as a GatsString</param>
+        public void Add( string val )
+        {
+            Add( new GatsString( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsInteger to the list.
+        /// </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="val">The long to be added as a GatsInteger</param>
+        public void Add( long val )
+        {
+            Add( new GatsInteger( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsFloat to the list.
+        /// </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="val">The double to be added as a GatsFloat</param>
+        public void Add( double val )
+        {
+            Add( new GatsFloat( val ) );
+        }
+
+        /// <summary>
+        /// Helper function to add a new GatsBoolean to the list.
+        /// </summary>
+        /// <param name="val">
+        /// The boolean value to be added as a GatsBoolean
+        /// </param>
+        public void Add( bool val )
+        {
+            Add( new GatsBoolean( val ) );
+        }
+
+        /// <summary>
+        /// Helper to append a GatsNull to the list.
+        /// </summary>
+        public void AddNull()
+        {
+            Add( new GatsNull() );
+        }
+
+        /// <summary>
+        /// Helper to append a GatsDictionary to the list.
+        /// </summary>
+        /// <remarks>
+        /// A new GatsDictionary is constructed, appended to the list, and
+        /// returned.
+        /// </remarks>
+        public GatsDictionary AddDict()
+        {
+            GatsDictionary dict = new GatsDictionary();
+            Add( dict );
+            return dict;
+        }
+
+        /// <summary>
+        /// Helper to append a GatsList to the list.
+        /// </summary>
+        /// <remarks>
+        /// A new GatsList is constructed, appended to the list, and returned.
+        /// </remarks>
+        public GatsList AddList()
+        {
+            GatsList list = new GatsList();
+            Add( list );
+            return list;
+        }
+
+        //
         // List interface overrides under here.
         //
         public int IndexOf( GatsObject obj )