🔥 consolidate documentation

doc/mkdocs/docs/api/basic_json/sax_parse.md

@@ -26,7 +26,7 @@ Read from input and generate SAX events
     The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
     respectively as UTF-8, UTF-16 and UTF-32.
 
-The SAX event lister must follow the interface of `json_sax`.
+The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).
 
 ## Template parameters
 

doc/mkdocs/docs/api/json_sax/binary.md

@@ -0,0 +1,24 @@
+# json_sax::binary
+
+```cpp
+virtual bool binary(binary_t& val) = 0;
+```
+
+A binary value was read.
+
+## Parameters
+
+`val` (in)
+:   binary value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Note
+
+It is safe to move the passed binary value.
+
+## Version history
+
+- Added in version 3.8.0.

doc/mkdocs/docs/api/json_sax/boolean.md

@@ -0,0 +1,20 @@
+# json_sax::boolean
+
+```cpp
+virtual bool boolean(bool val) = 0;
+```
+
+A boolean value was read.
+
+## Parameters
+
+`val` (in)
+:   boolean value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/end_array.md

@@ -0,0 +1,15 @@
+# json_sax::end_array
+
+```cpp
+virtual bool end_array() = 0;
+```
+
+The end of an array was read.
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/end_object.md

@@ -0,0 +1,15 @@
+# json_sax::end_object
+
+```cpp
+virtual bool end_object() = 0;
+```
+
+The end of an object was read.
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/index.md

