wxJSON - The wxWidgets implementation of JSON
version 1.1
http://luccat.users.sourceforge.net/wxjson/
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
Here is an example of JSON formatted data:
{
"book":
{
"title" : "How to catch Peter Pan",
"author" : "Captain Hook",
"pages" : 285,
"price" : 29.95,
"translations" :
[
"german",
"french",
"spanish",
"italian"
]
}
}
And this is the same data in XML format:
<book title="How to catch Peter Pan" author="Captain Hook" pages=285 price=29.95>
<translations>
<item "german"/>
<item "french"/>
<item "spanish"/>
<item "italian"/>
</translations>
</book>
As you can see, JSON format is much more readable by humans and uses a syntax similar to many C-like languages. Someone may say that XML is object-oriented and JSON in not. The answer is that none of the two formats is really object-oriented. In fact, XML is a document-oriented format while JSON is a data-oriented format.
JSON handles data. There are the following data types in JSON:
- strings: a string is a sequence of ZERO or more unicode characters wrapped in double quotes, using backslash escapes
- numbers: a number is very much like a C or Java number, except that the octal and hexadecimal formats are not used
- the following three literals: null, true and false
- objects: a JSON object is a collection of name/value pairs
- arrays: an array is an ordered collection of values
JSON is built on two structures:
- the object: a collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
- the array: an ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.
The JSON object is an unordered collection of key/value pairs (or name/value pairs). The keys are strings and the values are any of the JSON types including object and array. A colon separates the keys from the values, and comma separates the pairs. The whole thing is wrapped in curly braces. It maps directly onto objects, structs, records, and hashtables. This is an example of a JSON object:
{
"name": "Jack (\"Bee\") Nimble",
"format": {
"type": "rect",
"size" :
{
"width": 1920,
"height": 1080,
},
"interlace": false,
"frame rate": 24
}
}
The JSON array is an ordered collection of values separated by commas. The whole thing is wrapped in square brackets. It maps directly onto arrays, vectors, and lists. These are examples of JSON arrays:
["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
[
[0, -1, 0],
[1, 0, 0],
[0, 0, 1]
]
The wxJSON library is a JSON implementation for wxWidgets and it is composed of only three classes which uses the
wxBase library: the only needed classes are:
wxString,
wxObjArray,
wxHashMap,
wxInputStream,
wxOutputStream,
wxArrayString and the
wxMBConv -derived classes. wxJSON does not depend on the
std::string class nor on STL containers.
The following three classes are defined in wxJSON:
- wxJSONValue this class holds the JSON value which can be an integer, a double, a boolean, a string, an array of JSON values or a map of key/value pairs
Pages related to this documentation:
The
wxJSON library only consists of three source files and their related header files:
jsonvalue.cpp
jsonreader.cpp
jsonwriter.cpp
For info about installation of the library read the INSTALL text file in the top-level directory. You can download this library in the following ways:
- using anonymous access to the Subversion repository of the wxCode project on SourceForge. You will need the bakefile tools in order to generate the makefiles for your system / compiler to actually compile the library unless you write it yourself.
- download the tarball which contains the makefiles for the most common systems / compilers by clikking here
The
wxJSON library is a complete implementation of the JSON data-interchange format. All JSON specifications are implemented in this library plus some extensions in the writer and in the parser class.
One of the most important features that is not present in this JSON implementation is iterators. Many other JSON implementations do provide iterators for the array and the object JSON types. I do not implement them because they need STL containers and I do not want the wxJSON library to depend on STL although there is a plan to let the user choose the container to be used: wxWidget's implementation or STL (see http://luccat.users.sourceforge.net/wxjson/newver_01.html#vers12).
JSON data format is very stable. It is accredited to be stable forever or, at least, until programming languages will be based on numbers, strings, booleans, structures and arrays. This version (1.1) is a stable release but there are plans to add some new features to the library (see http://luccat.users.sourceforge.net/wxjson/newver_01.html). Also, new versions of this library will be realesed in order to keep wxJSON compatible with the new releases of wxWidgets.
Many thanks to Bryan Ashby, Robbie Groenewoudt, Alexander Stigsen, Andrejs Cainikovs, Piotr Likus and Kolya Kosenko for their help, hints, feedback.
