From d8d499ce9b88dd83000c94efc73ce68bd1034715 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 24 Jul 2020 14:35:52 +0200 Subject: [PATCH] :memo: add more documentation --- doc/mkdocs/docs/features/binary_formats/cbor.md | 11 ++++++++--- doc/mkdocs/docs/features/binary_values.md | 2 +- doc/mkdocs/docs/features/parsing/sax_interface.md | 3 +++ doc/mkdocs/docs/home/license.md | 2 +- include/nlohmann/json.hpp | 2 -- single_include/nlohmann/json.hpp | 2 -- 6 files changed, 13 insertions(+), 9 deletions(-) diff --git a/doc/mkdocs/docs/features/binary_formats/cbor.md b/doc/mkdocs/docs/features/binary_formats/cbor.md index daea3a51..daa29be8 100644 --- a/doc/mkdocs/docs/features/binary_formats/cbor.md +++ b/doc/mkdocs/docs/features/binary_formats/cbor.md @@ -64,7 +64,6 @@ binary | *size*: 4294967296..18446744073709551615 | byte string (8 by If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`. - !!! info "Unused CBOR types" The following CBOR types are not used in the conversion: @@ -77,13 +76,16 @@ binary | *size*: 4294967296..18446744073709551615 | byte string (8 by - bignum (0xC2..0xC3) - decimal fraction (0xC4) - bigfloat (0xC5) - - tagged items (0xC6..0xD4, 0xD8..0xDB) - expected conversions (0xD5..0xD7) - simple values (0xE0..0xF3, 0xF8) - undefined (0xF7) - half-precision floats (0xF9) - break (0xFF) +!!! info "Tagged items" + + Binary subtypes will be serialized as tagged items. See [binary values](../binary_values.md#cbor) for an example. + ??? example ```cpp @@ -150,7 +152,6 @@ Double-Precision Float | number_float | 0xFB - bignum (0xC2..0xC3) - decimal fraction (0xC4) - bigfloat (0xC5) - - tagged items (0xC6..0xD4, 0xD8..0xDB) - expected conversions (0xD5..0xD7) - simple values (0xE0..0xF3, 0xF8) - undefined (0xF7) @@ -159,6 +160,10 @@ Double-Precision Float | number_float | 0xFB CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected. +!!! warning "Tagged items" + + Tagged items will throw a parse error by default. However, they can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`. + ??? example ```cpp diff --git a/doc/mkdocs/docs/features/binary_values.md b/doc/mkdocs/docs/features/binary_values.md index 14cc65b1..4716aac7 100644 --- a/doc/mkdocs/docs/features/binary_values.md +++ b/doc/mkdocs/docs/features/binary_values.md @@ -158,7 +158,7 @@ JSON does not have a binary type, and this library does not introduce a new type ### CBOR -[CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array. +[CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Subtypes will be serialized as tags. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array. ??? example diff --git a/doc/mkdocs/docs/features/parsing/sax_interface.md b/doc/mkdocs/docs/features/parsing/sax_interface.md index ef83a532..73153482 100644 --- a/doc/mkdocs/docs/features/parsing/sax_interface.md +++ b/doc/mkdocs/docs/features/parsing/sax_interface.md @@ -14,6 +14,7 @@ interface json::sax_t { + {abstract} bool number_float(number_float_t val, const string_t& s) + {abstract} bool string(string_t& val) + + {abstract} bool binary(binary_t& val) + {abstract} bool start_object(std::size_t elements) + {abstract} bool end_object() @@ -41,6 +42,8 @@ bool number_float(number_float_t val, const string_t& s); // called when a string is parsed; value is passed and can be safely moved away bool string(string_t& val); +// called when a binary value is parsed; value is passed and can be safely moved away +bool binary(binary& val); // called when an object or array begins or ends, resp. The number of elements is passed (or -1 if not known) bool start_object(std::size_t elements); diff --git a/doc/mkdocs/docs/home/license.md b/doc/mkdocs/docs/home/license.md index 9211eddd..f7d0aa82 100644 --- a/doc/mkdocs/docs/home/license.md +++ b/doc/mkdocs/docs/home/license.md @@ -4,7 +4,7 @@ The class is licensed under the [MIT License](http://opensource.org/licenses/MIT): -Copyright © 2013-2019 [Niels Lohmann](http://nlohmann.me) +Copyright © 2013-2020 [Niels Lohmann](http://nlohmann.me) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 753dac35..b4da4887 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -7036,7 +7036,6 @@ class basic_json - bignum (0xC2..0xC3) - decimal fraction (0xC4) - bigfloat (0xC5) - - tagged items (0xC6..0xD4, 0xD8..0xDB) - expected conversions (0xD5..0xD7) - simple values (0xE0..0xF3, 0xF8) - undefined (0xF7) @@ -7423,7 +7422,6 @@ class basic_json - bignum (0xC2..0xC3) - decimal fraction (0xC4) - bigfloat (0xC5) - - tagged items (0xC6..0xD4, 0xD8..0xDB) - expected conversions (0xD5..0xD7) - simple values (0xE0..0xF3, 0xF8) - undefined (0xF7) diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 0b7d2411..53c174a3 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -23339,7 +23339,6 @@ class basic_json - bignum (0xC2..0xC3) - decimal fraction (0xC4) - bigfloat (0xC5) - - tagged items (0xC6..0xD4, 0xD8..0xDB) - expected conversions (0xD5..0xD7) - simple values (0xE0..0xF3, 0xF8) - undefined (0xF7) @@ -23726,7 +23725,6 @@ class basic_json - bignum (0xC2..0xC3) - decimal fraction (0xC4) - bigfloat (0xC5) - - tagged items (0xC6..0xD4, 0xD8..0xDB) - expected conversions (0xD5..0xD7) - simple values (0xE0..0xF3, 0xF8) - undefined (0xF7)