@@ -0,0 +1,44 @@
+# json_sax
+
+```cpp
+template<typename BasicJsonType>
+struct json_sax;
+```
+
+This class describes the SAX interface used by [sax_parse](../basic_json/sax_parse.md). Each function is called in
+different situations while the input is parsed. The boolean return value informs the parser whether to continue
+processing the input.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](../basic_json/index.md)
+
+## Member types
+
+- [**number_integer_t**](../basic_json/number_integer_t.md) - `BasicJsonType`'s type for numbers (integer)
+- [**number_unsigned_t**](../basic_json/number_unsigned_t.md) - `BasicJsonType`'s  type for numbers (unsigned)
+- [**number_float_t**](../basic_json/number_float_t.md) - `BasicJsonType`'s type for numbers (floating-point)
+- [**string_t**](../basic_json/string_t.md) - `BasicJsonType`'s type for strings
+- [**binary_t**](../basic_json/binary_t.md) - `BasicJsonType`'s type for binary arrays
+
+## Member functions
+
+- [**binary**](binary.md) (_virtual_) - a binary value was read
+- [**boolean**](boolean.md) (_virtual_) - a boolean value was read
+- [**end_array**](end_array.md) (_virtual_) - the end of an array was read
+- [**end_object**](end_object.md) (_virtual_) - the end of an object was read
+- [**key**](key.md) (_virtual_) - an object key was read
+- [**null**](null.md) (_virtual_) - a null value was read
+- [**number_float**](number_float.md) (_virtual_) - a floating-point number was read
+- [**number_integer**](number_integer.md) (_virtual_) - an integer number was read
+- [**number_unsigned**](number_unsigned.md) (_virtual_) - an unsigned integer number was read
+- [**parse_error**](parse_error.md) (_virtual_) - a parse error occurred
+- [**start_array**](start_array.md) (_virtual_) - the beginning of an array was read
+- [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
+- [**string**](string.md) (_virtual_) - a string value was read
+
+## Version history
+
+- Added in version 3.2.0.
+- Support for binary values (`binary_t`, `binary`) added in version 3.8.0.

doc/mkdocs/docs/api/json_sax/key.md

@@ -0,0 +1,24 @@
+# json_sax::key
+
+```cpp
+virtual bool key(string_t& val) = 0;
+```
+
+An object key was read.
+
+## Parameters
+
+`val` (in)
+:   object key
+
+## Return value
+
+Whether parsing should proceed.
+
+## Note
+
+It is safe to move the passed object key value.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/null.md

@@ -0,0 +1,15 @@
+# json_sax::null
+
+```cpp
+virtual bool null() = 0;
+```
+
+A null value was read.
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/number_float.md

@@ -0,0 +1,20 @@
+# json_sax::number_float
+
+```cpp
+virtual bool number_float(number_float_t val, const string_t& s) = 0;
+```
+
+A floating-point number was read.
+
+## Parameters
+
+`val` (in)
+:   floating-point value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/number_integer.md

@@ -0,0 +1,20 @@
+# json_sax::number_integer
+
+```cpp
+virtual bool number_integer(number_integer_t val) = 0;
+```
+
+An integer number was read.
+
+## Parameters
+
+`val` (in)
+:   integer value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/number_unsigned.md

@@ -0,0 +1,20 @@
+# json_sax::number_unsigned
+
+```cpp
+virtual bool number_unsigned(number_unsigned_t val) = 0;
+```
+
+An unsigned integer number was read.
+
+## Parameters
+
+`val` (in)
+:   unsigned integer value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/parse_error.md

@@ -0,0 +1,28 @@
+# json_sax::parse_error
+
+```cpp
+virtual bool parse_error(std::size_t position,
+                         const std::string& last_token,
+                         const detail::exception& ex) = 0;
+```
+
+A parse error occurred.
+
+## Parameters
+
+`position` (in)
+:   the position in the input where the error occurs
+
+`last_token` (in)
+:   the last read token
+
+`ex` (in)
+:   an exception object describing the error
+
+## Return value
+
+Whether parsing should proceed (**must return `#!cpp false`**).
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/start_array.md

@@ -0,0 +1,24 @@
+# json_sax::start_array
+
+```cpp
+virtual bool start_array(std::size_t elements) = 0;
+```
+
+The beginning of an array was read.
+
+## Parameters
+
+`elements` (in)
+:   number of object elements or `#!cpp -1` if unknown
+
+## Return value
+
+Whether parsing should proceed.
+
+## Note
+
+Binary formats may report the number of elements.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/start_object.md

@@ -0,0 +1,24 @@
+# json_sax::start_object
+
+```cpp
+virtual bool start_object(std::size_t elements) = 0;
+```
+
+The beginning of an object was read.
+
+## Parameters
+
+`elements` (in)
+:   number of object elements or `#!cpp -1` if unknown
+
+## Return value
+
+Whether parsing should proceed.
+
+## Note
+
+Binary formats may report the number of elements.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/string.md

@@ -0,0 +1,24 @@
+# json_sax::string
+
+```cpp
+virtual bool string(string_t& val) = 0;
+```
+
+A string value was read.
+
+## Parameters
+
+`val` (in)
+:   string value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Note
+
+It is safe to move the passed string value.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/mkdocs.yml

@@ -188,6 +188,21 @@ nav:
         - api/adl_serializer/to_json.md
       - api/json.md
       - api/json_pointer.md
+      - json_sax:
+        - api/json_sax/index.md
+        - api/json_sax/binary.md
+        - api/json_sax/boolean.md
+        - api/json_sax/end_array.md
+        - api/json_sax/end_object.md
+        - api/json_sax/key.md
+        - api/json_sax/null.md
+        - api/json_sax/number_float.md
+        - api/json_sax/number_integer.md
+        - api/json_sax/number_unsigned.md
+        - api/json_sax/parse_error.md
+        - api/json_sax/start_array.md
+        - api/json_sax/start_object.md
+        - api/json_sax/string.md
       - api/ordered_map.md
       - api/ordered_json.md
 

include/nlohmann/detail/conversions/to_chars.hpp

@@ -891,7 +891,7 @@ void grisu2(char* buf, int& len, int& decimal_exponent, FloatType value)
     //
     // The documentation for 'std::to_chars' (https://en.cppreference.com/w/cpp/utility/to_chars)
     // says "value is converted to a string as if by std::sprintf in the default ("C") locale"
-    // and since sprintf promotes float's to double's, I think this is exactly what 'std::to_chars'
+    // and since sprintf promotes floats to doubles, I think this is exactly what 'std::to_chars'
     // does.
     // On the other hand, the documentation for 'std::to_chars' requires that "parsing the
     // representation using the corresponding std::from_chars function recovers value exactly". That

include/nlohmann/detail/input/input_adapters.hpp

@@ -104,7 +104,7 @@ class input_stream_adapter
 
     // std::istream/std::streambuf use std::char_traits<char>::to_int_type, to
     // ensure that std::char_traits<char>::eof() and the character 0xFF do not
-    // end up as the same value, eg. 0xFFFFFFFF.
+    // end up as the same value, e.g. 0xFFFFFFFF.
     std::char_traits<char>::int_type get_character()
     {
         auto res = sb->sbumpc();
@@ -450,7 +450,7 @@ auto input_adapter(T (&array)[N]) -> decltype(input_adapter(array, array + N)) /
 }
 
 // This class only handles inputs of input_buffer_adapter type.
-// It's required so that expressions like {ptr, len} can be implicitely casted
+// It's required so that expressions like {ptr, len} can be implicitly cast
 // to the correct adapter.
 class span_input_adapter
 {

include/nlohmann/detail/input/json_sax.hpp

@@ -56,7 +56,7 @@ struct json_sax
     virtual bool number_unsigned(number_unsigned_t val) = 0;
 
     /*!
-    @brief an floating-point number was read
+    @brief a floating-point number was read
     @param[in] val  floating-point value
     @param[in] s    raw token value
     @return whether parsing should proceed
@@ -64,18 +64,18 @@ struct json_sax
     virtual bool number_float(number_float_t val, const string_t& s) = 0;
 
     /*!
-    @brief a string was read
+    @brief a string value was read
     @param[in] val  string value
     @return whether parsing should proceed
-    @note It is safe to move the passed string.
+    @note It is safe to move the passed string value.
     */
     virtual bool string(string_t& val) = 0;
 
     /*!
-    @brief a binary string was read
+    @brief a binary value was read
     @param[in] val  binary value
     @return whether parsing should proceed
-    @note It is safe to move the passed binary.
+    @note It is safe to move the passed binary value.
     */
     virtual bool binary(binary_t& val) = 0;
 

include/nlohmann/detail/input/lexer.hpp

@@ -343,7 +343,7 @@ class lexer : public lexer_base<BasicJsonType>
                                                         // low surrogate occupies the least significant 15 bits
                                                         + static_cast<unsigned int>(codepoint2)
                                                         // there is still the 0xD800, 0xDC00 and 0x10000 noise
-                                                        // in the result so we have to subtract with:
+                                                        // in the result, so we have to subtract with:
                                                         // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
                                                         - 0x35FDC00u);
                                     }

