Introduction to jsonlite
- What is jsonlite and JsonLite ObjC?
- Principles
- Getting Started with jsonlite
- Getting Started with JsonLite ObjC
- Roadmap
- Code Coverage
- License
What is jsonlite and JsonLite ObjC
jsonlite is JSON tokenizer. It's lightweight C library that can be used for low-level JSON processing or parser development.
JsonLite ObjC is JSON parser base on jsonlite. It's the fastest and flexible JSON parser for Objective-C.
Principles
- Lightweight is more important than syntax sugar
- Reliability & quality is most important than everything else
- Do that which is necessary
- Divide and Rule
Getting Started with jsonlite
Validator
Current example shows how quick and easy validate JSON.
What's New?
- JSON - JavaScript Object Notation
- JSON_DEPTH - maximal depth of JSON nested expressions
- jsonlite_parser_estimate_size - estimates memory usage (in bytes). This value depends on CPU architecture.
- jsonlite_parser_init - initialize parser
- jsonlite_parser_tokenize - process JSON payload
- jsonlite_parser_release - free all resources
#include <assert.h>
#include "jsonlite.h"
int main(int argc, const char * argv[]) {
const int JSON_DEPTH = 4; // Limitation of JSON depth
char json[] = "[-1, 0, 1, true, false, null]"; // JSON to validate
size_t mem_used = jsonlite_parser_estimate_size(JSON_DEPTH); // Estimate memory usage
printf("jsonlite will use %zd bytes of RAM for JSON validation", mem_used);
jsonlite_parser p = jsonlite_parser_init(JSON_DEPTH); // Init parser with specified depth
jsonlite_result result = jsonlite_parser_tokenize(p, json, sizeof(json)); // Check JSON
assert(result == jsonlite_result_ok); // Check result
jsonlite_parser_release(p); // Free resources
return 0;
}
Summer
Next example shows how to work with number tokens. jsonlite does not convert any number by itself. That's why you may use strtol or even arbitrary-precision arithmetic.
What's New?
- jsonlite_parser_callbacks - contains addresses of callback functions
- jsonlite_default_callbacks - contains default callback functions (they do nothing).
- jsonlite_parser_set_callback - sets new callback functions
- number_callback - callback function. It converts number token to C type and performs summing.
#include <stdlib.h>
#include <assert.h>
#include "jsonlite.h"
#include "jsonlite_token.h"
long long sum = 0;
static void number_callback(jsonlite_callback_context *ctx, jsonlite_token *token) {
char *end = NULL;
sum += strtoll((const char *)token->start, &end, 10);
assert(end == (char *)token->end);
}
int main(int argc, const char * argv[]) {
const int JSON_DEPTH = 4; // Limitation of JSON depth
char json[] = "[-13453453, 0, 1, 123, 45345, -94534555]"; // Numbers to sum
jsonlite_parser_callbacks cbs = jsonlite_default_callbacks; // Init callbacks with default values
cbs.number_found = &number_callback; // Assign new callback function
jsonlite_parser p = jsonlite_parser_init(JSON_DEPTH); // Init parser with specified depth
jsonlite_parser_set_callback(p, &cbs); // Set callback function(s)
jsonlite_parser_tokenize(p, json, sizeof(json)); // Tokenize/find numbers
jsonlite_parser_release(p); // Free resources
printf("Total sum: %lld", sum);
return 0;
}
Beautifier
The example shows how to quick make JSON pretty. The example is bigger than previous, please, see it here.
Getting Started with JsonLite ObjC
Parse to Cocoa Collection(s)
Current example shows how to quick tokenize and accumulate results to Cocoa collection.
What's New?
- dataUsingEncoding - buildin Cocoa method. It converts NSString to NSData object.
- JsonLiteAccumulator - convert JSON tokens to Cocoa classes and accumulate results to NSArray or NSDictionary.
- objectFromData - class method of JsonLiteAccumulator, it is helper method - encapsulation of full initialization (see next example).
#import <Foundation/Foundation.h>
#import "JsonLiteAccumulator.h"
int main(int argc, const char * argv[]) {
@autoreleasepool {
NSString *json = @"[\"hello\", null, 1234567890]";
NSData *data = [json dataUsingEncoding:NSUTF8StringEncoding];
NSArray *result = [JsonLiteAccumulator objectFromData:data withMaxDepth:4];
NSLog(@"%@", result);
}
return 0;
}
Chunks
A [chunk](http://en.wikipedia.org/wiki/Chunk_(information) is a fragment of JSON. JsonLite ObjC allows you to process a chunk while other parts of JSON are delivering by network. 'Chunk Oriented' processing style allow developer to improve memory usage and increase program performance, also its' provide ability to work with huge JSON data.
Also this example shows full parsing flow: create parser -> assign delegate -> parse data.
What's New?
- JsonLiteParser - sequential access JSON parser.
- JsonLiteAccumulator - implements JsonLiteParserDelegate protocol. Performs token conversion and accumulates results to Cocoa collections.
#import <Foundation/Foundation.h>
#import "JsonLiteParser.h"
#import "JsonLiteAccumulator.h"
char chuck1[] = "[\"hello\", nu";
char chuck2[] = "ll, 1234567890]";
int main(int argc, const char * argv[]) {
@autoreleasepool {
JsonLiteParser *parser = [JsonLiteParser parserWithDepth:4];
JsonLiteAccumulator *acc = [JsonLiteAccumulator accumulatorWithDepth:4];
parser.delegate = acc;
NSData *data = [[NSData alloc] initWithBytes:chuck1
length:sizeof(chuck1) - 1];
[parser parse:data];
[data release];
data = [[NSData alloc] initWithBytes:chuck2
length:sizeof(chuck2) - 1];
[parser parse:data];
[data release];
NSLog(@"Full object - %@", [acc object]);
}
return 0;
}
JSON & Model
It's really hard to deal with Cocoa collections. The best way is to bind JSON to some model.
What's New?
- Model - declaration of application object.
- JsonLiteDeserializer - implements JsonLiteParserDelegate protocol. Performs token conversion and binds results to specified model.
- JsonLiteSerializer - serialize Objective-C model or collection to JSON.
#import <Foundation/Foundation.h>
#import "JsonLiteParser.h"
#import "JsonLiteDeserializer.h"
#import "JsonLiteSerializer.h"
@interface Model : NSObject
@property (nonatomic, copy) NSString *string;
@property (nonatomic, copy) NSNumber *number;
@property (nonatomic, copy) NSArray *array;
@end
@implementation Model
- (void)dealloc {
self.string = nil;
self.number = nil;
self.array = nil;
[super dealloc];
}
@end
int main(int argc, const char * argv[]) {
@autoreleasepool {
NSString *json = @"{\"string\": \"hello\", \"number\" : 100, \"array\": [1, 2, 3]}";
NSData *data = [json dataUsingEncoding:NSUTF8StringEncoding];
JsonLiteParser *parser = [JsonLiteParser parserWithDepth:8];
JsonLiteDeserializer *des = [JsonLiteDeserializer deserializerWithRootClass:[Model class]];
parser.delegate = des;
[parser parse:data];
Model *model = [des object];
NSLog(@"String - %@", model.string);
NSLog(@"Number - %@", model.number);
NSLog(@"Array - %@", model.array);
model.string = @"Hello World";
model.number = [NSNumber numberWithInt:256];
model.array = [NSArray arrayWithObjects:@"Test", [NSNull null], nil];
JsonLiteSerializer *serializer = [JsonLiteSerializer serializer];
data = [serializer serializeObject:model];
json = [[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] autorelease];
NSLog(@"%@", json);
}
return 0;
}
Decimal Number
Only JsonLite ObjC can work with NSDecimalNumber object and you can forget about workaround with strings. It's very important feature for finance project.
What's New?
- NSDecimalNumber - class for base-10 arithmetic.
- JsonLiteDecimal - converter used by JsonLiteDeserializer to convert number token to NSDecimalNumber.
#import <Foundation/Foundation.h>
#import <Foundation/Foundation.h>
#import "JsonLiteParser.h"
#import "JsonLiteDeserializer.h"
#import "JsonLiteConverters.h"
@interface Model : NSObject
@property (nonatomic, copy) NSString *string;
@property (nonatomic, copy) NSDecimalNumber *number;
@end
@implementation Model
- (void)dealloc {
self.string = nil;
self.number = nil;
[super dealloc];
}
@end
int main(int argc, const char * argv[]) {
@autoreleasepool {
NSString *json = @"{\"string\": \"This is Decimal!\", \"number\" : 95673465936453649563978.99 }";
NSData *data = [json dataUsingEncoding:NSUTF8StringEncoding];
JsonLiteParser *parser = [JsonLiteParser parserWithDepth:8];
JsonLiteDeserializer *des = [JsonLiteDeserializer deserializerWithRootClass:[Model class]];
des.converter = [[[JsonLiteDecimal alloc] init] autorelease];
parser.delegate = des;
[parser parse:data];
Model *model = [des object];
NSLog(@"String - %@", model.string);
NSLog(@"Number - %@", model.number);
}
return 0;
}
Code Coverage
- 100% Function coverage
- 100% Statement coverage
- 100% Branch coverage.
See Code coverage configuration
License
jsonlite and JsonLite ObjC are licensed under the Apache License, Version 2.0
Copyright 2012-2013, Andrii Mamchur