JSONKit

JSONKit 同时由 BSD 许可和 Apache 许可 v2.0 许可。
版权所有 © 2011, John Engelhart。

一个非常高性能的 Objective-C JSON 库

更新： (2011/12/18) 下面的基准测试是在 Apples NSJSONSerialization 可用之前完成的（截至 Mac OS X 10.7 和 iOS 5）。显然的问题是：哪个更快，NSJSONSerialization 还是 JSONKit？据 这个网站 报告，JSONKit 比该快。根据记录的数字进行的“快速草稿”计算表明，JSONKit 比该快约 25% 到 40%，这是一个相当大的改进。

解析	序列化
比二进制 .plist 快 23%！	比二进制 .plist 快 549%！

• 基准测试在一个 2.66GHz Core 2 的 MacBook Pro 上进行。
• 所有 JSON 库均使用以下编译器编译：gcc-4.2 -DNS_BLOCK_ASSERTIONS -O3 -arch x86_64。
• 持续时间结果是 1000 次迭代的结果的平均值，该迭代由 getrusage 报告的用户 + 系统时间。
• 此处使用的 JSON 是来自 twitter_public_timeline.json 的 samsoffes/json-benchmarks。
• 由于 .plist 格式不支持序列化 NSNull，因此将原始 JSON 中的 null 值更改为 "null"。
• 包含压缩更改的 实验 分支。
  • JSONKit 会自动在运行时动态地将 libz.dylib 链接到 libz.dylib - 不需要在编译时手动链接。
  • 如果在缓冲区中检测到 gzip 签名标题，解析 / 反序列化会自动解压。
  • 您可以通过将 JKSerializeOptionCompress 传递给 -JSONDataWithOptions:error: 来压缩 / gzip 序列化的 JSON。

JSON对比PLIST，最终的较量 对常用的JSON库进行了基准测试，并将它们与苹果的.plist格式进行了比较。

JavaScript对象表示法，或称JSON，是一种轻量级的基于文本的序列化格式，用于结构化数据，被许多基于Web的服务和API使用。它由RFC 4627定义。

JSON提供了以下基本类型

• null
• 布尔值true和false
• 数字
• 字符串
• 数组
• 对象（也称为关联数组、键/值哈希表、映射、字典等）

这些基本类型映射到以下Objective-C框架类

JSONKit内部使用Core Foundation，并假设对于每个等效的基本类型，Core Foundation =Foundation，即 CFString ≡ NSString。

本文件中“必须”、“禁止”、“必要”、“应当”、“不应”、“应该”，“推荐”、“可以”和“可选”等关键字应按RFC 2119中的描述进行解释。

JSON到Objective-C基本类型映射的详细信息

