# RapidJSON

(Maybe) Ruby's fastest JSON library! Built using the [RapidJSON C++ library](https://rapidjson.org/)

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'rapidjson'
```

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install rapidjson

## Usage

``` ruby
RapidJSON.parse <<JSON
{
  "foo":"bar"
}
JSON
# => {"foo" => "bar"}
```

``` ruby
RapidJSON.encode(json_string)
# => '{"foo":"bar"}'
```

``` ruby
RapidJSON.pretty_encode(json_string)
# =>
# {
#    "foo": "bar"
# }
```

## Performance

Your current JSON parser/encoder is probably fine.

Unless there's good reason, it's probably best sticking with the standard `json` gem, which ships with Ruby. It become much faster in version 2.3, so try it again if you haven't recently!

However this library has a few performance advantages:

* JSON parsing
  * Performance is achieved mostly through using RapidJSON one of the fastest open source JSON parsing libraries. It supports SIMD (SSE2, SSE4.2, NEON), avoids allocated memory, and has been honed to be if not the fastest library (that honour likely going to simdjson) the library to beat for JSON performance.
* Object allocation
  * Wherever possible we avoid allocating objects. When generating JSON, RapidJSON will write the emitted JSON directly into the buffer of a Ruby string. (This is an optimization most Ruby JSON libraries will have)
  * When parsing JSON we parse directly form the source string with a single copy
  * When building a Hash for a JSON object, we use an fstrings (dedup'd and frozen strings) as the key
  * Whenever possible we build Ruby objects from C types (int, char \*, double) rather than constructing intermediate Ruby string objects.

Many of these optimization can be found in all popular Ruby JSON libraries

```
== Encoding canada.json (2090234 bytes)
                yajl     13.957  (± 0.0%) i/s -     70.000  in   5.015358s
                json     13.912  (± 0.0%) i/s -     70.000  in   5.032247s
                  oj     20.821  (± 0.0%) i/s -    106.000  in   5.090981s
           rapidjson     84.110  (± 2.4%) i/s -    424.000  in   5.042792s
```

```
== Parsing canada.json (2251051 bytes)
                yajl     35.510  (± 2.8%) i/s -    180.000  in   5.070803s
                json     22.105  (± 0.0%) i/s -    112.000  in   5.067063s
                  oj     15.163  (± 6.6%) i/s -     76.000  in   5.042864s
     fast_jsonparser     10.791  (± 0.0%) i/s -     54.000  in   5.004290s
           rapidjson    148.263  (± 2.0%) i/s -    742.000  in   5.006370s
```
Notes: oj seems unusually bad at this test, and is usually faster than yajl and
json, and comparable to rapidjson.
`fast_jsonparser` has been slow since Ruby 3.0, likely a bug, if fixed I'd
expect it to be the fasest JSON parser.

Other libraries may include modes to avoid constructing all objects. Currently
RapidJSON only focuses on the patterns and APIs users are likely to actually
use.

## Why another JSON library

I spent a week working on YAJL/yajl-ruby, and though I really liked the library, it hasn't kept up with the performance of the modern JSON libraries, specifically simdjson (C++), serde-json (Rust), and RapidJSON (C++). I was interested in how those libraries would integrate into Ruby. Of these, RapidJSON was the simplest fit for a Ruby extension. It's in C++ (clean Rust/Ruby bindings is unfortunately a work in progress), fast, uses SIMD instructions, supports encoding and decoding, and has a nice API to work with.

However, if you're happy with your current Ruby JSON library (including `json`) you should keep using it. They're all very good.

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jhawthorn/rapidjson. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jhawthorn/rapidjson/blob/main/CODE_OF_CONDUCT.md).

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Code of Conduct

Everyone interacting in the Rapidjson project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jhawthorn/rapidjson/blob/main/CODE_OF_CONDUCT.md).