{"id":16783115,"url":"https://github.com/grahamboree/voorhees","last_synced_at":"2025-03-22T00:31:56.734Z","repository":{"id":36162941,"uuid":"40467017","full_name":"grahamboree/Voorhees","owner":"grahamboree","description":"A small C# JSON library optimized for speed.","archived":false,"fork":false,"pushed_at":"2024-02-04T23:05:18.000Z","size":32964,"stargazers_count":22,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T06:35:49.185Z","etag":null,"topics":["csharp","csharp-library","json","unity","unity3d"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"pambot/ozymandias","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grahamboree.png","metadata":{"files":{"readme":"Readme.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-10T06:34:49.000Z","updated_at":"2024-09-22T22:32:29.000Z","dependencies_parsed_at":"2024-10-28T12:13:31.123Z","dependency_job_id":null,"html_url":"https://github.com/grahamboree/Voorhees","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahamboree%2FVoorhees","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahamboree%2FVoorhees/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahamboree%2FVoorhees/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahamboree%2FVoorhees/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grahamboree","download_url":"https://codeload.github.com/grahamboree/Voorhees/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244890102,"owners_count":20527030,"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","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":["csharp","csharp-library","json","unity","unity3d"],"created_at":"2024-10-13T07:48:59.779Z","updated_at":"2025-03-22T00:31:52.324Z","avatar_url":"https://github.com/grahamboree.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔪 Voorhees\n\n\u003cp align=\"center\"\u003e\n\t\u003ci\u003eA terrifyingly fast C# JSON framework with a focus CPU performance and minimizing allocations\u003c/i\u003e\t\n\u003c/p\u003e\n\n[![Build \u0026 Test](https://github.com/grahamboree/Voorhees/actions/workflows/build.yaml/badge.svg)](https://github.com/grahamboree/Voorhees/actions/workflows/build.yaml)[![Coverage Status](https://coveralls.io/repos/github/grahamboree/Voorhees/badge.svg?branch=main)](https://coveralls.io/github/grahamboree/Voorhees?branch=main)[![CodeFactor](https://www.codefactor.io/repository/github/grahamboree/voorhees/badge)](https://www.codefactor.io/repository/github/grahamboree/voorhees)\n\n## Features\n\n* Reads and writes json data into a structured object graph with minimal allocations.\n* High level API is one line of code to read or write JSON data.\n* Low level API reads from and writes to text streams. Seamlessly integrates with cryptographic streams and can read and write data directly to and from sockets, files, etc.\n* Maps complex objects to and from json values automatically without needing any annotations, markup, or codegen.\n* Fully supports reading and writing multi-dimensional arrays, unlike other popular C# JSON libraries.\n* Correctly serializes polymorphic type references.\n* Optional value annotiation instructs Voorhees to ignore specific parameters and fields when serializing objects.\n* Supports completely custom serializers/deserializers for arbitray types for full customizability of the JSON reading and writing process.\n* Generates either pretty-printed JSON or condensed JSON.\n\n---\n\n## Reading Json Data\n\nYou can read arbitrary json data into a `JsonValue` structure using the `JsonMapper.FromJson` method.  This method operates on `TextReader` streams, allowing for reading from strings, files, network messages, and more with a shared inteface.\n\n```C#\nusing Voorhees;\n\n// Load a json string into a JsonValue object graph.\nJsonValue jsonValue = JsonMapper.FromJson\u003cJsonValue\u003e(\"{ \\\"someIntValue\\\": 3}\");\n\nConsole.WriteLine(jsonValue.Type); // JsonValueType.Object\nConsole.WriteLine(jsonValue[\"someIntValue\"].Type); // JsonValueType.Int\nConsole.WriteLine((int)jsonValue[\"someIntValue\"]); // 3\n```\n\nYou can also map json data to a matching C# structure using the generic version of `JsonMapper.FromJson\u003cT\u003e`.  This is most useful for reading in structured data into existing corresponding C# types.\n\n```C#\nusing Voorhees;\n\nstruct ExampleStructure {\n\tpublic int someIntValue;\n}\n\nTextReader json = new StringReader(\"{ \\\"someIntValue\\\": 3}\");\nExampleStructure mappedValue = JsonMapper.FromJson\u003cExampleStructure\u003e(json);\n\nConsole.WriteLine(mappedValue.someIntValue); // 3\n```\n\n`JsonMapper` supports loading values into built-in collection types like `Dictionary\u003cT, U\u003e`, `List\u003cT\u003e`, arrays, and more:\n\n```C#\nstring dictJson = \"{\\\"one\\\": 1, \\\"two\\\": 2}\";\nDictionary\u003cstring, int\u003e numberNamesToInts = JsonMapper.FromJson\u003cDictionary\u003cstring, int\u003e\u003e(dictJson);\nConsole.WriteLine(numberNamesToInts.Count); // 2\nConsole.WriteLine(numberNamesToInts[\"one\"]); // 1\nConsole.WriteLine(numberNamesToInts[\"two\"]); // 2\n\nList\u003cint\u003e mappedList = JsonMapper.FromJson\u003cList\u003cint\u003e\u003e(\"[1, 2, 3]\");\nConsole.WriteLine(mappedList.Count); // 3\nConsole.WriteLine(mappedList[0]); // 1\nConsole.WriteLine(mappedList[1]); // 2\nConsole.WriteLine(mappedList[2]); // 3\n\nint[] mappedArray = JsonMapper.FromJson\u003cint[]\u003e(\"[1, 2, 3]\");\nConsole.WriteLine(mappedArray.Length); // 3\nConsole.WriteLine(mappedArray[0]); // 1\nConsole.WriteLine(mappedArray[1]); // 2\nConsole.WriteLine(mappedArray[2]); // 3\n```\n\n## Writing Json Data\n\nYou can convert a JsonValue object into the matching JSON string using `JsonMapper`:\n\n```C#\nusing Voorhees;\n\nJsonValue objectValue = new JsonValue {\n\t{ \"one\", 1 },\n\t{ \"two\", 2 },\n\t{ \"three\", 3 }\n};\nstring jsonObject = JsonMapper.ToJson(objectValue);\nConsole.WriteLine(jsonObject); // {\"one\":1,\"two\":2,\"three\":3}\n\nJsonValue arrayValue = new JsonValue {1, 2, 3};\nstring jsonArray = JsonMapper.ToJson(arrayValue);\nConsole.WriteLine(jsonObject); // [1,2,3]\n```\n\n`JsonMapper` also supports mapping arbitrary C# data types in addition to `JsonValue`.\n\n```C#\nusing Voorhees;\n\nstruct Player {\n\tpublic string name;\n\tpublic int gold;\n\tpublic float ageYears;\n}\n\nPlayer Bilbo = new Player {\n\tname = \"Bilbo Baggins\",\n\tgold = 99,\n\tageYears = 111.32f\n};\n\nstring bilboJson = JsonMapper.ToJson(Bilbo);\nConsole.WriteLine(bilboJson); // {\"name\":\"Bilbo Baggins\",\"gold\":99,\"ageYears\":111.32}\n\n\nint[] fibonacci = {1, 1, 2, 3, 5, 8};\nstring fibonacciJson = JsonMapper.ToJson(fibonacci);\nConsole.WriteLine(fibonacciJson); // [1,1,2,3,5,8]\n```\n\nBy default the JSON generated by JsonMapper does not have any whitespace.  This makes it as dense and small as possible, but not very convenient to read.  To generate more readable JSON results, you can optionally enable pretty-printing.\n\n```C#\nusing Voorhees;\n\nJsonValue objectValue = new JsonValue {\n\t{ \"one\", 1 },\n\t{ \"two\", 2 },\n\t{ \"three\", 3 }\n};\nstring jsonObject = JsonMapper.ToJson(objectValue, prettyPrint: true);\nConsole.WriteLine(jsonObject);\n/* Prints the following:\n{\n\t\"one\": 1,\n\t\"two\": 2,\n\t\"three\": 3\n}\n*/\n```\n\n## Working with JsonValue\n\n`JsonValue` is a discriminated union type that represents a [JSON value](https://www.json.org/json-en.html).  `JsonValue` represents a value that is either a `bool`, `int`, `double`, `string`, `List\u003cJsonValue\u003e` or `Dictionary\u003cstring, JsonValue\u003e`.  The `Type` parameter on a `JsonValue` instance returns an enum that indicates what the contained type is.\n\n**Creating JsonValue instances**\n`JsonValue` has a number of implicit conversion constructors, and is compatible with the C# syntactic sugar for declaring list and dictionary literals:\n\n```C#\nJsonValue boolValue = false;\nJsonValue intValue = 3;\nJsonValue doubletValue = 3.5;\nJsonValue stringValue = \"lorem ipsum\";\nJsonValue listValue = new JsonValue {1, 2, 3};\nJsonValue objectValue = new JsonValue {{\"one\", 1}, {\"two\", 2}};\n\n// These can be combined to create complex structure literals:\nJsonValue complexValue = new JsonValue {\n\t{\"intValue\", 42},\n\t{\"boolValue\", true},\n\t{\"twoTranslations\", new JsonValue {\n\t\t\t{\"es\", \"dos\"},\n\t\t\t{\"cn\", \"si\"},\n\t\t\t{\"jp\", \"ni\"},\n\t\t\t{\"fr\", \"deux\"}\n\t\t}\n\t},\n\t{\"somePrimes\", new JsonValue {2, 3, 5, 7, 11}}\n};\n```\n\n`JsonValue` instances also define a number of implicit conversion operators to convert to an instance of the underlying basic type.\n```C#\n// assuming the above JsonValue definitions...\n\nConsole.WriteLine((bool)boolValue); // false\nConsole.WriteLine((int)intValue); // 3\nConsole.WriteLine((double)doubleValue); // 3.5\nConsole.WriteLine((string)stringValue); // lorem ipsum\n```\n\n## Customizing Object Mapping \u0026 Operating on Streams\n\nJSON value reading and writing behavior can be completely customized by providing importer and exporter functions.  These custom functions are registered to a `JsonMapper` instance via the `RegisterImporter` and `RegisterExporter` methods.  Reading and writing with a `JsonMapper` instance (using any registered custom parsing functions) is done through the `Read()` and `Write()` methods, rather than the static `JsonMapper.ToJson()` and `JsonMapper.FromJson()` functions.\n\nThe `Read` and `Write` methods of `JsonMapper` operate on `TextReader` and `TextWriter` streams.  This integrates with `CryptoStream` subclasses and allows for reading and writing to files, sockets, etc.  `TextReader` streams are wrapped in a `JsonTokenReader` instance, while `TextWriter` streams are wrapped in a `JsonTokenWriter` instance.  These wrappers provide json-specific reading and writing methods.\n\n``` C#\nusing Voorhees;\n\nclass MyNumber {\n\tpublic int value;\n}\n\n// Creating a mapper instance allows us to customize mapping behavior.\nvar mapper = new JsonMapper();\n\n// Parse an integer as a MyNumber instance.\nmapper.RegisterImporter\u003cMyNumber\u003e(reader =\u003e {\n\treturn new MyNumber {\n\t\tvalue = int.Parse(reader.ConsumeNumber())\n\t};\n});\n\n// Write MyNumber values as integers, rather than objects\nmapper.RegisterExporter((myNum, tokenWriter) =\u003e {\n\ttokenWriter.Write(myNum.value);\n});\n\nvar num = new MyNumber { value = 42 };\n\n// Write an instance \n// Writes an instance of MyNumber to the StringBuilder via the StringWriter and JsonTokenWriter.\nvar jsonBuilder = new StringBuilder();\nusing (var stringWriter = new StringWriter(jsonBuilder)) {\n\tvar tokenWriter = new JsonTokenWriter(stringWriter, prettyPrint:false);\n\n\t\n\tmapper.Write(num, tokenWriter);\n}\n\nstring json = jsonBuilder.ToString(); // \"42\"\n\n// Read a MyNumber instance from the json string we just made.\nusing (var stringReader = new StringReader(json)) {\n\tvar tokenReader = new JsonTokenReader(stringReader);\n\tnum = mapper.Read\u003cMyNumber\u003e(tokenReader)\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrahamboree%2Fvoorhees","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrahamboree%2Fvoorhees","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrahamboree%2Fvoorhees/lists"}