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

helpers.

8 files changed, 322 insertions, 4 deletions

diff --git a/cs-dotnet/src/gatsboolean.cs b/cs-dotnet/src/gatsboolean.cs
index 11c8115..0fcc6e9 100644
--- a/cs-dotnet/src/gatsboolean.cs
+++ b/cs-dotnet/src/gatsboolean.cs
@@ -9,6 +9,15 @@ using System.IO;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Encapsulates a single bool value.
+    /// </summary>
+    /// <remarks>
+    /// The boolean type is one of the simpler ones encoding-wise.  Instead of
+    /// a single type specfiier in the encoded GATS format, it uses two, and
+    /// no payload.  A '1' type specifier indicates a boolean value of true, and
+    /// a '0' type specfiier indicates a false.
+    /// </remarks>
     public class GatsBoolean : GatsObject
     {
         public bool Value { get; set; }
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 )
diff --git a/cs-dotnet/src/gatsfloat.cs b/cs-dotnet/src/gatsfloat.cs
index 4709097..9763855 100644
--- a/cs-dotnet/src/gatsfloat.cs
+++ b/cs-dotnet/src/gatsfloat.cs
@@ -10,6 +10,31 @@ using System;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Encapsulates a single floating point value.
+    /// </summary>
+    /// <remarks>
+    /// The GATS floating point encoding is bit-exact with any standard
+    /// floating point encoding similar to the IEEE encoding.  This means that
+    /// unlike textual encoding you will always get the exact same floating
+    /// point value back that you encoded.  This format is arbitrary precision
+    /// and not dependant on platform or hardware.
+    ///
+    /// Although the format is arbitrary precision, the backend in C# uses a
+    /// double for maximum precision without resorting to a software arbitrary
+    /// precision library.
+    ///
+    /// Interestingly, unlike many other languages, C# provides a decimal type
+    /// that is also floating point, however the decimal type is encoded using
+    /// a bcd-like scheme.  This makes it an excellent choice for many human
+    /// activities, but it cannot be encoded precisely as a GatsFloat.  If you
+    /// would like to preserve the decimal nature of those types it may be
+    /// better to encode them as strings.
+    ///
+    /// In encoding, the GATS float uses two different type specifiers, an 'f'
+    /// indicates a normal floating point value.  An 'F' represents a special
+    /// value: positive or negative NaN, infinity, or zero.
+    /// </remarks>
     public class GatsFloat : GatsObject
     {
         private static readonly double Log256 = Math.Log( 256.0 );
@@ -41,10 +66,10 @@ namespace Com.Xagasoft.Gats
                 {
                     case 'N': Value = -Double.NaN;                                  break;
                     case 'n': Value = Double.NaN;                                       break;
-                    case 'I': Value = Double.NegativeInfinity;  break;
-                    case 'i': Value = Double.PositiveInfinity;  break;
-                    case 'Z': Value = -0.0;                             break;
-                    case 'z': Value = 0.0;                                      break;
+                    case 'I': Value = Double.NegativeInfinity;          break;
+                    case 'i': Value = Double.PositiveInfinity;          break;
+                    case 'Z': Value = -0.0;                                     break;
+                    case 'z': Value = 0.0;                                              break;
                 }
             }
             else if( type == 'f' )
diff --git a/cs-dotnet/src/gatsinteger.cs b/cs-dotnet/src/gatsinteger.cs
index 268769b..5ef17d8 100644
--- a/cs-dotnet/src/gatsinteger.cs
+++ b/cs-dotnet/src/gatsinteger.cs
@@ -9,6 +9,18 @@ using System.IO;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Encapsulates a single integer value.
+    /// </summary>
+    /// <remarks>
+    /// The GATS integer encoding is arbitrary precision, and only consumes as
+    /// many bytes as it needs to represent a given number.  There is no such
+    /// thing as an unsigned GATS integer.
+    ///
+    /// Internally the GatsInteger stores it's value in a long.
+    ///
+    /// In encoding, the type specifier for a GATS integer is 'i'.
+    /// </remarks>
     public class GatsInteger : GatsObject
     {
         public long Value { get; set; }
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 )
diff --git a/cs-dotnet/src/gatsnull.cs b/cs-dotnet/src/gatsnull.cs
index 009676f..49ca243 100644
--- a/cs-dotnet/src/gatsnull.cs
+++ b/cs-dotnet/src/gatsnull.cs
@@ -9,6 +9,17 @@ using System.IO;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Represents a NULL value.
+    /// </summary>
+    /// <remarks>
+    /// There are a couple of reasons for using a real, instantiated object to
+    /// represent NULL instead of just using null.  Primarily, however, it is
+    /// important to know the difference between an intentionally encoded null
+    /// and an absence of any object at all.
+    ///
+    /// The GatsNull doesn't contain any fields.
+    /// </remarks>
     public class GatsNull : GatsObject
     {
         public GatsNull()
diff --git a/cs-dotnet/src/gatsstring.cs b/cs-dotnet/src/gatsstring.cs
index 3fa3b7e..0935b05 100644
--- a/cs-dotnet/src/gatsstring.cs
+++ b/cs-dotnet/src/gatsstring.cs
@@ -9,6 +9,22 @@ using System.IO;
 
 namespace Com.Xagasoft.Gats
 {
+    /// <summary>
+    /// Encapsulates a single byte array.
+    /// </summary>
+    /// <remarks>
+    /// A GATS string, unlike a C# string primitive, is simply an array of
+    /// bytes.  This is actually more flexible in many ways, as it allows a
+    /// GatsString to contain any binary data.  However, to encode textual data
+    /// there is no hard and fast standard.  If a string primitive is passed
+    /// into a GatsString it will be encoded into UTF-8.  If you would rather
+    /// use a different encoding then encode your data first, and then pass it
+    /// in as a byte array.
+    ///
+    /// The ToString implementation provided by GatsString also assumes that
+    /// the contained data is UTF-8 encoded.  This may cause some minor issues
+    /// when attempting to debug strings that contain binary.
+    /// </remarks>
     public class GatsString : GatsObject
     {
         public byte[] Value { get; set; }
diff --git a/cs-dotnet/src/tests/dictionary.cs b/cs-dotnet/src/tests/dictionary.cs
index b97cb7d..78fec38 100644
--- a/cs-dotnet/src/tests/dictionary.cs
+++ b/cs-dotnet/src/tests/dictionary.cs
@@ -37,6 +37,14 @@ public class Test
         d.Add("float", new GatsFloat( 87.332 ) );
         d.Add("string", new GatsString("Yup, a string") );
         d.Add("bool", new GatsBoolean( false ) );
+        d.Add("long", 998877665544L );
+        d.Add("int2", 998877 );
+        d.Add("short", (short)9988 );
+        d.Add("byte", (byte)99 );
+        d.Add("float2", 87.332F );
+        d.Add("double", 87.332D );
+        d.Add("string2", "Yup, a string" );
+        d.Add("bool2", false );
         Write( d, ms );
         ms.Seek( 0, SeekOrigin.Begin );
         Read( ms );