{"id":20862553,"url":"https://github.com/ishotihadus/usamin","last_synced_at":"2025-08-23T09:08:11.319Z","repository":{"id":59158800,"uuid":"122703974","full_name":"Ishotihadus/usamin","owner":"Ishotihadus","description":"A fast JSON serializer / deserializer for Ruby with RapidJSON.","archived":false,"fork":false,"pushed_at":"2022-06-07T13:56:50.000Z","size":77,"stargazers_count":11,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-23T09:08:11.124Z","etag":null,"topics":["json","ruby","ruby-gem"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/usamin","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ishotihadus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-24T04:47:07.000Z","updated_at":"2023-09-13T14:15:54.000Z","dependencies_parsed_at":"2022-09-13T20:11:20.220Z","dependency_job_id":null,"html_url":"https://github.com/Ishotihadus/usamin","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Ishotihadus/usamin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ishotihadus%2Fusamin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ishotihadus%2Fusamin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ishotihadus%2Fusamin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ishotihadus%2Fusamin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ishotihadus","download_url":"https://codeload.github.com/Ishotihadus/usamin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ishotihadus%2Fusamin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746302,"owners_count":24813556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","ruby","ruby-gem"],"created_at":"2024-11-18T05:24:28.279Z","updated_at":"2025-08-23T09:08:11.285Z","avatar_url":"https://github.com/Ishotihadus.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Usamin\n\nA fast JSON serializer / deserializer for Ruby with [RapidJSON](http://rapidjson.org/).\n\nThe name of \"Usamin\" is derived from [Nana Abe](https://www.project-imas.com/wiki/Nana_Abe).\n\nI congratulate her on her election as the [7th Cinderella Girl](https://www.project-imas.com/wiki/THE_iDOLM@STER_Cinderella_Girls_General_Election#7th_Cinderella_Girl_General_Election).\n\n## Installation\n\nInstall RapidJSON beforehand. Only header files are necessary, and no need to build.\n\nNext, add this line to your application's Gemfile:\n\n```ruby\ngem 'usamin'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install usamin\n\nThe directory of RapidJSON can be explicitly specified with `--with-rapidjson-dir` option.\n\n    $ gem install usamin -- --with-rapidjson-dir=/usr/local/opt/rapidjson\n\n## Usage\n\n### Loading library\n\n```ruby\nrequire 'usamin'\n```\n\n### Parsing\n\n```ruby\njson = \u003c\u003cJSON\n[\n    {\n        \"name\": \"miku maekawa\",\n        \"age\": 15,\n        \"height\": 152,\n        \"weight\": 45,\n        \"body_size\": [85, 55, 81],\n        \"birthday\": \"2/22\",\n        \"cv\": \"natsumi takamori\"\n    },\n    {\n        \"name\": \"nana abe\",\n        \"age\": 17,\n        \"height\": 146,\n        \"weight\": 40,\n        \"body_size\": [84, 57, 84],\n        \"birthday\": \"5/15\",\n        \"cv\": \"marie miyake\"\n    }\n]\nJSON\n\nUsamin.parse(json)\n```\n\n### Lazy loading\n\n```ruby\ndata = Usamin.load(json)\n#=\u003e =\u003e [{...}, {...}]\n```\n\nHere, `data` is not an Array, but this can be handled like an Array.\n\n```ruby\ndata.size\n#=\u003e 2\n\ndata.map{|e| e['name']}\n#=\u003e [\"miku maekawa\", \"nana abe\"]\n```\n\nObjects also can be handled like Hash objects.\n\n```ruby\ndata.first['name']\n#=\u003e \"miku maekawa\"\n\ndata.first[:name]\n#=\u003e \"miku maekawa\"\n\ndata.first.keys\n#=\u003e [\"name\", \"age\", \"height\", \"weight\", \"body_size\", \"birthday\", \"cv\"]\n```\n\nThe methods `eval` and `eval_r` convert these data structures into Ruby data structures. `_r` means recursiveness.\n\n```ruby\ndata.eval\n#=\u003e [#\u003cUsamin::Hash\u003e, #\u003cUsamin::Hash\u003e]\n\ndata.first.eval_r\n#=\u003e {\"name\"=\u003e\"miku maekawa\", \"age\"=\u003e15, \"height\"=\u003e152, \"weight\"=\u003e45, \"body_size\"=\u003e[85, 55, 81], \"birthday\"=\u003e\"2/22\", \"cv\"=\u003e\"natsumi takamori\"}\n\n# same as Usamin.parse(json)\nUsamin.load(json).eval_r\n```\n\nUsamin supports pattern matching, which is introduced in Ruby 2.7.0.\n\nNote that all keys are treated as symbols in pattern matching.\n\n```ruby\ndata = Usamin.load('{\"maekawa\": \"miku\", \"osaki\": [\"tenka\", \"amana\"], \"hisakawa\": { \"hayate\": \"haa\", \"nagi\": \"naa\" }}')\n#=\u003e {\"maekawa\"=\u003e\"miku\", \"osaki\"=\u003e[...], \"hisakawa\"=\u003e{...}}\n\ncase data\nin maekawa:, hisakawa: {**sisters}\n    sisters\nend\n#=\u003e {:hayate=\u003e\"haa\", :nagi=\u003e\"naa\"}\n```\n\n#### Notes about lazy loading data\n\n- Frozen. Modification is not allowed.\n- Hash objects are based on not hash tables but arrays. An index access to an object costs O(n).\n\n### Generating\n\n```ruby\ndata = [{\"name\" =\u003e \"miku maekawa\", \"age\" =\u003e 15,\n    \"height\" =\u003e 152, \"weight\" =\u003e 45,\n    \"body_size\" =\u003e [85, 55, 81], \"birthday\" =\u003e \"2/22\",\n    \"cv\" =\u003e \"natsumi takamori\"}, {\n    \"name\" =\u003e \"nana abe\", \"age\" =\u003e 17,\n    \"height\" =\u003e 146, \"weight\" =\u003e 40,\n    \"body_size\" =\u003e [84, 57, 84], \"birthday\" =\u003e \"5/15\",\n    \"cv\" =\u003e \"marie miyake\"}]\n\nUsamin.generate(data)\n\n# pretty generation is also supported\nUsamin.pretty_generate(data)\n```\n\nOf course, UsaminValue also can be serialized.\n\n```ruby\ndata = Usamin.load(json)\nUsamin.generate(data[1])\n```\n\n### Fast parsing\n\nUsamin uses `kParseFullPrecisionFlag` by default, but this option makes parsing a little slow.\n\nYou can use `:fast` option to avoid this.\n\n```ruby\n# default\nUsamin.parse('77.777700000000795')\n#=\u003e 77.77770000000079\n\n# fast but not precise\nUsamin.parse('77.777700000000795', fast: true)\n#=\u003e 77.7777000000008\n```\n\n### Error handling\n\n```ruby\nstr = '{\"this is bad example\"'\nUsamin.parse(str)\n# Usamin::ParserError: Missing a colon after a name of object member. Offset: 22\n```\n\n### Overwrite JSON module\n\nYou can overwrite JSON module methods by loading `usamin/overwrite`.\n\n```ruby\nrequire 'usamin/overwrite'\n\n# These methods are based on Usamin\nJSON.parse(json)\nJSON.generate(data)\nJSON.pretty_generate(data)\n```\n\nThe overwritten methods are as follows:\n\n- JSON.parse -\u003e Usamin.parse\n- JSON.load / JSON.restore -\u003e Usamin.parse\n- JSON.generate -\u003e Usamin.generate / Usamin.pretty_generate\n- JSON.pretty_generate -\u003e Usamin.pretty_generate\n\nYou can automatically switch packages by following technique.\n\n```ruby\nbegin\n    require 'usamin'\n    require 'usamin/overwrite'\nrescue LoadError\n    require 'json'\nend\n```\n\n### Documentation\n\nSee: http://www.rubydoc.info/gems/usamin/\n\n## Benchmarks\n\nBased on [nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark).\n\n### Roundtrips\n\nUsamin passes all roundtrips, and the results are same as official JSON package.\n\n### Reliability of parsed data\n\nUsamin and JSON load the same data from 3 big json data in nativejson-benchmark.\n\n### Performance\n\nThe values show the elapsed time for operating 20 times. SSE4.2 was enabled in these tests.\n\nRuby 2.7.0-rc2. json 2.3.0, oj 3.10.0, usamin 7.7.10 (rapidjson 1.1.0).\n\n#### Parsing\n\n```\nnativejson-benchmark/data/canada.json\njson                     0.734855   0.005684   0.740539 (  0.743125)\noj                       1.906612   0.022766   1.929378 (  1.938912)\nusamin                   0.546606   0.016939   0.563545 (  0.565339)\nusamin (fast)            0.221778   0.013511   0.235289 (  0.235782)\nusamin (load)            0.467457   0.018688   0.486145 (  0.487849)\nusamin (load / fast)     0.166556   0.025738   0.192294 (  0.192736)\n\nnativejson-benchmark/data/citm_catalog.json\njson                     0.339319   0.004765   0.344084 (  0.345174)\noj                       0.224548   0.000997   0.225545 (  0.225837)\nusamin                   0.278662   0.003313   0.281975 (  0.285040)\nusamin (fast)            0.232262   0.001691   0.233953 (  0.234662)\nusamin (load)            0.111687   0.006829   0.118516 (  0.118821)\nusamin (load / fast)     0.072404   0.007138   0.079542 (  0.079620)\n\nnativejson-benchmark/data/twitter.json\njson                     0.208798   0.004463   0.213261 (  0.213952)\noj                       0.134336   0.000970   0.135306 (  0.135999)\nusamin                   0.174997   0.000755   0.175752 (  0.176467)\nusamin (fast)            0.176687   0.001193   0.177880 (  0.179466)\nusamin (load)            0.062983   0.004450   0.067433 (  0.067547)\nusamin (load / fast)     0.063495   0.006539   0.070034 (  0.071615)\n```\n\n#### Generating\n\n```\nnativejson-benchmark/data/canada.json\njson                     2.039965   0.015920   2.055885 (  2.065514)\noj                       2.008353   0.004610   2.012963 (  2.016850)\nusamin                   0.276563   0.015915   0.292478 (  0.294615)\nusamin (load)            0.256360   0.010180   0.266540 (  0.268350)\n\nnativejson-benchmark/data/citm_catalog.json\njson                     0.068053   0.004018   0.072071 (  0.072138)\noj                       0.060933   0.003070   0.064003 (  0.064161)\nusamin                   0.056743   0.008311   0.065054 (  0.065449)\nusamin (load)            0.037438   0.003680   0.041118 (  0.041461)\n\nnativejson-benchmark/data/twitter.json\njson                     0.040689   0.003881   0.044570 (  0.044641)\noj                       0.038957   0.003410   0.042367 (  0.042525)\nusamin                   0.037130   0.005539   0.042669 (  0.042951)\nusamin (load)            0.031568   0.003316   0.034884 (  0.035690)\n```\n\n#### Pretty Generating\n\n```\nnativejson-benchmark/data/canada.json\njson                     2.247403   0.056727   2.304130 (  2.312832)\noj                       1.560007   0.005153   1.565160 (  1.569151)\nusamin                   0.353357   0.063384   0.416741 (  0.418236)\nusamin (load)            0.341948   0.055289   0.397237 (  0.399525)\n\nnativejson-benchmark/data/citm_catalog.json\njson                     0.128840   0.008824   0.137664 (  0.139104)\noj                       0.061869   0.004010   0.065879 (  0.067000)\nusamin                   0.071300   0.005988   0.077288 (  0.077439)\nusamin (load)            0.048758   0.004353   0.053111 (  0.053186)\n\nnativejson-benchmark/data/twitter.json\njson                     0.060095   0.004639   0.064734 (  0.065314)\noj                       0.037025   0.004194   0.041219 (  0.041495)\nusamin                   0.053145   0.011938   0.065083 (  0.065184)\nusamin (load)            0.034704   0.002547   0.037251 (  0.037505)\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/Ishotihadus/usamin.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT) at the request of RapidJSON.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fishotihadus%2Fusamin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fishotihadus%2Fusamin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fishotihadus%2Fusamin/lists"}