Inherits from NSObject
Declared in SBJsonStreamParser.h

Overview

Parse a stream of JSON data.

Using this class directly you can reduce the apparent latency for each download/parse cycle of documents over a slow connection. You can start parsing and return chunks of the parsed document before the entire document is downloaded.

Using this class is also useful to parse huge documents on disk bit by bit so you don’t have to keep them all in memory.

JSON is mapped to Objective-C types in the following way:

  • null –> NSNull
  • string –> NSString
  • array –> NSMutableArray
  • object –> NSMutableDictionary
  • true –> NSNumber’s -numberWithBool:YES
  • false –> NSNumber’s -numberWithBool:NO
  • integer up to 19 digits –> NSNumber’s -numberWithLongLong:
  • all other numbers –> NSDecimalNumber

Since Objective-C doesn’t have a dedicated class for boolean values, these turns into NSNumber instances. However, since these are initialised with the -initWithBool: method they round-trip back to JSON properly. In other words, they won’t silently suddenly become 0 or 1; they’ll be represented as ‘true’ and ‘false’ again.

As an optimisation integers up to 19 digits in length (the max length for signed long long integers) turn into NSNumber instances, while complex ones turn into NSDecimalNumber instances. We can thus avoid any loss of precision as JSON allows ridiculously large numbers.

See also SBJsonStreamParserAdapter for more information.

Tasks

Properties

delegate

Delegate to receive messages

@property (unsafe_unretained) id<> delegate

Discussion

The object set here receives a series of messages as the parser breaks down the JSON stream into valid tokens.

Usually this should be an instance of SBJsonStreamParserAdapter, but you can substitute your own implementation of the SBJsonStreamParserDelegate protocol if you need to.

Declared In

SBJsonStreamParser.h

error

Holds the error after SBJsonStreamParserError was returned

@property (copy) NSString *error

Declared In

SBJsonStreamParser.h

maxDepth

The max parse depth

@property NSUInteger maxDepth

Discussion

If the input is nested deeper than this the parser will halt parsing and return an error.

Defaults to 32.

Declared In

SBJsonStreamParser.h

state

@property (nonatomic, unsafe_unretained) SBJsonStreamParserState *state

stateStack

@property (nonatomic, readonly, strong) NSMutableArray *stateStack

supportMultipleDocuments

Expect multiple documents separated by whitespace

@property BOOL supportMultipleDocuments

Discussion

Normally the parse: method returns SBJsonStreamParserComplete when it’s found a complete JSON document. Attempting to parse any more data at that point is considered an error. (“Garbage after JSON”.)

If you set this property to true the parser will never return SBJsonStreamParserComplete. Rather, once an object is completed it will expect another object to immediately follow, separated only by (optional) whitespace.

Declared In

SBJsonStreamParser.h

Instance Methods

parse:

Parse some JSON

- (SBJsonStreamParserStatus)parse:(NSData *)data

Parameters

data

An NSData object containing the next chunk of JSON

@return – SBJsonStreamParserComplete if a full document was found – SBJsonStreamParserWaitingForData if a partial document was found and more data is required to complete it – SBJsonStreamParserError if an error occured. (See the error property for details in this case.)

Discussion

The JSON is assumed to be UTF8 encoded. This can be a full JSON document, or a part of one.

Declared In

SBJsonStreamParser.h