• 关于Unicode的细节和需求，《JSON规范》略显模糊，并且它没有规定如何处理Unicode问题和错误。大多数的模糊性来源于对RFC 4627第3节“编码”的解释和范围：JSON文本应使用Unicode进行编码。作者的意见和解释是，《RFC 4627》要求JSON实现必须遵循《Unicode标准》中规定的要求，尤其是在《Unicode标准的第Conformance章节中，规定了与处理、解释和操作Unicode文本相关的要求。

  JSONKit的默认行为是严格遵守RFC 4627。作者的意见和解释是，《RFC 4627》要求JSON应以Unicode进行编码，因此不符合《Unicode标准》中定义的有效Unicode的JSON是无效的JSON。因此，JSONKit不会接受包含无效Unicode的JSON。默认的严格行为意味着没有启用JKParseOptionLooseUnicode选项。

  当启用JKParseOptionLooseUnicode选项时，JSONKit遵循Unicode 6.0标准，第三章-一致性中给出的规范和建议，特别是3.9节“Unicode编码形式”。作为一个一般规则，任何遇到的无效Unicode都将用Unicode代码点U+FFFD替换。JSONKit试图遵循推荐的使用U+FFFD的最佳实践：将无效子序列的最大部分替换为单个U+FFFD。

  以下Unicode代码点被视为无效Unicode，如果启用JKParseOptionLooseUnicode选项，将用U+FFFD替换

  U+0000.
  U+D800 到 U+DFFF， inclusively。
  U+FDD0 到 U+FDEF， inclusively。
  U+nFFFE 和 U+nFFFF，其中 n 是从 0x0 到 0x10

  代码点 U+FDD0 到 U+FDEF、U+nFFFE 和 U+nFFFF（其中 n 是从 0x0 到 0x10）被Unicode标准定义为“非字符”，不应相互交换。

  User+0000是合法的Unicode编码点，对它不做异常处理。这是因为在字符串处理代码中，这个特定的编码点被用于指定字符串的结尾。任何这样的字符串处理代码都可能在User+0000出现的地方错误地停止字符串的处理。虽然在这一点上，合理人可能会有不同的意见，但作者认为允许包含User+0000的JSON字符串带来的风险大于其带来的好处。在字符串中允许User+0000未修改地出现的一个风险是它可能会通过微妙地改变字符串的语义，从而有能力被恶意的攻击者利用。这与从Unicode文本中任意删除字符的问题相似。

  RFC 4627 在第4节“解析器”中允许这样的限制：实现可以设置字符串的长度和字符内容限制。虽然Unicode标准允许对原始JSON进行修改（用User+FFFD替换非法Unicode），但RFC 4627 对此问题没有明确说明。作者的观点和解释是，RFC 4627第3节《编码》中的JSON文本应使用Unicode编码暗示了这种修改不仅允许，而且任何严格遵循RFC 4627的JSON实现都必须预期这种修改。作者感到有必要指出，这种观点和解释可能不被他人分享，实际上可能是少数意见和解释。你应该意识到，任何对原始JSON的修改可能会细微地改变其语义，因此可能对其消费最终结果的相关内容有安全相关的含义。

  重要的是要注意，JSONKit不会删除正在解析的JSON中的字符，因为这是Unicode标准中指定的一项要求。更多信息可以在Unicode安全FAQ和Unicode技术报告第36号——Unicode安全考虑中找到，特别是非可视化安全问题部分。

• JSON规范并没有指定JSON字符串值的详细要求，除了这些字符串必须由Unicode编码点组成，也没有指定如何处理错误。虽然JSONKit会尽力（在上述有关Unicode的合理警告范围内）准确地保留解析的JSON字符串，但它无法保证NSString将保留原始JSON字符串的准确Unicode语义。

  JSONKit在对解析后的JSON字符串进行操作时不会进行任何Unicode规范化，但不能保证使用NSString类来实例化JSON字符串使用功能时，不会对解析后使用的JSON字符串进行Unicode规范化。该NSString类可能会添加额外的限制或者以某种方式将JSON字符串转换，使得JSON字符串与实例化的NSString对象不是一一对应的。换句话说，JSONKit不能保证当你将一个JSON字符串转换成一个NSString对象然后再转换回JSON字符串，这两个JSON字符串将完全相同，尽管在实际情况中它们确实如此。"完全相同"在这种情况下意味着位对位相同。JSONKit甚至不能保证两个JSON字符串将是Unicode等效的，尽管在实际情况中它们将是，并且这是两个来回转换的JSON字符串不再位对位相同最可能的原因。

• JSONKit将true和false映射到CFBoolean值kCFBooleanTrue和kCFBooleanFalse。从概念上讲，可以将CFBoolean值视为并作为NSNumber类的对象来处理。使用CFBoolean的好处是，true和false的JSON值可以在不进行转换或提升到值分别为0或1的NSNumber的情况下进行循环序列化和反序列化。

• JSON规范未指定JSON数值的细节或要求，也未指定应如何处理转换错误。通常，JSONKit不会接受含有它无法无误或无精度损失转换的JSON数值的JSON。

  对于非浮点数（即不包括.或e|E的JSON数值），无论目标架构是32位还是64位，JSONKit都使用内部64位C原始类型。对于无符号值（即不以-开始的值），这允许值为264-1，而对于负值，最多可达-263。作为一个特例，JSON数值-0被视为浮点数，因为底层浮点原始类型能够表示负零，而底层的补码非浮点原始类型不能。超出这些限制的包含数值的JSON将失败解析，可选择返回一个NSError对象。使用strtoll()和strtoull()函数进行这些转换。

  C语言中的double基本类型，或IEEE 754双精度64位浮点格式，用于表示浮点JSON数值。包含无法表示为double数值的浮点数（例如，由于溢出或下溢）的JSON将解析失败，并且可以选择性地返回一个NSError对象。使用strtod()函数进行转换。请注意，JSON标准不允许无限大或NaN（不是数值）。浮点值的转换和处理并不简单。不幸的是，RFC 4627对此类细节处理保持沉默。不应该依赖或期望被循环转换的浮点值将具有相同的文本表示或甚至相等的比较。即使JSONKit被用作解析器和JSON的创建者，这也同样如此，更不用说在不同系统和实现之间传输JSON了。

