A Very High Performance Objective-C JSON Library
JSONKit is licensed under the terms of the BSD License. Copyright © 2011, John Engelhart.
JSON provides the following primitive types:
- Associative Arrays (Objects in RFC 4627 nomenclature, a.k.a. Key / Value Hash Tables, Maps, Dictionaries, etc.)
These primitive types are mapped to the following Objective-C Foundation classes:
JSON To Objective-C Primitive Mapping Details
While the JSON specification specifies that the serialized JSON must be encoded in Unicode, it does not specify how Unicode encoding errors should be handled. In general, JSONKit will not accept JSON that contains ill-formed Unicode.
JKParseOptionLooseUnicodeoption is used, JSONKit follows the specifications and recommendations given in The Unicode 5.2 standard, Chapter 3, section 3.9 Unicode Encoding Forms. As a general rule of thumb, the Unicode code point
U+FFFDis substituted for any ill-formed Unicode encountered. JSONKit attempts to follow the recommended Best Practice for Using U+FFFD: Replace each maximal subpart of an ill-formed subsequence by a single U+FFFD. Additionally, the following Unicode code points are treated as ill-formed Unicode, and if
JKParseOptionLooseUnicodeis enabled, cause
U+FFFDto be substituted in their place:
U+nFFFF, where n is from
The code points
U+nFFFF(where n is from
0x10), are defined as Noncharacters by the Unicode standard and "should never be interchanged".
RFC 4627 allows for these limitations under section 4, Parsers:
An implementation may set limits on the length and character contents of strings.
NSStringclass may place additional restrictions or otherwise transform the JSON String in such a way so that the JSON String is not bijective with the instantiated
NSStringobject. In other words, JSONKit can not guarantee that when you round trip a JSON String to a
NSStringand then back to a JSON String that the two JSON Strings will be exactly the same, even though in practice they are. For clarity, "exactly" in this case means bit for bit identical. JSONKit can not even guarantee that the two JSON Strings will be Unicode equivalent, even though in practice they will be and would be the most likely cause for the two round tripped JSON Strings to no longer be bit for bit identical. JSONKit does not perform any form of Unicode Normalization on the parsed strings. While JSONKit makes an effort (subject to the reasonable caveats above) to preserve the parsed JSON string exactly, it can not guarantee that
NSStringwill preserve the exact Unicode semantics of the original string.
kCFBooleanFalse, respectively. Conceptually,
CFBooleanvalues can be thought of, and treated as,
NSNumberclass objects. The benefit to using
falseJSON values can be round trip deserialized and serialized without conversion or promotion to a
NSNumberwith a value of
The JSON specification does not specify the details or requirements for JSON Number values, nor does it specify how errors due to conversion should be handled. In general, JSONKit will not accept JSON that contains JSON Number values that it can not convert with out error or loss of precision.
For non-floating-point numbers (i.e., JSON Number values that do not include a
e|E), JSONKit uses a 64-bit C primitive type internally, regardless of whether the target architecture is 32-bit or 64-bit. For unsigned values (i.e., those that do not begin with a
-), this allows for values up to
2⁶⁴-1and up to
-2⁶³for negative values. As a special case, the JSON Number
-0is treated as a floating-point number since the underlying floating-point primitive type is capable of representing a negative zero, whereas the underlying twos-complement non-floating-point primitive type can not. JSON that contains Number values that exceed these limits will fail to parse and optionally return a
NSErrorobject. The functions
strtoull()are used to perform the conversions.
doubleprimitive type, or IEEE 754 Double 64-bit floating-point, is used to represent floating-point JSON Number values. JSON that contains floating-point Number values that can not be represented as a
double(i.e., due to over or underflow) will fail to parse and optionally return a
NSErrorobject. The function
strtod()is used to perform the conversion. Note that the JSON standard does not allow for infinities or
NaN(Not a Number).
For JSON Associative Arrays (or
objectin RFC 4627 nomenclature), RFC 4627 says
The names within an object SHOULD be unique(note:
keyin JSONKit nomenclature). At this time the JSONKit behavior is
undefinedfor JSON that contains names within an object that are not unique. However, JSONKit currently tries to follow a "the last key / value pair parsed is the one chosen" policy. This behavior is not finalized and should not be depended on.
Objective-C To JSON Primitive Mapping Details
NSDictionaryclass allows for any object, which can be of any class, to be used as a
key. JSON, however, only permits Strings to be used as
keys. Therefore JSONKit will fail with an error if it encounters a
NSDictionarythat contains keys that are not
NSStringobjects during serialization.
JSON does not allow for Numbers that are
±NaN. Therefore JSONKit will fail with an error if it encounters a
NSNumberthat contains such a value during serialization.
Please use the github.com JSONKit Issue Tracker to report bugs.
The author requests that you do not file a bug report with JSONKit regarding problems reported by the
clang static analyzer unless you first manually verify that it is an actual, bona-fide problem with JSONKit and, if appropriate, is not "legal" C code as defined by the C99 language specification. If the
clang static analyzer is reporting a problem with JSONKit that is not an actual, bona-fide problem and is perfectly legal code as defined by the C99 language specification, then the appropriate place to file a bug report or complaint is with the developers of the
clang static analyzer.
JSONKit is not designed to be used with the Mac OS X Garbage Collection. The behavior of JSONKit when compiled with
undefined. It is extremely unlikely that Mac OS X Garbage Collection will ever be supported.
The JSON to be parsed by JSONKit must be encoded as Unicode. In the unlikely event you end up with JSON that is not encoded as Unicode, you must first convert the JSON to Unicode, preferably as
UTF8. One way to accomplish this is with the
Internally, the low level parsing engine uses
NSDataobject as its argument and it is assumed that the raw bytes contained in the
UTF8encoded, otherwise the behavior is
It is not safe to use the same instantiated
JSONDecoderobject from multiple threads at the same time. If you wish to share a
JSONDecoderbetween threads, you are responsible for adding mutex barriers to ensure that only one thread is decoding JSON using the shared
JSONDecoderobject at a time.
Tips for speed
NS_BLOCK_ASSERTIONSpre-processor flag. JSONKit makes heavy use of
NSCParameterAssert()internally to ensure that various arguments, variables, and other state contains only legal and expected values. If an assertion check fails it causes a run time exception that will normally cause a program to terminate. These checks and assertions come with a price: they take time to execute and do not contribute to the work being performed. It is perfectly safe to enable
NS_BLOCK_ASSERTIONSas JSONKit always performs checks that are required for correct operation. The checks performed with
NSCParameterAssert()are completely optional and are meant to be used in "debug" builds where extra integrity checks are usually desired. While your mileage may vary, the author has found that adding
-O2optimization setting can generally result in an approximate 7-12% increase in performance.
JK_ENABLE_CF_TRANSFER_OWNERSHIP_CALLBACKSpre-processor flag. Please see the entry for JSONKit version 1.3 in
CHANGELOG.mdfor some important caveats and potential complications that may result in the use of this option. Enabling this option does not violate any officially documented requirements or behavior, or make use of undocumented API's. The most important caveat is you must ensure that the collection objects (i.e.,
NSDictionary) created by JSONKit are never sent a
-mutableCopymessage when this option is enabled. While your mileage may vary, the author has found that adding
JK_ENABLE_CF_TRANSFER_OWNERSHIP_CALLBACKScan generally result in an approximate 10-26% increase in performance.
Since the very low level parsing engine works exclusively with
UTF8byte streams, anything that is not already encoded as
UTF8must first be converted to
UTF8. While JSONKit provides additions to the
NSStringclass which allows you to conveniently convert JSON contained in a
NSString, this convenience does come with a price. JSONKit uses the
-UTF8Stringmethod to obtain a
UTF8encoded version of a
NSString, and while the details of how a strings performs that conversion are an internal implementation detail, it is likely that this conversion carries a cost both in terms of time and the memory needed to store the conversion result. Therefore, if speed is a priority, you should avoid using the
NSStringconvenience methods if possible.
If you are receiving JSON data from a web server, and you are able to determine that the raw bytes returned by the web server is JSON encoded as
UTF8, you should use the
-parseUTF8String:length:which immediately begins parsing the pointers bytes. In practice, every JSONKit method that converts JSON to an Objective-C object eventually calls this method to perform the conversion.
If you are using one of the various ways provided by the
NSURLfamily of classes to receive JSON results from a web server, which typically return the results in the form of a
NSDataobject, and you are able to determine that the raw bytes contained in the
NSDataare encoded as
UTF8, then you should use either the
-objectFromJSONData. If are going to be converting a lot of JSON, the better choice is to instantiate a
JSONDecoderobject once and use the same instantiated object to perform all your conversions. This has two benefits:
-objectFromJSONDatacreates an autoreleased
JSONDecoderobject to perform the one time conversion. By instantiating a
JSONDecoderobject once and using the
parseJSONData:method repeatedly, you can avoid this overhead.
- The instantiated object cache from the previous JSON conversion is reused. This can result in both better performance and a reduction in memory usage if the JSON your are converting is very similar. A typical example might be if you are converting JSON at periodic intervals that consists of real time status updates.
Note: The bytes contained in a
NSData object must be
Important: Methods will raise
parseOptionFlags is not valid.
parseUTF8String: will raise
parseJSONData: will raise
+ (id)decoder; + (id)decoderWithParseOptions:(JKParseOptionFlags)parseOptionFlags; - (id)initWithParseOptions:(JKParseOptionFlags)parseOptionFlags; - (void)clearCache; - (id)parseUTF8String:(const unsigned char *)string length:(size_t)length; - (id)parseUTF8String:(const unsigned char *)string length:(size_t)length error:(NSError **)error; - (id)parseJSONData:(NSData *)jsonData; - (id)parseJSONData:(NSData *)jsonData error:(NSError **)error;
- (id)objectFromJSONString; - (id)objectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags; - (id)objectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;
- (id)objectFromJSONData; - (id)objectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags; - (id)objectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;
||This is the default if no other other parse option flags are specified, and the option used when a convenience method does not provide an argument for explicitly specifying the parse options to use. Synonymous with
||The JSON will be parsed in strict accordance with the RFC 4627 specification.|
||Allow C style
||Allow Unicode recommended
||Normally the decoder will stop with an error at any malformed Unicode. This option allows JSON with malformed Unicode to be parsed without reporting an error. Any malformed Unicode is replaced with
Note: The bytes contained in the returned
NSData object is
NSArray and NSDictionary Interface
- (NSData *)JSONData; - (NSData *)JSONDataWithOptions:(JKSerializeOptionFlags)serializeOptions error:(NSError **)error; - (NSString *)JSONString; - (NSString *)JSONStringWithOptions:(JKSerializeOptionFlags)serializeOptions error:(NSError **)error;
||This is the default if no other other serialize option flags are specified, and the option used when a convenience method does not provide an argument for explicitly specifying the serialize options to use.|
||When JSONKit encounters Unicode characters in