include/nlohmann/detail/macro_scope.hpp

@@ -44,7 +44,7 @@
     #pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
 #endif
 
-// allow to disable exceptions
+// allow disabling exceptions
 #if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION)
     #define JSON_THROW(exception) throw exception
     #define JSON_TRY try
@@ -78,7 +78,7 @@
     #define JSON_INTERNAL_CATCH JSON_INTERNAL_CATCH_USER
 #endif
 
-// allow to override assert
+// allow overriding assert
 #if !defined(JSON_ASSERT)
     #include <cassert> // assert
     #define JSON_ASSERT(x) assert(x)

include/nlohmann/detail/output/serializer.hpp

@@ -729,7 +729,7 @@ class serializer
         // spare 1 byte for '\0'
         JSON_ASSERT(n_chars < number_buffer.size() - 1);
 
-        // jump to the end to generate the string from backward
+        // jump to the end to generate the string from backward,
         // so we later avoid reversing the result
         buffer_ptr += n_chars;
 
@@ -831,7 +831,7 @@ class serializer
 
         o->write_characters(number_buffer.data(), static_cast<std::size_t>(len));
 
-        // determine if need to append ".0"
+        // determine if we need to append ".0"
         const bool value_is_int_like =
             std::none_of(number_buffer.begin(), number_buffer.begin() + len + 1,
                          [](char c)

include/nlohmann/json.hpp

@@ -1785,7 +1785,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return v;
     }
 
-    // specialization to allow to call get_to with a basic_json value
+    // specialization to allow calling get_to with a basic_json value
     // see https://github.com/nlohmann/json/issues/2175
     template<typename ValueType,
              detail::enable_if_t <
@@ -2858,7 +2858,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         const auto old_capacity = m_value.array->capacity();
         m_value.array->push_back(std::move(val));
         set_parent(m_value.array->back(), old_capacity);
-        // if val is moved from, basic_json move constructor marks it null so we do not call the destructor
+        // if val is moved from, basic_json move constructor marks it null, so we do not call the destructor
     }
 
     /// @brief add an object to an array
@@ -4551,7 +4551,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                     ++i;
                 }
 
-                // i now reached the end of at least one array
+                // We now reached the end of at least one array
                 // in a second pass, traverse the remaining elements
 
                 // remove my remaining elements

single_include/nlohmann/json.hpp

@@ -2332,7 +2332,7 @@ using is_detected_convertible =
     #pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
 #endif
 
-// allow to disable exceptions
+// allow disabling exceptions
 #if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION)
     #define JSON_THROW(exception) throw exception
     #define JSON_TRY try
@@ -2366,7 +2366,7 @@ using is_detected_convertible =
     #define JSON_INTERNAL_CATCH JSON_INTERNAL_CATCH_USER
 #endif
 
-// allow to override assert
+// allow overriding assert
 #if !defined(JSON_ASSERT)
     #include <cassert> // assert
     #define JSON_ASSERT(x) assert(x)
