From f68cfc5a0a8a07a2729636b1a1bedc41d2de738d Mon Sep 17 00:00:00 2001 From: Mike Buland Date: Sat, 17 Nov 2012 18:10:06 +0000 Subject: Added XML standard in-code documentation, also GatsList and GatsDictionary helpers. --- cs-dotnet/src/gatsboolean.cs | 9 +++ cs-dotnet/src/gatsdictionary.cs | 129 ++++++++++++++++++++++++++++++++++++++ cs-dotnet/src/gatsfloat.cs | 33 ++++++++-- cs-dotnet/src/gatsinteger.cs | 12 ++++ cs-dotnet/src/gatslist.cs | 108 +++++++++++++++++++++++++++++++ cs-dotnet/src/gatsnull.cs | 11 ++++ cs-dotnet/src/gatsstring.cs | 16 +++++ cs-dotnet/src/tests/dictionary.cs | 8 +++ 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 { + /// + /// Encapsulates a single bool value. + /// + /// + /// 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. + /// 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 { + /// + /// Encapsulates a single dictionary of GatsObjects. + /// + /// + /// 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. + /// public class GatsDictionary : GatsObject, IDictionary // ICollection>, // IEnumerable> @@ -67,6 +87,115 @@ namespace Com.Xagasoft.Gats s.WriteByte( (int)'e' ); } + // + // Extra helper functions for making life with GATS easier + // + + /// + /// Helper function to add a new GatsString to the dictionary from a + /// byte array. + /// + /// The key to insert the new value with + /// The byte array to be inserted as a string + public void Add( string key, byte[] val ) + { + Add( key, new GatsString( val ) ); + } + + /// + /// Helper function to add a new GatsString to the dictionary from a + /// string. + /// + /// + /// The string is encoded UTF-8 by .NETs internal facilities. + /// + /// The key to insert the new value with + /// The string to be inserted as a string + public void Add( string key, string val ) + { + Add( key, new GatsString( val ) ); + } + + /// + /// Helper function to add a new GatsInteger to the dictionary. + /// + /// + /// 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. + /// + /// The key to insert the new value with + /// The long to be inserted + public void Add( string key, long val ) + { + Add( key, new GatsInteger( val ) ); + } + + /// + /// Helper function to add a new GatsFloat to the dictionary. + /// + /// + /// 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. + /// + /// The key to insert the new value with + /// The double to be inserted + public void Add( string key, double val ) + { + Add( key, new GatsFloat( val ) ); + } + + /// + /// Helper function to add a new GatsBoolean to the dictionary. + /// + /// The key to insert the new value with + /// The boolean value to be inserted + public void Add( string key, bool val ) + { + Add( key, new GatsBoolean( val ) ); + } + + /// + /// Helper function to add a new GatsNull to the dictionary. + /// + /// The key to insert the new null value with + public void AddNull( string key ) + { + Add( key, new GatsNull() ); + } + + /// + /// Helper function to add a new GatsDictionary to the dictionary. + /// + /// + /// A new GatsDictionary is created, added to the dictionary, and + /// returned. + /// + /// The key to insert the new value with + /// A new, empty dictionary that is already added + public GatsDictionary AddDict( string key ) + { + GatsDictionary dict = new GatsDictionary(); + Add( key, dict ); + return dict; + } + + /// + /// Helper function to add a new GatsList to the dictionary. + /// + /// + /// A new GatsList is created, added to the dictionary, and returned. + /// + /// The key to insert the new value with + /// A new, empty list that is already added + public GatsList AddList( string key ) + { + GatsList list = new GatsList(); + Add( key, list ); + return list; + } + // // List interface overrides under here. // 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 { + /// + /// Encapsulates a single floating point value. + /// + /// + /// 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. + /// 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 { + /// + /// Encapsulates a single integer value. + /// + /// + /// 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'. + /// 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 { + /// + /// Encapsulates a single list of GatsObjects. + /// + /// + /// 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. + /// public class GatsList : GatsObject, IList, ICollection, IEnumerable // IReadOnlyList, IReadOnlyCollection, @@ -59,6 +68,105 @@ namespace Com.Xagasoft.Gats s.WriteByte( (int)'e' ); } + // + // Helper functions + // + + /// + /// Helper function to add a new GatsString to the list. + /// + /// The byte array to be added as a GatsString + public void Add( byte[] val ) + { + Add( new GatsString( val ) ); + } + + /// + /// Helper function to add a new GatsString to the list. + /// + /// + /// The string is encoded UTF-8 by .NETs internal facilities. + /// + /// The string to be added as a GatsString + public void Add( string val ) + { + Add( new GatsString( val ) ); + } + + /// + /// Helper function to add a new GatsInteger to the list. + /// + /// + /// 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. + /// + /// The long to be added as a GatsInteger + public void Add( long val ) + { + Add( new GatsInteger( val ) ); + } + + /// + /// Helper function to add a new GatsFloat to the list. + /// + /// + /// 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. + /// + /// The double to be added as a GatsFloat + public void Add( double val ) + { + Add( new GatsFloat( val ) ); + } + + /// + /// Helper function to add a new GatsBoolean to the list. + /// + /// + /// The boolean value to be added as a GatsBoolean + /// + public void Add( bool val ) + { + Add( new GatsBoolean( val ) ); + } + + /// + /// Helper to append a GatsNull to the list. + /// + public void AddNull() + { + Add( new GatsNull() ); + } + + /// + /// Helper to append a GatsDictionary to the list. + /// + /// + /// A new GatsDictionary is constructed, appended to the list, and + /// returned. + /// + public GatsDictionary AddDict() + { + GatsDictionary dict = new GatsDictionary(); + Add( dict ); + return dict; + } + + /// + /// Helper to append a GatsList to the list. + /// + /// + /// A new GatsList is constructed, appended to the list, and returned. + /// + public GatsList AddList() + { + GatsList list = new GatsList(); + Add( list ); + return list; + } + // // List interface overrides under here. // 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 { + /// + /// Represents a NULL value. + /// + /// + /// 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. + /// 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 { + /// + /// Encapsulates a single byte array. + /// + /// + /// 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. + /// 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 ); -- cgit v1.2.3