diff options
author | Mike Buland <eichlan@xagasoft.com> | 2012-11-17 18:10:06 +0000 |
---|---|---|
committer | Mike Buland <eichlan@xagasoft.com> | 2012-11-17 18:10:06 +0000 |
commit | f68cfc5a0a8a07a2729636b1a1bedc41d2de738d (patch) | |
tree | 40fc14f900b14e5db66b54ddf9b2e8bfb0035dae | |
parent | 38f03bf3279c5e0351539777db52bb9f1a4bc614 (diff) | |
download | libgats-f68cfc5a0a8a07a2729636b1a1bedc41d2de738d.tar.gz libgats-f68cfc5a0a8a07a2729636b1a1bedc41d2de738d.tar.bz2 libgats-f68cfc5a0a8a07a2729636b1a1bedc41d2de738d.tar.xz libgats-f68cfc5a0a8a07a2729636b1a1bedc41d2de738d.zip |
Added XML standard in-code documentation, also GatsList and GatsDictionary
helpers.
-rw-r--r-- | cs-dotnet/src/gatsboolean.cs | 9 | ||||
-rw-r--r-- | cs-dotnet/src/gatsdictionary.cs | 129 | ||||
-rw-r--r-- | cs-dotnet/src/gatsfloat.cs | 33 | ||||
-rw-r--r-- | cs-dotnet/src/gatsinteger.cs | 12 | ||||
-rw-r--r-- | cs-dotnet/src/gatslist.cs | 108 | ||||
-rw-r--r-- | cs-dotnet/src/gatsnull.cs | 11 | ||||
-rw-r--r-- | cs-dotnet/src/gatsstring.cs | 16 | ||||
-rw-r--r-- | 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; | |||
9 | 9 | ||
10 | namespace Com.Xagasoft.Gats | 10 | namespace Com.Xagasoft.Gats |
11 | { | 11 | { |
12 | /// <summary> | ||
13 | /// Encapsulates a single bool value. | ||
14 | /// </summary> | ||
15 | /// <remarks> | ||
16 | /// The boolean type is one of the simpler ones encoding-wise. Instead of | ||
17 | /// a single type specfiier in the encoded GATS format, it uses two, and | ||
18 | /// no payload. A '1' type specifier indicates a boolean value of true, and | ||
19 | /// a '0' type specfiier indicates a false. | ||
20 | /// </remarks> | ||
12 | public class GatsBoolean : GatsObject | 21 | public class GatsBoolean : GatsObject |
13 | { | 22 | { |
14 | public bool Value { get; set; } | 23 | 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; | |||
13 | 13 | ||
14 | namespace Com.Xagasoft.Gats | 14 | namespace Com.Xagasoft.Gats |
15 | { | 15 | { |
16 | /// <summary> | ||
17 | /// Encapsulates a single dictionary of GatsObjects. | ||
18 | /// </summary> | ||
19 | /// <remarks> | ||
20 | /// All keys are strings, and are encoded UTF-8. At the moment it is | ||
21 | /// advisable to stick to 7-bit ASCII or LATIN-1 compatible strings for | ||
22 | /// interoperability. If you want full unicode for keys, be sure you | ||
23 | /// handle it correctly with all libraries. | ||
24 | /// | ||
25 | /// Values can be any valid GatsObject. | ||
26 | /// | ||
27 | /// Just like dictionaries in memory, order is not important and is | ||
28 | /// considered random in encoded GATS. This means that dictionary items | ||
29 | /// may be in a different order after writing them and reading them back | ||
30 | /// again. Do not rely on a specific order, if you need ordered data use | ||
31 | /// a GatsList. | ||
32 | /// | ||
33 | /// All standard dictionary interface methods are implemented, so you can | ||
34 | /// use a GatsDictionary just like the .NET standard Dictionary. | ||
35 | /// </remarks> | ||
16 | public class GatsDictionary : GatsObject, IDictionary<string, GatsObject> | 36 | public class GatsDictionary : GatsObject, IDictionary<string, GatsObject> |
17 | // ICollection<KeyValuePair<string, GatsObject>>, | 37 | // ICollection<KeyValuePair<string, GatsObject>>, |
18 | // IEnumerable<KeyValuePair<string, GatsObject>> | 38 | // IEnumerable<KeyValuePair<string, GatsObject>> |
@@ -68,6 +88,115 @@ namespace Com.Xagasoft.Gats | |||
68 | } | 88 | } |
69 | 89 | ||
70 | // | 90 | // |
91 | // Extra helper functions for making life with GATS easier | ||
92 | // | ||
93 | |||
94 | /// <summary> | ||
95 | /// Helper function to add a new GatsString to the dictionary from a | ||
96 | /// byte array. | ||
97 | /// </summary> | ||
98 | /// <param name="key">The key to insert the new value with</param> | ||
99 | /// <param name="val">The byte array to be inserted as a string</param> | ||
100 | public void Add( string key, byte[] val ) | ||
101 | { | ||
102 | Add( key, new GatsString( val ) ); | ||
103 | } | ||
104 | |||
105 | /// <summary> | ||
106 | /// Helper function to add a new GatsString to the dictionary from a | ||
107 | /// string. | ||
108 | /// </summary> | ||
109 | /// <remarks> | ||
110 | /// The string is encoded UTF-8 by .NETs internal facilities. | ||
111 | /// </remarks> | ||
112 | /// <param name="key">The key to insert the new value with</param> | ||
113 | /// <param name="val">The string to be inserted as a string</param> | ||
114 | public void Add( string key, string val ) | ||
115 | { | ||
116 | Add( key, new GatsString( val ) ); | ||
117 | } | ||
118 | |||
119 | /// <summary> | ||
120 | /// Helper function to add a new GatsInteger to the dictionary. | ||
121 | /// </summary> | ||
122 | /// <remarks> | ||
123 | /// Implicit upcasting should allow all integer types (byte, short, | ||
124 | /// int, long), and automatic unboxing should allow all object variants | ||
125 | /// to be passed into this method without problem. | ||
126 | /// </remarks> | ||
127 | /// <param name="key">The key to insert the new value with</param> | ||
128 | /// <param name="val">The long to be inserted</param> | ||
129 | public void Add( string key, long val ) | ||
130 | { | ||
131 | Add( key, new GatsInteger( val ) ); | ||
132 | } | ||
133 | |||
134 | /// <summary> | ||
135 | /// Helper function to add a new GatsFloat to the dictionary. | ||
136 | /// </summary> | ||
137 | /// <remarks> | ||
138 | /// Implicit upcasting should allow floats and doubles to both be | ||
139 | /// accepted by this method. Please note that decimal types are not | ||
140 | /// strictly compatible, please see GatsFloat for more details. | ||
141 | /// </remarks> | ||
142 | /// <param name="key">The key to insert the new value with</param> | ||
143 | /// <param name="val">The double to be inserted</param> | ||
144 | public void Add( string key, double val ) | ||
145 | { | ||
146 | Add( key, new GatsFloat( val ) ); | ||
147 | } | ||
148 | |||
149 | /// <summary> | ||
150 | /// Helper function to add a new GatsBoolean to the dictionary. | ||
151 | /// </summary> | ||
152 | /// <param name="key">The key to insert the new value with</param> | ||
153 | /// <param name="val">The boolean value to be inserted</param> | ||
154 | public void Add( string key, bool val ) | ||
155 | { | ||
156 | Add( key, new GatsBoolean( val ) ); | ||
157 | } | ||
158 | |||
159 | /// <summary> | ||
160 | /// Helper function to add a new GatsNull to the dictionary. | ||
161 | /// </summary> | ||
162 | /// <param name="key">The key to insert the new null value with</param> | ||
163 | public void AddNull( string key ) | ||
164 | { | ||
165 | Add( key, new GatsNull() ); | ||
166 | } | ||
167 | |||
168 | /// <summary> | ||
169 | /// Helper function to add a new GatsDictionary to the dictionary. | ||
170 | /// </summary> | ||
171 | /// <remarks> | ||
172 | /// A new GatsDictionary is created, added to the dictionary, and | ||
173 | /// returned. | ||
174 | /// </remarks> | ||
175 | /// <param name="key">The key to insert the new value with</param> | ||
176 | /// <returns>A new, empty dictionary that is already added</returns> | ||
177 | public GatsDictionary AddDict( string key ) | ||
178 | { | ||
179 | GatsDictionary dict = new GatsDictionary(); | ||
180 | Add( key, dict ); | ||
181 | return dict; | ||
182 | } | ||
183 | |||
184 | /// <summary> | ||
185 | /// Helper function to add a new GatsList to the dictionary. | ||
186 | /// </summary> | ||
187 | /// <remarks> | ||
188 | /// A new GatsList is created, added to the dictionary, and returned. | ||
189 | /// </remarks> | ||
190 | /// <param name="key">The key to insert the new value with</param> | ||
191 | /// <returns>A new, empty list that is already added</returns> | ||
192 | public GatsList AddList( string key ) | ||
193 | { | ||
194 | GatsList list = new GatsList(); | ||
195 | Add( key, list ); | ||
196 | return list; | ||
197 | } | ||
198 | |||
199 | // | ||
71 | // List interface overrides under here. | 200 | // List interface overrides under here. |
72 | // | 201 | // |
73 | public void Add( string key, GatsObject obj ) | 202 | 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; | |||
10 | 10 | ||
11 | namespace Com.Xagasoft.Gats | 11 | namespace Com.Xagasoft.Gats |
12 | { | 12 | { |
13 | /// <summary> | ||
14 | /// Encapsulates a single floating point value. | ||
15 | /// </summary> | ||
16 | /// <remarks> | ||
17 | /// The GATS floating point encoding is bit-exact with any standard | ||
18 | /// floating point encoding similar to the IEEE encoding. This means that | ||
19 | /// unlike textual encoding you will always get the exact same floating | ||
20 | /// point value back that you encoded. This format is arbitrary precision | ||
21 | /// and not dependant on platform or hardware. | ||
22 | /// | ||
23 | /// Although the format is arbitrary precision, the backend in C# uses a | ||
24 | /// double for maximum precision without resorting to a software arbitrary | ||
25 | /// precision library. | ||
26 | /// | ||
27 | /// Interestingly, unlike many other languages, C# provides a decimal type | ||
28 | /// that is also floating point, however the decimal type is encoded using | ||
29 | /// a bcd-like scheme. This makes it an excellent choice for many human | ||
30 | /// activities, but it cannot be encoded precisely as a GatsFloat. If you | ||
31 | /// would like to preserve the decimal nature of those types it may be | ||
32 | /// better to encode them as strings. | ||
33 | /// | ||
34 | /// In encoding, the GATS float uses two different type specifiers, an 'f' | ||
35 | /// indicates a normal floating point value. An 'F' represents a special | ||
36 | /// value: positive or negative NaN, infinity, or zero. | ||
37 | /// </remarks> | ||
13 | public class GatsFloat : GatsObject | 38 | public class GatsFloat : GatsObject |
14 | { | 39 | { |
15 | private static readonly double Log256 = Math.Log( 256.0 ); | 40 | private static readonly double Log256 = Math.Log( 256.0 ); |
@@ -41,10 +66,10 @@ namespace Com.Xagasoft.Gats | |||
41 | { | 66 | { |
42 | case 'N': Value = -Double.NaN; break; | 67 | case 'N': Value = -Double.NaN; break; |
43 | case 'n': Value = Double.NaN; break; | 68 | case 'n': Value = Double.NaN; break; |
44 | case 'I': Value = Double.NegativeInfinity; break; | 69 | case 'I': Value = Double.NegativeInfinity; break; |
45 | case 'i': Value = Double.PositiveInfinity; break; | 70 | case 'i': Value = Double.PositiveInfinity; break; |
46 | case 'Z': Value = -0.0; break; | 71 | case 'Z': Value = -0.0; break; |
47 | case 'z': Value = 0.0; break; | 72 | case 'z': Value = 0.0; break; |
48 | } | 73 | } |
49 | } | 74 | } |
50 | else if( type == 'f' ) | 75 | 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; | |||
9 | 9 | ||
10 | namespace Com.Xagasoft.Gats | 10 | namespace Com.Xagasoft.Gats |
11 | { | 11 | { |
12 | /// <summary> | ||
13 | /// Encapsulates a single integer value. | ||
14 | /// </summary> | ||
15 | /// <remarks> | ||
16 | /// The GATS integer encoding is arbitrary precision, and only consumes as | ||
17 | /// many bytes as it needs to represent a given number. There is no such | ||
18 | /// thing as an unsigned GATS integer. | ||
19 | /// | ||
20 | /// Internally the GatsInteger stores it's value in a long. | ||
21 | /// | ||
22 | /// In encoding, the type specifier for a GATS integer is 'i'. | ||
23 | /// </remarks> | ||
12 | public class GatsInteger : GatsObject | 24 | public class GatsInteger : GatsObject |
13 | { | 25 | { |
14 | public long Value { get; set; } | 26 | 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; | |||
13 | 13 | ||
14 | namespace Com.Xagasoft.Gats | 14 | namespace Com.Xagasoft.Gats |
15 | { | 15 | { |
16 | /// <summary> | ||
17 | /// Encapsulates a single list of GatsObjects. | ||
18 | /// </summary> | ||
19 | /// <remarks> | ||
20 | /// A list of arbitrary size containing ordered GatsObjects. All standard | ||
21 | /// .NET IList, ICollection, and IEnumerable interfaces are implemented, | ||
22 | /// so a GatsList should work just like a standard List, but with a few | ||
23 | /// extras. | ||
24 | /// </remarks> | ||
16 | public class GatsList : GatsObject, IList<GatsObject>, | 25 | public class GatsList : GatsObject, IList<GatsObject>, |
17 | ICollection<GatsObject>, IEnumerable<GatsObject> | 26 | ICollection<GatsObject>, IEnumerable<GatsObject> |
18 | // IReadOnlyList<GatsObject>, IReadOnlyCollection<GatsObject>, | 27 | // IReadOnlyList<GatsObject>, IReadOnlyCollection<GatsObject>, |
@@ -60,6 +69,105 @@ namespace Com.Xagasoft.Gats | |||
60 | } | 69 | } |
61 | 70 | ||
62 | // | 71 | // |
72 | // Helper functions | ||
73 | // | ||
74 | |||
75 | /// <summary> | ||
76 | /// Helper function to add a new GatsString to the list. | ||
77 | /// </summary> | ||
78 | /// <param name="val">The byte array to be added as a GatsString</param> | ||
79 | public void Add( byte[] val ) | ||
80 | { | ||
81 | Add( new GatsString( val ) ); | ||
82 | } | ||
83 | |||
84 | /// <summary> | ||
85 | /// Helper function to add a new GatsString to the list. | ||
86 | /// </summary> | ||
87 | /// <remarks> | ||
88 | /// The string is encoded UTF-8 by .NETs internal facilities. | ||
89 | /// </remarks> | ||
90 | /// <param name="val">The string to be added as a GatsString</param> | ||
91 | public void Add( string val ) | ||
92 | { | ||
93 | Add( new GatsString( val ) ); | ||
94 | } | ||
95 | |||
96 | /// <summary> | ||
97 | /// Helper function to add a new GatsInteger to the list. | ||
98 | /// </summary> | ||
99 | /// <remarks> | ||
100 | /// Implicit upcasting should allow all integer types (byte, short, | ||
101 | /// int, long), and automatic unboxing should allow all object variants | ||
102 | /// to be passed into this method without problem. | ||
103 | /// </remarks> | ||
104 | /// <param name="val">The long to be added as a GatsInteger</param> | ||
105 | public void Add( long val ) | ||
106 | { | ||
107 | Add( new GatsInteger( val ) ); | ||
108 | } | ||
109 | |||
110 | /// <summary> | ||
111 | /// Helper function to add a new GatsFloat to the list. | ||
112 | /// </summary> | ||
113 | /// <remarks> | ||
114 | /// Implicit upcasting should allow floats and doubles to both be | ||
115 | /// accepted by this method. Please note that decimal types are not | ||
116 | /// strictly compatible, please see GatsFloat for more details. | ||
117 | /// </remarks> | ||
118 | /// <param name="val">The double to be added as a GatsFloat</param> | ||
119 | public void Add( double val ) | ||
120 | { | ||
121 | Add( new GatsFloat( val ) ); | ||
122 | } | ||
123 | |||
124 | /// <summary> | ||
125 | /// Helper function to add a new GatsBoolean to the list. | ||
126 | /// </summary> | ||
127 | /// <param name="val"> | ||
128 | /// The boolean value to be added as a GatsBoolean | ||
129 | /// </param> | ||
130 | public void Add( bool val ) | ||
131 | { | ||
132 | Add( new GatsBoolean( val ) ); | ||
133 | } | ||
134 | |||
135 | /// <summary> | ||
136 | /// Helper to append a GatsNull to the list. | ||
137 | /// </summary> | ||
138 | public void AddNull() | ||
139 | { | ||
140 | Add( new GatsNull() ); | ||
141 | } | ||
142 | |||
143 | /// <summary> | ||
144 | /// Helper to append a GatsDictionary to the list. | ||
145 | /// </summary> | ||
146 | /// <remarks> | ||
147 | /// A new GatsDictionary is constructed, appended to the list, and | ||
148 | /// returned. | ||
149 | /// </remarks> | ||
150 | public GatsDictionary AddDict() | ||
151 | { | ||
152 | GatsDictionary dict = new GatsDictionary(); | ||
153 | Add( dict ); | ||
154 | return dict; | ||
155 | } | ||
156 | |||
157 | /// <summary> | ||
158 | /// Helper to append a GatsList to the list. | ||
159 | /// </summary> | ||
160 | /// <remarks> | ||
161 | /// A new GatsList is constructed, appended to the list, and returned. | ||
162 | /// </remarks> | ||
163 | public GatsList AddList() | ||
164 | { | ||
165 | GatsList list = new GatsList(); | ||
166 | Add( list ); | ||
167 | return list; | ||
168 | } | ||
169 | |||
170 | // | ||
63 | // List interface overrides under here. | 171 | // List interface overrides under here. |
64 | // | 172 | // |
65 | public int IndexOf( GatsObject obj ) | 173 | 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; | |||
9 | 9 | ||
10 | namespace Com.Xagasoft.Gats | 10 | namespace Com.Xagasoft.Gats |
11 | { | 11 | { |
12 | /// <summary> | ||
13 | /// Represents a NULL value. | ||
14 | /// </summary> | ||
15 | /// <remarks> | ||
16 | /// There are a couple of reasons for using a real, instantiated object to | ||
17 | /// represent NULL instead of just using null. Primarily, however, it is | ||
18 | /// important to know the difference between an intentionally encoded null | ||
19 | /// and an absence of any object at all. | ||
20 | /// | ||
21 | /// The GatsNull doesn't contain any fields. | ||
22 | /// </remarks> | ||
12 | public class GatsNull : GatsObject | 23 | public class GatsNull : GatsObject |
13 | { | 24 | { |
14 | public GatsNull() | 25 | 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; | |||
9 | 9 | ||
10 | namespace Com.Xagasoft.Gats | 10 | namespace Com.Xagasoft.Gats |
11 | { | 11 | { |
12 | /// <summary> | ||
13 | /// Encapsulates a single byte array. | ||
14 | /// </summary> | ||
15 | /// <remarks> | ||
16 | /// A GATS string, unlike a C# string primitive, is simply an array of | ||
17 | /// bytes. This is actually more flexible in many ways, as it allows a | ||
18 | /// GatsString to contain any binary data. However, to encode textual data | ||
19 | /// there is no hard and fast standard. If a string primitive is passed | ||
20 | /// into a GatsString it will be encoded into UTF-8. If you would rather | ||
21 | /// use a different encoding then encode your data first, and then pass it | ||
22 | /// in as a byte array. | ||
23 | /// | ||
24 | /// The ToString implementation provided by GatsString also assumes that | ||
25 | /// the contained data is UTF-8 encoded. This may cause some minor issues | ||
26 | /// when attempting to debug strings that contain binary. | ||
27 | /// </remarks> | ||
12 | public class GatsString : GatsObject | 28 | public class GatsString : GatsObject |
13 | { | 29 | { |
14 | public byte[] Value { get; set; } | 30 | 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 | |||
37 | d.Add("float", new GatsFloat( 87.332 ) ); | 37 | d.Add("float", new GatsFloat( 87.332 ) ); |
38 | d.Add("string", new GatsString("Yup, a string") ); | 38 | d.Add("string", new GatsString("Yup, a string") ); |
39 | d.Add("bool", new GatsBoolean( false ) ); | 39 | d.Add("bool", new GatsBoolean( false ) ); |
40 | d.Add("long", 998877665544L ); | ||
41 | d.Add("int2", 998877 ); | ||
42 | d.Add("short", (short)9988 ); | ||
43 | d.Add("byte", (byte)99 ); | ||
44 | d.Add("float2", 87.332F ); | ||
45 | d.Add("double", 87.332D ); | ||
46 | d.Add("string2", "Yup, a string" ); | ||
47 | d.Add("bool2", false ); | ||
40 | Write( d, ms ); | 48 | Write( d, ms ); |
41 | ms.Seek( 0, SeekOrigin.Begin ); | 49 | ms.Seek( 0, SeekOrigin.Begin ); |
42 | Read( ms ); | 50 | Read( ms ); |