@@ -5503,7 +5503,7 @@ class input_stream_adapter
 
     // std::istream/std::streambuf use std::char_traits<char>::to_int_type, to
     // ensure that std::char_traits<char>::eof() and the character 0xFF do not
-    // end up as the same value, eg. 0xFFFFFFFF.
+    // end up as the same value, e.g. 0xFFFFFFFF.
     std::char_traits<char>::int_type get_character()
     {
         auto res = sb->sbumpc();
@@ -5849,7 +5849,7 @@ auto input_adapter(T (&array)[N]) -> decltype(input_adapter(array, array + N)) /
 }
 
 // This class only handles inputs of input_buffer_adapter type.
-// It's required so that expressions like {ptr, len} can be implicitely casted
+// It's required so that expressions like {ptr, len} can be implicitly cast
 // to the correct adapter.
 class span_input_adapter
 {
@@ -5942,7 +5942,7 @@ struct json_sax
     virtual bool number_unsigned(number_unsigned_t val) = 0;
 
     /*!
-    @brief an floating-point number was read
+    @brief a floating-point number was read
     @param[in] val  floating-point value
     @param[in] s    raw token value
     @return whether parsing should proceed
@@ -5950,18 +5950,18 @@ struct json_sax
     virtual bool number_float(number_float_t val, const string_t& s) = 0;
 
     /*!
-    @brief a string was read
+    @brief a string value was read
     @param[in] val  string value
     @return whether parsing should proceed
-    @note It is safe to move the passed string.
+    @note It is safe to move the passed string value.
     */
     virtual bool string(string_t& val) = 0;
 
     /*!
-    @brief a binary string was read
+    @brief a binary value was read
     @param[in] val  binary value
     @return whether parsing should proceed
-    @note It is safe to move the passed binary.
+    @note It is safe to move the passed binary value.
     */
     virtual bool binary(binary_t& val) = 0;
 
@@ -6945,7 +6945,7 @@ class lexer : public lexer_base<BasicJsonType>
                                                         // low surrogate occupies the least significant 15 bits
                                                         + static_cast<unsigned int>(codepoint2)
                                                         // there is still the 0xD800, 0xDC00 and 0x10000 noise
-                                                        // in the result so we have to subtract with:
+                                                        // in the result, so we have to subtract with:
                                                         // (0xD800 << 10) + DC00 - 0x10000 = 0x35FDC00
                                                         - 0x35FDC00u);
                                     }
@@ -16189,7 +16189,7 @@ void grisu2(char* buf, int& len, int& decimal_exponent, FloatType value)
     //
     // The documentation for 'std::to_chars' (https://en.cppreference.com/w/cpp/utility/to_chars)
     // says "value is converted to a string as if by std::sprintf in the default ("C") locale"
-    // and since sprintf promotes float's to double's, I think this is exactly what 'std::to_chars'
+    // and since sprintf promotes floats to doubles, I think this is exactly what 'std::to_chars'
     // does.
     // On the other hand, the documentation for 'std::to_chars' requires that "parsing the
     // representation using the corresponding std::from_chars function recovers value exactly". That
@@ -17127,7 +17127,7 @@ class serializer
         // spare 1 byte for '\0'
         JSON_ASSERT(n_chars < number_buffer.size() - 1);
 
-        // jump to the end to generate the string from backward
+        // jump to the end to generate the string from backward,
         // so we later avoid reversing the result
         buffer_ptr += n_chars;
 
@@ -17229,7 +17229,7 @@ class serializer
 
         o->write_characters(number_buffer.data(), static_cast<std::size_t>(len));
 
-        // determine if need to append ".0"
+        // determine if we need to append ".0"
         const bool value_is_int_like =
             std::none_of(number_buffer.begin(), number_buffer.begin() + len + 1,
                          [](char c)
@@ -19260,7 +19260,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return v;
     }
 
-    // specialization to allow to call get_to with a basic_json value
+    // specialization to allow calling get_to with a basic_json value
     // see https://github.com/nlohmann/json/issues/2175
     template<typename ValueType,
              detail::enable_if_t <
@@ -20333,7 +20333,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         const auto old_capacity = m_value.array->capacity();
         m_value.array->push_back(std::move(val));
         set_parent(m_value.array->back(), old_capacity);
-        // if val is moved from, basic_json move constructor marks it null so we do not call the destructor
+        // if val is moved from, basic_json move constructor marks it null, so we do not call the destructor
     }
 
     /// @brief add an object to an array
@@ -22026,7 +22026,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                     ++i;
                 }
 
-                // i now reached the end of at least one array
+                // We now reached the end of at least one array
                 // in a second pass, traverse the remaining elements
 
                 // remove my remaining elements