- tidied code

README.md

@@ -12,9 +12,9 @@ There are myriads of [JSON](http://json.org) libraries out there, and each may e
 
 Other aspects were not so important to us:
 
-- **Memory efficiency**. Each JSON object has an overhead of one pointer and one enumeration element (1 byte). We use the following C++ data types: `std::string` for strings, `int` or `double` for numbers, `std::map` for objects, `std::vector` for arrays, and `bool` for Booleans. We know that there are more efficient ways to store the values, but we are happy enough right now. And by the way: [Valgrind](http://valgrind.org) says our code is free of leaks.
+- **Memory efficiency**. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). We use the following C++ data types: `std::string` for strings, `int` or `double` for numbers, `std::map` for objects, `std::vector` for arrays, and `bool` for Booleans. We know that there are more efficient ways to store the values, but we are happy enough right now. And by the way: [Valgrind](http://valgrind.org) says our code is free of leaks.
 
-- **Speed**. We currently implement the parser as naive [recursive descent parser](http://en.wikipedia.org/wiki/Recursive_descent_parser) with hand coded string handling. It is fast enough, but a [LALR-parser](http://en.wikipedia.org/wiki/LALR_parser) with a decent regular expression processor should be even faster.
+- **Speed**. We currently implement the parser as naive [recursive descent parser](http://en.wikipedia.org/wiki/Recursive_descent_parser) with hand coded string handling. It is fast enough, but a [LALR-parser](http://en.wikipedia.org/wiki/LALR_parser) with a decent regular expression processor should be even faster (but would consist of more files which makes the integration harder).
 
 - **Rigourous standard compliance**. We followed the [specification](http://json.org) as close as possible, but did not invest too much in a 100% compliance with respect to Unicode support. As a result, there might be edge cases of false positives and false negatives, but as long as we have a hand-written parser, we won't invest too much to be fully compliant.
 
@@ -48,7 +48,7 @@ j["name"] = "Niels";
 // add an object inside the object
 j["further"]["entry"] = 42;
 
-// add an array that is stored as std::vector
+// add an array that is stored as std::vector (C++11)
 j["list"] = { 1, 0, 2 };
 ```
 
@@ -63,6 +63,8 @@ j << "{ \"pi\": 3.141, \"happy\": true }";
 std::cout << j;
 ```
 
+These operators work for any subclases of `std::istream` or `std::ostream`.
+
 ### STL-like access
 
 ```cpp
@@ -77,6 +79,11 @@ for (JSON::iterator it = j.begin(); it != j.end(); ++it) {
   std::cout << *it << '\n';
 }
 
+// C++11 style
+for (auto element : j) {
+  std::cout << element << '\n';
+}
+
 // getter/setter
 std::string tmp = j[0];
 j[1] = 42;
@@ -85,4 +92,42 @@ j[1] = 42;
 j.size();     // 3
 j.empty();    // false
 j.type();     // JSON::array
+
+// create an object
+JSON o;
+o["foo"] = 23;
+o["bar"] = false;
+o["baz"] = 3.141;
+
+// find an entry
+if (o.find("foo") != o.end()) {
+  // there is an entry with key "foo"
+}
+
+// iterate the object
+for (JSON::iterator it = o.begin(); it != o.end(); ++it) {
+  std::cout << it.key() << ':' << it.value() << '\n';
+}
 ```
+
+### Implicit conversions
+
+The type of the JSON object is determined automatically by the expression to store. Likewise, the stored value is implicitly converted 
+
+```cpp
+/// strings
+std::string s1 = "Hello, world!";
+JSON js = s;
+std::string s2 = j;
+
+// Booleans
+bool b1 = true;
+JSON jb = b1;
+bool b2 = jb;
+
+// numbers
+int i = 42;
+JSON jn = i;
+double f = jn;
+```
+

src/JSON.h

@@ -5,17 +5,12 @@
 #define __cplusplus11
 #endif
 
-// allow us to use "nullptr" everywhere
-#include <cstddef>
-#ifndef nullptr
-#define nullptr NULL
-#endif
-
+// STL containers
 #include <string>
 #include <vector>
 #include <map>
 
-// additional C++11 header
+// additional C++11 headers
 #ifdef __cplusplus11
 #include <mutex>
 #include <initializer_list>
@@ -27,8 +22,8 @@ class JSON {
         class iterator;
         class const_iterator;
 
-    private:
 #ifdef __cplusplus11
+    private:
         /// mutex to guard payload
         static std::mutex _token;
 #endif
@@ -55,19 +50,32 @@ class JSON {
 
         /// a JSON value
         union value {
+            /// array as pointer to array_t
             array_t* array;
+            /// object as pointer to object_t
             object_t* object;
+            /// string as pointer to string_t
             string_t* string;
+            /// Boolean
             boolean_t boolean;
+            /// number (integer)
             number_t number;
+            /// number (float)
             number_float_t number_float;
 
+            /// default constructor
             value() {}
+            /// constructor for arrays
             value(array_t* array): array(array) {}
+            /// constructor for objects
             value(object_t* object): object(object) {}
+            /// constructor for strings
             value(string_t* string): string(string) {}
+            /// constructor for Booleans
             value(boolean_t boolean) : boolean(boolean) {}
+            /// constructor for numbers (integer)
             value(number_t number) : number(number) {}
+            /// constructor for numbers (float)
             value(number_float_t number_float) : number_float(number_float) {}
         };
 
@@ -84,15 +92,15 @@ class JSON {
 #endif
 
     public:
-        /// create an empty (null) object
+        /// create a null object
         JSON();
-        /// create an empty object according to given type
+        /// create an object according to given type
         JSON(json_t);
-        /// create a string object from C++ string
+        /// create a string object from a C++ string
         JSON(const std::string&);
-        /// create a string object from C string
+        /// create a string object from a C string
         JSON(char*);
-        /// create a string object from C string
+        /// create a string object from a C string
         JSON(const char*);
         /// create a Boolean object
         JSON(const bool);
@@ -135,13 +143,16 @@ class JSON {
         operator double() const;
         /// implicit conversion to Boolean (only for Booleans)
         operator bool() const;
+        /// implicit conversion to JSON vector (not for objects)
+        operator std::vector<JSON>() const;
+        /// implicit conversion to JSON map (only for objects)
+        operator std::map<std::string, JSON>() const;
 
         /// write to stream
         friend std::ostream& operator<<(std::ostream& o, const JSON& j) {
             o << j.toString();
             return o;
         }
-
         /// write to stream
         friend std::ostream& operator>>(const JSON& j, std::ostream& o) {
             o << j.toString();
@@ -153,7 +164,6 @@ class JSON {
             parser(i).parse(j);
             return i;
         }
-
         /// read from stream
         friend std::istream& operator<<(JSON& j, std::istream& i) {
             parser(i).parse(j);
@@ -211,8 +221,11 @@ class JSON {
 
         /// find an element in an object (returns end() iterator otherwise)
         iterator find(const std::string&);
+        /// find an element in an object (returns end() iterator otherwise)
         const_iterator find(const std::string&) const;
+        /// find an element in an object (returns end() iterator otherwise)
         iterator find(const char*);
+        /// find an element in an object (returns end() iterator otherwise)
         const_iterator find(const char*) const;
 
         /// direct access to the underlying payload
@@ -222,6 +235,8 @@ class JSON {
 
         /// lexicographically compares the values
         bool operator==(const JSON&) const;
+        /// lexicographically compares the values
+        bool operator!=(const JSON&) const;
 
     private:
         /// return the type as string
@@ -299,26 +314,43 @@ class JSON {
         const_iterator cend() const;
 
     private:
+        /// a helper class to parse a JSON object
         class parser {
             public:
+                /// a parser reading from a C string
                 parser(char*);
+                /// a parser reading from a C++ string
                 parser(std::string&);
+                /// a parser reading from an input stream
                 parser(std::istream&);
+                /// destructor of the parser
                 ~parser();
+                /// parse into a given JSON object
                 void parse(JSON&);
 
             private:
+                /// read the next character, stripping whitespace
                 bool next();
-                void error(std::string = "") __attribute__((noreturn));
+                /// raise an exception with an error message
+                void error(std::string) __attribute__((noreturn));
+                /// parse a quoted string
                 std::string parseString();
+                /// parse a Boolean "true"
                 void parseTrue();
+                /// parse a Boolean "false"
                 void parseFalse();
+                /// parse a null object
                 void parseNull();
+                /// a helper function to expect a certain character
                 void expect(char);
 
+                /// the current character
                 char _current;
+                /// a buffer of the input
                 char* _buffer;
+                /// the position inside the input buffer
                 size_t _pos;
+                /// the length of the input buffer
                 size_t _length;
         };
 };