Usamin
A fast JSON serializer / deserializer for Ruby with RapidJSON.
The name of "Usamin" is derived from Nana Abe.
I congratulate her on her election as the 7th Cinderella Girl.
Installation
Install RapidJSON beforehand. Only header files are necessary, and no need to build.
Next, add this line to your application's Gemfile:
gem 'usamin'And then execute:
$ bundle
Or install it yourself as:
$ gem install usamin
The directory of RapidJSON can be explicitly specified with --with-rapidjson-dir option.
$ gem install usamin -- --with-rapidjson-dir=/usr/local/opt/rapidjson
Usage
Loading library
require 'usamin'Parsing
json = <<JSON
[
{
"name": "miku maekawa",
"age": 15,
"height": 152,
"weight": 45,
"body_size": [85, 55, 81],
"birthday": "2/22",
"cv": "natsumi takamori"
},
{
"name": "nana abe",
"age": 17,
"height": 146,
"weight": 40,
"body_size": [84, 57, 84],
"birthday": "5/15",
"cv": "marie miyake"
}
]
JSON
Usamin.parse(json)Lazy loading
data = Usamin.load(json)
#=> => [{...}, {...}]Here, data is not an Array, but this can be handled like an Array.
data.size
#=> 2
data.map{|e| e['name']}
#=> ["miku maekawa", "nana abe"]Objects also can be handled like Hash objects.
data.first['name']
#=> "miku maekawa"
data.first[:name]
#=> "miku maekawa"
data.first.keys
#=> ["name", "age", "height", "weight", "body_size", "birthday", "cv"]The methods eval and eval_r convert these data structures into Ruby data structures. _r means recursiveness.
data.eval
#=> [#<Usamin::Hash>, #<Usamin::Hash>]
data.first.eval_r
#=> {"name"=>"miku maekawa", "age"=>15, "height"=>152, "weight"=>45, "body_size"=>[85, 55, 81], "birthday"=>"2/22", "cv"=>"natsumi takamori"}
# same as Usamin.parse(json)
Usamin.load(json).eval_rUsamin supports pattern matching, which is introduced in Ruby 2.7.0.
Note that all keys are treated as symbols in pattern matching.
data = Usamin.load('{"maekawa": "miku", "osaki": ["tenka", "amana"], "hisakawa": { "hayate": "haa", "nagi": "naa" }}')
#=> {"maekawa"=>"miku", "osaki"=>[...], "hisakawa"=>{...}}
case data
in maekawa:, hisakawa: {**sisters}
sisters
end
#=> {:hayate=>"haa", :nagi=>"naa"}Notes about lazy loading data
- Frozen. Modification is not allowed.
- Hash objects are based on not hash tables but arrays. An index access to an object costs O(n).
Generating
data = [{"name" => "miku maekawa", "age" => 15,
"height" => 152, "weight" => 45,
"body_size" => [85, 55, 81], "birthday" => "2/22",
"cv" => "natsumi takamori"}, {
"name" => "nana abe", "age" => 17,
"height" => 146, "weight" => 40,
"body_size" => [84, 57, 84], "birthday" => "5/15",
"cv" => "marie miyake"}]
Usamin.generate(data)
# pretty generation is also supported
Usamin.pretty_generate(data)Of course, UsaminValue also can be serialized.
data = Usamin.load(json)
Usamin.generate(data[1])Fast parsing
Usamin uses kParseFullPrecisionFlag by default, but this option makes parsing a little slow.
You can use :fast option to avoid this.
# default
Usamin.parse('77.777700000000795')
#=> 77.77770000000079
# fast but not precise
Usamin.parse('77.777700000000795', fast: true)
#=> 77.7777000000008Error handling
str = '{"this is bad example"'
Usamin.parse(str)
# Usamin::ParserError: Missing a colon after a name of object member. Offset: 22Overwrite JSON module
You can overwrite JSON module methods by loading usamin/overwrite.
require 'usamin/overwrite'
# These methods are based on Usamin
JSON.parse(json)
JSON.generate(data)
JSON.pretty_generate(data)The overwritten methods are as follows:
- JSON.parse -> Usamin.parse
- JSON.load / JSON.restore -> Usamin.parse
- JSON.generate -> Usamin.generate / Usamin.pretty_generate
- JSON.pretty_generate -> Usamin.pretty_generate
You can automatically switch packages by following technique.
begin
require 'usamin'
require 'usamin/overwrite'
rescue LoadError
require 'json'
endDocumentation
See: http://www.rubydoc.info/gems/usamin/
Benchmarks
Based on nativejson-benchmark.
Roundtrips
Usamin passes all roundtrips, and the results are same as official JSON package.
Reliability of parsed data
Usamin and JSON load the same data from 3 big json data in nativejson-benchmark.
Performance
The values show the elapsed time for operating 20 times. SSE4.2 was enabled in these tests.
Ruby 2.7.0-rc2. json 2.3.0, oj 3.10.0, usamin 7.7.10 (rapidjson 1.1.0).
Parsing
nativejson-benchmark/data/canada.json
json 0.734855 0.005684 0.740539 ( 0.743125)
oj 1.906612 0.022766 1.929378 ( 1.938912)
usamin 0.546606 0.016939 0.563545 ( 0.565339)
usamin (fast) 0.221778 0.013511 0.235289 ( 0.235782)
usamin (load) 0.467457 0.018688 0.486145 ( 0.487849)
usamin (load / fast) 0.166556 0.025738 0.192294 ( 0.192736)
nativejson-benchmark/data/citm_catalog.json
json 0.339319 0.004765 0.344084 ( 0.345174)
oj 0.224548 0.000997 0.225545 ( 0.225837)
usamin 0.278662 0.003313 0.281975 ( 0.285040)
usamin (fast) 0.232262 0.001691 0.233953 ( 0.234662)
usamin (load) 0.111687 0.006829 0.118516 ( 0.118821)
usamin (load / fast) 0.072404 0.007138 0.079542 ( 0.079620)
nativejson-benchmark/data/twitter.json
json 0.208798 0.004463 0.213261 ( 0.213952)
oj 0.134336 0.000970 0.135306 ( 0.135999)
usamin 0.174997 0.000755 0.175752 ( 0.176467)
usamin (fast) 0.176687 0.001193 0.177880 ( 0.179466)
usamin (load) 0.062983 0.004450 0.067433 ( 0.067547)
usamin (load / fast) 0.063495 0.006539 0.070034 ( 0.071615)
Generating
nativejson-benchmark/data/canada.json
json 2.039965 0.015920 2.055885 ( 2.065514)
oj 2.008353 0.004610 2.012963 ( 2.016850)
usamin 0.276563 0.015915 0.292478 ( 0.294615)
usamin (load) 0.256360 0.010180 0.266540 ( 0.268350)
nativejson-benchmark/data/citm_catalog.json
json 0.068053 0.004018 0.072071 ( 0.072138)
oj 0.060933 0.003070 0.064003 ( 0.064161)
usamin 0.056743 0.008311 0.065054 ( 0.065449)
usamin (load) 0.037438 0.003680 0.041118 ( 0.041461)
nativejson-benchmark/data/twitter.json
json 0.040689 0.003881 0.044570 ( 0.044641)
oj 0.038957 0.003410 0.042367 ( 0.042525)
usamin 0.037130 0.005539 0.042669 ( 0.042951)
usamin (load) 0.031568 0.003316 0.034884 ( 0.035690)
Pretty Generating
nativejson-benchmark/data/canada.json
json 2.247403 0.056727 2.304130 ( 2.312832)
oj 1.560007 0.005153 1.565160 ( 1.569151)
usamin 0.353357 0.063384 0.416741 ( 0.418236)
usamin (load) 0.341948 0.055289 0.397237 ( 0.399525)
nativejson-benchmark/data/citm_catalog.json
json 0.128840 0.008824 0.137664 ( 0.139104)
oj 0.061869 0.004010 0.065879 ( 0.067000)
usamin 0.071300 0.005988 0.077288 ( 0.077439)
usamin (load) 0.048758 0.004353 0.053111 ( 0.053186)
nativejson-benchmark/data/twitter.json
json 0.060095 0.004639 0.064734 ( 0.065314)
oj 0.037025 0.004194 0.041219 ( 0.041495)
usamin 0.053145 0.011938 0.065083 ( 0.065184)
usamin (load) 0.034704 0.002547 0.037251 ( 0.037505)
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Ishotihadus/usamin.
License
The gem is available as open source under the terms of the MIT License at the request of RapidJSON.