aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--cs-dotnet/src/gatsboolean.cs9
-rw-r--r--cs-dotnet/src/gatsdictionary.cs129
-rw-r--r--cs-dotnet/src/gatsfloat.cs33
-rw-r--r--cs-dotnet/src/gatsinteger.cs12
-rw-r--r--cs-dotnet/src/gatslist.cs108
-rw-r--r--cs-dotnet/src/gatsnull.cs11
-rw-r--r--cs-dotnet/src/gatsstring.cs16
-rw-r--r--cs-dotnet/src/tests/dictionary.cs8
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
10namespace Com.Xagasoft.Gats 10namespace 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
14namespace Com.Xagasoft.Gats 14namespace 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
11namespace Com.Xagasoft.Gats 11namespace 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
10namespace Com.Xagasoft.Gats 10namespace 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
14namespace Com.Xagasoft.Gats 14namespace 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
10namespace Com.Xagasoft.Gats 10namespace 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
10namespace Com.Xagasoft.Gats 10namespace 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 );