• 对于JSON对象（或JSONKit术语中的NSDictionary），RFC 4627规定“对象内名称应唯一”（注意：name在JSONKit术语中是key）。目前，对于包含对象中不唯一名称的JSON，JSONKit的行为是未定义的。然而，JSONKit目前试图遵循“选择最后解析的键/值对”政策。这项行为尚未最终确定，不应依赖。

  之前关于JSON字符串的限制对于JSON对象很重要，因为JSON字符串用作key。JSON规范没有指定用于JSON对象中的keys的JSON字符串的细节或要求，特别是两个keys比较相等的含义。不幸的是，由于RFC 4627声明“JSON文本必须使用Unicode编码”，这意味着必须使用Unicode标准来解释JSON，并且Unicode标准允许使用不同Unicode代码点编码的字符串“比较相等”。JSONKit专门使用NSString来管理解析后的JSON字符串。因为NSString使用Unicode作为其基础，因此存在将原始JSON字符串中包含的Unicode代码点微弱且默默地转换为Unicode等效字符串的可能性。因此，对于在JSON对象中用作keys的JSON字符串，如果这些字符串在Unicode等效但不二进制等效的情况下，JSONKit的行为是未定义的。

  另请参阅
      W3C - 字符串身份匹配和字符串索引需求

Objective-C To JSON基本映射细节

• 在序列化时，顶层容器以及所有子元素在枚举过程中必须保持严格的不变性。这个属性用于进行某些优化，例如，如果一个特定的对象已经被序列化，可以重用之前序列化的UTF8字符串的结果（即，可以直接复制先前序列化的UTF8字符串，而不是再次执行所有序列化工作）。虽然这也许只对那些使用或继承自JSONKit序列化类的运行时或自定义类进行极其不同寻常操作的人感兴趣（即，每次请求其值进行序列化时，值都会发生变化的自定义对象），但它也涵盖了在枚举过程中任何要序列化的对象被修改的情况（即，由另一个线程进行修改）。JSONKit请求对象值次数是不确定的，最少一次，最多可达它在序列化JSON中出现的次数——因此，对象每次出现在序列化输出中时，都不能依赖于接收到请求其值的消息。如果违反这些要求，行为是未定义的。

• 要序列化的对象必须是循环的。如果要序列化的对象包含循环引用，行为是未定义的。例如，…将导致未定义行为。

  [arrayOne addObject:arrayTwo];
  [arrayTwo addObject:arrayOne];
  id json = [arrayOne JSONString];

  …将导致未定义行为。

• NSString对象的内部内容被编码为UTF8并添加到序列化的JSON中。JSONKit假设NSString生产格式良好的UTF8 Unicode，并且不进行额外的转换验证。当启用JKSerializeOptionEscapeUnicode时，JSONKit将使用\uXXXX将作为单个UTF16代码单元编码的Unicode代码点编码，并将需要UTF16代理对的Unicode代码点编码为\uhigh\ulow。虽然JSONKit尽力准确序列化NSString对象的内部内容，但要符合RFC 4627的要求，NSString类使用Unicode标准来表示字符串。你应该知道，Unicode标准按照以下方式定义字符串等价性：比较相等的字符串不必是位对位的相同。因此，可能存在NSString可能以使其成为Unicode等价的方式进行字符串的修改，但与原始字符串不是位对位的相同的可能性。

• NSDictionary类允许使用任何对象作为key，而JSON只允许使用字符串作为keys。因此，如果JSONKit在序列化过程中遇到包含非NSString对象键的NSDictionary，则会出错。更具体地说，键必须返回YES，当发送-isKindOfClass:

• 如果JSONKit在序列化过程中遇到非NSNull、NSNumber、NSString、NSArray或NSDictionary类的对象时，将会报错。更具体地说，如果遇到的对象中，上述所有类的-isKindOfClass:方法都返回NO，JSONKit将报错。

• JSON不允许Numbers为±Infinity或±NaN。因此，如果JSONKit在序列化过程中遇到包含这些值的NSNumber对象，将报错。

• 使用[NSNumber numberWithBool:YES]和[NSNumber numberWithBool:NO]创建的对象将分别映射到JSON值true和false。具体来说，一个对象必须与kCFBooleanTrue或kCFBooleanFalse有指针相等性（即 if((id)object == (id)kCFBooleanTrue) ），才能映射到JSON值true和false。

• 不是布尔值的NSNumber对象将被发送到-objCType来确定其表示的C原始数据类型。那些响应类型为cislq集合的对象被视为long long类型，响应类型为CISLQB集合的对象被视为unsigned long long类型，响应类型为fd集合的对象被视为double类型。响应类型不在所提及类型集合中的NSNumber对象将导致JSONKit报错。

  更具体地说，使用CFNumberGetValue(object, kCFNumberLongLongType, &longLong)来检索有符号和无符号的整数值，并使用-objCType方法报告的类型来确定结果是带符号的还是无符号的。对于浮点值，使用CFNumberGetValue，并使用kCFNumberDoubleType作为类型参数来检索值。

  浮点数使用printf格式转换说明符%.17g转换为它们的十进制表示形式。理论上，这允许表示至多等效于float或IEEE 754 单精度 32 位浮点的精度。这意味着，在实用层面，double值转换为float值时会有精度损失。RFC 4627标准对此如何处理浮点数没有明确规定，作者发现现实世界中的JSON实现在这方面差异很大。此外，%g格式转换说明符可能会将能够精确表示为整数的浮点值转换为不包含.或e的文本表示形式——基本上是将浮点值无声地提升为整数值（例如，5.0变为5）。由于这些问题以及许多其他关于浮点值转换和处理问题，您不应期望或依赖于浮点值保持其全部精度，或者当进行反向转换时，进行比较。

+ (id)decoder;
+ (id)decoderWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)initWithParseOptions:(JKParseOptionFlags)parseOptionFlags;

- (void)clearCache;

- (id)objectWithUTF8String:(const unsigned char *)string length:(size_t)length;
- (id)objectWithUTF8String:(const unsigned char *)string length:(size_t)length error:(NSError **)error;
- (id)mutableObjectWithUTF8String:(const unsigned char *)string length:(size_t)length;
- (id)mutableObjectWithUTF8String:(const unsigned char *)string length:(size_t)length error:(NSError **)error;

- (id)objectWithData:(NSData *)jsonData;
- (id)objectWithData:(NSData *)jsonData error:(NSError **)error;
- (id)mutableObjectWithData:(NSData *)jsonData;
- (id)mutableObjectWithData:(NSData *)jsonData error:(NSError **)error;

- (id)objectFromJSONString;
- (id)objectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)objectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;
- (id)mutableObjectFromJSONString;
- (id)mutableObjectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)mutableObjectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;

- (id)objectFromJSONData;
- (id)objectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)objectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;
- (id)mutableObjectFromJSONData;
- (id)mutableObjectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)mutableObjectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;

- (NSData *)JSONData;
- (NSData *)JSONDataWithOptions:(JKSerializeOptionFlags)serializeOptions error:(NSError **)error;
- (NSString *)JSONString;
- (NSString *)JSONStringWithOptions:(JKSerializeOptionFlags)serializeOptions error:(NSError **)error;

- (NSData *)JSONData;
- (NSData *)JSONDataWithOptions:(JKSerializeOptionFlags)serializeOptions includeQuotes:(BOOL)includeQuotes error:(NSError **)error;
- (NSString *)JSONString;
- (NSString *)JSONStringWithOptions:(JKSerializeOptionFlags)serializeOptions includeQuotes:(BOOL)includeQuotes error:(NSError **)error;