From b4e4dbe346bfb95d4f457787292afbd997a1f8f6 Mon Sep 17 00:00:00 2001 From: nlohmann Date: Fri, 7 Aug 2026 17:31:54 +0000 Subject: [PATCH] deploy: 23518f54fec80cdc8ab603a24b14a65232bdfcda --- 404.html | 2 +- api/adl_serializer/from_json/index.html | 4 +- api/adl_serializer/index.html | 4 +- api/adl_serializer/to_json/index.html | 4 +- api/basic_json/accept/index.html | 4 +- api/basic_json/array/index.html | 4 +- api/basic_json/array_t/index.html | 4 +- api/basic_json/at/index.html | 4 +- api/basic_json/back/index.html | 4 +- api/basic_json/basic_json/index.html | 4 +- api/basic_json/begin/index.html | 4 +- api/basic_json/binary/index.html | 4 +- api/basic_json/binary_t/index.html | 4 +- api/basic_json/boolean_t/index.html | 4 +- api/basic_json/cbegin/index.html | 4 +- api/basic_json/cbor_tag_handler_t/index.html | 4 +- api/basic_json/cend/index.html | 4 +- api/basic_json/clear/index.html | 4 +- api/basic_json/contains/index.html | 4 +- api/basic_json/count/index.html | 4 +- api/basic_json/crbegin/index.html | 4 +- api/basic_json/crend/index.html | 4 +- .../default_object_comparator_t/index.html | 4 +- api/basic_json/diff/index.html | 4 +- api/basic_json/dump/index.html | 4 +- api/basic_json/emplace/index.html | 4 +- api/basic_json/emplace_back/index.html | 4 +- api/basic_json/empty/index.html | 4 +- api/basic_json/end/index.html | 4 +- api/basic_json/end_pos/index.html | 4 +- api/basic_json/erase/index.html | 4 +- api/basic_json/error_handler_t/index.html | 4 +- api/basic_json/exception/index.html | 4 +- api/basic_json/find/index.html | 4 +- api/basic_json/flatten/index.html | 4 +- api/basic_json/format_as/index.html | 4 +- api/basic_json/from_bjdata/index.html | 4 +- api/basic_json/from_bson/index.html | 4 +- api/basic_json/from_cbor/index.html | 4 +- api/basic_json/from_msgpack/index.html | 4 +- api/basic_json/from_ubjson/index.html | 4 +- api/basic_json/front/index.html | 4 +- api/basic_json/get/index.html | 4 +- api/basic_json/get_allocator/index.html | 4 +- api/basic_json/get_binary/index.html | 4 +- api/basic_json/get_ptr/index.html | 4 +- api/basic_json/get_ref/index.html | 4 +- api/basic_json/get_to/index.html | 4 +- api/basic_json/index.html | 4 +- api/basic_json/input_format_t/index.html | 4 +- api/basic_json/insert/index.html | 4 +- api/basic_json/invalid_iterator/index.html | 4 +- api/basic_json/is_array/index.html | 4 +- api/basic_json/is_binary/index.html | 4 +- api/basic_json/is_boolean/index.html | 4 +- api/basic_json/is_discarded/index.html | 4 +- api/basic_json/is_null/index.html | 4 +- api/basic_json/is_number/index.html | 4 +- api/basic_json/is_number_float/index.html | 4 +- api/basic_json/is_number_integer/index.html | 4 +- api/basic_json/is_number_unsigned/index.html | 4 +- api/basic_json/is_object/index.html | 4 +- api/basic_json/is_primitive/index.html | 4 +- api/basic_json/is_string/index.html | 4 +- api/basic_json/is_structured/index.html | 4 +- api/basic_json/items/index.html | 4 +- api/basic_json/json_base_class_t/index.html | 4 +- api/basic_json/json_serializer/index.html | 4 +- api/basic_json/max_size/index.html | 4 +- api/basic_json/merge_patch/index.html | 4 +- api/basic_json/meta/index.html | 4 +- api/basic_json/number_float_t/index.html | 4 +- api/basic_json/number_integer_t/index.html | 4 +- api/basic_json/number_unsigned_t/index.html | 4 +- api/basic_json/object/index.html | 4 +- api/basic_json/object_comparator_t/index.html | 4 +- api/basic_json/object_t/index.html | 4 +- api/basic_json/operator+=/index.html | 4 +- api/basic_json/operator=/index.html | 4 +- api/basic_json/operator[]/index.html | 4 +- api/basic_json/operator_ValueType/index.html | 4 +- api/basic_json/operator_eq/index.html | 4 +- api/basic_json/operator_ge/index.html | 4 +- api/basic_json/operator_gt/index.html | 4 +- api/basic_json/operator_le/index.html | 4 +- api/basic_json/operator_lt/index.html | 4 +- api/basic_json/operator_ne/index.html | 4 +- api/basic_json/operator_spaceship/index.html | 4 +- api/basic_json/operator_value_t/index.html | 4 +- api/basic_json/other_error/index.html | 4 +- api/basic_json/out_of_range/index.html | 4 +- api/basic_json/parse/index.html | 4 +- api/basic_json/parse_error/index.html | 4 +- api/basic_json/parse_event_t/index.html | 4 +- api/basic_json/parser_callback_t/index.html | 4 +- api/basic_json/patch/index.html | 4 +- api/basic_json/patch_inplace/index.html | 4 +- api/basic_json/push_back/index.html | 4 +- api/basic_json/rbegin/index.html | 4 +- api/basic_json/rend/index.html | 4 +- api/basic_json/sax_parse/index.html | 4 +- api/basic_json/size/index.html | 4 +- api/basic_json/start_pos/index.html | 4 +- api/basic_json/std_formatter/index.html | 4 +- api/basic_json/std_hash/index.html | 4 +- api/basic_json/std_swap/index.html | 4 +- api/basic_json/string_t/index.html | 4 +- api/basic_json/swap/index.html | 4 +- api/basic_json/to_bjdata/index.html | 4 +- api/basic_json/to_bson/index.html | 4 +- api/basic_json/to_cbor/index.html | 4 +- api/basic_json/to_msgpack/index.html | 4 +- api/basic_json/to_string/index.html | 4 +- api/basic_json/to_ubjson/index.html | 4 +- api/basic_json/type/index.html | 4 +- api/basic_json/type_error/index.html | 4 +- api/basic_json/type_name/index.html | 4 +- api/basic_json/unflatten/index.html | 4 +- api/basic_json/update/index.html | 4 +- api/basic_json/value/index.html | 4 +- api/basic_json/value_t/index.html | 4 +- api/basic_json/~basic_json/index.html | 4 +- .../byte_container_with_subtype/index.html | 4 +- .../clear_subtype/index.html | 4 +- .../has_subtype/index.html | 4 +- api/byte_container_with_subtype/index.html | 4 +- .../set_subtype/index.html | 4 +- .../subtype/index.html | 4 +- api/json/index.html | 4 +- api/json_pointer/back/index.html | 4 +- api/json_pointer/empty/index.html | 4 +- api/json_pointer/front/index.html | 4 +- api/json_pointer/index.html | 4 +- api/json_pointer/json_pointer/index.html | 4 +- api/json_pointer/operator_eq/index.html | 4 +- api/json_pointer/operator_ne/index.html | 4 +- api/json_pointer/operator_slash/index.html | 4 +- api/json_pointer/operator_slasheq/index.html | 4 +- api/json_pointer/operator_string_t/index.html | 4 +- api/json_pointer/parent_pointer/index.html | 4 +- api/json_pointer/pop_back/index.html | 4 +- api/json_pointer/pop_front/index.html | 4 +- api/json_pointer/push_back/index.html | 4 +- api/json_pointer/push_front/index.html | 4 +- api/json_pointer/string_t/index.html | 4 +- api/json_pointer/to_string/index.html | 4 +- api/json_sax/binary/index.html | 4 +- api/json_sax/boolean/index.html | 4 +- api/json_sax/end_array/index.html | 4 +- api/json_sax/end_object/index.html | 4 +- api/json_sax/index.html | 4 +- api/json_sax/key/index.html | 4 +- api/json_sax/null/index.html | 4 +- api/json_sax/number_float/index.html | 4 +- api/json_sax/number_integer/index.html | 4 +- api/json_sax/number_unsigned/index.html | 4 +- api/json_sax/parse_error/index.html | 4 +- api/json_sax/start_array/index.html | 4 +- api/json_sax/start_object/index.html | 4 +- api/json_sax/string/index.html | 4 +- api/macros/index.html | 2 +- api/macros/json_assert/index.html | 4 +- .../json_brace_init_copy_semantics/index.html | 4 +- .../json_diagnostic_positions/index.html | 4 +- api/macros/json_diagnostics/index.html | 4 +- .../index.html | 4 +- api/macros/json_has_cpp_11/index.html | 4 +- api/macros/json_has_filesystem/index.html | 4 +- api/macros/json_has_ranges/index.html | 4 +- api/macros/json_has_static_rtti/index.html | 4 +- api/macros/json_has_std_format/index.html | 4 +- .../json_has_three_way_comparison/index.html | 4 +- api/macros/json_no_io/index.html | 4 +- api/macros/json_noexception/index.html | 4 +- .../index.html | 4 +- .../index.html | 4 +- api/macros/json_throw_user/index.html | 4 +- api/macros/json_use_global_udls/index.html | 4 +- .../json_use_implicit_conversions/index.html | 4 +- .../index.html | 4 +- .../nlohmann_define_derived_type/index.html | 4 +- .../nlohmann_define_type_intrusive/index.html | 4 +- .../index.html | 4 +- .../index.html | 4 +- api/macros/nlohmann_json_namespace/index.html | 4 +- .../nlohmann_json_namespace_begin/index.html | 4 +- .../index.html | 4 +- .../nlohmann_json_serialize_enum/index.html | 4 +- .../index.html | 4 +- .../nlohmann_json_version_major/index.html | 4 +- api/operator_gtgt/index.html | 4 +- api/operator_literal_json/index.html | 4 +- api/operator_literal_json_pointer/index.html | 4 +- api/operator_ltlt/index.html | 4 +- api/ordered_json/index.html | 4 +- api/ordered_map/index.html | 4 +- community.md | 1 + community/code_of_conduct/index.html | 2 +- community/contribution_guidelines/index.html | 4 +- community/ecosystem.md | 40 ++ community/ecosystem/index.html | 1 + community/ecosystem/index.md | 29 + community/governance/index.html | 2 +- community/index.html | 2 +- community/index.md | 1 + community/quality_assurance/index.html | 4 +- community/security_policy/index.html | 2 +- features/arbitrary_types/index.html | 4 +- features/assertions/index.html | 4 +- features/binary_formats/bjdata/index.html | 4 +- features/binary_formats/bson/index.html | 4 +- features/binary_formats/cbor/index.html | 4 +- features/binary_formats/index.html | 2 +- .../binary_formats/messagepack/index.html | 4 +- features/binary_formats/ubjson/index.html | 4 +- features/binary_values/index.html | 4 +- features/comments/index.html | 4 +- features/conversions/index.html | 4 +- features/creating_values/index.html | 4 +- .../element_access/checked_access/index.html | 4 +- .../element_access/default_value/index.html | 4 +- features/element_access/index.html | 2 +- .../unchecked_access/index.html | 4 +- features/enum_conversion/index.html | 4 +- features/index.html | 2 +- features/iterators/index.html | 4 +- features/json_patch/index.html | 4 +- features/json_pointer/index.html | 4 +- features/macros/index.html | 2 +- features/merge_patch/index.html | 4 +- features/modifying_values/index.html | 4 +- features/modules/index.html | 4 +- features/namespace/index.html | 4 +- features/object_order/index.html | 4 +- features/parsing/index.html | 4 +- features/parsing/json_lines/index.html | 4 +- features/parsing/parse_exceptions/index.html | 4 +- features/parsing/parser_callbacks/index.html | 4 +- features/parsing/sax_interface/index.html | 4 +- features/serialization/index.html | 4 +- features/trailing_commas/index.html | 4 +- features/types/index.html | 4 +- features/types/number_handling/index.html | 4 +- home/architecture/index.html | 4 +- home/customers/index.html | 2 +- home/debugging/index.html | 2 +- home/design_goals/index.html | 2 +- home/exceptions/index.html | 4 +- home/faq/index.html | 4 +- home/license/index.html | 2 +- home/releases/index.html | 2 +- home/sponsors/index.html | 2 +- index.html | 2 +- integration/cmake/index.html | 4 +- integration/index.html | 4 +- integration/migration_guide/index.html | 4 +- integration/package_managers/index.html | 4 +- integration/pkg-config/index.html | 4 +- llms.txt | 1 + search/search_index.json | 2 +- sitemap.xml | 508 +++++++++--------- sitemap.xml.gz | Bin 1831 -> 1838 bytes 262 files changed, 819 insertions(+), 742 deletions(-) create mode 100644 community/ecosystem.md create mode 100644 community/ecosystem/index.html create mode 100644 community/ecosystem/index.md diff --git a/404.html b/404.html index 7593a0274..a6f9d96cd 100644 --- a/404.html +++ b/404.html @@ -1 +1 @@ - JSON for Modern C++

404 - Not found

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + JSON for Modern C++

404 - Not found

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/adl_serializer/from_json/index.html b/api/adl_serializer/from_json/index.html index 044cf3615..6f485f124 100644 --- a/api/adl_serializer/from_json/index.html +++ b/api/adl_serializer/from_json/index.html @@ -1,4 +1,4 @@ - from_json - JSON for Modern C++
Skip to content

nlohmann::adl_serializer::from_json

// (1)
+ from_json - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::adl_serializer::from_json
 
// (1)
 template<typename BasicJsonType, typename TargetType = ValueType>
 static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
     noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
@@ -101,4 +101,4 @@
     std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
 }
 
 
Output:
 
Ned Flanders (60) lives in 744 Evergreen Terrace
-
  
See also
  
Version history
 
     
  • Added in version 2.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/adl_serializer/index.html b/api/adl_serializer/index.html index e0c98ee97..83cec47db 100644 --- a/api/adl_serializer/index.html +++ b/api/adl_serializer/index.html @@ -1,4 +1,4 @@ - Overview - JSON for Modern C++
Skip to content

nlohmann::adl_serializer

template<typename, typename>
+ Overview - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::adl_serializer
 
template<typename, typename>
 struct adl_serializer;
 
 
Serializer that uses ADL (Argument-Dependent Lookup) to choose to_json/from_json functions from the types' namespaces.
 
It is implemented similarly to
 
template<typename ValueType>
 struct adl_serializer {
@@ -12,4 +12,4 @@
         // same thing, but with the "from_json" method
     }
 };
-
 
Member functions
 
     
  • from_json - convert a JSON value to any value type
    •  
  • to_json - convert any value type to a JSON value
    •  
 
Version history
 
     
  • Added in version 2.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Member functions

  • from_json - convert a JSON value to any value type
  • to_json - convert any value type to a JSON value

Version history

  • Added in version 2.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/adl_serializer/to_json/index.html b/api/adl_serializer/to_json/index.html index 7c2b60e89..86dbb62cc 100644 --- a/api/adl_serializer/to_json/index.html +++ b/api/adl_serializer/to_json/index.html @@ -1,4 +1,4 @@ - to_json - JSON for Modern C++
Skip to content

nlohmann::adl_serializer::to_json

template<typename BasicJsonType, typename TargetType = ValueType>
+ to_json - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::adl_serializer::to_json
 
template<typename BasicJsonType, typename TargetType = ValueType>
 static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
     noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))
 -> decltype(::nlohmann::to_json(j, std::forward<TargetType>(val)), void())
@@ -35,4 +35,4 @@
     std::cout << j << std::endl;
 }
 
 
Output:
 
{"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
-
  
See also
  
Version history
 
     
  • Added in version 2.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/accept/index.html b/api/basic_json/accept/index.html index 6779769b1..82312f797 100644 --- a/api/basic_json/accept/index.html +++ b/api/basic_json/accept/index.html @@ -1,4 +1,4 @@ - accept - JSON for Modern C++
Skip to content

nlohmann::basic_json::accept

// (1)
+ accept - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::accept
 
// (1)
 template<typename InputType>
 static bool accept(InputType&& i,
                    const bool ignore_comments = false,
@@ -36,4 +36,4 @@
               << json::accept(invalid_text) << '\n';
 }
 
 
Output:
 
true false
-
  
See also
 
     
  • parse - deserialize from a compatible input
    •  
  • sax_parse - parse input using the SAX interface
    •  
  • operator>> - deserialize from stream
    •  
 
Version history
 
     
  • Added in version 3.0.0.
    •  
  • Ignoring comments via ignore_comments added in version 3.9.0.
    •  
  • Changed runtime assertion in case of FILE* null pointers to exception in version 3.12.0.
    •  
  • Added ignore_trailing_commas in version 3.13.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
Overload (2) replaces calls to accept with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like accept({ptr, ptr+len}, ...); with accept(ptr, ptr+len, ...);.
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • parse - deserialize from a compatible input
  • sax_parse - parse input using the SAX interface
  • operator>> - deserialize from stream

Version history

  • Added in version 3.0.0.
  • Ignoring comments via ignore_comments added in version 3.9.0.
  • Changed runtime assertion in case of FILE* null pointers to exception in version 3.12.0.
  • Added ignore_trailing_commas in version 3.13.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

Overload (2) replaces calls to accept with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like accept({ptr, ptr+len}, ...); with accept(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/array/index.html b/api/basic_json/array/index.html index 99f6af56b..fe5e3c6fa 100644 --- a/api/basic_json/array/index.html +++ b/api/basic_json/array/index.html @@ -1,4 +1,4 @@ - array - JSON for Modern C++
Skip to content

nlohmann::basic_json::array

static basic_json array(initializer_list_t init = {});
+ array - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::array
 
static basic_json array(initializer_list_t init = {});
 
 
Creates a JSON array value from a given initializer list. That is, given a list of values a, b, c, creates the JSON value [a, b, c]. If the initializer list is empty, the empty array [] is created.
 
Parameters
 
 
init (in)
 
initializer list with JSON values to create an array from (optional)
 
 
Return value
 
JSON array value
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
Complexity
 
Linear in the size of init.
 
Notes
 
This function is only needed to express two edge cases that cannot be realized with the initializer list constructor (basic_json(initializer_list_t, bool, value_t)). These cases are:
 
     
  1. creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list constructor would create an object, taking the first elements as keys
    2.  
  2. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty object
    3.  
 
Examples
 
 Example 
The following code shows an example for the array function.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -22,4 +22,4 @@
 []
 [1,2,3,4]
 [["one",1],["two",2]]
-
 
 
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/array_t/index.html b/api/basic_json/array_t/index.html index 8eba5b315..ac186e0dd 100644 --- a/api/basic_json/array_t/index.html +++ b/api/basic_json/array_t/index.html @@ -1,4 +1,4 @@ - array_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::array_t

using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
+ array_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::array_t
 
using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
 
 
The type used to store JSON arrays.
 
RFC 8259 describes JSON arrays as follows:
 
 
An array is an ordered sequence of zero or more values.
 
 
To store objects in C++, a type is defined by the template parameters explained below.
 
Template parameters
 
 
ArrayType
 
container type to store arrays (e.g., std::vector or std::list)
 
AllocatorType
 
the allocator to use for objects (e.g., std::allocator)
 
 
Notes
 
Default type
 
With the default values for ArrayType (std::vector) and AllocatorType (std::allocator), the default value for array_t is:
 
std::vector<
   basic_json, // value_type
   std::allocator<basic_json> // allocator_type
@@ -14,4 +14,4 @@
     std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;
 }
 
 
Output:
 
true
-
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/at/index.html b/api/basic_json/at/index.html index e9f0b7bcd..b0b21dfa6 100644 --- a/api/basic_json/at/index.html +++ b/api/basic_json/at/index.html @@ -1,4 +1,4 @@ - at - JSON for Modern C++
Skip to content

nlohmann::basic_json::at

// (1)
+ at - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::at
 
// (1)
 reference at(size_type idx);
 const_reference at(size_type idx) const;
 
@@ -498,4 +498,4 @@
 [json.exception.out_of_range.402] array index '-' (2) is out of range
 [json.exception.out_of_range.403] key 'foo' not found
 [json.exception.out_of_range.404] unresolved reference token 'foo'
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0.
    2.  
  2. Added in version 1.0.0.
    3.  
  3. Added in version 3.11.0.
    4.  
  4. Added in version 2.0.0.
    5.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0.
  2. Added in version 1.0.0.
  3. Added in version 3.11.0.
  4. Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/back/index.html b/api/basic_json/back/index.html index 0ca847221..7af081c76 100644 --- a/api/basic_json/back/index.html +++ b/api/basic_json/back/index.html @@ -1,4 +1,4 @@ - back - JSON for Modern C++
Skip to content

nlohmann::basic_json::back

reference back();
+ back - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::back
 
reference back();
 
 const_reference back() const;
 
 
Returns a reference to the last element in the container. For a JSON container c, the expression c.back() is equivalent to
 
auto tmp = c.end();
@@ -49,4 +49,4 @@
 16
 "Hello, world"
 [json.exception.invalid_iterator.214] cannot get value
-
  
See also
 
     
  • front to access the first element
    •  
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Adjusted code to return reference to binary values in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • front to access the first element

Version history

  • Added in version 1.0.0.
  • Adjusted code to return reference to binary values in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/basic_json/index.html b/api/basic_json/basic_json/index.html index 8103653a3..ce0c24a5b 100644 --- a/api/basic_json/basic_json/index.html +++ b/api/basic_json/basic_json/index.html @@ -1,4 +1,4 @@ - (Constructor) - JSON for Modern C++
Skip to content

nlohmann::basic_json::basic_json

// (1)
+ (Constructor) - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::basic_json
 
// (1)
 basic_json(const value_t v);
 
 // (2)
@@ -458,4 +458,4 @@
 }
 
 
Output:
 
null
 23
-
  
Version history
 
     
  1. Since version 1.0.0.
    2.  
  2. Since version 1.0.0.
    3.  
  3. Since version 2.1.0.
    4.  
  4. Since version 3.2.0.
    5.  
  5. Since version 1.0.0.
    6.  
  6. Since version 1.0.0.
    7.  
  7. Since version 1.0.0.
    8.  
  8. Since version 1.0.0.
    9.  
  9. Since version 1.0.0.
    10.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Since version 1.0.0.
  2. Since version 1.0.0.
  3. Since version 2.1.0.
  4. Since version 3.2.0.
  5. Since version 1.0.0.
  6. Since version 1.0.0.
  7. Since version 1.0.0.
  8. Since version 1.0.0.
  9. Since version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/begin/index.html b/api/basic_json/begin/index.html index 987c02da5..68ebdfc13 100644 --- a/api/basic_json/begin/index.html +++ b/api/basic_json/begin/index.html @@ -1,4 +1,4 @@ - begin - JSON for Modern C++
Skip to content

nlohmann::basic_json::begin

iterator begin() noexcept;
+ begin - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::begin
 
iterator begin() noexcept;
 const_iterator begin() const noexcept;
 
 
Returns an iterator to the first element.
 
Illustration from cppreference.com
 
Return value
 
iterator to the first element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for begin().
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -17,4 +17,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
1
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/binary/index.html b/api/basic_json/binary/index.html index a1872acd6..9054fb8b9 100644 --- a/api/basic_json/binary/index.html +++ b/api/basic_json/binary/index.html @@ -1,4 +1,4 @@ - binary - JSON for Modern C++
Skip to content

nlohmann::basic_json::binary

// (1)
+ binary - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::binary
 
// (1)
 static basic_json binary(const typename binary_t::container_type& init);
 static basic_json binary(typename binary_t::container_type&& init);
 
@@ -24,4 +24,4 @@
     std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
 }
 
 
Output:
 
type: binary, subtype: 42
-
  
Version history
 
     
  • Added in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/binary_t/index.html b/api/basic_json/binary_t/index.html index 9acdb7483..3a66d2094 100644 --- a/api/basic_json/binary_t/index.html +++ b/api/basic_json/binary_t/index.html @@ -1,4 +1,4 @@ - binary_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::binary_t

using binary_t = byte_container_with_subtype<BinaryType>;
+ binary_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::binary_t
 
using binary_t = byte_container_with_subtype<BinaryType>;
 
 
This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
 
Additionally, as an implementation detail, the subtype of the binary data is carried around as a std::uint64_t, which is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is incompatible with each other, and it is up to the user to translate between them). The subtype is added to BinaryType via the helper type byte_container_with_subtype.
 
CBOR's RFC 8949 describes this type as:
 
 
Major type 2: A byte string. The number of bytes in the string is equal to the argument.
 
 
MessagePack's documentation on the bin type family describes this type as:
 
 
Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
 
 
BSON's specifications describe several binary types; however, this type is intended to represent the generic binary type which has the description:
 
 
Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and tools.
 
 
None of these impose any limitations on the internal representation other than the basic unit of storage be some type of array whose parts are decomposable into bytes.
 
The default representation of this binary format is a std::vector<std::uint8_t>, which is a very common way to represent a byte array in modern C++.
 
Template parameters
 
 
BinaryType
 
 
container type to store arrays
 
Although not formally expressed as a C++ concept, BinaryType must be default-constructible, copy/move-constructible, and support push_back(), .data(), and .size(), because byte_container_with_subtype derives directly from it. Its value_type must additionally be exactly one byte wide (e.g., std::uint8_t/char/std::byte): the binary serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via reinterpret_cast, which is only correct for byte-sized elements -- a container like std::vector<std::intptr_t> will not work as BinaryType.
 
 
 
Notes
 
Default type
 
The default values for BinaryType is std::vector<std::uint8_t>.
 
Custom BinaryType behavior
 
When a custom BinaryType is configured (other than the default std::vector<std::uint8_t>), you can assign values of that type directly to a basic_json instance, and they will automatically be recognized as binary values rather than arrays:
 
using custom_json = nlohmann::basic_json<
     nlohmann::ordered_map,  // ObjectType
     std::vector,            // ArrayType
@@ -30,4 +30,4 @@
     std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;
 }
 
 
Output:
 
true
-
  
See also
  
Version history
 
     
  • Added in version 3.8.0. Changed the type of subtype to std::uint64_t in version 3.10.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.8.0. Changed the type of subtype to std::uint64_t in version 3.10.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/boolean_t/index.html b/api/basic_json/boolean_t/index.html index 4ff621ffa..400a609ff 100644 --- a/api/basic_json/boolean_t/index.html +++ b/api/basic_json/boolean_t/index.html @@ -1,4 +1,4 @@ - boolean_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::boolean_t

using boolean_t = BooleanType;
+ boolean_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::boolean_t
 
using boolean_t = BooleanType;
 
 
The type used to store JSON booleans.
 
RFC 8259 implicitly describes a boolean as a type which differentiates the two literals true and false.
 
To store boolean values in C++, a type is defined by the template parameter BooleanType which chooses the type to use.
 
Notes
 
Default type
 
With the default values for BooleanType (bool), the default value for boolean_t is bool.
 
Storage
 
Boolean values are stored directly inside a basic_json type.
 
Examples
 
 Example 
The following code shows that boolean_t is by default, a typedef to bool.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -10,4 +10,4 @@
     std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;
 }
 
 
Output:
 
true
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/cbegin/index.html b/api/basic_json/cbegin/index.html index 776079b3e..e42bfafce 100644 --- a/api/basic_json/cbegin/index.html +++ b/api/basic_json/cbegin/index.html @@ -1,4 +1,4 @@ - cbegin - JSON for Modern C++
Skip to content

nlohmann::basic_json::cbegin

const_iterator cbegin() const noexcept;
+ cbegin - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::cbegin
 
const_iterator cbegin() const noexcept;
 
 
Returns an iterator to the first element.
 
Illustration from cppreference.com
 
Return value
 
iterator to the first element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for cbegin().
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -16,4 +16,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
1
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/cbor_tag_handler_t/index.html b/api/basic_json/cbor_tag_handler_t/index.html index 44a15e6c2..f50fa8e47 100644 --- a/api/basic_json/cbor_tag_handler_t/index.html +++ b/api/basic_json/cbor_tag_handler_t/index.html @@ -1,4 +1,4 @@ - cbor_tag_handler_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::cbor_tag_handler_t

enum class cbor_tag_handler_t
+ cbor_tag_handler_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::cbor_tag_handler_t
 
enum class cbor_tag_handler_t
 {
     error,
     ignore,
@@ -35,4 +35,4 @@
 
 
Output:
 
[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8
 {"bytes":[202,254,186,190],"subtype":null}
 {"bytes":[202,254,186,190],"subtype":66}
-
  
Version history
 
     
  • Added in version 3.9.0. Added value store in 3.10.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.9.0. Added value store in 3.10.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/cend/index.html b/api/basic_json/cend/index.html index c1c8145d5..977c0005b 100644 --- a/api/basic_json/cend/index.html +++ b/api/basic_json/cend/index.html @@ -1,4 +1,4 @@ - cend - JSON for Modern C++
Skip to content

nlohmann::basic_json::cend

const_iterator cend() const noexcept;
+ cend - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::cend
 
const_iterator cend() const noexcept;
 
 
Returns an iterator to one past the last element.
 
Illustration from cppreference.com
 
Return value
 
iterator one past the last element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for cend().
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -19,4 +19,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
5
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/clear/index.html b/api/basic_json/clear/index.html index 811bbe43f..5182f72c3 100644 --- a/api/basic_json/clear/index.html +++ b/api/basic_json/clear/index.html @@ -1,4 +1,4 @@ - clear - JSON for Modern C++
Skip to content

nlohmann::basic_json::clear

void clear() noexcept;
+ clear - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::clear
 
void clear() noexcept;
 
 
Clears the content of a JSON value and resets it to the default value as if basic_json(value_t) would have been called with the current value type from type():
 
  
 Value type initial value 
   
 null null 
 
 boolean false 
 
 string "" 
 
 number 0 
 
 binary An empty byte vector 
 
 object {} 
 
 array [] 
  
 
Has the same effect as calling
 
*this = basic_json(type());
 
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Linear in the size of the JSON value.
 
Notes
 
All iterators, pointers, and references related to this container are invalidated.
 
Examples
 
 Example 
The example below shows the effect of clear() to different JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -41,4 +41,4 @@
 {}
 []
 ""
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Added support for binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Added support for binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/contains/index.html b/api/basic_json/contains/index.html index 2f9db1abc..960c466fb 100644 --- a/api/basic_json/contains/index.html +++ b/api/basic_json/contains/index.html @@ -1,4 +1,4 @@ - contains - JSON for Modern C++
Skip to content

nlohmann::basic_json::contains

// (1)
+ contains - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::contains
 
// (1)
 bool contains(const typename object_t::key_type& key) const;
 
 // (2)
@@ -101,4 +101,4 @@
 false
 false
 false
-
  
See also
 
     
  • find find a value in an object
    •  
  • count returns the number of occurrences of a key
    •  
 
Version history
 
     
  1. Added in version 3.11.0.
    2.  
  2. Added in version 3.6.0. Extended template KeyType to support comparable types in version 3.11.0.
    3.  
  3. Added in version 3.7.0.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • find find a value in an object
  • count returns the number of occurrences of a key

Version history

  1. Added in version 3.11.0.
  2. Added in version 3.6.0. Extended template KeyType to support comparable types in version 3.11.0.
  3. Added in version 3.7.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/count/index.html b/api/basic_json/count/index.html index 79b95eb1e..faed6c609 100644 --- a/api/basic_json/count/index.html +++ b/api/basic_json/count/index.html @@ -1,4 +1,4 @@ - count - JSON for Modern C++
Skip to content

nlohmann::basic_json::count

// (1)
+ count - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::count
 
// (1)
 size_type count(const typename object_t::key_type& key) const;
 
 // (2)
@@ -46,4 +46,4 @@
 }
 
 
Output:
 
number of elements with key "two": 1
 number of elements with key "three": 0
-
  
See also
 
     
  • find find a value in an object
    •  
  • contains checks whether a key exists
    •  
 
Version history
 
     
  1. Added in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Changed parameter key type to KeyType&& in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • find find a value in an object
  • contains checks whether a key exists

Version history

  1. Added in version 3.11.0.
  2. Added in version 1.0.0. Changed parameter key type to KeyType&& in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/crbegin/index.html b/api/basic_json/crbegin/index.html index d3d4e5ae9..f190cd4d9 100644 --- a/api/basic_json/crbegin/index.html +++ b/api/basic_json/crbegin/index.html @@ -1,4 +1,4 @@ - crbegin - JSON for Modern C++
Skip to content

nlohmann::basic_json::crbegin

const_reverse_iterator crbegin() const noexcept;
+ crbegin - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::crbegin
 
const_reverse_iterator crbegin() const noexcept;
 
 
Returns an iterator to the reverse-beginning; that is, the last element.
 
Illustration from cppreference.com
 
Return value
 
reverse iterator to the last element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for crbegin().
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -16,4 +16,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
5
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/crend/index.html b/api/basic_json/crend/index.html index 9344e411c..03df0e4d7 100644 --- a/api/basic_json/crend/index.html +++ b/api/basic_json/crend/index.html @@ -1,4 +1,4 @@ - crend - JSON for Modern C++
Skip to content

nlohmann::basic_json::crend

const_reverse_iterator crend() const noexcept;
+ crend - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::crend
 
const_reverse_iterator crend() const noexcept;
 
 
Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.
 
Illustration from cppreference.com
 
Return value
 
reverse iterator to the element following the last element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for crend().
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -19,4 +19,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
1
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/default_object_comparator_t/index.html b/api/basic_json/default_object_comparator_t/index.html index ea61f8d27..b7fc793a2 100644 --- a/api/basic_json/default_object_comparator_t/index.html +++ b/api/basic_json/default_object_comparator_t/index.html @@ -1,4 +1,4 @@ - default_object_comparator_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::default_object_comparator_t

using default_object_comparator_t = std::less<StringType>;  // until C++14
+ default_object_comparator_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::default_object_comparator_t
 
using default_object_comparator_t = std::less<StringType>;  // until C++14
 
 using default_object_comparator_t = std::less<>;            // since C++14
 
 
The default comparator used by object_t.
 
Since C++14 a transparent comparator is used which prevents unnecessary string construction when looking up a key in an object.
 
The actual comparator used depends on object_t and can be obtained via object_comparator_t.
 
Examples
 
 Example 
The example below demonstrates the default comparator.
 
#include <iostream>
@@ -14,4 +14,4 @@
 }
 
 
Output:
 
one < two : true
 three < four : false
-
 
 
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/diff/index.html b/api/basic_json/diff/index.html index 53cd164b7..5e1683d8f 100644 --- a/api/basic_json/diff/index.html +++ b/api/basic_json/diff/index.html @@ -1,4 +1,4 @@ - diff - JSON for Modern C++
Skip to content

nlohmann::basic_json::diff

static basic_json diff(const basic_json& source,
+ diff - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::diff
 
static basic_json diff(const basic_json& source,
                        const basic_json& target);
 
 
Creates a JSON Patch so that value source can be changed into the value target by calling patch function.
 
For two JSON values source and target, the following code yields always true: 
source.patch(diff(source, target)) == target;
 
 
Parameters
 
 
source (in)
 
JSON value to compare from
 
target (in)
 
JSON value to compare against
 
 
Return value
 
a JSON patch to convert the source to target
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
Complexity
 
Linear in the lengths of source and target.
 
Notes
 
Currently, only remove, add, and replace operations are generated.
 
Examples
 
 Example 
The following code shows how a JSON patch is created as a diff for two JSON values.
 
#include <iostream>
@@ -63,4 +63,4 @@
         "world"
     ]
 }
-
 
 
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/dump/index.html b/api/basic_json/dump/index.html index 1d3023adb..6f732a5ae 100644 --- a/api/basic_json/dump/index.html +++ b/api/basic_json/dump/index.html @@ -1,4 +1,4 @@ - dump - JSON for Modern C++
Skip to content

nlohmann::basic_json::dump

string_t dump(const int indent = -1,
+ dump - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::dump
 
string_t dump(const int indent = -1,
               const char indent_char = ' ',
               const bool ensure_ascii = false,
               const error_handler_t error_handler = error_handler_t::strict) const;
@@ -105,4 +105,4 @@
 [json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
 string with replaced invalid characters: "ä�ü"
 string with ignored invalid characters: "äü"
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Indentation character indent_char, option ensure_ascii and exceptions added in version 3.0.0.
    •  
  • Error handlers added in version 3.4.0.
    •  
  • Serialization of binary values added in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Indentation character indent_char, option ensure_ascii and exceptions added in version 3.0.0.
  • Error handlers added in version 3.4.0.
  • Serialization of binary values added in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/emplace/index.html b/api/basic_json/emplace/index.html index 8136e658d..9d787a7be 100644 --- a/api/basic_json/emplace/index.html +++ b/api/basic_json/emplace/index.html @@ -1,4 +1,4 @@ - emplace - JSON for Modern C++
Skip to content

nlohmann::basic_json::emplace

template<class... Args>
+ emplace - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::emplace
 
template<class... Args>
 std::pair<iterator, bool> emplace(Args&& ... args);
 
 
Inserts a new element into a JSON object constructed in-place with the given args if there is no element with the key in the container. If the function is called on a JSON null value, an empty object is created before appending the value created from args.
 
Template parameters
 
 
Args
 
compatible types to create a basic_json object
 
 
Iterator invalidation
 
For ordered_json, adding a value to an object can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.
 
Parameters
 
 
args (in)
 
arguments to forward to a constructor of basic_json
 
 
Return value
 
a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 
Exceptions
 
Throws type_error.311 when called on a type other than JSON object or null; example: "cannot use emplace() with number"
 
Complexity
 
Logarithmic in the size of the container, O(log(size())).
 
Examples
 
 Example 
The example shows how emplace() can be used to add elements to a JSON object. Note how the null value was silently converted to a JSON object. Further note how no value is added if there was already one value stored with the same key.
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -37,4 +37,4 @@
 3 true
 {"A":"a","B":"b"}
 "b" false
-
 
 
See also
  
Version history
 
     
  • Since version 2.0.8.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Since version 2.0.8.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/emplace_back/index.html b/api/basic_json/emplace_back/index.html index a028a9eb3..90bd7cfd2 100644 --- a/api/basic_json/emplace_back/index.html +++ b/api/basic_json/emplace_back/index.html @@ -1,4 +1,4 @@ - emplace_back - JSON for Modern C++
Skip to content

nlohmann::basic_json::emplace_back

template<class... Args>
+ emplace_back - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::emplace_back
 
template<class... Args>
 reference emplace_back(Args&& ... args);
 
 
Creates a JSON value from the passed parameters args to the end of the JSON value. If the function is called on a JSON null value, an empty array is created before appending the value created from args.
 
Template parameters
 
 
Args
 
compatible types to create a basic_json object
 
 
Iterator invalidation
 
By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise, only the end() iterator is invalidated.
 
Parameters
 
 
args (in)
 
arguments to forward to a constructor of basic_json
 
 
Return value
 
reference to the inserted element
 
Exceptions
 
Throws type_error.311 when called on a type other than JSON array or null; example: "cannot use emplace_back() with number"
 
Complexity
 
Amortized constant.
 
Examples
 
 Example 
The example shows how emplace_back() can be used to add elements to a JSON array. Note how the null value was silently converted to a JSON array.
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -28,4 +28,4 @@
 null
 [1,2,3,4,5,6]
 ["first",["second","second","second"]]
-
 
 
See also
  
Version history
 
     
  • Since version 2.0.8.
    •  
  • Returns reference since 3.7.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Since version 2.0.8.
  • Returns reference since 3.7.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/empty/index.html b/api/basic_json/empty/index.html index 90cd596fe..281bdb27b 100644 --- a/api/basic_json/empty/index.html +++ b/api/basic_json/empty/index.html @@ -1,4 +1,4 @@ - empty - JSON for Modern C++
Skip to content

nlohmann::basic_json::empty

bool empty() const noexcept;
+ empty - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::empty
 
bool empty() const noexcept;
 
 
Checks if a JSON value has no elements (i.e., whether its size() is 0).
 
Return value
 
The return value depends on the different types and is defined as follows:
 
  
 Value type return value 
   
 null true 
 
 boolean false 
 
 string false 
 
 number false 
 
 binary false 
 
 object result of function object_t::empty() 
 
 array result of function array_t::empty() 
  
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant, as long as array_t and object_t satisfy the Container concept; that is, their empty() functions have constant complexity.
 
Possible implementation
 
bool empty() const noexcept
 {
     return size() == 0;
@@ -42,4 +42,4 @@
 false
 true
 false
-
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to return false for binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Extended to return false for binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/end/index.html b/api/basic_json/end/index.html index 944f6243c..fad6b32f4 100644 --- a/api/basic_json/end/index.html +++ b/api/basic_json/end/index.html @@ -1,4 +1,4 @@ - end - JSON for Modern C++
Skip to content

nlohmann::basic_json::end

iterator end() noexcept;
+ end - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::end
 
iterator end() noexcept;
 const_iterator end() const noexcept;
 
 
Returns an iterator to one past the last element.
 
Illustration from cppreference.com
 
Return value
 
iterator one past the last element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for end().
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -20,4 +20,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
5
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/end_pos/index.html b/api/basic_json/end_pos/index.html index 2d909015d..e7eb95528 100644 --- a/api/basic_json/end_pos/index.html +++ b/api/basic_json/end_pos/index.html @@ -1,4 +1,4 @@ - end_pos - JSON for Modern C++
Skip to content

nlohmann::basic_json::end_pos

#if JSON_DIAGNOSTIC_POSITIONS
+ end_pos - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::end_pos
 
#if JSON_DIAGNOSTIC_POSITIONS
 constexpr std::size_t end_pos() const noexcept;
 #endif
 
 
Returns the position immediately following the last character of the JSON string from which the value was parsed from.
 
  
 JSON type return value 
   
 object position after the closing } 
 
 array position after the closing ] 
 
 string position after the closing " 
 
 number position after the last character 
 
 boolean position after e 
 
 null position after l 
  
 
Return value
 
the position of the character following the last character of the given value in the parsed JSON string, if the value was created by the parse function, or std::string::npos if the value was constructed otherwise
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Notes
 
 
Note
 
The function is only available if macro JSON_DIAGNOSTIC_POSITIONS has been defined to 1 before including the library header.
 
 
 
Invalidation
 
The returned positions are only valid as long as the JSON value is not changed. The positions are not updated when the JSON value is changed.
 
 
Examples
 
 Example 
#include <iostream>
@@ -101,4 +101,4 @@ Original string:
 1
 Parsed string: 
 1
-
 
The output shows the start/end positions of all the objects and fields in the JSON string.
 
 
See also
  
Version history
 
     
  • Added in version 3.12.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

The output shows the start/end positions of all the objects and fields in the JSON string.

See also

Version history

  • Added in version 3.12.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/erase/index.html b/api/basic_json/erase/index.html index 7da7d62da..a0101bfd3 100644 --- a/api/basic_json/erase/index.html +++ b/api/basic_json/erase/index.html @@ -1,4 +1,4 @@ - erase - JSON for Modern C++
Skip to content

nlohmann::basic_json::erase

// (1)
+ erase - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::erase
 
// (1)
 iterator erase(iterator pos);
 const_iterator erase(const_iterator pos);
 
@@ -148,4 +148,4 @@
     std::cout << j_array << '\n';
 }
 
 
Output:
 
[0,1,3,4,5]
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
    2.  
  2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
    3.  
  3. Added in version 1.0.0.
    4.  
  4. Added in version 3.11.0.
    5.  
  5. Added in version 1.0.0.
    6.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
  2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
  3. Added in version 1.0.0.
  4. Added in version 3.11.0.
  5. Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/error_handler_t/index.html b/api/basic_json/error_handler_t/index.html index 5c6ff8129..07f5d680d 100644 --- a/api/basic_json/error_handler_t/index.html +++ b/api/basic_json/error_handler_t/index.html @@ -1,4 +1,4 @@ - error_handler_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::error_handler_t

enum class error_handler_t {
+ error_handler_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::error_handler_t
 
enum class error_handler_t {
     strict,
     replace,
     ignore
@@ -30,4 +30,4 @@
 
 
Output:
 
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
 string with replaced invalid characters: "ä�ü"
 string with ignored invalid characters: "äü"
-
  
Version history
 
     
  • Added in version 3.4.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.4.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/exception/index.html b/api/basic_json/exception/index.html index 6747b9066..c75b12b36 100644 --- a/api/basic_json/exception/index.html +++ b/api/basic_json/exception/index.html @@ -1,4 +1,4 @@ - exception - JSON for Modern C++
Skip to content

nlohmann::basic_json::exception

class exception : public std::exception;
+ exception - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::exception
 
class exception : public std::exception;
 
 
This class is an extension of std::exception objects with a member id for exception ids. It is used as the base class for all exceptions thrown by the basic_json class. This class can hence be used as "wildcard" to catch exceptions, see example below.
 
classDiagram
   direction LR
 
@@ -49,4 +49,4 @@
 }
 
 
Output:
 
message: [json.exception.out_of_range.403] key 'non-existing' not found
 exception id: 403
-
  
See also
 
List of exceptions
 
Version history
 
     
  • Since version 3.0.0.
    •
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

List of exceptions

Version history

\ No newline at end of file diff --git a/api/basic_json/find/index.html b/api/basic_json/find/index.html index f94186ad7..ad149bd50 100644 --- a/api/basic_json/find/index.html +++ b/api/basic_json/find/index.html @@ -1,4 +1,4 @@ - find - JSON for Modern C++
Skip to content

nlohmann::basic_json::find

// (1)
+ find - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::find
 
// (1)
 iterator find(const typename object_t::key_type& key);
 const_iterator find(const typename object_t::key_type& key) const;
 
@@ -55,4 +55,4 @@
 
 
Output:
 
"two" was found: true
 value at key "two": 2
 "three" was found: false
-
  
See also
 
     
  • count returns the number of occurrences of a key
    •  
  • contains checks whether a key exists
    •  
 
Version history
 
     
  1. Added in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • count returns the number of occurrences of a key
  • contains checks whether a key exists

Version history

  1. Added in version 3.11.0.
  2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/flatten/index.html b/api/basic_json/flatten/index.html index 0d1954543..124e0c79c 100644 --- a/api/basic_json/flatten/index.html +++ b/api/basic_json/flatten/index.html @@ -1,4 +1,4 @@ - flatten - JSON for Modern C++
Skip to content

nlohmann::basic_json::flatten

basic_json flatten() const;
+ flatten - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::flatten
 
basic_json flatten() const;
 
 
The function creates a JSON object whose keys are JSON pointers (see RFC 6901) and whose values are all primitive (see is_primitive() for more information). The original JSON value can be restored using the unflatten() function.
 
Return value
 
an object that maps JSON pointers to primitive values
 
Exception safety
 
Strong exception safety: if an exception occurs, the original value stays intact.
 
Complexity
 
Linear in the size of the JSON value.
 
Notes
 
Empty objects and arrays are flattened to null and will not be reconstructed correctly by the unflatten() function.
 
Examples
 
 Example 
The following code shows how a JSON object is flattened to an object whose keys consist of JSON pointers.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -43,4 +43,4 @@
     "/object/value": 42.99,
     "/pi": 3.141
 }
-
 
 
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/format_as/index.html b/api/basic_json/format_as/index.html index 536aaf266..7ddd50f6b 100644 --- a/api/basic_json/format_as/index.html +++ b/api/basic_json/format_as/index.html @@ -1,4 +1,4 @@ - format_as - JSON for Modern C++
Skip to content

format_as(basic_json)

template <typename BasicJsonType>
+ format_as - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
format_as(basic_json)
 
template <typename BasicJsonType>
 std::string format_as(const BasicJsonType& j);
 
 
This function implements the format_as customization point used by the {fmt} library (fmtlib). It has no dependency on any fmt header and no effect at all unless a caller's translation unit also includes fmt and calls fmt::format/fmt::print on a JSON value.
 
Template parameters
 
 
BasicJsonType
 
a specialization of basic_json
 
 
Return value
 
string containing the serialization of the JSON value (same as dump())
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 
Exceptions
 
Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded
 
Complexity
 
Linear.
 
Possible implementation
 
template <typename BasicJsonType>
 std::string format_as(const BasicJsonType& j)
@@ -84,4 +84,4 @@
     std::cout << j_str << std::endl;
 }
 
 
Output:
 
{"one":1,"two":2}
-
  
See also
  
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/from_bjdata/index.html b/api/basic_json/from_bjdata/index.html index c3e12b5d3..6481c42c4 100644 --- a/api/basic_json/from_bjdata/index.html +++ b/api/basic_json/from_bjdata/index.html @@ -1,4 +1,4 @@ - from_bjdata - JSON for Modern C++
Skip to content

nlohmann::basic_json::from_bjdata

// (1)
+ from_bjdata - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::from_bjdata
 
// (1)
 template<typename InputType>
 static basic_json from_bjdata(InputType&& i,
                               const bool strict = true,
@@ -32,4 +32,4 @@
   "compact": true,
   "schema": 0
 }
-
  
See also
 
     
  • to_bjdata create a BJData serialization of a JSON value
    •  
  • from_cbor create a JSON value from an input in CBOR format
    •  
  • from_msgpack create a JSON value from an input in MessagePack format
    •  
  • from_bson create a JSON value from an input in BSON format
    •  
  • from_ubjson create a JSON value from an input in UBJSON format
    •  
 
Version history
 
     
  • Added in version 3.11.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • to_bjdata create a BJData serialization of a JSON value
  • from_cbor create a JSON value from an input in CBOR format
  • from_msgpack create a JSON value from an input in MessagePack format
  • from_bson create a JSON value from an input in BSON format
  • from_ubjson create a JSON value from an input in UBJSON format

Version history

  • Added in version 3.11.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/from_bson/index.html b/api/basic_json/from_bson/index.html index 6ea586097..3429bc330 100644 --- a/api/basic_json/from_bson/index.html +++ b/api/basic_json/from_bson/index.html @@ -1,4 +1,4 @@ - from_bson - JSON for Modern C++
Skip to content

nlohmann::basic_json::from_bson

// (1)
+ from_bson - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::from_bson
 
// (1)
 template<typename InputType>
 static basic_json from_bson(InputType&& i,
                             const bool strict = true,
@@ -33,4 +33,4 @@
   "compact": true,
   "schema": 0
 }
-
  
See also
  
Version history
 
     
  • Added in version 3.4.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
     
  • Overload (2) replaces calls to from_bson with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_bson(ptr, len, ...); with from_bson(ptr, ptr+len, ...);.
    •  
  • Overload (2) replaces calls to from_bson with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_bson({ptr, ptr+len}, ...); with from_bson(ptr, ptr+len, ...);.
    •  
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.4.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

  • Overload (2) replaces calls to from_bson with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_bson(ptr, len, ...); with from_bson(ptr, ptr+len, ...);.
  • Overload (2) replaces calls to from_bson with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_bson({ptr, ptr+len}, ...); with from_bson(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/from_cbor/index.html b/api/basic_json/from_cbor/index.html index 77603b0c8..b958657d5 100644 --- a/api/basic_json/from_cbor/index.html +++ b/api/basic_json/from_cbor/index.html @@ -1,4 +1,4 @@ - from_cbor - JSON for Modern C++
Skip to content

nlohmann::basic_json::from_cbor

// (1)
+ from_cbor - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::from_cbor
 
// (1)
 template<typename InputType>
 static basic_json from_cbor(InputType&& i,
                             const bool strict = true,
@@ -35,4 +35,4 @@
   "compact": true,
   "schema": 0
 }
-
  
See also
 
     
  • to_cbor create a CBOR serialization of a JSON value
    •  
  • from_msgpack create a JSON value from an input in MessagePack format
    •  
  • from_bson create a JSON value from an input in BSON format
    •  
  • from_ubjson create a JSON value from an input in UBJSON format
    •  
  • from_bjdata create a JSON value from an input in BJData format
    •  
 
Version history
 
     
  • Added in version 2.0.9.
    •  
  • Parameter start_index since version 2.1.1.
    •  
  • Changed to consume input adapters, removed start_index parameter, and added strict parameter in version 3.0.0.
    •  
  • Added allow_exceptions parameter in version 3.2.0.
    •  
  • Added tag_handler parameter in version 3.9.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
     
  • Overload (2) replaces calls to from_cbor with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_cbor(ptr, len, ...); with from_cbor(ptr, ptr+len, ...);.
    •  
  • Overload (2) replaces calls to from_cbor with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_cbor({ptr, ptr+len}, ...); with from_cbor(ptr, ptr+len, ...);.
    •  
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • to_cbor create a CBOR serialization of a JSON value
  • from_msgpack create a JSON value from an input in MessagePack format
  • from_bson create a JSON value from an input in BSON format
  • from_ubjson create a JSON value from an input in UBJSON format
  • from_bjdata create a JSON value from an input in BJData format

Version history

  • Added in version 2.0.9.
  • Parameter start_index since version 2.1.1.
  • Changed to consume input adapters, removed start_index parameter, and added strict parameter in version 3.0.0.
  • Added allow_exceptions parameter in version 3.2.0.
  • Added tag_handler parameter in version 3.9.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

  • Overload (2) replaces calls to from_cbor with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_cbor(ptr, len, ...); with from_cbor(ptr, ptr+len, ...);.
  • Overload (2) replaces calls to from_cbor with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_cbor({ptr, ptr+len}, ...); with from_cbor(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/from_msgpack/index.html b/api/basic_json/from_msgpack/index.html index 93bec56ed..34e4c9c95 100644 --- a/api/basic_json/from_msgpack/index.html +++ b/api/basic_json/from_msgpack/index.html @@ -1,4 +1,4 @@ - from_msgpack - JSON for Modern C++
Skip to content

nlohmann::basic_json::from_msgpack

// (1)
+ from_msgpack - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::from_msgpack
 
// (1)
 template<typename InputType>
 static basic_json from_msgpack(InputType&& i,
                                const bool strict = true,
@@ -32,4 +32,4 @@
   "compact": true,
   "schema": 0
 }
-
  
See also
 
     
  • to_msgpack create a MessagePack serialization of a JSON value
    •  
  • from_cbor create a JSON value from an input in CBOR format
    •  
  • from_bson create a JSON value from an input in BSON format
    •  
  • from_ubjson create a JSON value from an input in UBJSON format
    •  
  • from_bjdata create a JSON value from an input in BJData format
    •  
 
Version history
 
     
  • Added in version 2.0.9.
    •  
  • Parameter start_index since version 2.1.1.
    •  
  • Changed to consume input adapters, removed start_index parameter, and added strict parameter in version 3.0.0.
    •  
  • Added allow_exceptions parameter in version 3.2.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
     
  • Overload (2) replaces calls to from_msgpack with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_msgpack(ptr, len, ...); with from_msgpack(ptr, ptr+len, ...);.
    •  
  • Overload (2) replaces calls to from_msgpack with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_msgpack({ptr, ptr+len}, ...); with from_msgpack(ptr, ptr+len, ...);.
    •  
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • to_msgpack create a MessagePack serialization of a JSON value
  • from_cbor create a JSON value from an input in CBOR format
  • from_bson create a JSON value from an input in BSON format
  • from_ubjson create a JSON value from an input in UBJSON format
  • from_bjdata create a JSON value from an input in BJData format

Version history

  • Added in version 2.0.9.
  • Parameter start_index since version 2.1.1.
  • Changed to consume input adapters, removed start_index parameter, and added strict parameter in version 3.0.0.
  • Added allow_exceptions parameter in version 3.2.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

  • Overload (2) replaces calls to from_msgpack with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_msgpack(ptr, len, ...); with from_msgpack(ptr, ptr+len, ...);.
  • Overload (2) replaces calls to from_msgpack with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_msgpack({ptr, ptr+len}, ...); with from_msgpack(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/from_ubjson/index.html b/api/basic_json/from_ubjson/index.html index 378da5a00..6ce2d7153 100644 --- a/api/basic_json/from_ubjson/index.html +++ b/api/basic_json/from_ubjson/index.html @@ -1,4 +1,4 @@ - from_ubjson - JSON for Modern C++
Skip to content

nlohmann::basic_json::from_ubjson

// (1)
+ from_ubjson - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::from_ubjson
 
// (1)
 template<typename InputType>
 static basic_json from_ubjson(InputType&& i,
                               const bool strict = true,
@@ -32,4 +32,4 @@
   "compact": true,
   "schema": 0
 }
-
  
See also
 
     
  • to_ubjson create a UBJSON serialization of a JSON value
    •  
  • from_cbor create a JSON value from an input in CBOR format
    •  
  • from_msgpack create a JSON value from an input in MessagePack format
    •  
  • from_bson create a JSON value from an input in BSON format
    •  
  • from_bjdata create a JSON value from an input in BJData format
    •  
 
Version history
 
     
  • Added in version 3.1.0.
    •  
  • Added allow_exceptions parameter in version 3.2.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
     
  • Overload (2) replaces calls to from_ubjson with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_ubjson(ptr, len, ...); with from_ubjson(ptr, ptr+len, ...);.
    •  
  • Overload (2) replaces calls to from_ubjson with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_ubjson({ptr, ptr+len}, ...); with from_ubjson(ptr, ptr+len, ...);.
    •  
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • to_ubjson create a UBJSON serialization of a JSON value
  • from_cbor create a JSON value from an input in CBOR format
  • from_msgpack create a JSON value from an input in MessagePack format
  • from_bson create a JSON value from an input in BSON format
  • from_bjdata create a JSON value from an input in BJData format

Version history

  • Added in version 3.1.0.
  • Added allow_exceptions parameter in version 3.2.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

  • Overload (2) replaces calls to from_ubjson with a pointer and a length as first two parameters, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_ubjson(ptr, len, ...); with from_ubjson(ptr, ptr+len, ...);.
  • Overload (2) replaces calls to from_ubjson with a pair of iterators as their first parameter, which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like from_ubjson({ptr, ptr+len}, ...); with from_ubjson(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/front/index.html b/api/basic_json/front/index.html index 145aa7809..f272300e0 100644 --- a/api/basic_json/front/index.html +++ b/api/basic_json/front/index.html @@ -1,4 +1,4 @@ - front - JSON for Modern C++
Skip to content

nlohmann::basic_json::front

reference front();
+ front - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::front
 
reference front();
 const_reference front() const;
 
 
Returns a reference to the first element in the container. For a JSON container c, the expression c.front() is equivalent to *c.begin().
 
Return value
 
In the case of a structured type (array or object), a reference to the first element is returned. In the case of number, string, boolean, or binary values, a reference to the value is returned.
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
Exceptions
 
If the JSON value is null, exception invalid_iterator.214 is thrown.
 
Complexity
 
Constant.
 
Notes
 
 
Precondition
 
The array or object must not be empty. Calling front on an empty array or object yields undefined behavior.
 
 
Examples
 
 Example 
The following code shows an example for front().
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -35,4 +35,4 @@
 1
 1
 "Hello, world"
-
 
 
See also
 
     
  • back to access the last element
    •  
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Adjusted code to return reference to binary values in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • back to access the last element

Version history

  • Added in version 1.0.0.
  • Adjusted code to return reference to binary values in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/get/index.html b/api/basic_json/get/index.html index 283e1ac8f..e5fc1a339 100644 --- a/api/basic_json/get/index.html +++ b/api/basic_json/get/index.html @@ -1,4 +1,4 @@ - get - JSON for Modern C++
Skip to content

nlohmann::basic_json::get

// (1)
+ get - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::get
 
// (1)
 template<typename ValueType>
 ValueType get() const noexcept(
     noexcept(JSONSerializer<ValueType>::from_json(
@@ -103,4 +103,4 @@
 }
 
 
Output:
 
17 17 17 17
 true
-
  
See also
  
Version history
 
     
  1. Since version 2.1.0.
    2.  
  2. Since version 2.1.0. Extended to work with other specializations of basic_json in version 3.2.0.
    3.  
  3. Since version 1.0.0.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Since version 2.1.0.
  2. Since version 2.1.0. Extended to work with other specializations of basic_json in version 3.2.0.
  3. Since version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/get_allocator/index.html b/api/basic_json/get_allocator/index.html index 109e4911a..5b9a2f6a7 100644 --- a/api/basic_json/get_allocator/index.html +++ b/api/basic_json/get_allocator/index.html @@ -1,4 +1,4 @@ - get_allocator - JSON for Modern C++
Skip to content

nlohmann::basic_json::get_allocator

static allocator_type get_allocator();
+ get_allocator - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::get_allocator
 
static allocator_type get_allocator();
 
 
Returns the allocator associated with the container.
 
Return value
 
associated allocator
 
Examples
 
 Example 
The example shows how get_allocator() is used to created json values.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -18,4 +18,4 @@
     traits_t::deallocate(alloc, j, 1);
 }
 
 
Output:
 
"Hello, world!"
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/get_binary/index.html b/api/basic_json/get_binary/index.html index 1631050e3..b155a257f 100644 --- a/api/basic_json/get_binary/index.html +++ b/api/basic_json/get_binary/index.html @@ -1,4 +1,4 @@ - get_binary - JSON for Modern C++
Skip to content

nlohmann::basic_json::get_binary

binary_t& get_binary();
+ get_binary - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::get_binary
 
binary_t& get_binary();
 
 const binary_t& get_binary() const;
 
 
Returns a reference to the stored binary value.
 
Return value
 
Reference to binary value.
 
Exception safety
 
Strong exception safety: if an exception occurs, the original value stays intact.
 
Exceptions
 
Throws type_error.302 if the value is not binary
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows how to query a binary value.
 
#include <iostream>
@@ -18,4 +18,4 @@
     std::cout << "type: " << j.type_name() << ", subtype: " << j.get_binary().subtype() << std::endl;
 }
 
 
Output:
 
type: binary, subtype: 42
-
 
 
See also
 
     
  • get get a value (explicit conversion)
    •  
  • get_ref get a reference to the stored value
    •  
 
Version history
 
     
  • Added in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • get get a value (explicit conversion)
  • get_ref get a reference to the stored value

Version history

  • Added in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/get_ptr/index.html b/api/basic_json/get_ptr/index.html index da6679964..40dc649b3 100644 --- a/api/basic_json/get_ptr/index.html +++ b/api/basic_json/get_ptr/index.html @@ -1,4 +1,4 @@ - get_ptr - JSON for Modern C++
Skip to content

nlohmann::basic_json::get_ptr

template<typename PointerType>
+ get_ptr - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::get_ptr
 
template<typename PointerType>
 PointerType get_ptr() noexcept;
 
 template<typename PointerType>
@@ -44,4 +44,4 @@ value at 0x6000029fc088 is 1
 }
 
 
Output:
 
17 17 17 17
 true
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Extended to binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/get_ref/index.html b/api/basic_json/get_ref/index.html index d9d425f91..e1af23689 100644 --- a/api/basic_json/get_ref/index.html +++ b/api/basic_json/get_ref/index.html @@ -1,4 +1,4 @@ - get_ref - JSON for Modern C++
Skip to content

nlohmann::basic_json::get_ref

template<typename ReferenceType>
+ get_ref - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::get_ref
 
template<typename ReferenceType>
 ReferenceType get_ref();
 
 template<typename ReferenceType>
@@ -32,4 +32,4 @@
 }
 
 
Output:
 
17 17
 [json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is number
-
  
See also
  
Version history
 
     
  • Added in version 1.1.0.
    •  
  • Extended to binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.1.0.
  • Extended to binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/get_to/index.html b/api/basic_json/get_to/index.html index 9dd4a679b..bd1cb7e8e 100644 --- a/api/basic_json/get_to/index.html +++ b/api/basic_json/get_to/index.html @@ -1,4 +1,4 @@ - get_to - JSON for Modern C++
Skip to content

nlohmann::basic_json::get_to

template<typename ValueType>
+ get_to - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::get_to
 
template<typename ValueType>
 ValueType& get_to(ValueType& v) const noexcept(
     noexcept(JSONSerializer<ValueType>::from_json(
         std::declval<const basic_json_t&>(), v)));
@@ -74,4 +74,4 @@
 null: null
 boolean: true
 array: [1,2,3,4,5]
-
  
See also
 
     
  • get get a value (explicit conversion)
    •  
  • get_ref get a reference to the stored value
    •  
  • get_ptr get a pointer to the stored value
    •  
  • Converting values - the type conversions article
    •  
 
Version history
 
     
  • Since version 3.3.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • get get a value (explicit conversion)
  • get_ref get a reference to the stored value
  • get_ptr get a pointer to the stored value
  • Converting values - the type conversions article

Version history

  • Since version 3.3.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/index.html b/api/basic_json/index.html index e923b9a92..d973d2aa7 100644 --- a/api/basic_json/index.html +++ b/api/basic_json/index.html @@ -1,4 +1,4 @@ - Overview - JSON for Modern C++
Skip to content

nlohmann::basic_json

Defined in header <nlohmann/json.hpp>

template<
+ Overview - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json
 
Defined in header <nlohmann/json.hpp>
 
template<
     template<typename U, typename V, typename... Args> class ObjectType = std::map,
     template<typename U, typename... Args> class ArrayType = std::vector,
     class StringType = std::string,
@@ -78,4 +78,4 @@
     "pi": 3.141,
     "size": 8
 }
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/input_format_t/index.html b/api/basic_json/input_format_t/index.html index 40248802d..a9e660f43 100644 --- a/api/basic_json/input_format_t/index.html +++ b/api/basic_json/input_format_t/index.html @@ -1,4 +1,4 @@ - input_format_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::input_format_t

enum class input_format_t {
+ input_format_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::input_format_t
 
enum class input_format_t {
     json,
     cbor,
     msgpack,
@@ -123,4 +123,4 @@
 
 
Output:
 
binary(val=[...])
 
 result: true
-
  
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/insert/index.html b/api/basic_json/insert/index.html index 83808cfca..d51275b6d 100644 --- a/api/basic_json/insert/index.html +++ b/api/basic_json/insert/index.html @@ -1,4 +1,4 @@ - insert - JSON for Modern C++
Skip to content

nlohmann::basic_json::insert

// (1)
+ insert - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::insert
 
// (1)
 iterator insert(const_iterator pos, const basic_json& val);
 iterator insert(const_iterator pos, basic_json&& val);
 
@@ -116,4 +116,4 @@
 
 
Output:
 
{"one":"eins","two":"zwei"}
 {"eleven":"elf","seventeen":"siebzehn"}
 {"eleven":"elf","one":"eins","seventeen":"siebzehn","two":"zwei"}
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0.
    2.  
  2. Added in version 1.0.0.
    3.  
  3. Added in version 1.0.0.
    4.  
  4. Added in version 1.0.0.
    5.  
  5. Added in version 3.0.0.
    6.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0.
  2. Added in version 1.0.0.
  3. Added in version 1.0.0.
  4. Added in version 1.0.0.
  5. Added in version 3.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/invalid_iterator/index.html b/api/basic_json/invalid_iterator/index.html index 5dd9f6650..eb1a2cd6d 100644 --- a/api/basic_json/invalid_iterator/index.html +++ b/api/basic_json/invalid_iterator/index.html @@ -1,4 +1,4 @@ - invalid_iterator - JSON for Modern C++
Skip to content

nlohmann::basic_json::invalid_iterator

class invalid_iterator : public exception;
+ invalid_iterator - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::invalid_iterator
 
class invalid_iterator : public exception;
 
 
This exception is thrown if iterators passed to a library function do not match the expected semantics.
 
Exceptions have ids 2xx (see list of iterator errors).
 
classDiagram
   direction LR
 
@@ -50,4 +50,4 @@
 }
 
 
Output:
 
message: [json.exception.invalid_iterator.207] cannot use key() for non-object iterators
 exception id: 207
-
  
See also
  
Version history
 
     
  • Since version 3.0.0.
    •
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

Version history

\ No newline at end of file diff --git a/api/basic_json/is_array/index.html b/api/basic_json/is_array/index.html index 8e85c4f9e..91821f1a5 100644 --- a/api/basic_json/is_array/index.html +++ b/api/basic_json/is_array/index.html @@ -1,4 +1,4 @@ - is_array - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_array

constexpr bool is_array() const noexcept;
+ is_array - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_array
 
constexpr bool is_array() const noexcept;
 
 
This function returns true if and only if the JSON value is an array.
 
Return value
 
true if type is an array, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_array() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 true
 false
 false
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_binary/index.html b/api/basic_json/is_binary/index.html index f704730b1..8926f9b46 100644 --- a/api/basic_json/is_binary/index.html +++ b/api/basic_json/is_binary/index.html @@ -1,4 +1,4 @@ - is_binary - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_binary

constexpr bool is_binary() const noexcept;
+ is_binary - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_binary
 
constexpr bool is_binary() const noexcept;
 
 
This function returns true if and only if the JSON value is a binary array.
 
Return value
 
true if type is binary, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_binary() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 true
-
 
 
Version history
 
     
  • Added in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_boolean/index.html b/api/basic_json/is_boolean/index.html index 9936c3993..ba86d563f 100644 --- a/api/basic_json/is_boolean/index.html +++ b/api/basic_json/is_boolean/index.html @@ -1,4 +1,4 @@ - is_boolean - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_boolean

constexpr bool is_boolean() const noexcept;
+ is_boolean - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_boolean
 
constexpr bool is_boolean() const noexcept;
 
 
This function returns true if and only if the JSON value is true or false.
 
Return value
 
true if type is boolean, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_boolean() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 false
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_discarded/index.html b/api/basic_json/is_discarded/index.html index b2e124dbc..04b28504f 100644 --- a/api/basic_json/is_discarded/index.html +++ b/api/basic_json/is_discarded/index.html @@ -1,4 +1,4 @@ - is_discarded - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_discarded

constexpr bool is_discarded() const noexcept;
+ is_discarded - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_discarded
 
constexpr bool is_discarded() const noexcept;
 
 
This function returns true for a JSON value if either:
 
     
  • the value was discarded during parsing with a callback function (see parser_callback_t), or
    •  
  • the value is the result of parsing invalid JSON with parameter allow_exceptions set to false; see parse for more information.
    •  
 
Return value
 
true if type is discarded, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Notes
 
 
Comparisons
 
Discarded values are never compared equal with operator==. That is, checking whether a JSON value j is discarded will only work via:
 
j.is_discarded()
 
 
because
 
j == json::value_t::discarded
 
 
will always be false.
 
 
 
Removal during parsing with callback functions
 
When a value is discarded by a callback function (see parser_callback_t) during parsing, then it is removed when it is part of a structured value. For instance, if the second value of an array is discarded, instead of [null, discarded, false], the array [null, false] is returned. If the top-level value itself is discarded by the callback, the parse call returns a null value.
 
 
After a successful parse, this function always returns false: discarded values can only occur during parsing and are either removed when inside a structured value or replaced by null at the top level. The exception is parsing with allow_exceptions set to false: a parse error then yields a discarded value for which this function returns true (see parse).
 
Examples
 
 Example 
The following code exemplifies is_discarded() for all JSON types.
 
#include <iostream>
@@ -40,4 +40,4 @@
 false
 false
 false
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_null/index.html b/api/basic_json/is_null/index.html index f97e7256b..3c613afd5 100644 --- a/api/basic_json/is_null/index.html +++ b/api/basic_json/is_null/index.html @@ -1,4 +1,4 @@ - is_null - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_null

constexpr bool is_null() const noexcept;
+ is_null - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_null
 
constexpr bool is_null() const noexcept;
 
 
This function returns true if and only if the JSON value is null.
 
Return value
 
true if type is null, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_null() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 false
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_number/index.html b/api/basic_json/is_number/index.html index 4dff5a299..36fac1d9b 100644 --- a/api/basic_json/is_number/index.html +++ b/api/basic_json/is_number/index.html @@ -1,4 +1,4 @@ - is_number - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_number

constexpr bool is_number() const noexcept;
+ is_number - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_number
 
constexpr bool is_number() const noexcept;
 
 
This function returns true if and only if the JSON value is a number. This includes both integer (signed and unsigned) and floating-point values.
 
Return value
 
true if type is number (regardless whether integer, unsigned integer, or floating-point), false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Possible implementation
 
constexpr bool is_number() const noexcept
 {
     return is_number_integer() || is_number_float();
@@ -42,4 +42,4 @@
 false
 false
 false
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to also return true for unsigned integers in 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Extended to also return true for unsigned integers in 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_number_float/index.html b/api/basic_json/is_number_float/index.html index 9d306b916..4b0e4508b 100644 --- a/api/basic_json/is_number_float/index.html +++ b/api/basic_json/is_number_float/index.html @@ -1,4 +1,4 @@ - is_number_float - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_number_float

constexpr bool is_number_float() const noexcept;
+ is_number_float - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_number_float
 
constexpr bool is_number_float() const noexcept;
 
 
This function returns true if and only if the JSON value is a floating-point number. This excludes signed and unsigned integer values.
 
Return value
 
true if type is a floating-point number, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_number_float() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 false
-
 
 
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_number_integer/index.html b/api/basic_json/is_number_integer/index.html index 68537e872..07f76d594 100644 --- a/api/basic_json/is_number_integer/index.html +++ b/api/basic_json/is_number_integer/index.html @@ -1,4 +1,4 @@ - is_number_integer - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_number_integer

constexpr bool is_number_integer() const noexcept;
+ is_number_integer - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_number_integer
 
constexpr bool is_number_integer() const noexcept;
 
 
This function returns true if and only if the JSON value is a signed or unsigned integer number. This excludes floating-point values.
 
Return value
 
true if type is an integer or unsigned integer number, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_number_integer() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 false
-
 
 
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to also return true for unsigned integers in 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Extended to also return true for unsigned integers in 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_number_unsigned/index.html b/api/basic_json/is_number_unsigned/index.html index 55614aef8..8dd938dbb 100644 --- a/api/basic_json/is_number_unsigned/index.html +++ b/api/basic_json/is_number_unsigned/index.html @@ -1,4 +1,4 @@ - is_number_unsigned - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_number_unsigned

constexpr bool is_number_unsigned() const noexcept;
+ is_number_unsigned - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_number_unsigned
 
constexpr bool is_number_unsigned() const noexcept;
 
 
This function returns true if and only if the JSON value is an unsigned integer number. This excludes floating-point and signed integer values.
 
Return value
 
true if type is an unsigned integer number, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_number_unsigned() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 false
-
 
 
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_object/index.html b/api/basic_json/is_object/index.html index 6ad2b5af3..c2ba96e69 100644 --- a/api/basic_json/is_object/index.html +++ b/api/basic_json/is_object/index.html @@ -1,4 +1,4 @@ - is_object - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_object

constexpr bool is_object() const noexcept;
+ is_object - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_object
 
constexpr bool is_object() const noexcept;
 
 
This function returns true if and only if the JSON value is an object.
 
Return value
 
true if type is an object, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_object() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 false
 false
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_primitive/index.html b/api/basic_json/is_primitive/index.html index 5ddbff4a6..808df6b20 100644 --- a/api/basic_json/is_primitive/index.html +++ b/api/basic_json/is_primitive/index.html @@ -1,4 +1,4 @@ - is_primitive - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_primitive

constexpr bool is_primitive() const noexcept;
+ is_primitive - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_primitive
 
constexpr bool is_primitive() const noexcept;
 
 
This function returns true if and only if the JSON type is primitive (string, number, boolean, null, binary).
 
Return value
 
true if type is primitive (string, number, boolean, null, or binary), false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Possible implementation
 
constexpr bool is_primitive() const noexcept
 {
     return is_null() || is_string() || is_boolean() || is_number() || is_binary();
@@ -42,4 +42,4 @@
 false
 true
 true
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to return true for binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Extended to return true for binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_string/index.html b/api/basic_json/is_string/index.html index eab62230c..5aced9047 100644 --- a/api/basic_json/is_string/index.html +++ b/api/basic_json/is_string/index.html @@ -1,4 +1,4 @@ - is_string - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_string

constexpr bool is_string() const noexcept;
+ is_string - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_string
 
constexpr bool is_string() const noexcept;
 
 
This function returns true if and only if the JSON value is a string.
 
Return value
 
true if type is a string, false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies is_string() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -38,4 +38,4 @@
 false
 true
 false
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/is_structured/index.html b/api/basic_json/is_structured/index.html index bec33112c..5d8408ae0 100644 --- a/api/basic_json/is_structured/index.html +++ b/api/basic_json/is_structured/index.html @@ -1,4 +1,4 @@ - is_structured - JSON for Modern C++
Skip to content

nlohmann::basic_json::is_structured

constexpr bool is_structured() const noexcept;
+ is_structured - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::is_structured
 
constexpr bool is_structured() const noexcept;
 
 
This function returns true if and only if the JSON type is structured (array or object).
 
Return value
 
true if type is structured (array or object), false otherwise.
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Possible implementation
 
constexpr bool is_structured() const noexcept
 {
     return is_array() || is_object();
@@ -42,4 +42,4 @@
 true
 false
 false
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/items/index.html b/api/basic_json/items/index.html index b46f0c527..648e99993 100644 --- a/api/basic_json/items/index.html +++ b/api/basic_json/items/index.html @@ -1,4 +1,4 @@ - items - JSON for Modern C++
Skip to content

nlohmann::basic_json::items

iteration_proxy<iterator> items() noexcept;
+ items - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::items
 
iteration_proxy<iterator> items() noexcept;
 iteration_proxy<const_iterator> items() const noexcept;
 
 
This function allows accessing iterator::key() and iterator::value() during range-based for loops. In these loops, a reference to the JSON values is returned, so there is no access to the underlying iterator.
 
For loop without items() function:
 
for (auto it = j_object.begin(); it != j_object.end(); ++it)
 {
@@ -48,4 +48,4 @@
 key: 2, value: 4
 key: 3, value: 8
 key: 4, value: 16
-
  
See also
 
     
  • begin returns an iterator to the first element
    •  
  • end returns an iterator to one past the last element
    •  
 
Version history
 
     
  • Added iterator_wrapper in version 3.0.0.
    •  
  • Added items and deprecated iterator_wrapper in version 3.1.0.
    •  
  • Added structured binding support in version 3.5.0.
    •  
 
 
Deprecation
 
This function replaces the static function iterator_wrapper which was introduced in version 1.0.0, but has been deprecated in version 3.1.0. Function iterator_wrapper will be removed in version 4.0.0. Please replace all occurrences of iterator_wrapper(j) with j.items().
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • begin returns an iterator to the first element
  • end returns an iterator to one past the last element

Version history

  • Added iterator_wrapper in version 3.0.0.
  • Added items and deprecated iterator_wrapper in version 3.1.0.
  • Added structured binding support in version 3.5.0.

Deprecation

This function replaces the static function iterator_wrapper which was introduced in version 1.0.0, but has been deprecated in version 3.1.0. Function iterator_wrapper will be removed in version 4.0.0. Please replace all occurrences of iterator_wrapper(j) with j.items().

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/json_base_class_t/index.html b/api/basic_json/json_base_class_t/index.html index 69fc9f10d..0ce5ae99b 100644 --- a/api/basic_json/json_base_class_t/index.html +++ b/api/basic_json/json_base_class_t/index.html @@ -1,4 +1,4 @@ - json_base_class_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::json_base_class_t

using json_base_class_t = detail::json_base_class<CustomBaseClass>;
+ json_base_class_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::json_base_class_t
 
using json_base_class_t = detail::json_base_class<CustomBaseClass>;
 
 
The base class used to inject custom functionality into each instance of basic_json. Examples of such functionality might be metadata, additional member functions (e.g., visitors), or other application-specific code.
 
Template parameters
 
 
CustomBaseClass
 
the base class to be added to basic_json
 
 
Notes
 
Default type
 
The default value for CustomBaseClass is void. In this case, an empty base class is used and no additional functionality is injected.
 
Limitations
 
The type CustomBaseClass has to be a default-constructible class. basic_json only supports copy/move construction/assignment if CustomBaseClass does so as well.
 
Examples
 
 Example 
The following code shows how to inject custom data and methods for each node.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -91,4 +91,4 @@
 /null - metadata = 42 -> null
 /object - metadata = 21 -> {"uint":1}
 /object/uint - metadata = 42 -> 1
-
 
 
Version history
 
     
  • Added in version 3.12.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.12.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/json_serializer/index.html b/api/basic_json/json_serializer/index.html index 1c3c2a737..be04c5bf7 100644 --- a/api/basic_json/json_serializer/index.html +++ b/api/basic_json/json_serializer/index.html @@ -1,4 +1,4 @@ - json_serializer - JSON for Modern C++
Skip to content

nlohmann::basic_json::json_serializer

template<typename T, typename SFINAE>
+ json_serializer - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::json_serializer
 
template<typename T, typename SFINAE>
 using json_serializer = JSONSerializer<T, SFINAE>;
 
 
Template parameters
 
 
T
 
type to convert; will be used in the to_json/from_json functions
 
SFINAE
 
type to add compile type checks via SFINAE; usually void
 
 
Notes
 
Default type
 
The default values for json_serializer is adl_serializer.
 
Examples
 
 Example 
The example below shows how a conversion of a non-default-constructible type is implemented via a specialization of the adl_serializer.
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -54,4 +54,4 @@
     std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
 }
 
 
Output:
 
Ned Flanders (60) lives in 744 Evergreen Terrace
-
 
 
Version history
 
     
  • Since version 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Since version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/max_size/index.html b/api/basic_json/max_size/index.html index a7b23de45..794e6d7eb 100644 --- a/api/basic_json/max_size/index.html +++ b/api/basic_json/max_size/index.html @@ -1,4 +1,4 @@ - max_size - JSON for Modern C++
Skip to content

nlohmann::basic_json::max_size

size_type max_size() const noexcept;
+ max_size - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::max_size
 
size_type max_size() const noexcept;
 
 
Returns the maximum number of elements a JSON value is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the JSON value.
 
Return value
 
The return value depends on the different types and is defined as follows:
 
  
 Value type return value 
   
 null 0 (same as size()) 
 
 boolean 1 (same as size()) 
 
 string 1 (same as size()) 
 
 number 1 (same as size()) 
 
 binary 1 (same as size()) 
 
 object result of function object_t::max_size() 
 
 array result of function array_t::max_size() 
  
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant, as long as array_t and object_t satisfy the Container concept; that is, their max_size() functions have constant complexity.
 
Notes
 
This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of string elements the JSON value can store which is 1.
 
Examples
 
 Example 
The following code calls max_size() on the different value types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -31,4 +31,4 @@
 115292150460684697
 576460752303423487
 1
-
 
Note the output is platform-dependent.
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to return 1 for binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Note the output is platform-dependent.

Version history

  • Added in version 1.0.0.
  • Extended to return 1 for binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/merge_patch/index.html b/api/basic_json/merge_patch/index.html index 1b6156ac5..d9b69e169 100644 --- a/api/basic_json/merge_patch/index.html +++ b/api/basic_json/merge_patch/index.html @@ -1,4 +1,4 @@ - merge_patch - JSON for Modern C++
Skip to content

nlohmann::basic_json::merge_patch

void merge_patch(const basic_json& apply_patch);
+ merge_patch - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::merge_patch
 
void merge_patch(const basic_json& apply_patch);
 
 
The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This function applies a merge patch to the current JSON value.
 
The function implements the following algorithm from Section 2 of RFC 7396 (JSON Merge Patch):
 
define MergePatch(Target, Patch):
   if Patch is an Object:
     if Target is not an Object:
@@ -64,4 +64,4 @@
     ],
     "title": "Hello!"
 }
-
  
See also
  
Version history
 
     
  • Added in version 3.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/meta/index.html b/api/basic_json/meta/index.html index 5b8160945..78a4088b8 100644 --- a/api/basic_json/meta/index.html +++ b/api/basic_json/meta/index.html @@ -1,4 +1,4 @@ - meta - JSON for Modern C++
Skip to content

nlohmann::basic_json::meta

static basic_json meta();
+ meta - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::meta
 
static basic_json meta();
 
 
This function returns a JSON object with information about the library, including the version number and information on the platform and compiler.
 
Return value
 
JSON object holding version information
 
  
 key description 
   
 compiler Information on the used compiler. It is an object with the following keys: c++ (the used C++ standard), family (the compiler family; possible values are clang, icc, gcc, ilecpp, msvc, pgcpp, sunpro, and unknown), and version (the compiler version). On HP aCC compilers, compiler is instead the plain string hp. 
 
 copyright The copyright line for the library as string. 
 
 name The name of the library as string. 
 
 platform The used platform as string. Possible values are win32, linux, apple, unix, and unknown. 
 
 url The URL of the project as string. 
 
 version The version of the library. It is an object with the following keys: major, minor, and patch as defined by Semantic Versioning, and string (the version string). 
  
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example output of the meta() function.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -27,4 +27,4 @@
         "string": "3.12.0"
     }
 }
-
 
Note the output is platform-dependent.
 
 
See also
  
Version history
 
     
  • Added in version 2.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Note the output is platform-dependent.

See also

Version history

  • Added in version 2.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/number_float_t/index.html b/api/basic_json/number_float_t/index.html index 9d4262177..801c0cbe8 100644 --- a/api/basic_json/number_float_t/index.html +++ b/api/basic_json/number_float_t/index.html @@ -1,4 +1,4 @@ - number_float_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::number_float_t

using number_float_t = NumberFloatType;
+ number_float_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::number_float_t
 
using number_float_t = NumberFloatType;
 
 
The type used to store JSON numbers (floating-point).
 
RFC 8259 describes numbers as follows:
 
 
The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
 
 
This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is known whether the number is a signed integer, an unsigned integer, or a floating-point number. Therefore, three different types, number_integer_t, number_unsigned_t and number_float_t are used.
 
To store floating-point numbers in C++, a type is defined by the template parameter NumberFloatType which chooses the type to use.
 
Notes
 
Default type
 
With the default values for NumberFloatType (double), the default value for number_float_t is double.
 
Default behavior
 
     
  • The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in floating-point literals will be ignored. Internally, the value will be stored as a decimal number. For instance, the C++ floating-point literal 01.2 will be serialized to 1.2. During deserialization, leading zeros yield an error.
    •  
  • Not-a-number (NaN) values will be serialized to null.
    •  
 
Limits
 
RFC 8259 states:
 
 
This specification allows implementations to set limits on the range and precision of numbers accepted. Since software that implements IEEE 754-2008 binary64 (double precision) numbers is generally available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide, in the sense that implementations will approximate JSON numbers within the expected precision.
 
 
This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values smaller than -1.79769313486232e+308 and values greater than 1.79769313486232e+308 will be stored as NaN internally and be serialized to null.
 
Storage
 
Floating-point number values are stored directly inside a basic_json type.
 
Examples
 
 Example 
The following code shows that number_float_t is by default, a typedef to double.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -10,4 +10,4 @@
     std::cout << std::boolalpha << std::is_same<double, json::number_float_t>::value << std::endl;
 }
 
 
Output:
 
true
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/number_integer_t/index.html b/api/basic_json/number_integer_t/index.html index 1210712a3..4b77072c4 100644 --- a/api/basic_json/number_integer_t/index.html +++ b/api/basic_json/number_integer_t/index.html @@ -1,4 +1,4 @@ - number_integer_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::number_integer_t

using number_integer_t = NumberIntegerType;
+ number_integer_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::number_integer_t
 
using number_integer_t = NumberIntegerType;
 
 
The type used to store JSON numbers (integers).
 
RFC 8259 describes numbers as follows:
 
 
The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
 
 
This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is known whether the number is a signed integer, an unsigned integer, or a floating-point number. Therefore, three different types, number_integer_t, number_unsigned_t and number_float_t are used.
 
To store integer numbers in C++, a type is defined by the template parameter NumberIntegerType which chooses the type to use.
 
Notes
 
Default type
 
With the default values for NumberIntegerType (std::int64_t), the default value for number_integer_t is std::int64_t.
 
Default behavior
 
     
  • The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++ integer literal 010 will be serialized to 8. During deserialization, leading zeros yield an error.
    •  
 
Limits
 
RFC 8259 specifies:
 
 
An implementation may set limits on the range and precision of numbers.
 
 
When the default type is used, the maximal integer number that can be stored is 9223372036854775807 (INT64_MAX) and the minimal integer number that can be stored is -9223372036854775808 (INT64_MIN). Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored as number_unsigned_t or number_float_t.
 
RFC 8259 further states:
 
 
Note that when such software is used, numbers that are integers and are in the range [-2^{53}+1, 2^{53}-1] are interoperable in the sense that implementations will agree exactly on their numeric values.
 
 
As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is interoperable.
 
Storage
 
Integer number values are stored directly inside a basic_json type.
 
Examples
 
 Example 
The following code shows that number_integer_t is by default, a typedef to std::int64_t.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -10,4 +10,4 @@
     std::cout << std::boolalpha << std::is_same<std::int64_t, json::number_integer_t>::value << std::endl;
 }
 
 
Output:
 
true
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/number_unsigned_t/index.html b/api/basic_json/number_unsigned_t/index.html index 75f8c64e2..c90ab0f96 100644 --- a/api/basic_json/number_unsigned_t/index.html +++ b/api/basic_json/number_unsigned_t/index.html @@ -1,4 +1,4 @@ - number_unsigned_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::number_unsigned_t

using number_unsigned_t = NumberUnsignedType;
+ number_unsigned_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::number_unsigned_t
 
using number_unsigned_t = NumberUnsignedType;
 
 
The type used to store JSON numbers (unsigned).
 
RFC 8259 describes numbers as follows:
 
 
The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
 
 
This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is known whether the number is a signed integer, an unsigned integer, or a floating-point number. Therefore, three different types, number_integer_t, number_unsigned_t and number_float_t are used.
 
To store unsigned integer numbers in C++, a type is defined by the template parameter NumberUnsignedType which chooses the type to use.
 
Notes
 
Default type
 
With the default values for NumberUnsignedType (std::uint64_t), the default value for number_unsigned_t is std::uint64_t.
 
Default behavior
 
     
  • The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++ integer literal 010 will be serialized to 8. During deserialization, leading zeros yield an error.
    •  
 
Limits
 
RFC 8259 specifies:
 
 
An implementation may set limits on the range and precision of numbers.
 
 
When the default type is used, the maximal integer number that can be stored is 18446744073709551615 (UINT64_MAX) and the minimal integer number that can be stored is 0. Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored as number_integer_t or number_float_t.
 
RFC 8259 further states:
 
 
Note that when such software is used, numbers that are integers and are in the range [-2^{53}+1, 2^{53}-1] are interoperable in the sense that implementations will agree exactly on their numeric values.
 
 
As this range is a subrange (when considered in conjunction with the number_integer_t type) of the exactly supported range [0, UINT64_MAX], this class's integer type is interoperable.
 
Storage
 
Integer number values are stored directly inside a basic_json type.
 
Examples
 
 Example 
The following code shows that number_unsigned_t is by default, a typedef to std::uint64_t.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -10,4 +10,4 @@
     std::cout << std::boolalpha << std::is_same<std::uint64_t, json::number_unsigned_t>::value << std::endl;
 }
 
 
Output:
 
true
-
 
 
Version history
 
     
  • Added in version 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/object/index.html b/api/basic_json/object/index.html index bb66f6575..90512c6c7 100644 --- a/api/basic_json/object/index.html +++ b/api/basic_json/object/index.html @@ -1,4 +1,4 @@ - object - JSON for Modern C++
Skip to content

nlohmann::basic_json::object

static basic_json object(initializer_list_t init = {});
+ object - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::object
 
static basic_json object(initializer_list_t init = {});
 
 
Creates a JSON object value from a given initializer list. The initializer lists elements must be pairs, and their first elements must be strings. If the initializer list is empty, the empty object {} is created.
 
Parameters
 
 
init (in)
 
initializer list with JSON values to create an object from (optional)
 
 
Return value
 
JSON object value
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
Exceptions
 
Throws type_error.301 if init is not a list of pairs whose first elements are strings. In this case, no object can be created. When such a value is passed to basic_json(initializer_list_t, bool, value_t), an array would have been created from the passed initializer list init. See the example below.
 
Complexity
 
Linear in the size of init.
 
Notes
 
This function is only added for symmetry reasons. In contrast to the related function array(initializer_list_t), there are no cases that can only be expressed by this function. That is, any initializer list init can also be passed to the initializer list constructor basic_json(initializer_list_t, bool, value_t).
 
Examples
 
 Example 
The following code shows an example for the object function.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -31,4 +31,4 @@
 {}
 {"one":1,"two":2}
 [json.exception.type_error.301] cannot create object from initializer list
-
 
 
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/object_comparator_t/index.html b/api/basic_json/object_comparator_t/index.html index da594740e..bd485e48d 100644 --- a/api/basic_json/object_comparator_t/index.html +++ b/api/basic_json/object_comparator_t/index.html @@ -1,4 +1,4 @@ - object_comparator_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::object_comparator_t

using object_comparator_t = typename object_t::key_compare;
+ object_comparator_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::object_comparator_t
 
using object_comparator_t = typename object_t::key_compare;
 // or
 using object_comparator_t = default_object_comparator_t;
 
 
The comparator used by object_t. Defined as typename object_t::key_compare if available, and default_object_comparator_t otherwise.
 
Examples
 
 Example 
The example below demonstrates the used object comparator.
 
#include <iostream>
@@ -14,4 +14,4 @@
 }
 
 
Output:
 
json::object_comparator_t("one", "two") = true
 json::object_comparator_t("three", "four") = false
-
 
 
Version history
 
     
  • Added in version 3.0.0.
    •  
  • Changed to be conditionally defined as typename object_t::key_compare or default_object_comparator_t in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.0.0.
  • Changed to be conditionally defined as typename object_t::key_compare or default_object_comparator_t in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/object_t/index.html b/api/basic_json/object_t/index.html index 2338e701f..841b115c0 100644 --- a/api/basic_json/object_t/index.html +++ b/api/basic_json/object_t/index.html @@ -1,4 +1,4 @@ - object_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::object_t

using object_t = ObjectType<StringType,
+ object_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::object_t
 
using object_t = ObjectType<StringType,
                             basic_json,
                             default_object_comparator_t,
                             AllocatorType<std::pair<const StringType, basic_json>>>;
@@ -28,4 +28,4 @@
     std::cout << std::boolalpha << std::is_same<std::map<json::string_t, json>, json::object_t>::value << std::endl;
 }
 
 
Output:
 
true
-
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator+=/index.html b/api/basic_json/operator+=/index.html index 03e1577f2..68adff9cc 100644 --- a/api/basic_json/operator+=/index.html +++ b/api/basic_json/operator+=/index.html @@ -1,4 +1,4 @@ - operator+= - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator+=

// (1)
+ operator+= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator+=
 
// (1)
 reference operator+=(basic_json&& val);
 reference operator+=(const basic_json& val);
 
@@ -96,4 +96,4 @@
 null
 {"four":4,"one":1,"three":3,"two":2}
 [["five",5]]
-
  
See also
  
Version history
 
     
  1. Since version 1.0.0.
    2.  
  2. Since version 1.0.0.
    3.  
  3. Since version 2.0.0.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Since version 1.0.0.
  2. Since version 1.0.0.
  3. Since version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator=/index.html b/api/basic_json/operator=/index.html index cadbe3698..a038fc2e8 100644 --- a/api/basic_json/operator=/index.html +++ b/api/basic_json/operator=/index.html @@ -1,4 +1,4 @@ - operator= - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator=

basic_json& operator=(basic_json other) noexcept (
+ operator= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator=
 
basic_json& operator=(basic_json other) noexcept (
     std::is_nothrow_move_constructible<value_t>::value &&
     std::is_nothrow_move_assignable<value_t>::value &&
     std::is_nothrow_move_constructible<json_value>::value &&
@@ -25,4 +25,4 @@
 }
 
 
Output:
 
23
 23
-
  
See also
 
     
  • basic_json create a JSON value
    •  
  • swap exchanges the contents of two JSON values
    •  
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • basic_json create a JSON value
  • swap exchanges the contents of two JSON values

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator[]/index.html b/api/basic_json/operator[]/index.html index e7c529f38..12fd41765 100644 --- a/api/basic_json/operator[]/index.html +++ b/api/basic_json/operator[]/index.html @@ -1,4 +1,4 @@ - operator[] - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator[]

// (1)
+ operator[] - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator[]
 
// (1)
 reference operator[](size_type idx);
 const_reference operator[](size_type idx) const;
 
@@ -283,4 +283,4 @@
 "foo"
 [1,2]
 2
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0.
    2.  
  2. Added in version 1.0.0. Added overloads for T* key in version 1.1.0. Removed overloads for T* key (replaced by 3) in version 3.11.0.
    3.  
  3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept std::string_view-convertible keys, as already supported by at, value, find, and other lookup functions.
    4.  
  4. Added in version 2.0.0.
    5.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0.
  2. Added in version 1.0.0. Added overloads for T* key in version 1.1.0. Removed overloads for T* key (replaced by 3) in version 3.11.0.
  3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept std::string_view-convertible keys, as already supported by at, value, find, and other lookup functions.
  4. Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_ValueType/index.html b/api/basic_json/operator_ValueType/index.html index 3a136082e..6e34b472a 100644 --- a/api/basic_json/operator_ValueType/index.html +++ b/api/basic_json/operator_ValueType/index.html @@ -1,4 +1,4 @@ - operator ValueType - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator ValueType

template<typename ValueType>
+ operator ValueType - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator ValueType
 
template<typename ValueType>
 JSON_EXPLICIT operator ValueType() const;
 
 
Implicit type conversion between the JSON value and a compatible value. The call is realized by calling get(). See Notes for the meaning of JSON_EXPLICIT.
 
Template parameters
 
 
ValueType
 
the value type to return
 
 
Return value
 
copy of the JSON value, converted to ValueType
 
Exceptions
 
Depends on what json_serializer<ValueType> from_json() method throws
 
Complexity
 
Linear in the size of the JSON value.
 
Notes
 
 
Definition of JSON_EXPLICIT
 
By default JSON_EXPLICIT is defined to the empty string, so the signature is:
 
template<typename ValueType>
 operator ValueType() const;
@@ -76,4 +76,4 @@
 boolean: true
 array: [1,2,3,4,5]
 [json.exception.type_error.302] type must be boolean, but is string
-
  
See also
  
Version history
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_eq/index.html b/api/basic_json/operator_eq/index.html index 52f79a4e9..5f2594fea 100644 --- a/api/basic_json/operator_eq/index.html +++ b/api/basic_json/operator_eq/index.html @@ -1,4 +1,4 @@ - operator== - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator==

// until C++20
+ operator== - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator==
 
// until C++20
 bool operator==(const_reference lhs, const_reference rhs) noexcept;   // (1)
 
 template<typename ScalarType>
@@ -115,4 +115,4 @@
 17 == nullptr false
 "foo" == nullptr false
 null == nullptr true
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
  2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_ge/index.html b/api/basic_json/operator_ge/index.html index fadc80286..dce732d7a 100644 --- a/api/basic_json/operator_ge/index.html +++ b/api/basic_json/operator_ge/index.html @@ -1,4 +1,4 @@ - operator>= - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator>=

// until C++20
+ operator>= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator>=
 
// until C++20
 bool operator>=(const_reference lhs, const_reference rhs) noexcept;   // (1)
 
 template<typename ScalarType>
@@ -34,4 +34,4 @@
 {"A":"a","B":"b"} >= {"A":"a","B":"b"} true
 17 >= 17.0000000000001 false
 "foo" >= "bar" true
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_gt/index.html b/api/basic_json/operator_gt/index.html index 0a83bb3b4..942043b93 100644 --- a/api/basic_json/operator_gt/index.html +++ b/api/basic_json/operator_gt/index.html @@ -1,4 +1,4 @@ - operator> - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator>

// until C++20
+ operator> - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator>
 
// until C++20
 bool operator>(const_reference lhs, const_reference rhs) noexcept;   // (1)
 
 template<typename ScalarType>
@@ -34,4 +34,4 @@
 {"A":"a","B":"b"} > {"A":"a","B":"b"} false
 17 > 17.0000000000001 false
 "foo" > "bar" true
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_le/index.html b/api/basic_json/operator_le/index.html index 8701c4476..a2e36e795 100644 --- a/api/basic_json/operator_le/index.html +++ b/api/basic_json/operator_le/index.html @@ -1,4 +1,4 @@ - operator<= - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator<=

// until C++20
+ operator<= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator<=
 
// until C++20
 bool operator<=(const_reference lhs, const_reference rhs) noexcept;   // (1)
 
 template<typename ScalarType>
@@ -34,4 +34,4 @@
 {"A":"a","B":"b"} <= {"A":"a","B":"b"} true
 17 <= 17.0000000000001 true
 "foo" <= "bar" false
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_lt/index.html b/api/basic_json/operator_lt/index.html index 1e80fedec..388a0c2c6 100644 --- a/api/basic_json/operator_lt/index.html +++ b/api/basic_json/operator_lt/index.html @@ -1,4 +1,4 @@ - operator< - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator<

// until C++20
+ operator< - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator<
 
// until C++20
 bool operator<(const_reference lhs, const_reference rhs) noexcept;   // (1)
 
 template<typename ScalarType>
@@ -34,4 +34,4 @@
 {"A":"a","B":"b"} == {"A":"a","B":"b"} false
 17 == 17.0000000000001 true
 "foo" == "bar" false
-
  
See also
  
Version history
 
     
  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    2.  
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
  2. Added in version 1.0.0. Conditionally removed since C++20 in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_ne/index.html b/api/basic_json/operator_ne/index.html index ab7e9c3cb..a39c4cbfe 100644 --- a/api/basic_json/operator_ne/index.html +++ b/api/basic_json/operator_ne/index.html @@ -1,4 +1,4 @@ - operator!= - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator!=

// until C++20
+ operator!= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator!=
 
// until C++20
 bool operator!=(const_reference lhs, const_reference rhs) noexcept;   // (1)
 
 template<typename ScalarType>
@@ -69,4 +69,4 @@
 17 != nullptr true
 "foo" != nullptr true
 null != nullptr false
-
  
Version history
 
     
  1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0. Changed in version 3.13.0 to remove special-casing for NaN and discarded values; operator!= now consistently means !(a == b).
    2.  
  2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0. Changed in version 3.13.0 to remove special-casing for NaN and discarded values; operator!= now consistently means !(a == b).
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Added in version 1.0.0. Added C++20 member functions in version 3.11.0. Changed in version 3.13.0 to remove special-casing for NaN and discarded values; operator!= now consistently means !(a == b).
  2. Added in version 1.0.0. Added C++20 member functions in version 3.11.0. Changed in version 3.13.0 to remove special-casing for NaN and discarded values; operator!= now consistently means !(a == b).
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_spaceship/index.html b/api/basic_json/operator_spaceship/index.html index 0232f4b79..2a27e827a 100644 --- a/api/basic_json/operator_spaceship/index.html +++ b/api/basic_json/operator_spaceship/index.html @@ -1,4 +1,4 @@ - operator - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator<=>

// since C++20
+ operator - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator<=>
 
// since C++20
 class basic_json {
     std::partial_ordering operator<=>(const_reference rhs) const noexcept;  // (1)
 
@@ -93,4 +93,4 @@
 17 <=> 17.000000 := equivalent
 17 <=> nan := unordered
 "17" <=> 17 := greater
-
  
See also
  
Version history
 
     
  1. Added in version 3.11.0.
    2.  
  2. Added in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 3.11.0.
  2. Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/operator_value_t/index.html b/api/basic_json/operator_value_t/index.html index 87cec30d6..fdb0ef7c6 100644 --- a/api/basic_json/operator_value_t/index.html +++ b/api/basic_json/operator_value_t/index.html @@ -1,4 +1,4 @@ - operator value_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::operator value_t

constexpr operator value_t() const noexcept;
+ operator value_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::operator value_t
 
constexpr operator value_t() const noexcept;
 
 
Return the type of the JSON value as a value from the value_t enumeration.
 
Return value
 
the type of the JSON value
 
  
 Value type return value 
   
 null value_t::null 
 
 boolean value_t::boolean 
 
 string value_t::string 
 
 number (integer) value_t::number_integer 
 
 number (unsigned integer) value_t::number_unsigned 
 
 number (floating-point) value_t::number_float 
 
 object value_t::object 
 
 array value_t::array 
 
 binary value_t::binary 
 
 discarded value_t::discarded 
  
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies operator value_t() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -45,4 +45,4 @@
 true
 true
 true
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Added unsigned integer type in version 2.0.0.
    •  
  • Added binary type in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Added unsigned integer type in version 2.0.0.
  • Added binary type in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/other_error/index.html b/api/basic_json/other_error/index.html index af5098e4f..ac9444738 100644 --- a/api/basic_json/other_error/index.html +++ b/api/basic_json/other_error/index.html @@ -1,4 +1,4 @@ - other_error - JSON for Modern C++
Skip to content

nlohmann::basic_json::other_error

class other_error : public exception;
+ other_error - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::other_error
 
class other_error : public exception;
 
 
This exception is thrown in case of errors that cannot be classified with the other exception types.
 
Exceptions have ids 5xx (see list of other errors).
 
classDiagram
   direction LR
 
@@ -59,4 +59,4 @@
 }
 
 
Output:
 
message: [json.exception.other_error.501] unsuccessful: {"op":"test","path":"/best_biscuit/name","value":"Choco Leibniz"}
 exception id: 501
-
  
See also
  
Version history
 
     
  • Since version 3.0.0.
    •
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

Version history

\ No newline at end of file diff --git a/api/basic_json/out_of_range/index.html b/api/basic_json/out_of_range/index.html index 611f5403c..f3d7e389a 100644 --- a/api/basic_json/out_of_range/index.html +++ b/api/basic_json/out_of_range/index.html @@ -1,4 +1,4 @@ - out_of_range - JSON for Modern C++
Skip to content

nlohmann::basic_json::out_of_range

class out_of_range : public exception;
+ out_of_range - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::out_of_range
 
class out_of_range : public exception;
 
 
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for instance, in the case of array indices or nonexisting object keys.
 
Exceptions have ids 4xx (see list of out-of-range errors).
 
classDiagram
   direction LR
 
@@ -49,4 +49,4 @@
 }
 
 
Output:
 
message: [json.exception.out_of_range.401] array index 4 is out of range
 exception id: 401
-
  
See also
  
Version history
 
     
  • Since version 3.0.0.
    •
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

Version history

\ No newline at end of file diff --git a/api/basic_json/parse/index.html b/api/basic_json/parse/index.html index 2f79027db..b540445b1 100644 --- a/api/basic_json/parse/index.html +++ b/api/basic_json/parse/index.html @@ -1,4 +1,4 @@ - parse - JSON for Modern C++
Skip to content

nlohmann::basic_json::parse

// (1)
+ parse - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::parse
 
// (1)
 template<typename InputType>
 static basic_json parse(InputType&& i,
                         const parser_callback_t cb = nullptr,
@@ -424,4 +424,4 @@
     "Neptune"
   ]
 }
-
  
See also
 
     
  • accept - check if the input is valid JSON
    •  
  • sax_parse - parse input using the SAX interface
    •  
  • operator>> - deserialize from stream
    •  
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Overload for contiguous containers (1) added in version 2.0.3.
    •  
  • Ignoring comments via ignore_comments added in version 3.9.0.
    •  
  • Changed runtime assertion in case of FILE* null pointers to exception in version 3.12.0.
    •  
  • Added ignore_trailing_commas in version 3.13.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
Overload (2) replaces calls to parse with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like parse({ptr, ptr+len}, ...); with parse(ptr, ptr+len, ...);.
 
You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • accept - check if the input is valid JSON
  • sax_parse - parse input using the SAX interface
  • operator>> - deserialize from stream

Version history

  • Added in version 1.0.0.
  • Overload for contiguous containers (1) added in version 2.0.3.
  • Ignoring comments via ignore_comments added in version 3.9.0.
  • Changed runtime assertion in case of FILE* null pointers to exception in version 3.12.0.
  • Added ignore_trailing_commas in version 3.13.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

Overload (2) replaces calls to parse with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like parse({ptr, ptr+len}, ...); with parse(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/parse_error/index.html b/api/basic_json/parse_error/index.html index dd7c167c1..7679d50cc 100644 --- a/api/basic_json/parse_error/index.html +++ b/api/basic_json/parse_error/index.html @@ -1,4 +1,4 @@ - parse_error - JSON for Modern C++
Skip to content

nlohmann::basic_json::parse_error

class parse_error : public exception;
+ parse_error - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::parse_error
 
class parse_error : public exception;
 
 
The library throws this exception when a parse error occurs. Parse errors can occur during the deserialization of JSON text, BSON, CBOR, MessagePack, UBJSON, as well as when using JSON Patch.
 
Member byte holds the byte index of the last read character in the input file (see note below).
 
Exceptions have ids 1xx (see list of parse errors).
 
classDiagram
   direction LR
 
@@ -50,4 +50,4 @@
 
 
Output:
 
message: [json.exception.parse_error.101] parse error at line 1, column 8: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
 exception id: 101
 byte position of error: 8
-
  
See also
  
Version history
 
     
  • Since version 3.0.0.
    •
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

Version history

\ No newline at end of file diff --git a/api/basic_json/parse_event_t/index.html b/api/basic_json/parse_event_t/index.html index 596afb044..48b57d634 100644 --- a/api/basic_json/parse_event_t/index.html +++ b/api/basic_json/parse_event_t/index.html @@ -1,4 +1,4 @@ - parse_event_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::parse_event_t

enum class parse_event_t : std::uint8_t {
+ parse_event_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::parse_event_t
 
enum class parse_event_t : std::uint8_t {
     object_start,
     object_end,
     array_start,
@@ -6,4 +6,4 @@
     key,
     value
 };
-
 
The parser callback distinguishes the following events:
 
     
  • object_start: the parser read { and started to process a JSON object
    •  
  • key: the parser read a key of a value in an object
    •  
  • object_end: the parser read } and finished processing a JSON object
    •  
  • array_start: the parser read [ and started to process a JSON array
    •  
  • array_end: the parser read ] and finished processing a JSON array
    •  
  • value: the parser finished reading a JSON value
    •  
 
Examples
 
Example when certain parse events are triggered
 
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

The parser callback distinguishes the following events:

  • object_start: the parser read { and started to process a JSON object
  • key: the parser read a key of a value in an object
  • object_end: the parser read } and finished processing a JSON object
  • array_start: the parser read [ and started to process a JSON array
  • array_end: the parser read ] and finished processing a JSON array
  • value: the parser finished reading a JSON value

Examples

Example when certain parse events are triggered

See also

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/parser_callback_t/index.html b/api/basic_json/parser_callback_t/index.html index d8c9ab59e..00fc5f9c8 100644 --- a/api/basic_json/parser_callback_t/index.html +++ b/api/basic_json/parser_callback_t/index.html @@ -1,4 +1,4 @@ - parser_callback_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::parser_callback_t

template<typename BasicJsonType>
+ parser_callback_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::parser_callback_t
 
template<typename BasicJsonType>
 using parser_callback_t =
     std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
 
 
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to parse, it is called on certain events (passed as parse_event_t via parameter event) with a set recursion depth depth and context JSON value parsed. The return value of the callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
 
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values of the parameters depth, event, and parsed.
 
  
 parameter event description parameter depth parameter parsed 
   
 parse_event_t::object_start the parser read { and started to process a JSON object depth of the parent of the JSON object a JSON value with type discarded 
 
 parse_event_t::key the parser read a key of a value in an object depth of the currently parsed JSON object a JSON string containing the key 
 
 parse_event_t::object_end the parser read } and finished processing a JSON object depth of the parent of the JSON object the parsed JSON object 
 
 parse_event_t::array_start the parser read [ and started to process a JSON array depth of the parent of the JSON array a JSON value with type discarded 
 
 parse_event_t::array_end the parser read ] and finished processing a JSON array depth of the parent of the JSON array the parsed JSON array 
 
 parse_event_t::value the parser finished reading a JSON value depth of the value the parsed JSON value 
  
 
Example when certain parse events are triggered
 
Discarding a value (i.e., returning false) has different effects depending on the context in which function was called:
 
     
  • Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read. This holds for every value type and for both kinds of parent: a discarded element is removed from the surrounding array, and a discarded member is removed from the surrounding object together with its key.
    •  
  • Arrays and objects can be discarded either at their parse_event_t::array_start/parse_event_t::object_start event or at their parse_event_t::array_end/parse_event_t::object_end event, and both remove the whole value. Discarding it at the start event also means the callback is called neither for the content of the value nor for its matching end event.
    •  
  • Discarding a parse_event_t::key event discards the whole object member. The callback is still called for the associated value, but its return value has no further effect.
    •  
  • In case a value outside a structured type is skipped, it is replaced with null. This case happens if the top-level element is skipped.
    •  
 
Parameters
 
 
depth (in)
 
the depth of the recursion during parsing
 
event (in)
 
an event of type parse_event_t indicating the context in the callback function has been called
 
parsed (in, out)
 
the current intermediate parse result; note that writing to this value has no effect for parse_event_t::key events
 
 
Return value
 
Whether the JSON value which called the function during parsing should be kept (true) or not (false). In the latter case, it is skipped completely, or replaced by null if it is the top-level value.
 
Examples
 
 Example 
The example below demonstrates the parse() function with and without callback function.
 
#include <iostream>
@@ -135,4 +135,4 @@
 {"IDs":[116,943]}
 {"IDs":[116,943]}
 null
-
 
 
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Fixed in version 3.13.0 to also remove discarded values from a parent object; before, discarding an array or a value stored under an object key left a discarded member behind, which made the parse result serialize to invalid JSON.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Fixed in version 3.13.0 to also remove discarded values from a parent object; before, discarding an array or a value stored under an object key left a discarded member behind, which made the parse result serialize to invalid JSON.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/patch/index.html b/api/basic_json/patch/index.html index 63255fd58..59f58bd2e 100644 --- a/api/basic_json/patch/index.html +++ b/api/basic_json/patch/index.html @@ -1,4 +1,4 @@ - patch - JSON for Modern C++
Skip to content

nlohmann::basic_json::patch

basic_json patch(const basic_json& json_patch) const;
+ patch - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::patch
 
basic_json patch(const basic_json& json_patch) const;
 
 
JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from the patch.
 
Parameters
 
 
json_patch (in)
 
JSON patch document
 
 
Return value
 
patched document
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
Exceptions
 
     
  • Throws parse_error.104 if the JSON patch does not consist of an array of objects.
    •  
  • Throws parse_error.105 if the JSON patch is malformed (e.g., mandatory attributes are missing); example: "operation add must have member path".
    •  
  • Throws out_of_range.401 if an array index is out of range.
    •  
  • Throws out_of_range.403 if a JSON pointer inside the patch could not be resolved successfully in the current JSON value; example: "key baz not found".
    •  
  • Throws out_of_range.405 if JSON pointer has no parent ("add", "remove", "move")
    •  
  • Throws out_of_range.411 if an "add" operation's target location has a parent that is neither an object nor an array.
    •  
  • Throws other_error.501 if "test" operation was unsuccessful.
    •  
 
Complexity
 
Linear in the size of the JSON value and the length of the JSON patch. As usually the patch affects only a fraction of the JSON value, the complexity can usually be neglected.
 
Notes
 
The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
 
Examples
 
 Example 
The following code shows how a JSON patch is applied to a value.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -43,4 +43,4 @@
         "world"
     ]
 }
-
 
 
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
  • Added out_of_range.411 and stopped relying on an internal assertion when an "add" operation's target location has a non-object/non-array parent in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.0.0.
  • Added out_of_range.411 and stopped relying on an internal assertion when an "add" operation's target location has a non-object/non-array parent in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/patch_inplace/index.html b/api/basic_json/patch_inplace/index.html index 5470f4490..71d61f11b 100644 --- a/api/basic_json/patch_inplace/index.html +++ b/api/basic_json/patch_inplace/index.html @@ -1,4 +1,4 @@ - patch_inplace - JSON for Modern C++
Skip to content

nlohmann::basic_json::patch_inplace

void patch_inplace(const basic_json& json_patch);
+ patch_inplace - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::patch_inplace
 
void patch_inplace(const basic_json& json_patch);
 
 
JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from the patch. This function applies a JSON patch in place and returns void.
 
Parameters
 
 
json_patch (in)
 
JSON patch document
 
 
Exception safety
 
No guarantees, value may be corrupted by an unsuccessful patch operation.
 
Exceptions
 
     
  • Throws parse_error.104 if the JSON patch does not consist of an array of objects.
    •  
  • Throws parse_error.105 if the JSON patch is malformed (e.g., mandatory attributes are missing); example: "operation add must have member path".
    •  
  • Throws out_of_range.401 if an array index is out of range.
    •  
  • Throws out_of_range.403 if a JSON pointer inside the patch could not be resolved successfully in the current JSON value; example: "key baz not found".
    •  
  • Throws out_of_range.405 if JSON pointer has no parent ("add", "remove", "move")
    •  
  • Throws out_of_range.411 if an "add" operation's target location has a parent that is neither an object nor an array.
    •  
  • Throws other_error.501 if "test" operation was unsuccessful.
    •  
 
Complexity
 
Linear in the size of the JSON value and the length of the JSON patch. As usually the patch affects only a fraction of the JSON value, the complexity can usually be neglected.
 
Notes
 
Unlike patch, patch_inplace applies the operation "in place" and no copy of the JSON value is created. That makes it faster for large documents by avoiding the copy. However, the JSON value might be corrupted if the function throws an exception.
 
Examples
 
 Example 
The following code shows how a JSON patch is applied to a value.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -47,4 +47,4 @@
         "world"
     ]
 }
-
 
 
See also
  
Version history
 
     
  • Added in version 3.11.0.
    •  
  • Added out_of_range.411 and stopped relying on an internal assertion when an "add" operation's target location has a non-object/non-array parent in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.0.
  • Added out_of_range.411 and stopped relying on an internal assertion when an "add" operation's target location has a non-object/non-array parent in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/push_back/index.html b/api/basic_json/push_back/index.html index b9ce4dd6b..8ff428afb 100644 --- a/api/basic_json/push_back/index.html +++ b/api/basic_json/push_back/index.html @@ -1,4 +1,4 @@ - push_back - JSON for Modern C++
Skip to content

nlohmann::basic_json::push_back

// (1)
+ push_back - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::push_back
 
// (1)
 void push_back(basic_json&& val);
 void push_back(const basic_json& val);
 
@@ -96,4 +96,4 @@
 null
 {"four":4,"one":1,"three":3,"two":2}
 [["five",5]]
-
  
See also
  
Version history
 
     
  1. Since version 1.0.0.
    2.  
  2. Since version 1.0.0.
    3.  
  3. Since version 2.0.0.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Since version 1.0.0.
  2. Since version 1.0.0.
  3. Since version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/rbegin/index.html b/api/basic_json/rbegin/index.html index 8ff2a272c..7cc94d311 100644 --- a/api/basic_json/rbegin/index.html +++ b/api/basic_json/rbegin/index.html @@ -1,4 +1,4 @@ - rbegin - JSON for Modern C++
Skip to content

nlohmann::basic_json::rbegin

reverse_iterator rbegin() noexcept;
+ rbegin - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::rbegin
 
reverse_iterator rbegin() noexcept;
 const_reverse_iterator rbegin() const noexcept;
 
 
Returns an iterator to the reverse-beginning; that is, the last element.
 
Illustration from cppreference.com
 
Return value
 
reverse iterator to the last element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for rbegin().
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -17,4 +17,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
5
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/rend/index.html b/api/basic_json/rend/index.html index c00af4989..a18aec1a5 100644 --- a/api/basic_json/rend/index.html +++ b/api/basic_json/rend/index.html @@ -1,4 +1,4 @@ - rend - JSON for Modern C++
Skip to content

nlohmann::basic_json::rend

reverse_iterator rend() noexcept;
+ rend - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::rend
 
reverse_iterator rend() noexcept;
 const_reverse_iterator rend() const noexcept;
 
 
Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.
 
Illustration from cppreference.com
 
Return value
 
reverse iterator to the element following the last element
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code shows an example for rend().
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -20,4 +20,4 @@
     std::cout << *it << '\n';
 }
 
 
Output:
 
1
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/sax_parse/index.html b/api/basic_json/sax_parse/index.html index 905951e70..ed06ca3bc 100644 --- a/api/basic_json/sax_parse/index.html +++ b/api/basic_json/sax_parse/index.html @@ -1,4 +1,4 @@ - sax_parse - JSON for Modern C++
Skip to content

nlohmann::basic_json::sax_parse

// (1)
+ sax_parse - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::sax_parse
 
// (1)
 template <typename InputType, typename SAX>
 static bool sax_parse(InputType&& i,
                       SAX* sax,
@@ -183,4 +183,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
  
See also
 
     
  • parse - deserialize from a compatible input
    •  
  • accept - check if the input is valid JSON
    •  
 
Version history
 
     
  • Added in version 3.2.0.
    •  
  • Ignoring comments via ignore_comments added in version 3.9.0.
    •  
  • Added ignore_trailing_commas in version 3.13.0.
    •  
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
    •  
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
    •  
 
 
Deprecation
 
Overload (2) replaces calls to sax_parse with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like sax_parse({ptr, ptr+len}); with sax_parse(ptr, ptr+len);.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • parse - deserialize from a compatible input
  • accept - check if the input is valid JSON

Version history

  • Added in version 3.2.0.
  • Ignoring comments via ignore_comments added in version 3.9.0.
  • Added ignore_trailing_commas in version 3.13.0.
  • Extended container support (1) to include types with lvalue-only ADL begin/end (matching std::begin/std::end semantics) in version 3.13.0.
  • Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

Deprecation

Overload (2) replaces calls to sax_parse with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like sax_parse({ptr, ptr+len}); with sax_parse(ptr, ptr+len);.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/size/index.html b/api/basic_json/size/index.html index 4aa57943e..0a7c31cf6 100644 --- a/api/basic_json/size/index.html +++ b/api/basic_json/size/index.html @@ -1,4 +1,4 @@ - size - JSON for Modern C++
Skip to content

nlohmann::basic_json::size

size_type size() const noexcept;
+ size - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::size
 
size_type size() const noexcept;
 
 
Returns the number of elements in a JSON value.
 
Return value
 
The return value depends on the different types and is defined as follows:
 
  
 Value type return value 
   
 null 0 
 
 boolean 1 
 
 string 1 
 
 number 1 
 
 binary 1 
 
 object result of function object_t::size() 
 
 array result of function array_t::size() 
  
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant, as long as array_t and object_t satisfy the Container concept; that is, their size() functions have constant complexity.
 
Notes
 
This function does not return the length of a string stored as JSON value -- it returns the number of elements in the JSON value which is 1 in the case of a string.
 
Examples
 
 Example 
The following code calls size() on the different value types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -37,4 +37,4 @@
 5
 0
 1
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended to return 1 for binary types in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Extended to return 1 for binary types in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/start_pos/index.html b/api/basic_json/start_pos/index.html index fb2c3ab8c..d4d9d0e0d 100644 --- a/api/basic_json/start_pos/index.html +++ b/api/basic_json/start_pos/index.html @@ -1,4 +1,4 @@ - start_pos - JSON for Modern C++
Skip to content

nlohmann::basic_json::start_pos

#if JSON_DIAGNOSTIC_POSITIONS
+ start_pos - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::start_pos
 
#if JSON_DIAGNOSTIC_POSITIONS
 constexpr std::size_t start_pos() const noexcept;
 #endif
 
 
Returns the position of the first character in the JSON string from which the value was parsed from.
 
  
 JSON type return value 
   
 object position of the opening { 
 
 array position of the opening [ 
 
 string position of the opening " 
 
 number position of the first character 
 
 boolean position of t for true and f for false 
 
 null position of n 
  
 
Return value
 
the position of the first character of the value in the parsed JSON string, if the value was created by the parse function, or std::string::npos if the value was constructed otherwise
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Notes
 
 
Note
 
The function is only available if macro JSON_DIAGNOSTIC_POSITIONS has been defined to 1 before including the library header.
 
 
 
Invalidation
 
The returned positions are only valid as long as the JSON value is not changed. The positions are not updated when the JSON value is changed.
 
 
Examples
 
 Example 
#include <iostream>
@@ -101,4 +101,4 @@ Original string:
 1
 Parsed string: 
 1
-
 
The output shows the start/end positions of all the objects and fields in the JSON string.
 
 
See also
  
Version history
 
     
  • Added in version 3.12.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

The output shows the start/end positions of all the objects and fields in the JSON string.

See also

Version history

  • Added in version 3.12.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/std_formatter/index.html b/api/basic_json/std_formatter/index.html index 5d62ad08e..dcb9db96f 100644 --- a/api/basic_json/std_formatter/index.html +++ b/api/basic_json/std_formatter/index.html @@ -1,4 +1,4 @@ - std::formatter<basic_json> - JSON for Modern C++
Skip to content

std::formatter<nlohmann::basic_json>

namespace std {
+ std::formatter<basic_json> - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
std::formatter<nlohmann::basic_json>
 
namespace std {
     template <>
     struct formatter<nlohmann::basic_json, char>;
 }
@@ -40,4 +40,4 @@
 ...."one": 1,
 ...."two": 2
 }
-
  
See also
  
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/std_hash/index.html b/api/basic_json/std_hash/index.html index 596d20445..1a08d2ba8 100644 --- a/api/basic_json/std_hash/index.html +++ b/api/basic_json/std_hash/index.html @@ -1,4 +1,4 @@ - std::hash<basic_json> - JSON for Modern C++
Skip to content

std::hash<nlohmann::basic_json>

namespace std {
+ std::hash<basic_json> - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
std::hash<nlohmann::basic_json>
 
namespace std {
     struct hash<nlohmann::basic_json>;
 }
 
 
Return a hash value for a JSON object. The hash function tries to rely on std::hash where possible. Furthermore, the type of the JSON value is taken into account to have different hash values for null, 0, 0U, and false, etc.
 
Examples
 
 Example 
The example shows how to calculate hash values for different JSON values.
 
#include <iostream>
@@ -28,4 +28,4 @@
 hash({}) = 2654435832
 hash([]) = 2654435899
 hash({"hello": "world"}) = 4469488738203676328
-
 
Note the output is platform-dependent.
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended for arbitrary basic_json types in version 3.10.5.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Note the output is platform-dependent.

Version history

  • Added in version 1.0.0.
  • Extended for arbitrary basic_json types in version 3.10.5.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/std_swap/index.html b/api/basic_json/std_swap/index.html index 20d504ff7..a97c16c51 100644 --- a/api/basic_json/std_swap/index.html +++ b/api/basic_json/std_swap/index.html @@ -1,4 +1,4 @@ - std::swap<basic_json> - JSON for Modern C++
Skip to content

std::swap<basic_json>

namespace std {
+ std::swap<basic_json> - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
std::swap<basic_json>
 
namespace std {
     void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2);
 }
 
 
Exchanges the values of two JSON objects.
 
Parameters
 
 
j1 (in, out)
 
value to be replaced by j2
 
j2 (in, out)
 
value to be replaced by j1
 
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant.
 
Possible implementation
 
void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2)
@@ -26,4 +26,4 @@
 }
 
 
Output:
 
j1 = {"one":1,"two":2} | j2 = [1,2,4,8,16]
 j1 = [1,2,4,8,16] | j2 = {"one":1,"two":2}
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Extended for arbitrary basic_json types in version 3.10.5.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Extended for arbitrary basic_json types in version 3.10.5.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/string_t/index.html b/api/basic_json/string_t/index.html index 430209ed2..7b7c7ab0c 100644 --- a/api/basic_json/string_t/index.html +++ b/api/basic_json/string_t/index.html @@ -1,4 +1,4 @@ - string_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::string_t

using string_t = StringType;
+ string_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::string_t
 
using string_t = StringType;
 
 
The type used to store JSON strings.
 
RFC 8259 describes JSON strings as follows:
 
 
A string is a sequence of zero or more Unicode characters.
 
 
To store strings in C++, a type is defined by the template parameter described below. Unicode values are split by the JSON class into byte-sized characters during deserialization.
 
Template parameters
 
 
StringType
 
 
the container to store strings (e.g., std::string). Note this container is used for keys/names in objects, see object_t.
 
StringType must have a char-compatible value_type: the library relies on UTF-8/char-based storage and processing internally, so std::wstring, std::u16string, and std::u32string are not valid choices for StringType. To work with wide-character data, convert it to/from UTF-8 at the boundary instead -- see the FAQ's wide string handling section for a conversion recipe.
 
 
 
Notes
 
Default type
 
With the default values for StringType (std::string), the default value for string_t is std::string.
 
Encoding
 
Strings are stored in UTF-8 encoding. Therefore, functions like std::string::size() or std::string::length() return the number of bytes in the string rather than the number of characters or glyphs.
 
String comparison
 
RFC 8259 states:
 
 
Software implementations are typically required to test names of object members for equality. Implementations that transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not equal.
 
 
This implementation is interoperable as it does compare strings code unit by code unit.
 
Storage
 
String values are stored as pointers in a basic_json type. That is, for any access to string values, a pointer of type string_t* must be dereferenced.
 
Cross-basic_json conversion requirements
 
When converting a string value from one basic_json specialization to another via the converting constructor, the target string_t must be directly constructible from the source basic_json's string_t type. If this requirement is not met, the conversion does not fail; instead, the string is silently converted as an array of character codes, which is incorrect. See issue #3425 for details and an example.
 
Examples
 
 Example 
The following code shows that string_t is by default, a typedef to std::string.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -10,4 +10,4 @@
     std::cout << std::boolalpha << std::is_same<std::string, json::string_t>::value << std::endl;
 }
 
 
Output:
 
true
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/swap/index.html b/api/basic_json/swap/index.html index 017bf8b11..cae59578f 100644 --- a/api/basic_json/swap/index.html +++ b/api/basic_json/swap/index.html @@ -1,4 +1,4 @@ - swap - JSON for Modern C++
Skip to content

nlohmann::basic_json::swap

// (1)
+ swap - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::swap
 
// (1)
 void swap(reference other) noexcept (
     std::is_nothrow_move_constructible<value_t>::value &&
     std::is_nothrow_move_assignable<value_t>::value &&
@@ -136,4 +136,4 @@
 }
 
 
Output:
 
value = {"bytes":[4,5,6],"subtype":null}
 binary = {"bytes":[1,2,3],"subtype":null}
-
  
See also
  
Version history
 
     
  1. Since version 1.0.0.
    2.  
  2. Since version 1.0.0.
    3.  
  3. Since version 1.0.0.
    4.  
  4. Since version 1.0.0.
    5.  
  5. Since version 1.0.0.
    6.  
  6. Since version 3.8.0.
    7.  
  7. Since version 3.8.0.
    8.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Since version 1.0.0.
  2. Since version 1.0.0.
  3. Since version 1.0.0.
  4. Since version 1.0.0.
  5. Since version 1.0.0.
  6. Since version 3.8.0.
  7. Since version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/to_bjdata/index.html b/api/basic_json/to_bjdata/index.html index d0493949b..3c0b7b16d 100644 --- a/api/basic_json/to_bjdata/index.html +++ b/api/basic_json/to_bjdata/index.html @@ -1,4 +1,4 @@ - to_bjdata - JSON for Modern C++
Skip to content

nlohmann::basic_json::to_bjdata

// (1)
+ to_bjdata - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::to_bjdata
 
// (1)
 static std::vector<std::uint8_t> to_bjdata(const basic_json& j,
                                            const bool use_size = false,
                                            const bool use_type = false,
@@ -79,4 +79,4 @@
 [i1i2i3i4i5i6i7i8]
 [#i8i1i2i3i4i5i6i7i8
 [$i#i812345678
-
  
See also
 
     
  • from_bjdata create a JSON value from an input in BJData format
    •  
  • to_cbor create a CBOR serialization of a JSON value
    •  
  • to_msgpack create a MessagePack serialization of a JSON value
    •  
  • to_bson create a BSON serialization of a JSON value
    •  
  • to_ubjson create a UBJSON serialization of a JSON value
    •  
 
Version history
 
     
  • Added in version 3.11.0.
    •  
  • BJData version parameter (for draft3 binary encoding) added in version 3.12.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • from_bjdata create a JSON value from an input in BJData format
  • to_cbor create a CBOR serialization of a JSON value
  • to_msgpack create a MessagePack serialization of a JSON value
  • to_bson create a BSON serialization of a JSON value
  • to_ubjson create a UBJSON serialization of a JSON value

Version history

  • Added in version 3.11.0.
  • BJData version parameter (for draft3 binary encoding) added in version 3.12.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/to_bson/index.html b/api/basic_json/to_bson/index.html index 53eff4d23..ba88a2a91 100644 --- a/api/basic_json/to_bson/index.html +++ b/api/basic_json/to_bson/index.html @@ -1,4 +1,4 @@ - to_bson - JSON for Modern C++
Skip to content

nlohmann::basic_json::to_bson

// (1)
+ to_bson - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::to_bson
 
// (1)
 static std::vector<std::uint8_t> to_bson(const basic_json& j);
 
 // (2)
@@ -27,4 +27,4 @@
     std::cout << std::endl;
 }
 
 
Output:
 
0x1b 0x00 0x00 0x00 0x08 0x63 0x6f 0x6d 0x70 0x61 0x63 0x74 0x00 0x01 0x10 0x73 0x63 0x68 0x65 0x6d 0x61 0x00 0x00 0x00 0x00 0x00 0x00 
-
  
See also
 
     
  • from_bson create a JSON value from an input in BSON format
    •  
  • to_cbor create a CBOR serialization of a JSON value
    •  
  • to_msgpack create a MessagePack serialization of a JSON value
    •  
  • to_ubjson create a UBJSON serialization of a JSON value
    •  
  • to_bjdata create a BJData serialization of a JSON value
    •  
 
Version history
 
     
  • Added in version 3.4.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • from_bson create a JSON value from an input in BSON format
  • to_cbor create a CBOR serialization of a JSON value
  • to_msgpack create a MessagePack serialization of a JSON value
  • to_ubjson create a UBJSON serialization of a JSON value
  • to_bjdata create a BJData serialization of a JSON value

Version history

  • Added in version 3.4.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/to_cbor/index.html b/api/basic_json/to_cbor/index.html index 23dbe002d..0fc476ed8 100644 --- a/api/basic_json/to_cbor/index.html +++ b/api/basic_json/to_cbor/index.html @@ -1,4 +1,4 @@ - to_cbor - JSON for Modern C++
Skip to content

nlohmann::basic_json::to_cbor

// (1)
+ to_cbor - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::to_cbor
 
// (1)
 static std::vector<std::uint8_t> to_cbor(const basic_json& j);
 
 // (2)
@@ -27,4 +27,4 @@
     std::cout << std::endl;
 }
 
 
Output:
 
0xa2 0x67 0x63 0x6f 0x6d 0x70 0x61 0x63 0x74 0xf5 0x66 0x73 0x63 0x68 0x65 0x6d 0x61 0x00 
-
  
See also
 
     
  • from_cbor create a JSON value from an input in CBOR format
    •  
  • to_msgpack create a MessagePack serialization of a JSON value
    •  
  • to_bson create a BSON serialization of a JSON value
    •  
  • to_ubjson create a UBJSON serialization of a JSON value
    •  
  • to_bjdata create a BJData serialization of a JSON value
    •  
 
Version history
 
     
  • Added in version 2.0.9.
    •  
  • Compact representation of floating-point numbers added in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • from_cbor create a JSON value from an input in CBOR format
  • to_msgpack create a MessagePack serialization of a JSON value
  • to_bson create a BSON serialization of a JSON value
  • to_ubjson create a UBJSON serialization of a JSON value
  • to_bjdata create a BJData serialization of a JSON value

Version history

  • Added in version 2.0.9.
  • Compact representation of floating-point numbers added in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/to_msgpack/index.html b/api/basic_json/to_msgpack/index.html index 3892c1d23..f55f9bda5 100644 --- a/api/basic_json/to_msgpack/index.html +++ b/api/basic_json/to_msgpack/index.html @@ -1,4 +1,4 @@ - to_msgpack - JSON for Modern C++
Skip to content

nlohmann::basic_json::to_msgpack

// (1)
+ to_msgpack - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::to_msgpack
 
// (1)
 static std::vector<std::uint8_t> to_msgpack(const basic_json& j);
 
 // (2)
@@ -27,4 +27,4 @@
     std::cout << std::endl;
 }
 
 
Output:
 
0x82 0xa7 0x63 0x6f 0x6d 0x70 0x61 0x63 0x74 0xc3 0xa6 0x73 0x63 0x68 0x65 0x6d 0x61 0x00 
-
  
See also
 
     
  • from_msgpack create a JSON value from an input in MessagePack format
    •  
  • to_cbor create a CBOR serialization of a JSON value
    •  
  • to_bson create a BSON serialization of a JSON value
    •  
  • to_ubjson create a UBJSON serialization of a JSON value
    •  
  • to_bjdata create a BJData serialization of a JSON value
    •  
 
Version history
 
     
  • Added in version 2.0.9.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • from_msgpack create a JSON value from an input in MessagePack format
  • to_cbor create a CBOR serialization of a JSON value
  • to_bson create a BSON serialization of a JSON value
  • to_ubjson create a UBJSON serialization of a JSON value
  • to_bjdata create a BJData serialization of a JSON value

Version history

  • Added in version 2.0.9.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/to_string/index.html b/api/basic_json/to_string/index.html index 19959546b..68c7188f8 100644 --- a/api/basic_json/to_string/index.html +++ b/api/basic_json/to_string/index.html @@ -1,4 +1,4 @@ - to_string - JSON for Modern C++
Skip to content

to_string(basic_json)

template <typename BasicJsonType>
+ to_string - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
to_string(basic_json)
 
template <typename BasicJsonType>
 std::string to_string(const BasicJsonType& j);
 
 
This function implements a user-defined to_string for JSON objects.
 
Template parameters
 
 
BasicJsonType
 
a specialization of basic_json
 
 
Return value
 
string containing the serialization of the JSON value
 
Exception safety
 
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 
Exceptions
 
Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded
 
Complexity
 
Linear.
 
Possible implementation
 
template <typename BasicJsonType>
 std::string to_string(const BasicJsonType& j)
@@ -28,4 +28,4 @@
 
 
Output:
 
{"one":1,"two":2}
 
 42
-
  
See also
  
Version history
 
Added in version 3.7.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Added in version 3.7.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/to_ubjson/index.html b/api/basic_json/to_ubjson/index.html index f29370572..1b918a485 100644 --- a/api/basic_json/to_ubjson/index.html +++ b/api/basic_json/to_ubjson/index.html @@ -1,4 +1,4 @@ - to_ubjson - JSON for Modern C++
Skip to content

nlohmann::basic_json::to_ubjson

// (1)
+ to_ubjson - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::to_ubjson
 
// (1)
 static std::vector<std::uint8_t> to_ubjson(const basic_json& j,
                                            const bool use_size = false,
                                            const bool use_type = false);
@@ -76,4 +76,4 @@
 [i1i2i3i4i5i6i7i8]
 [#i8i1i2i3i4i5i6i7i8
 [$i#i812345678
-
  
See also
 
     
  • from_ubjson create a JSON value from an input in UBJSON format
    •  
  • to_cbor create a CBOR serialization of a JSON value
    •  
  • to_msgpack create a MessagePack serialization of a JSON value
    •  
  • to_bson create a BSON serialization of a JSON value
    •  
  • to_bjdata create a BJData serialization of a JSON value
    •  
 
Version history
 
     
  • Added in version 3.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • from_ubjson create a JSON value from an input in UBJSON format
  • to_cbor create a CBOR serialization of a JSON value
  • to_msgpack create a MessagePack serialization of a JSON value
  • to_bson create a BSON serialization of a JSON value
  • to_bjdata create a BJData serialization of a JSON value

Version history

  • Added in version 3.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/type/index.html b/api/basic_json/type/index.html index 74a649650..b0bfedb1c 100644 --- a/api/basic_json/type/index.html +++ b/api/basic_json/type/index.html @@ -1,4 +1,4 @@ - type - JSON for Modern C++
Skip to content

nlohmann::basic_json::type

constexpr value_t type() const noexcept;
+ type - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::type
 
constexpr value_t type() const noexcept;
 
 
Return the type of the JSON value as a value from the value_t enumeration.
 
Return value
 
the type of the JSON value
 
  
 Value type return value 
   
 null value_t::null 
 
 boolean value_t::boolean 
 
 string value_t::string 
 
 number (integer) value_t::number_integer 
 
 number (unsigned integer) value_t::number_unsigned 
 
 number (floating-point) value_t::number_float 
 
 object value_t::object 
 
 array value_t::array 
 
 binary value_t::binary 
 
 discarded value_t::discarded 
  
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies type() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -35,4 +35,4 @@
 true
 true
 true
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Added unsigned integer type in version 2.0.0.
    •  
  • Added binary type in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Added unsigned integer type in version 2.0.0.
  • Added binary type in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/type_error/index.html b/api/basic_json/type_error/index.html index 6b15b09d6..bec53527e 100644 --- a/api/basic_json/type_error/index.html +++ b/api/basic_json/type_error/index.html @@ -1,4 +1,4 @@ - type_error - JSON for Modern C++
Skip to content

nlohmann::basic_json::type_error

class type_error : public exception;
+ type_error - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::type_error
 
class type_error : public exception;
 
 
This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type does not match the expected semantics.
 
Exceptions have ids 3xx (see list of type errors).
 
classDiagram
   direction LR
 
@@ -49,4 +49,4 @@
 }
 
 
Output:
 
message: [json.exception.type_error.308] cannot use push_back() with string
 exception id: 308
-
  
See also
  
Version history
 
     
  • Since version 3.0.0.
    •
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

Version history

\ No newline at end of file diff --git a/api/basic_json/type_name/index.html b/api/basic_json/type_name/index.html index c4fc559b6..aa4a35374 100644 --- a/api/basic_json/type_name/index.html +++ b/api/basic_json/type_name/index.html @@ -1,4 +1,4 @@ - type_name - JSON for Modern C++
Skip to content

nlohmann::basic_json::type_name

const char* type_name() const noexcept;
+ type_name - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::type_name
 
const char* type_name() const noexcept;
 
 
Returns the type name as string to be used in error messages -- usually to indicate that a function was called on a wrong JSON type.
 
Return value
 
a string representation of the type (value_t):
 
  
 Value type return value 
   
 null "null" 
 
 boolean "boolean" 
 
 string "string" 
 
 number (integer, unsigned integer, floating-point) "number" 
 
 object "object" 
 
 array "array" 
 
 binary "binary" 
 
 discarded "discarded" 
 
 invalid (corrupted value) "invalid" 
  
 
 
The \"invalid\" type
 
The "invalid" return value indicates a corrupted JSON value — this can occur if an enum value falls outside the range of valid value_t values. This is useful for diagnosing data corruption or internal errors.
 
 
Exception safety
 
No-throw guarantee: this member function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The following code exemplifies type_name() for all JSON types.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -34,4 +34,4 @@
 {"one":1,"two":2} is an object
 [1,2,4,8,16] is an array
 "Hello, world" is a string
-
 
 
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Part of the public API version since 2.1.0.
    •  
  • Changed return value to const char* and added noexcept in version 3.0.0.
    •  
  • Added support for binary type in version 3.8.0.
    •  
  • Added "invalid" return value for corrupted JSON values in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Part of the public API version since 2.1.0.
  • Changed return value to const char* and added noexcept in version 3.0.0.
  • Added support for binary type in version 3.8.0.
  • Added "invalid" return value for corrupted JSON values in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/unflatten/index.html b/api/basic_json/unflatten/index.html index 59e00a6c2..e1dfe18b6 100644 --- a/api/basic_json/unflatten/index.html +++ b/api/basic_json/unflatten/index.html @@ -1,4 +1,4 @@ - unflatten - JSON for Modern C++
Skip to content

nlohmann::basic_json::unflatten

basic_json unflatten() const;
+ unflatten - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::unflatten
 
basic_json unflatten() const;
 
 
The function restores the arbitrary nesting of a JSON value that has been flattened before using the flatten() function. The JSON value must meet certain constraints:
 
     
  1. The value must be an object.
    2.  
  2. The keys must be JSON pointers (see RFC 6901)
    3.  
  3. The mapped values must be primitive JSON types.
    4.  
 
Return value
 
the original JSON from a flattened version
 
Exception safety
 
Strong exception safety: if an exception occurs, the original value stays intact.
 
Exceptions
 
The function can throw the following exceptions:
 
     
  • Throws type_error.314 if value is not an object
    •  
  • Throws type_error.315 if object values are not primitive
    •  
  • Throws type_error.313 if a key (JSON pointer) leads to a conflicting nesting; example: "invalid value to unflatten"
    •  
  • Throws parse_error.109 if an array index in a key is not a number; example: "array index 'one' is not a number"
    •  
 
Complexity
 
Linear in the size of the JSON value.
 
Notes
 
Empty objects and arrays are flattened by flatten() to null values and cannot unflattened to their original type. Apart from this example, for a JSON value j, the following is always true: j == j.flatten().unflatten().
 
Examples
 
 Example 
The following code shows how a flattened JSON object is unflattened into the original nested JSON object.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -43,4 +43,4 @@
     },
     "pi": 3.141
 }
-
 
 
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/update/index.html b/api/basic_json/update/index.html index 089f323f5..c731eda0d 100644 --- a/api/basic_json/update/index.html +++ b/api/basic_json/update/index.html @@ -1,4 +1,4 @@ - update - JSON for Modern C++
Skip to content

nlohmann::basic_json::update

// (1)
+ update - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::update
 
// (1)
 void update(const_reference j, bool merge_objects = false);
 
 // (2)
@@ -110,4 +110,4 @@
     "active": true,
     "name": {"de": "Maus", "en": "mouse", "es": "ratón"}
 }
-
  
See also
  
Version history
 
     
  • Added in version 3.0.0.
    •  
  • Added merge_objects parameter in 3.10.5.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.0.0.
  • Added merge_objects parameter in 3.10.5.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/value/index.html b/api/basic_json/value/index.html index 59f452cd4..eb26ee6ef 100644 --- a/api/basic_json/value/index.html +++ b/api/basic_json/value/index.html @@ -1,4 +1,4 @@ - value - JSON for Modern C++
Skip to content

nlohmann::basic_json::value

// (1)
+ value - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::value
 
// (1)
 template<class ValueType>
 ValueType value(const typename object_t::key_type& key,
                 ValueType&& default_value) const;
@@ -136,4 +136,4 @@
               << " " << v_string << " " << v_boolean << "\n";
 }
 
 
Output:
 
1 42.23 oops false
-
  
See also
 
     
  • see at for access by reference with range checking
    •  
  • see operator[] for unchecked access by reference
    •  
 
Version history
 
     
  1. Added in version 1.0.0. Changed parameter default_value type from const ValueType& to ValueType&& in version 3.11.0.
    2.  
  2. Added in version 3.11.0. Made ValueType the first template parameter in version 3.11.2.
    3.  
  3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving ptr through an array unexpectedly threw out_of_range instead of returning the resolved element (or default_value, as documented).
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • see at for access by reference with range checking
  • see operator[] for unchecked access by reference

Version history

  1. Added in version 1.0.0. Changed parameter default_value type from const ValueType& to ValueType&& in version 3.11.0.
  2. Added in version 3.11.0. Made ValueType the first template parameter in version 3.11.2.
  3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving ptr through an array unexpectedly threw out_of_range instead of returning the resolved element (or default_value, as documented).
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/value_t/index.html b/api/basic_json/value_t/index.html index 1c77649b1..b8d4838ff 100644 --- a/api/basic_json/value_t/index.html +++ b/api/basic_json/value_t/index.html @@ -1,4 +1,4 @@ - value_t - JSON for Modern C++
Skip to content

nlohmann::basic_json::value_t

enum class value_t : std::uint8_t {
+ value_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::basic_json::value_t
 
enum class value_t : std::uint8_t {
     null,
     object,
     array,
@@ -46,4 +46,4 @@
 true
 true
 true
-
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Added unsigned integer type in version 2.0.0.
    •  
  • Added binary type in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 1.0.0.
  • Added unsigned integer type in version 2.0.0.
  • Added binary type in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/basic_json/~basic_json/index.html b/api/basic_json/~basic_json/index.html index 8992a2db2..c5256459d 100644 --- a/api/basic_json/~basic_json/index.html +++ b/api/basic_json/~basic_json/index.html @@ -1,2 +1,2 @@ - (Destructor) - JSON for Modern C++
Skip to content

nlohmann::basic_json::~basic_json

~basic_json() noexcept;
-

Destroys the JSON value and frees all allocated memory.

Exception safety

No-throw guarantee: this member function never throws exceptions.

Complexity

Linear.

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + (Destructor) - JSON for Modern C++
Skip to content

nlohmann::basic_json::~basic_json

~basic_json() noexcept;
+

Destroys the JSON value and frees all allocated memory.

Exception safety

No-throw guarantee: this member function never throws exceptions.

Complexity

Linear.

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/byte_container_with_subtype/byte_container_with_subtype/index.html b/api/byte_container_with_subtype/byte_container_with_subtype/index.html index 9876700f2..2de8bd1a1 100644 --- a/api/byte_container_with_subtype/byte_container_with_subtype/index.html +++ b/api/byte_container_with_subtype/byte_container_with_subtype/index.html @@ -1,4 +1,4 @@ - (constructor) - JSON for Modern C++
Skip to content

nlohmann::byte_container_with_subtype::byte_container_with_subtype

// (1)
+ (constructor) - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::byte_container_with_subtype::byte_container_with_subtype
 
// (1)
 byte_container_with_subtype();
 
 // (2)
@@ -34,4 +34,4 @@
 
 
Output:
 
{"bytes":[],"subtype":null}
 {"bytes":[202,254,186,190],"subtype":null}
 {"bytes":[202,254,186,190],"subtype":42}
-
  
Version history
 
Since version 3.8.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Since version 3.8.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/byte_container_with_subtype/clear_subtype/index.html b/api/byte_container_with_subtype/clear_subtype/index.html index 40545d543..50304ab08 100644 --- a/api/byte_container_with_subtype/clear_subtype/index.html +++ b/api/byte_container_with_subtype/clear_subtype/index.html @@ -1,4 +1,4 @@ - clear_subtype - JSON for Modern C++
Skip to content

nlohmann::byte_container_with_subtype::clear_subtype

void clear_subtype() noexcept;
+ clear_subtype - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::byte_container_with_subtype::clear_subtype
 
void clear_subtype() noexcept;
 
 
Clears the binary subtype and flags the value as not having a subtype, which has implications for serialization; for instance, MessagePack will prefer the bin family over the ext family.
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example below demonstrates how clear_subtype can remove subtypes.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -22,4 +22,4 @@
 }
 
 
Output:
 
before calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":42}
 after calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":null}
-
 
 
Version history
 
Since version 3.8.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Since version 3.8.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/byte_container_with_subtype/has_subtype/index.html b/api/byte_container_with_subtype/has_subtype/index.html index 721417807..96243ac7e 100644 --- a/api/byte_container_with_subtype/has_subtype/index.html +++ b/api/byte_container_with_subtype/has_subtype/index.html @@ -1,4 +1,4 @@ - has_subtype - JSON for Modern C++
Skip to content

nlohmann::byte_container_with_subtype::has_subtype

constexpr bool has_subtype() const noexcept;
+ has_subtype - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::byte_container_with_subtype::has_subtype
 
constexpr bool has_subtype() const noexcept;
 
 
Returns whether the value has a subtype.
 
Return value
 
whether the value has a subtype
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example below demonstrates how has_subtype can check whether a subtype was set.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -20,4 +20,4 @@
 }
 
 
Output:
 
c1.has_subtype() = false
 c2.has_subtype() = true
-
 
 
Version history
 
Since version 3.8.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Since version 3.8.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/byte_container_with_subtype/index.html b/api/byte_container_with_subtype/index.html index 449acc7f6..733990b54 100644 --- a/api/byte_container_with_subtype/index.html +++ b/api/byte_container_with_subtype/index.html @@ -1,3 +1,3 @@ - Overview - JSON for Modern C++
Skip to content

nlohmann::byte_container_with_subtype

template<typename BinaryType>
+ Overview - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::byte_container_with_subtype
 
template<typename BinaryType>
 class byte_container_with_subtype : public BinaryType;
-
 
This type extends the template parameter BinaryType provided to basic_json with a subtype used by BSON and MessagePack. This type exists so that the user does not have to specify a type themselves with a specific naming scheme in order to override the binary type.
 
Template parameters
 
 
BinaryType
 
container to store bytes (std::vector<std::uint8_t> by default)
 
 
Member types
 
     
  • container_type - the type of the underlying container (BinaryType)
    •  
  • subtype_type - the type of the subtype (std::uint64_t)
    •  
 
Member functions
  
Version history
 
     
  • Added in version 3.8.0.
    •  
  • Changed the type of subtypes to std::uint64_t in 3.10.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

This type extends the template parameter BinaryType provided to basic_json with a subtype used by BSON and MessagePack. This type exists so that the user does not have to specify a type themselves with a specific naming scheme in order to override the binary type.

Template parameters

BinaryType
container to store bytes (std::vector<std::uint8_t> by default)

Member types

  • container_type - the type of the underlying container (BinaryType)
  • subtype_type - the type of the subtype (std::uint64_t)

Member functions

Version history

  • Added in version 3.8.0.
  • Changed the type of subtypes to std::uint64_t in 3.10.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/byte_container_with_subtype/set_subtype/index.html b/api/byte_container_with_subtype/set_subtype/index.html index a0a61ce7d..201ced96f 100644 --- a/api/byte_container_with_subtype/set_subtype/index.html +++ b/api/byte_container_with_subtype/set_subtype/index.html @@ -1,4 +1,4 @@ - set_subtype - JSON for Modern C++
Skip to content

nlohmann::byte_container_with_subtype::set_subtype

void set_subtype(subtype_type subtype) noexcept;
+ set_subtype - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::byte_container_with_subtype::set_subtype
 
void set_subtype(subtype_type subtype) noexcept;
 
 
Sets the binary subtype of the value, also flags a binary JSON value as having a subtype, which has implications for serialization.
 
Parameters
 
 
subtype (in)
 
subtype to set
 
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example below demonstrates how a subtype can be set with set_subtype.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -23,4 +23,4 @@
 }
 
 
Output:
 
before calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":null}
 after calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":42}
-
 
 
Version history
 
Since version 3.8.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Since version 3.8.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/byte_container_with_subtype/subtype/index.html b/api/byte_container_with_subtype/subtype/index.html index cfdbbe96a..ace3c9db7 100644 --- a/api/byte_container_with_subtype/subtype/index.html +++ b/api/byte_container_with_subtype/subtype/index.html @@ -1,4 +1,4 @@ - subtype - JSON for Modern C++
Skip to content

nlohmann::byte_container_with_subtype::subtype

constexpr subtype_type subtype() const noexcept;
+ subtype - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::byte_container_with_subtype::subtype
 
constexpr subtype_type subtype() const noexcept;
 
 
Returns the numerical subtype of the value if it has a subtype. If it does not have a subtype, this function will return subtype_type(-1) as a sentinel value.
 
Return value
 
the numerical subtype of the binary value, or subtype_type(-1) if no subtype is set
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example below demonstrates how the subtype can be retrieved with subtype. Note how subtype_type(-1) is returned for container c1.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -23,4 +23,4 @@
 }
 
 
Output:
 
c1.subtype() = 18446744073709551615
 c2.subtype() = 42
-
 
 
Version history
 
     
  • Added in version 3.8.0
    •  
  • Fixed return value to properly return subtype_type(-1) as documented in version 3.10.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.8.0
  • Fixed return value to properly return subtype_type(-1) as documented in version 3.10.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json/index.html b/api/json/index.html index bdf85eee8..21cb61a20 100644 --- a/api/json/index.html +++ b/api/json/index.html @@ -1,4 +1,4 @@ - json - JSON for Modern C++
Skip to content

nlohmann::json

using json = basic_json<>;
+ json - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json
 
using json = basic_json<>;
 
 
This type is the default specialization of the basic_json class which uses the standard template types.
 
Examples
 
 Example 
The example below demonstrates how to use the type nlohmann::json.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
@@ -65,4 +65,4 @@
     "pi": 3.141,
     "size": 8
 }
-
 
 
Version history
 
Since version 1.0.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Since version 1.0.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/back/index.html b/api/json_pointer/back/index.html index 4f6f14bb3..a8cd92d0d 100644 --- a/api/json_pointer/back/index.html +++ b/api/json_pointer/back/index.html @@ -1,4 +1,4 @@ - back - JSON for Modern C++
Skip to content

nlohmann::json_pointer::back

const string_t& back() const;
+ back - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::back
 
const string_t& back() const;
 
 
Return the last reference token.
 
Return value
 
Last reference token.
 
Exceptions
 
Throws out_of_range.405 if the JSON pointer has no parent.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example shows the usage of back.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -16,4 +16,4 @@
 }
 
 
Output:
 
last reference token of "/foo" is "foo"
 last reference token of "/foo/0" is "0"
-
 
 
Version history
 
     
  • Added in version 3.6.0.
    •  
  • Changed return type to string_t in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.6.0.
  • Changed return type to string_t in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/empty/index.html b/api/json_pointer/empty/index.html index f613bd18a..0b4c2c6a1 100644 --- a/api/json_pointer/empty/index.html +++ b/api/json_pointer/empty/index.html @@ -1,4 +1,4 @@ - empty - JSON for Modern C++
Skip to content

nlohmann::json_pointer::empty

bool empty() const noexcept;
+ empty - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::empty
 
bool empty() const noexcept;
 
 
Return whether the pointer points to the root document.
 
Return value
 
true iff the JSON pointer points to the root document.
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example shows the result of empty for different JSON Pointers.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -23,4 +23,4 @@
 "": true
 "/foo": false
 "/foo/0": false
-
 
 
Version history
 
Added in version 3.6.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Added in version 3.6.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/front/index.html b/api/json_pointer/front/index.html index 0e13045ac..826c40ce8 100644 --- a/api/json_pointer/front/index.html +++ b/api/json_pointer/front/index.html @@ -1,4 +1,4 @@ - front - JSON for Modern C++
Skip to content

nlohmann::json_pointer::front

const string_t& front() const;
+ front - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::front
 
const string_t& front() const;
 
 
Return the first reference token.
 
Return value
 
First reference token.
 
Exceptions
 
Throws out_of_range.405 if the JSON pointer has no parent.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example shows the usage of front.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -16,4 +16,4 @@
 }
 
 
Output:
 
first reference token of "/foo" is "foo"
 first reference token of "/foo/0" is "foo"
-
 
 
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/index.html b/api/json_pointer/index.html index 56c0409ba..332024827 100644 --- a/api/json_pointer/index.html +++ b/api/json_pointer/index.html @@ -1,3 +1,3 @@ - Overview - JSON for Modern C++
Skip to content

nlohmann::json_pointer

template<typename RefStringType>
+ Overview - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer
 
template<typename RefStringType>
 class json_pointer;
-
 
A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with functions at and operator[]. Furthermore, JSON pointers are the base for JSON patches.
 
Template parameters
 
 
RefStringType
 
the string type used for the reference tokens making up the JSON pointer
 
 
 
Deprecation
 
For backwards compatibility RefStringType may also be a specialization of basic_json in which case string_t will be deduced as basic_json::string_t. This feature is deprecated and may be removed in a future major version.
 
 
Member types
 
     
  • string_t - the string type used for the reference tokens
    •  
 
Member functions
 
     
  • (constructor)
    •  
  • to_string - return a string representation of the JSON pointer
    •  
  • operator string_t - return a string representation of the JSON pointer
    •  
  • operator== - compare: equal
    •  
  • operator!= - compare: not equal
    •  
  • operator/= - append to the end of the JSON pointer
    •  
  • operator/ - create JSON Pointer by appending
    •  
  • parent_pointer - returns the parent of this JSON pointer
    •  
  • pop_back - remove the last reference token
    •  
  • back - return last reference token
    •  
  • push_back - append an unescaped token at the end of the pointer
    •  
  • pop_front - remove the first reference token
    •  
  • front - return first reference token
    •  
  • push_front - append an unescaped token at the start of the pointer
    •  
  • empty - return whether the pointer points to the root document
    •  
 
Literals
  
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
  • Changed template parameter from basic_json to string type in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with functions at and operator[]. Furthermore, JSON pointers are the base for JSON patches.

Template parameters

RefStringType
the string type used for the reference tokens making up the JSON pointer

Deprecation

For backwards compatibility RefStringType may also be a specialization of basic_json in which case string_t will be deduced as basic_json::string_t. This feature is deprecated and may be removed in a future major version.

Member types

  • string_t - the string type used for the reference tokens

Member functions

  • (constructor)
  • to_string - return a string representation of the JSON pointer
  • operator string_t - return a string representation of the JSON pointer
  • operator== - compare: equal
  • operator!= - compare: not equal
  • operator/= - append to the end of the JSON pointer
  • operator/ - create JSON Pointer by appending
  • parent_pointer - returns the parent of this JSON pointer
  • pop_back - remove the last reference token
  • back - return last reference token
  • push_back - append an unescaped token at the end of the pointer
  • pop_front - remove the first reference token
  • front - return first reference token
  • push_front - append an unescaped token at the start of the pointer
  • empty - return whether the pointer points to the root document

Literals

See also

Version history

  • Added in version 2.0.0.
  • Changed template parameter from basic_json to string type in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/json_pointer/index.html b/api/json_pointer/json_pointer/index.html index 1c1768f69..aa1385ae5 100644 --- a/api/json_pointer/json_pointer/index.html +++ b/api/json_pointer/json_pointer/index.html @@ -1,4 +1,4 @@ - (Constructor) - JSON for Modern C++
Skip to content

nlohmann::json_pointer::json_pointer

explicit json_pointer(const string_t& s = "");
+ (Constructor) - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::json_pointer
 
explicit json_pointer(const string_t& s = "");
 
 
Create a JSON pointer according to the syntax described in Section 3 of RFC6901.
 
Parameters
 
 
s (in)
 
string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value
 
 
Exceptions
 
     
  • Throws parse_error.107 if the given JSON pointer s is nonempty and does not begin with a slash (/); see example below.
    •  
  • Throws parse_error.108 if a tilde (~) in the given JSON pointer s is not followed by 0 (representing ~) or 1 (representing /); see example below.
    •  
 
Examples
 
 Example 
The example shows the construction several valid JSON pointers as well as the exceptional behavior.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -49,4 +49,4 @@
 
 
Output:
 
[json.exception.parse_error.107] parse error at byte 1: JSON pointer must be empty or begin with '/' - was: 'foo'
 [json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
 [json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
-
 
 
Version history
 
     
  • Added in version 2.0.0.
    •  
  • Changed type of s to string_t in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 2.0.0.
  • Changed type of s to string_t in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/operator_eq/index.html b/api/json_pointer/operator_eq/index.html index 8c68514d9..84903d64b 100644 --- a/api/json_pointer/operator_eq/index.html +++ b/api/json_pointer/operator_eq/index.html @@ -1,4 +1,4 @@ - operator== - JSON for Modern C++
Skip to content

nlohmann::json_pointer::operator==

// until C++20
+ operator== - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::operator==
 
// until C++20
 template<typename RefStringTypeLhs, typename RefStringTypeRhs>
 bool operator==(
     const json_pointer<RefStringTypeLhs>& lhs,
@@ -82,4 +82,4 @@
 "" == "": true
 "/foo" == "/foo": true
 "bar" == "/foo": [json.exception.parse_error.107] parse error at byte 1: JSON pointer must be empty or begin with '/' - was: 'bar'
-
  
Version history
 
     
  1. Added in version 2.1.0. Added C++20 member functions in version 3.11.2.
    2.  
  2. Added for backward compatibility and deprecated in version 3.11.2.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Added in version 2.1.0. Added C++20 member functions in version 3.11.2.
  2. Added for backward compatibility and deprecated in version 3.11.2.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/operator_ne/index.html b/api/json_pointer/operator_ne/index.html index f7579d78b..4b6f641df 100644 --- a/api/json_pointer/operator_ne/index.html +++ b/api/json_pointer/operator_ne/index.html @@ -1,4 +1,4 @@ - operator!= - JSON for Modern C++
Skip to content

nlohmann::json_pointer::operator!=

// until C++20
+ operator!= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::operator!=
 
// until C++20
 template<typename RefStringTypeLhs, typename RefStringTypeRhs>
 bool operator!=(
     const json_pointer<RefStringTypeLhs>& lhs,
@@ -72,4 +72,4 @@
 "" != "": false
 "/foo" != "/foo": false
 "bar" != "/foo": [json.exception.parse_error.107] parse error at byte 1: JSON pointer must be empty or begin with '/' - was: 'bar'
-
  
Version history
 
     
  1. Added in version 2.1.0.
    2.  
  2. Added for backward compatibility and deprecated in version 3.11.2.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Added in version 2.1.0.
  2. Added for backward compatibility and deprecated in version 3.11.2.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/operator_slash/index.html b/api/json_pointer/operator_slash/index.html index 8547c3405..fbb6970e6 100644 --- a/api/json_pointer/operator_slash/index.html +++ b/api/json_pointer/operator_slash/index.html @@ -1,4 +1,4 @@ - operator/ - JSON for Modern C++
Skip to content

nlohmann::json_pointer::operator/

// (1)
+ operator/ - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::operator/
 
// (1)
 json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs);
 
 // (2)
@@ -28,4 +28,4 @@
 
 
Output:
 
"/foo/bar/baz"
 "/foo/fob"
 "/foo/42"
-
  
Version history
 
     
  1. Added in version 3.6.0.
    2.  
  2. Added in version 3.6.0. Changed type of token to string_t in version 3.11.0.
    3.  
  3. Added in version 3.6.0.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Added in version 3.6.0.
  2. Added in version 3.6.0. Changed type of token to string_t in version 3.11.0.
  3. Added in version 3.6.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/operator_slasheq/index.html b/api/json_pointer/operator_slasheq/index.html index 421c3a473..44da13cba 100644 --- a/api/json_pointer/operator_slasheq/index.html +++ b/api/json_pointer/operator_slasheq/index.html @@ -1,4 +1,4 @@ - operator/= - JSON for Modern C++
Skip to content

nlohmann::json_pointer::operator/=

// (1)
+ operator/= - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::operator/=
 
// (1)
 json_pointer& operator/=(const json_pointer& ptr);
 
 // (2)
@@ -33,4 +33,4 @@
 "/foo/bar/baz"
 "/foo/bar/baz/fob"
 "/foo/bar/baz/fob/42"
-
  
Version history
 
     
  1. Added in version 3.6.0.
    2.  
  2. Added in version 3.6.0. Changed type of token to string_t in version 3.11.0.
    3.  
  3. Added in version 3.6.0.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Added in version 3.6.0.
  2. Added in version 3.6.0. Changed type of token to string_t in version 3.11.0.
  3. Added in version 3.6.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/operator_string_t/index.html b/api/json_pointer/operator_string_t/index.html index 1690d316e..b2d0c03a2 100644 --- a/api/json_pointer/operator_string_t/index.html +++ b/api/json_pointer/operator_string_t/index.html @@ -1,4 +1,4 @@ - operator string_t - JSON for Modern C++
Skip to content

nlohmann::json_pointer::operator string_t

operator string_t() const
+ operator string_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::operator string_t
 
operator string_t() const
 
 
Return a string representation of the JSON pointer.
 
Return value
 
A string representation of the JSON pointer
 
Possible implementation
 
operator string_t() const
 {
     return to_string();
@@ -24,4 +24,4 @@
 }
 
 
Output:
 
/foo/0
 /a~1b
-
  
See also
  
Version history
 
     
  • Since version 2.0.0.
    •  
  • Changed type to string_t and deprecated in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Since version 2.0.0.
  • Changed type to string_t and deprecated in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/parent_pointer/index.html b/api/json_pointer/parent_pointer/index.html index bc8806973..4864c0231 100644 --- a/api/json_pointer/parent_pointer/index.html +++ b/api/json_pointer/parent_pointer/index.html @@ -1,4 +1,4 @@ - parent_pointer - JSON for Modern C++
Skip to content

nlohmann::json_pointer::parent_pointer

json_pointer parent_pointer() const;
+ parent_pointer - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::parent_pointer
 
json_pointer parent_pointer() const;
 
 
Returns the parent of this JSON pointer.
 
Return value
 
Parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned.
 
Exception safety
 
No-throw guarantee: this function never throws exceptions.
 
Complexity
 
Linear in the length of the JSON pointer.
 
Examples
 
 Example 
The example shows the result of parent_pointer for different JSON Pointers.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -20,4 +20,4 @@
 
 
Output:
 
parent of "" is ""
 parent of "/foo" is ""
 parent of "/foo/0" is "/foo"
-
 
 
See also
 
     
  • pop_back remove the last reference token
    •  
  • back return the last reference token
    •  
 
Version history
 
Added in version 3.6.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • pop_back remove the last reference token
  • back return the last reference token

Version history

Added in version 3.6.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/pop_back/index.html b/api/json_pointer/pop_back/index.html index d6c146649..b19472a37 100644 --- a/api/json_pointer/pop_back/index.html +++ b/api/json_pointer/pop_back/index.html @@ -1,4 +1,4 @@ - pop_back - JSON for Modern C++
Skip to content

nlohmann::json_pointer::pop_back

void pop_back();
+ pop_back - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::pop_back
 
void pop_back();
 
 
Remove the last reference token.
 
Exceptions
 
Throws out_of_range.405 if the JSON pointer has no parent.
 
Complexity
 
Constant.
 
Examples
 
 Example 
The example shows the usage of pop_back.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -24,4 +24,4 @@
 "/foo/bar"
 "/foo"
 ""
-
 
 
Version history
 
Added in version 3.6.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Added in version 3.6.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/pop_front/index.html b/api/json_pointer/pop_front/index.html index 3f6e723ff..888ff4b61 100644 --- a/api/json_pointer/pop_front/index.html +++ b/api/json_pointer/pop_front/index.html @@ -1,4 +1,4 @@ - pop_front - JSON for Modern C++
Skip to content

nlohmann::json_pointer::pop_front

void pop_front();
+ pop_front - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::pop_front
 
void pop_front();
 
 
Remove the first reference token.
 
Exceptions
 
Throws out_of_range.405 if the JSON pointer has no parent.
 
Complexity
 
Linear in the number of reference tokens in the json_pointer.
 
Examples
 
 Example 
The example shows the usage of pop_front.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -24,4 +24,4 @@
 "/bar/baz"
 "/baz"
 ""
-
 
 
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/push_back/index.html b/api/json_pointer/push_back/index.html index e12ba5bf4..cbf400d42 100644 --- a/api/json_pointer/push_back/index.html +++ b/api/json_pointer/push_back/index.html @@ -1,4 +1,4 @@ - push_back - JSON for Modern C++
Skip to content

nlohmann::json_pointer::push_back

void push_back(const string_t& token);
+ push_back - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::push_back
 
void push_back(const string_t& token);
 
 void push_back(string_t&& token);
 
 
Append an unescaped token at the end of the reference pointer.
 
Parameters
 
 
token (in)
 
token to add
 
 
Complexity
 
Amortized constant.
 
Examples
 
 Example 
The example shows the result of push_back for different JSON Pointers.
 
#include <iostream>
@@ -26,4 +26,4 @@
 "/foo"
 "/foo/0"
 "/foo/0/bar"
-
 
 
Version history
 
     
  • Added in version 3.6.0.
    •  
  • Changed type of token to string_t in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.6.0.
  • Changed type of token to string_t in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/push_front/index.html b/api/json_pointer/push_front/index.html index c2ee566fc..799a6ab42 100644 --- a/api/json_pointer/push_front/index.html +++ b/api/json_pointer/push_front/index.html @@ -1,4 +1,4 @@ - push_front - JSON for Modern C++
Skip to content

nlohmann::json_pointer::push_front

void push_front(const string_t& token);
+ push_front - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::push_front
 
void push_front(const string_t& token);
 
 void push_front(string_t&& token);
 
 
Append an unescaped token at the start of the reference pointer.
 
Parameters
 
 
token (in)
 
token to add
 
 
Complexity
 
Linear in the number of reference tokens in the json_pointer.
 
Examples
 
 Example 
The example shows the result of push_front for different JSON Pointers.
 
#include <iostream>
@@ -26,4 +26,4 @@
 "/foo"
 "/0/foo"
 "/bar/0/foo"
-
 
 
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/string_t/index.html b/api/json_pointer/string_t/index.html index 9f3d43c94..0f23e50db 100644 --- a/api/json_pointer/string_t/index.html +++ b/api/json_pointer/string_t/index.html @@ -1,4 +1,4 @@ - string_t - JSON for Modern C++
Skip to content

nlohmann::json_pointer::string_t

using string_t = RefStringType;
+ string_t - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::string_t
 
using string_t = RefStringType;
 
 
The string type used for the reference tokens making up the JSON pointer.
 
See basic_json::string_t for more information.
 
Examples
 
 Example 
The example shows the type string_t and its relation to basic_json::string_t.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -14,4 +14,4 @@
 }
 
 
Output:
 
This is a string.
 true
-
 
 
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_pointer/to_string/index.html b/api/json_pointer/to_string/index.html index 517405b33..ab2b13d4e 100644 --- a/api/json_pointer/to_string/index.html +++ b/api/json_pointer/to_string/index.html @@ -1,4 +1,4 @@ - to_string - JSON for Modern C++
Skip to content

nlohmann::json_pointer::to_string

string_t to_string() const;
+ to_string - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_pointer::to_string
 
string_t to_string() const;
 
 
Return a string representation of the JSON pointer.
 
Return value
 
A string representation of the JSON pointer
 
Notes
 
For each JSON pointer ptr, it holds:
 
ptr == json_pointer(ptr.to_string());
 
 
Examples
 
 Example 
The example shows the result of to_string.
 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -46,4 +46,4 @@
 "/k"l"
 "/ "
 "/m~0n"
-
 
 
Version history
 
     
  • Since version 2.0.0.
    •  
  • Changed return type to string_t in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Since version 2.0.0.
  • Changed return type to string_t in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/binary/index.html b/api/json_sax/binary/index.html index afe07e5f8..bdfc39062 100644 --- a/api/json_sax/binary/index.html +++ b/api/json_sax/binary/index.html @@ -1,4 +1,4 @@ - binary - JSON for Modern C++
Skip to content

nlohmann::json_sax::binary

virtual bool binary(binary_t& val) = 0;
+ binary - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::binary
 
virtual bool binary(binary_t& val) = 0;
 
 
A binary value was read.
 
Parameters
 
 
val (in)
 
binary value
 
 
Return value
 
Whether parsing should proceed.
 
Notes
 
It is safe to move the passed binary value.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -116,4 +116,4 @@
 
 
Output:
 
binary(val=[...])
 
 result: true
-
 
 
Version history
 
     
  • Added in version 3.8.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.8.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/boolean/index.html b/api/json_sax/boolean/index.html index 034234721..9f34610b4 100644 --- a/api/json_sax/boolean/index.html +++ b/api/json_sax/boolean/index.html @@ -1,4 +1,4 @@ - boolean - JSON for Modern C++
Skip to content

nlohmann::json_sax::boolean

virtual bool boolean(bool val) = 0;
+ boolean - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::boolean
 
virtual bool boolean(bool val) = 0;
 
 
A boolean value was read.
 
Parameters
 
 
val (in)
 
boolean value
 
 
Return value
 
Whether parsing should proceed.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/end_array/index.html b/api/json_sax/end_array/index.html index e3797332a..0db4f0b6b 100644 --- a/api/json_sax/end_array/index.html +++ b/api/json_sax/end_array/index.html @@ -1,4 +1,4 @@ - end_array - JSON for Modern C++
Skip to content

nlohmann::json_sax::end_array

virtual bool end_array() = 0;
+ end_array - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::end_array
 
virtual bool end_array() = 0;
 
 
The end of an array was read.
 
Return value
 
Whether parsing should proceed.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/end_object/index.html b/api/json_sax/end_object/index.html index b846f0c7d..99170d5be 100644 --- a/api/json_sax/end_object/index.html +++ b/api/json_sax/end_object/index.html @@ -1,4 +1,4 @@ - end_object - JSON for Modern C++
Skip to content

nlohmann::json_sax::end_object

virtual bool end_object() = 0;
+ end_object - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::end_object
 
virtual bool end_object() = 0;
 
 
The end of an object was read.
 
Return value
 
Whether parsing should proceed.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/index.html b/api/json_sax/index.html index 06c824dac..bd1767af5 100644 --- a/api/json_sax/index.html +++ b/api/json_sax/index.html @@ -1,3 +1,3 @@ - Overview - JSON for Modern C++
Skip to content

nlohmann::json_sax

template<typename BasicJsonType>
+ Overview - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax
 
template<typename BasicJsonType>
 struct json_sax;
-
 
This class describes the SAX interface used by sax_parse. 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
 
 
Member types
  
Member functions
 
     
  • binary (virtual) - a binary value was read
    •  
  • boolean (virtual) - a boolean value was read
    •  
  • end_array (virtual) - the end of an array was read
    •  
  • end_object (virtual) - the end of an object was read
    •  
  • key (virtual) - an object key was read
    •  
  • null (virtual) - a null value was read
    •  
  • number_float (virtual) - a floating-point number was read
    •  
  • number_integer (virtual) - an integer number was read
    •  
  • number_unsigned (virtual) - an unsigned integer number was read
    •  
  • parse_error (virtual) - a parse error occurred
    •  
  • start_array (virtual) - the beginning of an array was read
    •  
  • start_object (virtual) - the beginning of an object was read
    •  
  • string (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.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

This class describes the SAX interface used by sax_parse. 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

Member types

Member functions

  • binary (virtual) - a binary value was read
  • boolean (virtual) - a boolean value was read
  • end_array (virtual) - the end of an array was read
  • end_object (virtual) - the end of an object was read
  • key (virtual) - an object key was read
  • null (virtual) - a null value was read
  • number_float (virtual) - a floating-point number was read
  • number_integer (virtual) - an integer number was read
  • number_unsigned (virtual) - an unsigned integer number was read
  • parse_error (virtual) - a parse error occurred
  • start_array (virtual) - the beginning of an array was read
  • start_object (virtual) - the beginning of an object was read
  • string (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.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/key/index.html b/api/json_sax/key/index.html index 08aaac207..d5e8c5d04 100644 --- a/api/json_sax/key/index.html +++ b/api/json_sax/key/index.html @@ -1,4 +1,4 @@ - key - JSON for Modern C++
Skip to content

nlohmann::json_sax::key

virtual bool key(string_t& val) = 0;
+ key - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::key
 
virtual bool key(string_t& val) = 0;
 
 
An object key was read.
 
Parameters
 
 
val (in)
 
object key
 
 
Return value
 
Whether parsing should proceed.
 
Notes
 
It is safe to move the passed object key value.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/null/index.html b/api/json_sax/null/index.html index aaacebaab..ffa91d7d8 100644 --- a/api/json_sax/null/index.html +++ b/api/json_sax/null/index.html @@ -1,4 +1,4 @@ - null - JSON for Modern C++
Skip to content

nlohmann::json_sax::null

virtual bool null() = 0;
+ null - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::null
 
virtual bool null() = 0;
 
 
A null value was read.
 
Return value
 
Whether parsing should proceed.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/number_float/index.html b/api/json_sax/number_float/index.html index 63cf02c16..3798a76d5 100644 --- a/api/json_sax/number_float/index.html +++ b/api/json_sax/number_float/index.html @@ -1,4 +1,4 @@ - number_float - JSON for Modern C++
Skip to content

nlohmann::json_sax::number_float

virtual bool number_float(number_float_t val, const string_t& s) = 0;
+ number_float - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::number_float
 
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
 
s (in)
 
string representation of the original input
 
 
Return value
 
Whether parsing should proceed.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/number_integer/index.html b/api/json_sax/number_integer/index.html index 02e7ee01c..9e2174491 100644 --- a/api/json_sax/number_integer/index.html +++ b/api/json_sax/number_integer/index.html @@ -1,4 +1,4 @@ - number_integer - JSON for Modern C++
Skip to content

nlohmann::json_sax::number_integer

virtual bool number_integer(number_integer_t val) = 0;
+ number_integer - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::number_integer
 
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.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/number_unsigned/index.html b/api/json_sax/number_unsigned/index.html index 8dfd16fa7..76debcfa2 100644 --- a/api/json_sax/number_unsigned/index.html +++ b/api/json_sax/number_unsigned/index.html @@ -1,4 +1,4 @@ - number_unsigned - JSON for Modern C++
Skip to content

nlohmann::json_sax::number_unsigned

virtual bool number_unsigned(number_unsigned_t val) = 0;
+ number_unsigned - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::number_unsigned
 
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.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/parse_error/index.html b/api/json_sax/parse_error/index.html index 7e9f9b032..5903f0cd5 100644 --- a/api/json_sax/parse_error/index.html +++ b/api/json_sax/parse_error/index.html @@ -1,4 +1,4 @@ - parse_error - JSON for Modern C++
Skip to content

nlohmann::json_sax::parse_error

virtual bool parse_error(std::size_t position,
+ parse_error - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::parse_error
 
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 false).
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
@@ -169,4 +169,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/start_array/index.html b/api/json_sax/start_array/index.html index d7b62e680..b7dfcbc86 100644 --- a/api/json_sax/start_array/index.html +++ b/api/json_sax/start_array/index.html @@ -1,4 +1,4 @@ - start_array - JSON for Modern C++
Skip to content

nlohmann::json_sax::start_array

virtual bool start_array(std::size_t elements) = 0;
+ start_array - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::start_array
 
virtual bool start_array(std::size_t elements) = 0;
 
 
The beginning of an array was read.
 
Parameters
 
 
elements (in)
 
number of array elements, or std::numeric_limits<std::size_t>::max() if unknown
 
 
Return value
 
Whether parsing should proceed.
 
Notes
 
Binary formats may report the number of elements.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/start_object/index.html b/api/json_sax/start_object/index.html index 73b5663ef..28be6fe0a 100644 --- a/api/json_sax/start_object/index.html +++ b/api/json_sax/start_object/index.html @@ -1,4 +1,4 @@ - start_object - JSON for Modern C++
Skip to content

nlohmann::json_sax::start_object

virtual bool start_object(std::size_t elements) = 0;
+ start_object - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::start_object
 
virtual bool start_object(std::size_t elements) = 0;
 
 
The beginning of an object was read.
 
Parameters
 
 
elements (in)
 
number of object elements, or std::numeric_limits<std::size_t>::max() if unknown
 
 
Return value
 
Whether parsing should proceed.
 
Notes
 
Binary formats may report the number of elements.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/json_sax/string/index.html b/api/json_sax/string/index.html index cd6817bb1..cf60c90f9 100644 --- a/api/json_sax/string/index.html +++ b/api/json_sax/string/index.html @@ -1,4 +1,4 @@ - string - JSON for Modern C++
Skip to content

nlohmann::json_sax::string

virtual bool string(string_t& val) = 0;
+ string - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::json_sax::string
 
virtual bool string(string_t& val) = 0;
 
 
A string value was read.
 
Parameters
 
 
val (in)
 
string value
 
 
Return value
 
Whether parsing should proceed.
 
Notes
 
It is safe to move the passed string value.
 
Examples
 
 Example 
The example below shows how the SAX interface is used.
 
#include <iostream>
 #include <iomanip>
 #include <sstream>
@@ -167,4 +167,4 @@
             ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
 
 result: false
-
 
 
Version history
 
     
  • Added in version 3.2.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.2.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/index.html b/api/macros/index.html index 64e8a6a39..b18a1e3ab 100644 --- a/api/macros/index.html +++ b/api/macros/index.html @@ -1 +1 @@ - Overview - JSON for Modern C++
Skip to content

Macros

Some aspects of the library can be configured by defining preprocessor macros before including the json.hpp header. See also the macro overview page.

Runtime assertions

Exceptions

Language support

Library version

Library namespace

Type conversions

Comparison behavior

Serialization/deserialization macros

Enums

Classes and structs

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Overview - JSON for Modern C++
Skip to content

Macros

Some aspects of the library can be configured by defining preprocessor macros before including the json.hpp header. See also the macro overview page.

Runtime assertions

Exceptions

Language support

Library version

Library namespace

Type conversions

Comparison behavior

Serialization/deserialization macros

Enums

Classes and structs

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_assert/index.html b/api/macros/json_assert/index.html index 741688e8a..9352551d0 100644 --- a/api/macros/json_assert/index.html +++ b/api/macros/json_assert/index.html @@ -1,4 +1,4 @@ - JSON_ASSERT - JSON for Modern C++
Skip to content

JSON_ASSERT

#define JSON_ASSERT(x) /* value */
+ JSON_ASSERT - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_ASSERT
 
#define JSON_ASSERT(x) /* value */
 
 
This macro controls which code is executed for runtime assertions of the library.
 
Parameters
 
 
x (in)
 
expression of a scalar type
 
 
Default definition
 
The default value is assert(x).
 
#define JSON_ASSERT(x) assert(x)
 
 
Therefore, assertions can be switched off by defining NDEBUG.
 
Notes
 
     
  • The library uses numerous assertions to guarantee invariants and to abort in case of otherwise undefined behavior (e.g., when calling operator[] with a missing object key on a const object). See page runtime assertions for more information.
    •  
  • Defining the macro to code that does not call std::abort may leave the library in an undefined state.
    •  
  • The macro is undefined outside the library.
    •  
 
Examples
 
 Example 1: default behavior 
The following code will trigger an assertion at runtime:
 
#include <nlohmann/json.hpp>
 
@@ -24,4 +24,4 @@
     auto v = j["missing"];
 }
 
 
Output:
 
assertion error in operator[]
-
 
 
See also
  
Version history
 
     
  • Added in version 3.9.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.9.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_brace_init_copy_semantics/index.html b/api/macros/json_brace_init_copy_semantics/index.html index 609af42b5..46ea8b23d 100644 --- a/api/macros/json_brace_init_copy_semantics/index.html +++ b/api/macros/json_brace_init_copy_semantics/index.html @@ -1,4 +1,4 @@ - JSON_BRACE_INIT_COPY_SEMANTICS - JSON for Modern C++
Skip to content

JSON_BRACE_INIT_COPY_SEMANTICS

#define JSON_BRACE_INIT_COPY_SEMANTICS /* value */
+ JSON_BRACE_INIT_COPY_SEMANTICS - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_BRACE_INIT_COPY_SEMANTICS
 
#define JSON_BRACE_INIT_COPY_SEMANTICS /* value */
 
 
When defined to 1, single-element brace initialization of a basic_json value is treated as a copy/move of the element rather than wrapping it in a single-element array.
 
Default definition
 
The default value is 0 (disabled — existing behavior is preserved).
 
#define JSON_BRACE_INIT_COPY_SEMANTICS 0
 
 
Notes
 
 
Background
 
C++ always prefers the initializer_list constructor over the copy/move constructor for brace initialization. This means that code like
 
json obj = {{"key", "value"}};
 json j{obj};
@@ -26,4 +26,4 @@
     json j{obj};
     // j is {"key":"value"}  -- copy of obj
 }
-
  
See also
  
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_diagnostic_positions/index.html b/api/macros/json_diagnostic_positions/index.html index e0d00d46b..5d609ccf4 100644 --- a/api/macros/json_diagnostic_positions/index.html +++ b/api/macros/json_diagnostic_positions/index.html @@ -1,4 +1,4 @@ - JSON_DIAGNOSTIC_POSITIONS - JSON for Modern C++
Skip to content

JSON_DIAGNOSTIC_POSITIONS

#define JSON_DIAGNOSTIC_POSITIONS /* value */
+ JSON_DIAGNOSTIC_POSITIONS - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_DIAGNOSTIC_POSITIONS
 
#define JSON_DIAGNOSTIC_POSITIONS /* value */
 
 
This macro enables position diagnostics for generated JSON objects.
 
When enabled, two new member functions start_pos() and end_pos() are added to basic_json values. If the value was created by calling theparse function, then these functions allow querying the byte positions of the value in the input it was parsed from. In case the value was constructed by other means, std::string::npos is returned.
 
start_pos() returns the position of the first character of a given value in the original JSON string, while end_pos() returns the position of the character following the last character. For objects and arrays, the first and last characters correspond to the opening or closing braces/brackets, respectively. For primitive values, the first and last character represents the opening and closing quotes (strings) or the first and last character of the field's numerical or predefined value (true, false, null), respectively.
 
  
 JSON type return value start_pos() return value end_pos() 
   
 object position of the opening { position after the closing } 
 
 array position of the opening [ position after the closing ] 
 
 string position of the opening " position after the closing " 
 
 number position of the first character position after the last character 
 
 boolean position of t for true and f for false position after e 
 
 null position of n position after l 
  
 
Given the above, end_pos()-start_pos() for a JSON value provides the length of the parsed JSON string for that value, including the opening or closing braces, brackets, or quotes.
 
Note that enabling this macro increases the size of every JSON value by two std::size_t fields and adds slight runtime overhead to parsing, copying JSON value objects, and the generation of error messages for exceptions. It also causes these values to be reported in those error messages.
 
Default definition
 
The default value is 0 (position diagnostics are switched off).
 
#define JSON_DIAGNOSTIC_POSITIONS 0
 
 
When the macro is not defined, the library will define it to its default value.
 
Notes
 
 
CMake option
 
Diagnostic positions can also be controlled with the CMake option JSON_Diagnostic_Positions (OFF by default) which defines JSON_DIAGNOSTIC_POSITIONS accordingly.
 
 
 
Availability
 
Diagnostic positions are only available if the value was created by the parse function. The sax_parse function or all other means to create a JSON value do not set the diagnostic positions and start_pos() and end_pos() will only return std::string::npos for these values.
 
 
 
Invalidation
 
The returned positions are only valid as long as the JSON value is not changed. The positions are not updated when the JSON value is changed.
 
 
Examples
 
 Example: retrieving positions 
#include <iostream>
 
@@ -165,4 +165,4 @@ Parsed string:
 }
 
 
Output:
 
[json.exception.type_error.302] (/address/housenumber) (bytes 92-95) type must be number, but is string
 
 
The output shows the exception with diagnostic path info and start/end positions.
-
 
 
See also
  
Version history
 
     
  • Added in version 3.12.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.12.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_diagnostics/index.html b/api/macros/json_diagnostics/index.html index 7693728bf..fcf533d52 100644 --- a/api/macros/json_diagnostics/index.html +++ b/api/macros/json_diagnostics/index.html @@ -1,4 +1,4 @@ - JSON_DIAGNOSTICS - JSON for Modern C++
Skip to content

JSON_DIAGNOSTICS

#define JSON_DIAGNOSTICS /* value */
+ JSON_DIAGNOSTICS - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_DIAGNOSTICS
 
#define JSON_DIAGNOSTICS /* value */
 
 
This macro enables extended diagnostics for exception messages. Possible values are 1 to enable or 0 to disable (default).
 
When enabled, exception messages contain a JSON Pointer to the JSON value that triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.
 
Default definition
 
The default value is 0 (extended diagnostics are switched off).
 
#define JSON_DIAGNOSTICS 0
 
 
When the macro is not defined, the library will define it to its default value.
 
Notes
 
 
ABI compatibility
 
As of version 3.11.0, this macro is no longer required to be defined consistently throughout a codebase to avoid One Definition Rule (ODR) violations, as the value of this macro is encoded in the namespace, resulting in distinct symbol names. 
 
This allows different parts of a codebase to use different versions or configurations of this library without causing improper behavior.
 
Where possible, it is still recommended that all code define this the same way for maximum interoperability.
 
 
 
CMake option
 
Diagnostic messages can also be controlled with the CMake option JSON_Diagnostics (OFF by default) which defines JSON_DIAGNOSTICS accordingly. Note this only applies when building the library from source — see the pre-installed-package caveat on that page.
 
 
Examples
 
 Example 1: default behavior 
#include <iostream>
 #include <nlohmann/json.hpp>
@@ -75,4 +75,4 @@
     }
 }
 
 
Output:
 
[json.exception.type_error.302] (bytes 92-95) type must be number, but is string
-
 The output shows the exception with start/end positions only.
 
 
See also
  
Version history
 
     
  • Added in version 3.10.0.
    •  
  • As of version 3.11.0, the definition is allowed to vary between translation units.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
The output shows the exception with start/end positions only.

See also

Version history

  • Added in version 3.10.0.
  • As of version 3.11.0, the definition is allowed to vary between translation units.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_disable_enum_serialization/index.html b/api/macros/json_disable_enum_serialization/index.html index 68e5e516e..4b7eaf7a0 100644 --- a/api/macros/json_disable_enum_serialization/index.html +++ b/api/macros/json_disable_enum_serialization/index.html @@ -1,4 +1,4 @@ - JSON_DISABLE_ENUM_SERIALIZATION - JSON for Modern C++
Skip to content

JSON_DISABLE_ENUM_SERIALIZATION

#define JSON_DISABLE_ENUM_SERIALIZATION /* value */
+ JSON_DISABLE_ENUM_SERIALIZATION - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_DISABLE_ENUM_SERIALIZATION
 
#define JSON_DISABLE_ENUM_SERIALIZATION /* value */
 
 
When defined to 1, default serialization and deserialization functions for enums are excluded and have to be provided by the user, for example, using NLOHMANN_JSON_SERIALIZE_ENUM (see arbitrary type conversions for more details).
 
Parsing or serializing an enum will result in a compiler error.
 
This works for both unscoped and scoped enums.
 
Default definition
 
The default value is 0.
 
#define JSON_DISABLE_ENUM_SERIALIZATION 0
 
 
Notes
 
 
CMake option
 
Enum serialization can also be controlled with the CMake option JSON_DisableEnumSerialization (OFF by default) which defines JSON_DISABLE_ENUM_SERIALIZATION accordingly.
 
 
Examples
 
 Example 1: Disabled behavior 
The code below forces the library not to create default serialization/deserialization functions from_json and to_json, meaning the code below does not compile.
 
#define JSON_DISABLE_ENUM_SERIALIZATION 1
 #include <nlohmann/json.hpp>
@@ -88,4 +88,4 @@
     // uses user-defined from_json function
     Choice ch = j.get<Choice>();
 }
-
 
 
See also
  
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_has_cpp_11/index.html b/api/macros/json_has_cpp_11/index.html index 888bd8208..7488f6cbd 100644 --- a/api/macros/json_has_cpp_11/index.html +++ b/api/macros/json_has_cpp_11/index.html @@ -1,4 +1,4 @@ - JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20 - JSON for Modern C++
Skip to content

JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26

#define JSON_HAS_CPP_11
+ JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20 - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26
 
#define JSON_HAS_CPP_11
 #define JSON_HAS_CPP_14
 #define JSON_HAS_CPP_17
 #define JSON_HAS_CPP_20
@@ -8,4 +8,4 @@
 #include <nlohmann/json.hpp>
 
 ...
-
  
Version history
 
     
  • Added in version 3.10.5.
    •  
  • Added JSON_HAS_CPP_23 in version 3.12.0.
    •  
  • Added JSON_HAS_CPP_26 in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.10.5.
  • Added JSON_HAS_CPP_23 in version 3.12.0.
  • Added JSON_HAS_CPP_26 in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_has_filesystem/index.html b/api/macros/json_has_filesystem/index.html index 758729810..3ea7597d3 100644 --- a/api/macros/json_has_filesystem/index.html +++ b/api/macros/json_has_filesystem/index.html @@ -1,7 +1,7 @@ - JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM - JSON for Modern C++
Skip to content

JSON_HAS_FILESYSTEM / JSON_HAS_EXPERIMENTAL_FILESYSTEM

#define JSON_HAS_FILESYSTEM /* value */
+ JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_HAS_FILESYSTEM / JSON_HAS_EXPERIMENTAL_FILESYSTEM
 
#define JSON_HAS_FILESYSTEM /* value */
 #define JSON_HAS_EXPERIMENTAL_FILESYSTEM /* value */
 
 
When compiling with C++17, the library provides conversions from and to std::filesystem::path. As compiler support for filesystem is limited, the library tries to detect whether <filesystem>/std::filesystem (JSON_HAS_FILESYSTEM) or <experimental/filesystem>/std::experimental::filesystem (JSON_HAS_EXPERIMENTAL_FILESYSTEM) should be used. To override the built-in check, define JSON_HAS_FILESYSTEM or JSON_HAS_EXPERIMENTAL_FILESYSTEM to 1.
 
Default definition
 
The default value is detected based on the preprocessor macros __cpp_lib_filesystem, __cpp_lib_experimental_filesystem, __has_include(<filesystem>), or __has_include(<experimental/filesystem>).
 
 
Known compiler/stdlib exclusions
 
Even when the feature-test macro indicates filesystem support is available, the library disables it on the following broken toolchains:
 
     
  • MinGW + GCC 8 — disabled entirely (broken std::filesystem implementation; MinGW-w64 bug 737)
    •  
  • GCC (non-Clang) < 8 — disabled (no filesystem support)
    •  
  • Clang < 7 — disabled (no filesystem support)
    •  
  • MSVC < 19.14 — disabled (no filesystem support)
    •  
  • iOS < 13 — disabled (no filesystem support)
    •  
  • macOS < Catalina (10.15) — disabled (no filesystem support)
    •  
 
If JSON_HAS_FILESYSTEM or JSON_HAS_EXPERIMENTAL_FILESYSTEM is 0 despite __cpp_lib_filesystem being defined, one of the exclusions above likely applies to your toolchain.
 
 
Notes
 
     
  • Note that older compilers or older versions of libstdc++ also require the library stdc++fs to be linked to for filesystem support.
    •  
  • Both macros are undefined outside the library.
    •  
 
Examples
 
 Example 
The code below forces the library to use the header <experimental/filesystem>.
 
#define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
     
  • Added in version 3.10.5.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.10.5.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_has_ranges/index.html b/api/macros/json_has_ranges/index.html index c1b215642..3ee53def0 100644 --- a/api/macros/json_has_ranges/index.html +++ b/api/macros/json_has_ranges/index.html @@ -1,6 +1,6 @@ - JSON_HAS_RANGES - JSON for Modern C++
Skip to content

JSON_HAS_RANGES

#define JSON_HAS_RANGES /* value */
+ JSON_HAS_RANGES - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_HAS_RANGES
 
#define JSON_HAS_RANGES /* value */
 
 
This macro indicates whether the standard library has any support for ranges. Implies support for concepts. Possible values are 1 when supported or 0 when unsupported.
 
Default definition
 
The default value is detected based on the preprocessor macro __cpp_lib_ranges.
 
When the macro is not defined, the library will define it to its default value.
 
 
Known compiler/stdlib exclusions
 
Even when the feature-test macro __cpp_lib_ranges indicates ranges support is available, the library disables it on the following incomplete or broken toolchains:
 
     
  • GCC 11.1.0 — disabled (the shipped <ranges> header has a syntax error; issue #4440)
    •  
  • libstdc++ < 11 — disabled (incomplete C++20 ranges support; issue #4440)
    •  
  • Clang < 16 with libstdc++ — disabled (incomplete ranges support; issue #4440)
    •  
  • libc++ < 160000 — disabled (incomplete C++20 ranges support; issue #4440)
    •  
  • nvcc (CUDA) 12.0.x and 12.1.x — disabled (the enable_borrowed_range variable-template syntax triggers a parse error under these two toolkit versions; fixed in CUDA 12.2; issue #3907)
    •  
 
If JSON_HAS_RANGES is 0 despite __cpp_lib_ranges being defined, one of the exclusions above likely applies to your toolchain.
 
 
Examples
 
 Example 
The code below forces the library to enable support for ranges:
 
#define JSON_HAS_RANGES 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_has_static_rtti/index.html b/api/macros/json_has_static_rtti/index.html index 9d476adef..426e6097c 100644 --- a/api/macros/json_has_static_rtti/index.html +++ b/api/macros/json_has_static_rtti/index.html @@ -1,6 +1,6 @@ - JSON_HAS_STATIC_RTTI - JSON for Modern C++
Skip to content

JSON_HAS_STATIC_RTTI

#define JSON_HAS_STATIC_RTTI /* value */
+ JSON_HAS_STATIC_RTTI - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_HAS_STATIC_RTTI
 
#define JSON_HAS_STATIC_RTTI /* value */
 
 
This macro indicates whether the standard library has any support for RTTI (run time type information). Possible values are 1 when supported or 0 when unsupported.
 
Default definition
 
The default value is detected based on the preprocessor macro _HAS_STATIC_RTTI.
 
When the macro is not defined, the library will define it to its default value.
 
Examples
 
 Example 
The code below forces the library to enable support for libraries with RTTI dependence:
 
#define JSON_HAS_STATIC_RTTI 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
     
  • Added in version 3.11.3.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.11.3.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_has_std_format/index.html b/api/macros/json_has_std_format/index.html index 815c162b8..3d8a38b20 100644 --- a/api/macros/json_has_std_format/index.html +++ b/api/macros/json_has_std_format/index.html @@ -1,6 +1,6 @@ - JSON_HAS_STD_FORMAT - JSON for Modern C++
Skip to content

JSON_HAS_STD_FORMAT

#define JSON_HAS_STD_FORMAT /* value */
+ JSON_HAS_STD_FORMAT - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_HAS_STD_FORMAT
 
#define JSON_HAS_STD_FORMAT /* value */
 
 
This macro indicates whether the standard library has support for std::format/std::formatter (that is, the <format> header). Possible values are 1 when supported or 0 when unsupported.
 
Default definition
 
The default value is detected based on the preprocessor macros JSON_HAS_CPP_20 and __cpp_lib_format.
 
When the macro is not defined, the library will define it to its default value.
 
Notes
 
 
Enabled functionality
 
When this macro evaluates to 1, the library provides a std::formatter<basic_json> specialization so JSON values can be used directly with std::format.
 
 
Examples
 
 Example 
The code below forces the library to disable support for std::format, even if the standard library would otherwise support it:
 
#define JSON_HAS_STD_FORMAT 0
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
     
  • Added in version 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_has_three_way_comparison/index.html b/api/macros/json_has_three_way_comparison/index.html index 5eba43208..2182283c6 100644 --- a/api/macros/json_has_three_way_comparison/index.html +++ b/api/macros/json_has_three_way_comparison/index.html @@ -1,6 +1,6 @@ - JSON_HAS_THREE_WAY_COMPARISON - JSON for Modern C++
Skip to content

JSON_HAS_THREE_WAY_COMPARISON

#define JSON_HAS_THREE_WAY_COMPARISON /* value */
+ JSON_HAS_THREE_WAY_COMPARISON - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_HAS_THREE_WAY_COMPARISON
 
#define JSON_HAS_THREE_WAY_COMPARISON /* value */
 
 
This macro indicates whether the compiler and standard library support 3-way comparison. Possible values are 1 when supported or 0 when unsupported.
 
Default definition
 
The default value is detected based on the preprocessor macros __cpp_impl_three_way_comparison and __cpp_lib_three_way_comparison.
 
When the macro is not defined, the library will define it to its default value.
 
Examples
 
 Example 
The code below forces the library to use 3-way comparison:
 
#define JSON_HAS_THREE_WAY_COMPARISON 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_no_io/index.html b/api/macros/json_no_io/index.html index 6828e92fe..4bce9d5a8 100644 --- a/api/macros/json_no_io/index.html +++ b/api/macros/json_no_io/index.html @@ -1,7 +1,7 @@ - JSON_NO_IO - JSON for Modern C++
Skip to content

JSON_NO_IO

#define JSON_NO_IO
+ JSON_NO_IO - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_NO_IO
 
#define JSON_NO_IO
 
 
When defined, headers <cstdio>, <ios>, <iosfwd>, <istream>, and <ostream> are not included and parse functions relying on these headers are excluded. This is relevant for environments where these I/O functions are disallowed for security reasons (e.g., Intel Software Guard Extensions (SGX)).
 
Default definition
 
By default, JSON_NO_IO is not defined.
 
#undef JSON_NO_IO
 
 
Examples
 
 Example 
The code below forces the library not to use the headers <cstdio>, <ios>, <iosfwd>, <istream>, and <ostream>.
 
#define JSON_NO_IO 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
     
  • Added in version 3.10.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  • Added in version 3.10.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_noexception/index.html b/api/macros/json_noexception/index.html index ebbcbb819..7ef3ace84 100644 --- a/api/macros/json_noexception/index.html +++ b/api/macros/json_noexception/index.html @@ -1,7 +1,7 @@ - JSON_NOEXCEPTION - JSON for Modern C++
Skip to content

JSON_NOEXCEPTION

#define JSON_NOEXCEPTION
+ JSON_NOEXCEPTION - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_NOEXCEPTION
 
#define JSON_NOEXCEPTION
 
 
Exceptions can be switched off by defining the symbol JSON_NOEXCEPTION. When defining JSON_NOEXCEPTION, try is replaced by if (true), catch is replaced by if (false), and throw is replaced by std::abort().
 
The same effect is achieved by setting the compiler flag -fno-exceptions.
 
Default definition
 
By default, the macro is not defined.
 
#undef JSON_NOEXCEPTION
 
 
Notes
 
The explanatory what() string of exceptions is not available for MSVC if exceptions are disabled, see #2824.
 
Examples
 
 Example 
The code below switches off exceptions in the library.
 
#define JSON_NOEXCEPTION 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
See also
  
Version history
 
Added in version 2.1.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Added in version 2.1.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_skip_library_version_check/index.html b/api/macros/json_skip_library_version_check/index.html index 74da32245..b747a900c 100644 --- a/api/macros/json_skip_library_version_check/index.html +++ b/api/macros/json_skip_library_version_check/index.html @@ -1,8 +1,8 @@ - JSON_SKIP_LIBRARY_VERSION_CHECK - JSON for Modern C++
Skip to content

JSON_SKIP_LIBRARY_VERSION_CHECK

#define JSON_SKIP_LIBRARY_VERSION_CHECK
+ JSON_SKIP_LIBRARY_VERSION_CHECK - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_SKIP_LIBRARY_VERSION_CHECK
 
#define JSON_SKIP_LIBRARY_VERSION_CHECK
 
 
When defined, the library will not create a compiler warning when a different version of the library was already included.
 
Default definition
 
By default, the macro is not defined.
 
#undef JSON_SKIP_LIBRARY_VERSION_CHECK
 
 
Notes
 
 
ABI compatibility
 
Mixing different library versions in the same code can be a problem as the different versions may not be ABI compatible.
 
 
Examples
 
 Example 
The code below switches off the warning about including a different version of the library.
 
#define JSON_SKIP_LIBRARY_VERSION_CHECK 1
 #include <nlohmann/json.hpp>
 
 ...
 
 
 
 
Example
 
The following warning will be shown in case a different version of the library was already included:
 
Already included a different version of the library!
-
 
 
Version history
 
Added in version 3.11.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Added in version 3.11.0.

\ No newline at end of file diff --git a/api/macros/json_skip_unsupported_compiler_check/index.html b/api/macros/json_skip_unsupported_compiler_check/index.html index 0e75540f7..423b04eed 100644 --- a/api/macros/json_skip_unsupported_compiler_check/index.html +++ b/api/macros/json_skip_unsupported_compiler_check/index.html @@ -1,7 +1,7 @@ - JSON_SKIP_UNSUPPORTED_COMPILER_CHECK - JSON for Modern C++
Skip to content

JSON_SKIP_UNSUPPORTED_COMPILER_CHECK

#define JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
+ JSON_SKIP_UNSUPPORTED_COMPILER_CHECK - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
 
#define JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
 
 
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows using the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
 
Default definition
 
By default, the macro is not defined.
 
#undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
 
 
Examples
 
 Example 
The code below switches off the check whether the compiler is supported.
 
#define JSON_SKIP_UNSUPPORTED_COMPILER_CHECK 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
Version history
 
Added in version 3.2.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

Added in version 3.2.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_throw_user/index.html b/api/macros/json_throw_user/index.html index a8e4649e2..5a5beb584 100644 --- a/api/macros/json_throw_user/index.html +++ b/api/macros/json_throw_user/index.html @@ -1,4 +1,4 @@ - JSON_CATCH_USER, JSON_THROW_USER, JSON_TRY_USER - JSON for Modern C++
Skip to content

JSON_CATCH_USER, JSON_THROW_USER, JSON_TRY_USER

// (1)
+ JSON_CATCH_USER, JSON_THROW_USER, JSON_TRY_USER - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_CATCH_USER, JSON_THROW_USER, JSON_TRY_USER
 
// (1)
 #define JSON_CATCH_USER(exception) /* value */
 // (2)
 #define JSON_THROW_USER(exception) /* value */
@@ -21,4 +21,4 @@
      std::abort();}
 
 #include <nlohmann/json.hpp>
-
  
See also
  
Version history
 
     
  • Added in version 3.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_use_global_udls/index.html b/api/macros/json_use_global_udls/index.html index 4d46f0ffc..a200d45d3 100644 --- a/api/macros/json_use_global_udls/index.html +++ b/api/macros/json_use_global_udls/index.html @@ -1,4 +1,4 @@ - JSON_USE_GLOBAL_UDLS - JSON for Modern C++
Skip to content

JSON_USE_GLOBAL_UDLS

#define JSON_USE_GLOBAL_UDLS /* value */
+ JSON_USE_GLOBAL_UDLS - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_USE_GLOBAL_UDLS
 
#define JSON_USE_GLOBAL_UDLS /* value */
 
 
When defined to 1, the user-defined string literals (UDLs) are placed into the global namespace instead of nlohmann::literals::json_literals.
 
Default definition
 
The default value is 1.
 
#define JSON_USE_GLOBAL_UDLS 1
 
 
When the macro is not defined, the library will define it to its default value.
 
Notes
 
 
Future behavior change
 
The user-defined string literals will be removed from the global namespace in the next major release of the library.
 
To prepare existing code, define JSON_USE_GLOBAL_UDLS to 0 and bring the string literals into scope where needed. Refer to any of the string literals for details.
 
 
 
CMake option
 
The placement of user-defined string literals can also be controlled with the CMake option JSON_GlobalUDLs (ON by default) which defines JSON_USE_GLOBAL_UDLS accordingly.
 
 
Examples
 
 Example 1: Default behavior 
The code below shows the default behavior using the _json UDL.
 
#include <nlohmann/json.hpp>
 
@@ -29,4 +29,4 @@
     std::cout << j << std::endl;
 }
 
 
Output:
 
42
-
 
 
See also
  
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_use_implicit_conversions/index.html b/api/macros/json_use_implicit_conversions/index.html index f7b5e8ddd..9d914eeb3 100644 --- a/api/macros/json_use_implicit_conversions/index.html +++ b/api/macros/json_use_implicit_conversions/index.html @@ -1,7 +1,7 @@ - JSON_USE_IMPLICIT_CONVERSIONS - JSON for Modern C++
Skip to content

JSON_USE_IMPLICIT_CONVERSIONS

#define JSON_USE_IMPLICIT_CONVERSIONS /* value */
+ JSON_USE_IMPLICIT_CONVERSIONS - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_USE_IMPLICIT_CONVERSIONS
 
#define JSON_USE_IMPLICIT_CONVERSIONS /* value */
 
 
When defined to 0, implicit conversions are switched off. By default, implicit conversions are switched on. The value directly affects operator ValueType.
 
Default definition
 
By default, implicit conversions are enabled.
 
#define JSON_USE_IMPLICIT_CONVERSIONS 1
 
 
Notes
 
 
Future behavior change
 
Implicit conversions will be switched off by default in the next major release of the library.
 
You can prepare existing code by already defining JSON_USE_IMPLICIT_CONVERSIONS to 0 and replace any implicit conversions with calls to get.
 
 
 
CMake option
 
Implicit conversions can also be controlled with the CMake option JSON_ImplicitConversions (ON by default) which defines JSON_USE_IMPLICIT_CONVERSIONS accordingly.
 
 
Examples
 
 Example 
This is an example for an implicit conversion:
 
json j = "Hello, world!";
 std::string s = j;
 
 
When JSON_USE_IMPLICIT_CONVERSIONS is defined to 0, the code above does no longer compile. Instead, it must be written like this:
 
json j = "Hello, world!";
 auto s = j.get<std::string>();
-
 
 
See also
  
Version history
 
     
  • Added in version 3.9.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.9.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/json_use_legacy_discarded_value_comparison/index.html b/api/macros/json_use_legacy_discarded_value_comparison/index.html index a33255aad..65fbf7b91 100644 --- a/api/macros/json_use_legacy_discarded_value_comparison/index.html +++ b/api/macros/json_use_legacy_discarded_value_comparison/index.html @@ -1,7 +1,7 @@ - JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON - JSON for Modern C++
Skip to content

JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON

#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
+ JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON
 
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
 
 
This macro enables the (incorrect) legacy comparison behavior of discarded JSON values. Possible values are 1 to enable or 0 to disable (default).
 
When enabled, comparisons involving at least one discarded JSON value yield results as follows:
 
  
 Operator Result 
   
 == false 
 
 != true 
 
 < false 
 
 <= true 
 
 >= true 
 
 > false 
  
 
Otherwise, comparisons involving at least one discarded JSON value always yield false.
 
Default definition
 
The default value is 0.
 
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 0
 
 
When the macro is not defined, the library will define it to its default value.
 
Notes
 
 
Inconsistent behavior in C++20 and beyond
 
When targeting C++20 or above, enabling the legacy comparison behavior is strongly discouraged.
 
     
  • The 3-way comparison operator (<=>) will always give the correct result (std::partial_ordering::unordered) regardless of the value of JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON.
    •  
  • Overloads for the equality and relational operators emulate the legacy behavior.
    •  
 
Code outside your control may use either 3-way comparison or the equality and relational operators, resulting in inconsistent and unpredictable behavior.
 
See operator<=> for more information on 3-way comparison.
 
 
 
Deprecation
 
The legacy comparison behavior is deprecated and may be removed in a future major version release.
 
New code should not depend on it and existing code should try to remove or rewrite expressions relying on it.
 
 
 
CMake option
 
Legacy comparison can also be controlled with the CMake option JSON_LegacyDiscardedValueComparison (OFF by default) which defines JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON accordingly.
 
 
Examples
 
 Example 
The code below switches on the legacy discarded value comparison behavior in the library.
 
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 1
 #include <nlohmann/json.hpp>
 
 ...
-
 
 
See also
  
Version history
 
     
  • Added in version 3.11.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_define_derived_type/index.html b/api/macros/nlohmann_define_derived_type/index.html index 81233c920..d97bf278b 100644 --- a/api/macros/nlohmann_define_derived_type/index.html +++ b/api/macros/nlohmann_define_derived_type/index.html @@ -1,4 +1,4 @@ - NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE - JSON for Modern C++
Skip to content

NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE

// (1)
+ NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE
 
// (1)
 #define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(type, base_type, member...)
 // (2)
 #define NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)
@@ -86,4 +86,4 @@
     "Ba": 23,
     "Bb": 42
 }
-
 
Notes:
 
     
  • A and B are default-constructible. This is a requirement for using the macro.
    •  
  • A has private members and is not a derived class. Hence, macro NLOHMANN_DEFINE_TYPE_INTRUSIVE is used.
    •  
  • As B is a derived class, NLOHMANN_DEFINE_TYPE_INTRUSIVE is not applicable, but NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE must be used.
    •  
  • The macro NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE is used inside the class use as NLOHMANN_DEFINE_TYPE_INTRUSIVE.
    •  
  
See also
  
Version history
 
     
  1. Added in version 3.12.0.
    2.  
  2. Added in version 3.12.0.
    3.  
  3. Added in version 3.12.0.
    4.  
  4. Added in version 3.12.0.
    5.  
  5. Added in version 3.12.0.
    6.  
  6. Added in version 3.12.0.
    7.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Notes:

  • A and B are default-constructible. This is a requirement for using the macro.
  • A has private members and is not a derived class. Hence, macro NLOHMANN_DEFINE_TYPE_INTRUSIVE is used.
  • As B is a derived class, NLOHMANN_DEFINE_TYPE_INTRUSIVE is not applicable, but NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE must be used.
  • The macro NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE is used inside the class use as NLOHMANN_DEFINE_TYPE_INTRUSIVE.

See also

Version history

  1. Added in version 3.12.0.
  2. Added in version 3.12.0.
  3. Added in version 3.12.0.
  4. Added in version 3.12.0.
  5. Added in version 3.12.0.
  6. Added in version 3.12.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_define_type_intrusive/index.html b/api/macros/nlohmann_define_type_intrusive/index.html index cdc7cfe06..9067a7606 100644 --- a/api/macros/nlohmann_define_type_intrusive/index.html +++ b/api/macros/nlohmann_define_type_intrusive/index.html @@ -1,4 +1,4 @@ - NLOHMANN_DEFINE_TYPE_INTRUSIVE, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE - JSON for Modern C++
Skip to content

NLOHMANN_DEFINE_TYPE_INTRUSIVE, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE

#define NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)              // (1)
+ NLOHMANN_DEFINE_TYPE_INTRUSIVE, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_DEFINE_TYPE_INTRUSIVE, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE
 
#define NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)              // (1)
 #define NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...) // (2)
 #define NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE(type, member...) // (3)
 
 
These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as serialization and want to use the member variable names as object keys in that object. The macro is to be defined inside the class/struct to create code for. Unlike NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, it can access private members. The first parameter is the name of the class/struct, and all remaining parameters name the members.
 
     
  1. Will use at during deserialization and will throw out_of_range.403 if a key is missing in the JSON object.
    2.  
  2. Will use value during deserialization and fall back to the default value for the respective type of the member variable if a key in the JSON object is missing. The generated from_json() function default constructs an object and uses its values as the defaults when calling the value function.
    3.  
  3. Only defines the serialization. Useful in cases when the type does not have a default constructor and only serialization is required.
    4.  
 
Summary:
 
  
 Need access to private members Need only serialization Allow missing values when de-serializing macro 
   
 
 
 
 NLOHMANN_DEFINE_TYPE_INTRUSIVE 
 
 
 
 
 NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT 
 
 
 
 
 NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE 
  
 
Parameters
 
 
type (in)
 
name of the type (class, struct) to serialize/deserialize
 
member (in)
 
name of the member variable to serialize/deserialize; up to 63 members can be given as a comma-separated list
 
 
Default definition
 
The macros add two friend functions to the class which take care of the serialization and deserialization:
 
template<typename BasicJsonType>
@@ -291,4 +291,4 @@
     json j = p;
     std::cout << "serialization: " << j << std::endl;
 }
-
  
See also
  
Version history
 
     
  1. Added in version 3.9.0.
    2.  
  2. Added in version 3.11.0.
    3.  
  3. Added in version 3.11.3.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 3.9.0.
  2. Added in version 3.11.0.
  3. Added in version 3.11.3.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_define_type_non_intrusive/index.html b/api/macros/nlohmann_define_type_non_intrusive/index.html index b156f9aae..6bf72e5d5 100644 --- a/api/macros/nlohmann_define_type_non_intrusive/index.html +++ b/api/macros/nlohmann_define_type_non_intrusive/index.html @@ -1,4 +1,4 @@ - NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE - JSON for Modern C++
Skip to content

NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE

#define NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)              // (1)
+ NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE
 
#define NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)              // (1)
 #define NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...) // (2)
 #define NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE(type, member...) // (3)
 
 
These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as serialization and want to use the member variable names as object keys in that object. The macro is to be defined outside the class/struct to create code for, but inside its namespace. Unlike NLOHMANN_DEFINE_TYPE_INTRUSIVE, it cannot access private members. The first parameter is the name of the class/struct, and all remaining parameters name the members.
 
     
  1. Will use at during deserialization and will throw out_of_range.403 if a key is missing in the JSON object.
    2.  
  2. Will use value during deserialization and fall back to the default value for the respective type of the member variable if a key in the JSON object is missing. The generated from_json() function default constructs an object and uses its values as the defaults when calling the value function.
    3.  
  3. Only defines the serialization. Useful in cases when the type does not have a default constructor and only serialization is required.
    4.  
 
Summary:
 
  
 Need access to private members Need only serialization Allow missing values when de-serializing macro 
   
 
 
 
 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE 
 
 
 
 
 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT 
 
 
 
 
 NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE 
  
 
Parameters
 
 
type (in)
 
name of the type (class, struct) to serialize/deserialize
 
member (in)
 
name of the (public) member variable to serialize/deserialize; up to 63 members can be given as a comma-separated list
 
 
Default definition
 
The macros add two functions to the namespace which take care of the serialization and deserialization:
 
template<typename BasicJsonType>
@@ -259,4 +259,4 @@
     json j = p;
     std::cout << "serialization: " << j << std::endl;
 }
-
  
See also
  
Version history
 
     
  1. Added in version 3.9.0.
    2.  
  2. Added in version 3.11.0.
    3.  
  3. Added in version 3.11.3.
    4.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  1. Added in version 3.9.0.
  2. Added in version 3.11.0.
  3. Added in version 3.11.3.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_define_type_with_names/index.html b/api/macros/nlohmann_define_type_with_names/index.html index 2fed5269a..48351d343 100644 --- a/api/macros/nlohmann_define_type_with_names/index.html +++ b/api/macros/nlohmann_define_type_with_names/index.html @@ -1,4 +1,4 @@ - NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES - JSON for Modern C++
Skip to content

NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES

#define NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES(type, "json_member_name", member...)
+ NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES
 
#define NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES(type, "json_member_name", member...)
 #define NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES(type, "json_member_name", member...)
 #define NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES(type, "json_member_name", member...)
 #define NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES(type, "json_member_name", member...)
@@ -108,4 +108,4 @@
         std::cout << "deserialization failed: " << e.what() << std::endl;
     }
 }
-
  
Version history
 
     
  1. Added in version 3.13.0.
    2.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Version history

  1. Added in version 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_json_namespace/index.html b/api/macros/nlohmann_json_namespace/index.html index d490bd9f6..0495064d4 100644 --- a/api/macros/nlohmann_json_namespace/index.html +++ b/api/macros/nlohmann_json_namespace/index.html @@ -1,4 +1,4 @@ - NLOHMANN_JSON_NAMESPACE - JSON for Modern C++
Skip to content

NLOHMANN_JSON_NAMESPACE

#define NLOHMANN_JSON_NAMESPACE /* value */
+ NLOHMANN_JSON_NAMESPACE - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_JSON_NAMESPACE
 
#define NLOHMANN_JSON_NAMESPACE /* value */
 
 
This macro evaluates to the full name of the nlohmann namespace.
 
Default definition
 
The default value consists of the root namespace (nlohmann) and an inline ABI namespace. See nlohmann Namespace for details.
 
When the macro is not defined, the library will define it to its default value. Overriding this value has no effect on the library.
 
Examples
 
 Example 
The example shows how to use NLOHMANN_JSON_NAMESPACE instead of just nlohmann, as well as how to output the value of NLOHMANN_JSON_NAMESPACE.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -14,4 +14,4 @@
     std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl;
 }
 
 
Output:
 
nlohmann::json_abi_v3_12_0
-
 
 
See also
  
Version history
 
     
  • Added in version 3.11.0. Changed inline namespace name in version 3.11.2.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.0. Changed inline namespace name in version 3.11.2.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_json_namespace_begin/index.html b/api/macros/nlohmann_json_namespace_begin/index.html index 39b9ac51d..5c5298f79 100644 --- a/api/macros/nlohmann_json_namespace_begin/index.html +++ b/api/macros/nlohmann_json_namespace_begin/index.html @@ -1,4 +1,4 @@ - NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END - JSON for Modern C++
Skip to content

NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END

#define NLOHMANN_JSON_NAMESPACE_BEGIN /* value */  // (1)
+ NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END
 
#define NLOHMANN_JSON_NAMESPACE_BEGIN /* value */  // (1)
 #define NLOHMANN_JSON_NAMESPACE_END   /* value */  // (2)
 
 
These macros can be used to open and close the nlohmann namespace. See nlohmann Namespace for details.
 
     
  1. Opens the namespace.
    2.  
  2. Closes the namespace.
    3.  
 
Default definition
 
The default definitions open and close the nlohmann namespace. The precise definition of [NLOHMANN_JSON_NAMESPACE_BEGIN] varies as described here.
 
     
  1.  
    Default definition of NLOHMANN_JSON_NAMESPACE_BEGIN:
     
    namespace nlohmann
 {
@@ -40,4 +40,4 @@
     std::cout << j << std::endl;
 }
 
     
    Output:
     
    [1,null]
-
      
    See also
      
    Version history
     
       
    • Added in version 3.11.0. Changed inline namespace name in version 3.11.2.
      •  
       
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.0. Changed inline namespace name in version 3.11.2.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_json_namespace_no_version/index.html b/api/macros/nlohmann_json_namespace_no_version/index.html index 87ec84c76..9b4bb6286 100644 --- a/api/macros/nlohmann_json_namespace_no_version/index.html +++ b/api/macros/nlohmann_json_namespace_no_version/index.html @@ -1,4 +1,4 @@ - NLOHMANN_JSON_NAMESPACE_NO_VERSION - JSON for Modern C++
Skip to content

NLOHMANN_JSON_NAMESPACE_NO_VERSION

#define NLOHMANN_JSON_NAMESPACE_NO_VERSION /* value */
+ NLOHMANN_JSON_NAMESPACE_NO_VERSION - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_JSON_NAMESPACE_NO_VERSION
 
#define NLOHMANN_JSON_NAMESPACE_NO_VERSION /* value */
 
 
If defined to 1, the version component is omitted from the inline namespace. See nlohmann Namespace for details.
 
Default definition
 
The default value is 0.
 
#define NLOHMANN_JSON_NAMESPACE_NO_VERSION 0
 
 
When the macro is not defined, the library will define it to its default value.
 
Examples
 
 Example 
The example shows how to use NLOHMANN_JSON_NAMESPACE_NO_VERSION to disable the version component of the inline namespace.
 
#include <iostream>
 
@@ -14,4 +14,4 @@
     std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl;
 }
 
 
Output:
 
nlohmann::json_abi
-
 
 
See also
  
Version history
 
     
  • Added in version 3.11.2.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.11.2.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_json_serialize_enum/index.html b/api/macros/nlohmann_json_serialize_enum/index.html index b9b3f1510..72f1a7d47 100644 --- a/api/macros/nlohmann_json_serialize_enum/index.html +++ b/api/macros/nlohmann_json_serialize_enum/index.html @@ -1,4 +1,4 @@ - NLOHMANN_JSON_SERIALIZE_ENUM - JSON for Modern C++
Skip to content

NLOHMANN_JSON_SERIALIZE_ENUM

#define NLOHMANN_JSON_SERIALIZE_ENUM(type, conversion...)
+ NLOHMANN_JSON_SERIALIZE_ENUM - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_JSON_SERIALIZE_ENUM
 
#define NLOHMANN_JSON_SERIALIZE_ENUM(type, conversion...)
 
 
By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later deserialized JSON data may be undefined or a different enum value than was originally intended.
 
The NLOHMANN_JSON_SERIALIZE_ENUM allows to define a user-defined serialization for every enumerator.
 
Parameters
 
 
type (in)
 
name of the enum to serialize/deserialize
 
conversion (in)
 
a pair of an enumerator and a JSON serialization; arbitrary pairs can be given as a comma-separated list
 
 
Default definition
 
The macro adds two functions to the namespace which take care of the serialization and deserialization:
 
template<typename BasicJsonType>
 inline void to_json(BasicJsonType& j, const type& e);
 template<typename BasicJsonType>
@@ -101,4 +101,4 @@
 
 
Output:
 
0 -> "red"
 "rot" -> 0
 "red" -> 0
-
  
See also
  
Version history
 
Added in version 3.4.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Added in version 3.4.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_json_serialize_enum_strict/index.html b/api/macros/nlohmann_json_serialize_enum_strict/index.html index b03ea7771..be3cedd7d 100644 --- a/api/macros/nlohmann_json_serialize_enum_strict/index.html +++ b/api/macros/nlohmann_json_serialize_enum_strict/index.html @@ -1,4 +1,4 @@ - NLOHMANN_JSON_SERIALIZE_ENUM_STRICT - JSON for Modern C++
Skip to content

NLOHMANN_JSON_SERIALIZE_ENUM_STRICT

#define NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(type, conversion...)
+ NLOHMANN_JSON_SERIALIZE_ENUM_STRICT - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_JSON_SERIALIZE_ENUM_STRICT
 
#define NLOHMANN_JSON_SERIALIZE_ENUM_STRICT(type, conversion...)
 
 
By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later deserialized JSON data may be undefined or a different enum value than was originally intended.
 
NLOHMANN_JSON_SERIALIZE_ENUM_STRICT allows to define a user-defined serialization for every enumerator that throws an exception on undefined input.
 
Parameters
 
 
type (in)
 
name of the enum to serialize/deserialize
 
conversion (in)
 
a pair of an enumerator and a JSON serialization; arbitrary pairs can be given as a comma-separated list
 
 
Default definition
 
The macro adds two functions to the namespace which take care of the serialization and deserialization:
 
template<typename BasicJsonType>
 inline void to_json(BasicJsonType& j, const type& e);
 template<typename BasicJsonType>
@@ -148,4 +148,4 @@
 }
 
 
Output: 
deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color
 deserialization failed: [json.exception.out_of_range.410] enum value out of range for Color: "what"
-
  
See also
  
Version history
 
Added in version 3.13.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Added in version 3.13.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/macros/nlohmann_json_version_major/index.html b/api/macros/nlohmann_json_version_major/index.html index 4ae3a00c1..6e0cbffe5 100644 --- a/api/macros/nlohmann_json_version_major/index.html +++ b/api/macros/nlohmann_json_version_major/index.html @@ -1,4 +1,4 @@ - NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH - JSON for Modern C++
Skip to content

NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH

#define NLOHMANN_JSON_VERSION_MAJOR /* value */
+ NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH
 
#define NLOHMANN_JSON_VERSION_MAJOR /* value */
 #define NLOHMANN_JSON_VERSION_MINOR /* value */
 #define NLOHMANN_JSON_VERSION_PATCH /* value */
 
 
These macros are defined by the library and contain the version numbers according to Semantic Versioning 2.0.0.
 
Default definition
 
The macros are defined according to the current library version.
 
Examples
 
 Example 
The example below shows how NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, and NLOHMANN_JSON_VERSION_PATCH are defined by the library.
 
#include <iostream>
@@ -14,4 +14,4 @@
               << NLOHMANN_JSON_VERSION_PATCH << std::endl;
 }
 
 
Output:
 
JSON for Modern C++ version 3.12.0
-
 
 
See also
  
Version history
 
     
  • Added in version 3.1.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 3.1.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/operator_gtgt/index.html b/api/operator_gtgt/index.html index b3674c8a0..23c0c3728 100644 --- a/api/operator_gtgt/index.html +++ b/api/operator_gtgt/index.html @@ -1,4 +1,4 @@ - operator>>(basic_json) - JSON for Modern C++
Skip to content

nlohmann::operator>>(basic_json)

std::istream& operator>>(std::istream& i, basic_json& j);
+ operator>>(basic_json) - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::operator>>(basic_json)
 
std::istream& operator>>(std::istream& i, basic_json& j);
 
 
Deserializes an input stream to a JSON value.
 
Parameters
 
 
i (in, out)
 
input stream to read a serialized JSON value from
 
j (in, out)
 
JSON value to write the deserialized input to
 
 
Return value
 
the stream i
 
Exceptions
  
Complexity
 
Linear in the length of the input. The parser is a predictive LL(1) parser.
 
Notes
 
A UTF-8 byte order mark is silently ignored.
 
Invalid Unicode escapes and unpaired surrogates in the input are reported as parse_error.101 with a detailed message.
 
operator>> parses exactly one JSON value, so it can be called repeatedly to read a sequence of concatenated JSON values from the same stream:
 
json j1, j2;
 input >> j1;  // parses the first value
 input >> j2;  // parses the next value
@@ -49,4 +49,4 @@
   "number": 23,
   "string": "Hello, world!"
 }
-
  
See also
 
     
  • accept - check if the input is valid JSON
    •  
  • parse - deserialize from a compatible input
    •  
 
Version history
 
     
  • Added in version 1.0.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • accept - check if the input is valid JSON
  • parse - deserialize from a compatible input

Version history

  • Added in version 1.0.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/operator_literal_json/index.html b/api/operator_literal_json/index.html index b7896dd6d..f3622f2db 100644 --- a/api/operator_literal_json/index.html +++ b/api/operator_literal_json/index.html @@ -1,4 +1,4 @@ - operator""_json - JSON for Modern C++
Skip to content

nlohmann::operator""_json

json operator ""_json(const char* s, std::size_t n);
+ operator""_json - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::operator""_json
 
json operator ""_json(const char* s, std::size_t n);
 json operator ""_json(const char8_t* s, std::size_t n);  // since C++20
 
 
This operator implements a user-defined string literal for JSON objects. It can be used by adding _json to a string literal and returns a json object if no parse error occurred.
 
It is recommended to bring the operator into scope using any of the following lines: 
using nlohmann::literals::operator ""_json;
 using namespace nlohmann::literals;
@@ -22,4 +22,4 @@
   "answer": 42,
   "hello": "world"
 }
-
  
See also
  
Version history
 
     
  • Added in version 1.0.0.
    •  
  • Moved to namespace nlohmann::literals::json_literals in 3.11.0.
    •  
  • Added char8_t* overload in 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 1.0.0.
  • Moved to namespace nlohmann::literals::json_literals in 3.11.0.
  • Added char8_t* overload in 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/operator_literal_json_pointer/index.html b/api/operator_literal_json_pointer/index.html index de29cb5d2..9f878e62b 100644 --- a/api/operator_literal_json_pointer/index.html +++ b/api/operator_literal_json_pointer/index.html @@ -1,4 +1,4 @@ - operator""_json_pointer - JSON for Modern C++
Skip to content

nlohmann::operator""_json_pointer

json_pointer operator ""_json_pointer(const char* s, std::size_t n);
+ operator""_json_pointer - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::operator""_json_pointer
 
json_pointer operator ""_json_pointer(const char* s, std::size_t n);
 json_pointer operator ""_json_pointer(const char8_t* s, std::size_t n);  // since C++20
 
 
This operator implements a user-defined string literal for JSON Pointers. It can be used by adding _json_pointer to a string literal and returns a json_pointer object if no parse error occurred.
 
It is recommended to bring the operator into scope using any of the following lines: 
using nlohmann::literals::operator ""_json_pointer;
 using namespace nlohmann::literals;
@@ -20,4 +20,4 @@
     std::cout << std::setw(2) << val << '\n';
 }
 
 
Output:
 
"world"
-
  
See also
  
Version history
 
     
  • Added in version 2.0.0.
    •  
  • Moved to namespace nlohmann::literals::json_literals in 3.11.0.
    •  
  • Added char8_t* overload in 3.13.0.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

  • Added in version 2.0.0.
  • Moved to namespace nlohmann::literals::json_literals in 3.11.0.
  • Added char8_t* overload in 3.13.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/operator_ltlt/index.html b/api/operator_ltlt/index.html index 1fa190fae..50f050146 100644 --- a/api/operator_ltlt/index.html +++ b/api/operator_ltlt/index.html @@ -1,4 +1,4 @@ - operator<<(basic_json), operator<<(json_pointer) - JSON for Modern C++
Skip to content

nlohmann::operator<<(basic_json), nlohmann::operator<<(json_pointer)

std::ostream& operator<<(std::ostream& o, const basic_json& j);      // (1)
+ operator<<(basic_json), operator<<(json_pointer) - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::operator<<(basic_json), nlohmann::operator<<(json_pointer)
 
std::ostream& operator<<(std::ostream& o, const basic_json& j);      // (1)
 
 std::ostream& operator<<(std::ostream& o, const json_pointer& ptr);  // (2)
 
 
     
  1. Serialize the given JSON value j to the output stream o. The JSON value will be serialized using the dump member function.
       
    • The indentation of the output can be controlled with the member variable width of the output stream o. For instance, using the manipulator std::setw(4) on o sets the indentation level to 4 and the serialization result is the same as calling dump(4).
      •  
    • The indentation character can be controlled with the member variable fill of the output stream o. For instance, the manipulator std::setfill('\\t') sets indentation to use a tab character rather than the default space character.
      •  
     
    2.  
  2. Write a string representation of the given JSON pointer ptr to the output stream o. The string representation is obtained using the to_string member function.
    3.  
 
Parameters
 
 
o (in, out)
 
stream to write to
 
j (in)
 
JSON value to serialize
 
ptr (in)
 
JSON pointer to write
 
 
Return value
 
the stream o
 
Exceptions
 
     
  1. Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded. Note that unlike the dump member functions, no error_handler can be set.
    2.  
  2. None.
    3.  
 
Complexity
 
Linear.
 
Notes
 
 
Deprecation
 
Function std::ostream& operator<<(std::ostream& o, const basic_json& j) replaces function std::ostream& operator>>(const basic_json& j, std::ostream& o) which has been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like j >> o; with o << j;.
 
 
Examples
 
 Example: (1) serialize JSON value to stream 
The example below shows the serialization with different parameters to width to adjust the indentation level.
 
#include <iostream>
@@ -57,4 +57,4 @@
     std::cout << ptr << std::endl;
 }
 
 
Output:
 
/foo/bar/baz
-
 
 
See also
 
     
  • dump - serialize to a JSON-formatted string
    •  
  • Serialization - the serialization article
    •  
 
Version history
 
     
  1. Added in version 1.0.0. Added support for indentation character and deprecated std::ostream& operator>>(const basic_json& j, std::ostream& o) in version 3.0.0.
    2.  
  2. Added in version 3.11.0.
    3.  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

  • dump - serialize to a JSON-formatted string
  • Serialization - the serialization article

Version history

  1. Added in version 1.0.0. Added support for indentation character and deprecated std::ostream& operator>>(const basic_json& j, std::ostream& o) in version 3.0.0.
  2. Added in version 3.11.0.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/ordered_json/index.html b/api/ordered_json/index.html index 1bba06bbe..766d65487 100644 --- a/api/ordered_json/index.html +++ b/api/ordered_json/index.html @@ -1,4 +1,4 @@ - ordered_json - JSON for Modern C++
Skip to content

nlohmann::ordered_json

using ordered_json = basic_json<ordered_map>;
+ ordered_json - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::ordered_json
 
using ordered_json = basic_json<ordered_map>;
 
 
This type preserves the insertion order of object keys.
 
Iterator invalidation
 
The type is based on ordered_map which in turn uses a std::vector to store object elements. Therefore, adding object elements can yield a reallocation in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Also, any iterator or reference after the insertion point will point to the same index, which is now a different value.
 
Complexity
 
ordered_map has no lookup index: every key-based object operation is a linear scan, so building or parsing an object of n keys costs O(n²) rather than O(n log n). See ordered_map complexity for the per-operation table and for measured numbers.
 
Examples
 
 Example 
The example below demonstrates how ordered_json preserves the insertion order of object keys.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 
@@ -18,4 +18,4 @@
   "two": 2,
   "three": 3
 }
-
 
 
See also
  
Version history
 
Since version 3.9.0.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Since version 3.9.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/api/ordered_map/index.html b/api/ordered_map/index.html index 5a3e79182..57176b70a 100644 --- a/api/ordered_map/index.html +++ b/api/ordered_map/index.html @@ -1,4 +1,4 @@ - ordered_map - JSON for Modern C++
Skip to content

nlohmann::ordered_map

template<class Key, class T, class IgnoredLess = std::less<Key>,
+ ordered_map - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann::ordered_map
 
template<class Key, class T, class IgnoredLess = std::less<Key>,
          class Allocator = std::allocator<std::pair<const Key, T>>>
 struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
 
 
A minimal map-like container that preserves insertion order for use within nlohmann::ordered_json (nlohmann::basic_json<ordered_map>).
 
Template parameters
 
 
Key
 
key type
 
T
 
mapped type
 
IgnoredLess
 
comparison function (ignored and only added to ensure compatibility with std::map)
 
Allocator
 
allocator type
 
 
Iterator invalidation
 
The type uses a std::vector to store object elements. Therefore, adding elements can yield a reallocation in which case all iterators (including the end() iterator) and all references to the elements are invalidated.
 
Member types
 
     
  • key_type - key type (Key)
    •  
  • mapped_type - mapped type (T)
    •  
  • Container - base container type (std::vector<std::pair<const Key, T>, Allocator>)
    •  
  • iterator
    •  
  • const_iterator
    •  
  • size_type
    •  
  • value_type
    •  
  • key_compare - key comparison function 
    std::equal_to<Key>  // until C++14
@@ -51,4 +51,4 @@
 m_std = { one:eins three:drei two:zwei }
 m_ordered = { two:zwei three:drei one:eins }
 m_std = { one:eins three:drei two:zwei }
-
      
    See also
      
    Version history
        
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Version history

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community.md b/community.md index caef17be3..50baeab25 100644 --- a/community.md +++ b/community.md @@ -1,5 +1,6 @@ # Community +- [Ecosystem](ecosystem.md) - third-party projects built on top of this library - [Code of Conduct](code_of_conduct.md) - the rules and norms of this project - [Contribution Guidelines](contribution_guidelines.md) - guidelines how to contribute to this project - [Governance](governance.md) - the governance model of this project diff --git a/community/code_of_conduct/index.html b/community/code_of_conduct/index.html index 971107a13..d0415c961 100644 --- a/community/code_of_conduct/index.html +++ b/community/code_of_conduct/index.html @@ -1 +1 @@ - Code of Conduct - JSON for Modern C++
Skip to content

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

  • The use of sexualized language or imagery, and sexual attention or advances of any kind
  • Trolling, insulting or derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or email address, without their explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at mail@nlohmann.me. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Code of Conduct - JSON for Modern C++
Skip to content

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

  • The use of sexualized language or imagery, and sexual attention or advances of any kind
  • Trolling, insulting or derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or email address, without their explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at mail@nlohmann.me. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community/contribution_guidelines/index.html b/community/contribution_guidelines/index.html index 574544c5f..6b17defbf 100644 --- a/community/contribution_guidelines/index.html +++ b/community/contribution_guidelines/index.html @@ -1,8 +1,8 @@ - Contribution Guidelines - JSON for Modern C++
Skip to content

Contribution Guidelines

Thank you for your interest in contributing to this project! What began as an exercise to explore the exciting features of C++11 has evolved into a widely used JSON library. I truly appreciate all the contributions from the community, whether it's proposing features, identifying bugs, or fixing mistakes! To ensure that our collaboration is efficient and effective, please follow these guidelines.

Feel free to discuss or suggest improvements to this document by submitting a pull request.

Ways to Contribute

There are multiple ways to contribute.

Reporting an issue

Please create an issue, assuming one does not already exist, and describe your concern. Note you need a GitHub account for this.

Clearly describe the issue:

  • If it is a bug, please describe how to reproduce it. If possible, attach a complete example which demonstrates the error. Please also state what you expected to happen instead of the error.
  • If you propose a change or addition, try to give an example what the improved code could look like or how to use it.
  • If you found a compilation error, please tell us which compiler (version and operating system) you used and paste the (relevant part of) the error messages to the ticket.

Please stick to the provided issue template bug report if possible.

Reporting a security vulnerability

You can report a security vulnerability according to our security policy.

Discussing a new feature

For questions, feature or support requests, please open a discussion. If you find a proposed answer satisfactory, please use the "Mark as answer" button to make it easier for readers to see what helped and for the community to filter for open questions.

Proposing a fix or an improvement

Join an ongoing discussion or comment on an existing issue before starting to code. This can help to avoid duplicate efforts or other frustration during the later review.

Create a pull request against the develop branch and follow the pull request template. In particular,

  • describe the changes in detail, both the what and why,
  • reference existing issues where applicable,
  • add tests to maintain 100% test coverage,
  • update the documentation as needed, and
  • ensure the source code is amalgamated.

We describe all points in detail below.

All contributions (including pull requests) must agree to the Developer Certificate of Origin (DCO) version 1.1. This is exactly the same one created and used by the Linux kernel developers and posted on http://developercertificate.org/. This is a developer's certification that he or she has the right to submit the patch for inclusion into the project.

How to...

Describe your changes

This library is primarily maintained as a spare-time project. As such, I cannot make any guarantee how quickly changes are merged and released. Therefore, it is very important to make the review as smooth as possible by explaining not only what you changed, but why. This rationale can be very valuable down the road when improvements or bugs are discussed years later.

Reference an existing issue

Link a pull request to an issue to clarify that a fix is forthcoming and which issue can be closed after merging. Only a few cases (e.g., fixing typos) do not require prior discussions.

Write tests

The library has an extensive test suite that currently covers 100 % of the library's code. These tests are crucial to maintain API stability and give future contributors confidence that they do not accidentally break things. As Titus Winters aptly put it:

If you liked it, you should have put a test on it.

Run the tests

First, ensure the test suite runs before making any changes:

$ cmake -S. -B build
+ Contribution Guidelines - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Contribution Guidelines
 
Thank you for your interest in contributing to this project! What began as an exercise to explore the exciting features of C++11 has evolved into a widely used JSON library. I truly appreciate all the contributions from the community, whether it's proposing features, identifying bugs, or fixing mistakes! To ensure that our collaboration is efficient and effective, please follow these guidelines.
 
Feel free to discuss or suggest improvements to this document by submitting a pull request.
 
Ways to Contribute
 
There are multiple ways to contribute.
 
Reporting an issue
 
Please create an issue, assuming one does not already exist, and describe your concern. Note you need a GitHub account for this.
 
Clearly describe the issue:
 
     
  • If it is a bug, please describe how to reproduce it. If possible, attach a complete example which demonstrates the error. Please also state what you expected to happen instead of the error.
    •  
  • If you propose a change or addition, try to give an example what the improved code could look like or how to use it.
    •  
  • If you found a compilation error, please tell us which compiler (version and operating system) you used and paste the (relevant part of) the error messages to the ticket.
    •  
 
Please stick to the provided issue template bug report if possible.
 
Reporting a security vulnerability
 
You can report a security vulnerability according to our security policy.
 
Discussing a new feature
 
For questions, feature or support requests, please open a discussion. If you find a proposed answer satisfactory, please use the "Mark as answer" button to make it easier for readers to see what helped and for the community to filter for open questions.
 
Proposing a fix or an improvement
 
Join an ongoing discussion or comment on an existing issue before starting to code. This can help to avoid duplicate efforts or other frustration during the later review.
 
Create a pull request against the develop branch and follow the pull request template. In particular,
 
     
  • describe the changes in detail, both the what and why,
    •  
  • reference existing issues where applicable,
    •  
  • add tests to maintain 100% test coverage,
    •  
  • update the documentation as needed, and
    •  
  • ensure the source code is amalgamated.
    •  
 
We describe all points in detail below.
 
All contributions (including pull requests) must agree to the Developer Certificate of Origin (DCO) version 1.1. This is exactly the same one created and used by the Linux kernel developers and posted on http://developercertificate.org/. This is a developer's certification that he or she has the right to submit the patch for inclusion into the project.
 
How to...
 
Describe your changes
 
This library is primarily maintained as a spare-time project. As such, I cannot make any guarantee how quickly changes are merged and released. Therefore, it is very important to make the review as smooth as possible by explaining not only what you changed, but why. This rationale can be very valuable down the road when improvements or bugs are discussed years later.
 
Reference an existing issue
 
Link a pull request to an issue to clarify that a fix is forthcoming and which issue can be closed after merging. Only a few cases (e.g., fixing typos) do not require prior discussions.
 
Write tests
 
The library has an extensive test suite that currently covers 100 % of the library's code. These tests are crucial to maintain API stability and give future contributors confidence that they do not accidentally break things. As Titus Winters aptly put it:
 
 
If you liked it, you should have put a test on it.
 
 
Run the tests
 
First, ensure the test suite runs before making any changes:
 
$ cmake -S. -B build
 $ cmake --build build -j 10
 $ ctest --test-dir build -j 10
 
 
The test suite should report:
 
100% tests passed, 0 tests failed out of 98
 
 
Add tests
 
The tests are located in tests/src/unit-*.cpp and contain doctest assertions like CHECK. The tests are structured along the features of the library or the nature of the tests. Usually, it should be clear from the context which existing file needs to be extended, and only very few cases require creating new test files.
 
When fixing a bug, edit unit-regression2.cpp and add a section referencing the fixed issue.
 
Exceptions
 
When you test exceptions, please use CHECK_THROWS_WITH_AS which also takes the what() argument of the thrown exception into account.
 
Coverage
 
If test coverage decreases, an automatic warning comment will be posted on the pull request. You can access a code coverage report as an artifact to the “Ubuntu” workflow.
 
Update the documentation
 
The main documentation of the library is generated from the files docs/mkdocs/docs. This folder contains dedicated pages for certain features, a list of all exceptions, and extensive API documentation with details on every public API function.
 
Build the documentation locally using:
 
make install_venv -C docs/mkdocs
 make serve -C docs/mkdocs
 
 
The documentation will then be available at http://127.0.0.1:8000/. See the documentation of mkdocs and Material for MkDocs for more information.
 
Amalgamate the source code
 
The single-header files single_include/nlohmann/json.hpp and single_include/nlohmann/json_fwd.hpp are generated from the source files in the include/nlohmann directory. Do not edit the files directly; instead, modify the include/nlohmann sources and regenerate the files by executing:
 
make amalgamate
-
 
Running make amalgamate will also apply automatic formatting to the source files using Artistic Style. This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.
  
     
  • The library’s README file is an excellent starting point to understand its functionality.
    •  
  • The documentation page is the reference documentation of the library.
    •  
  • RFC 8259 is the reference for the JavaScript Object Notation (JSON) Data Interchange Format.
    •  
 
Please don't...
 
Certain contributions are not helpful.
 
Break the public API
 
We take pride in the library being used by numerous customers across various industries. They all rely on the guarantees provided by semantic versioning. Please do not change the library such that the public API of the 3.x.y version is broken. This includes:
 
     
  • Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.
    •  
  • Removing functions.
    •  
  • Renaming functions or classes.
    •  
  • Changing exception handling.
    •  
  • Changing exception ids.
    •  
  • Changing access specifiers.
    •  
  • Changing default arguments.
    •  
 
Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.
 
Breaking changes may be introduced when they are guarded with a feature macro such as JSON_USE_IMPLICIT_CONVERSIONS which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.
 
Break C++11 language conformance
 
This library is designed to work with C++11 and later. This means that any supported C++11 compiler should compile the library without problems. Some compilers like GCC 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.
 
Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective JSON_HAS_CPP_14 macros.
 
Break JSON conformance
 
Please refrain from proposing changes that would break JSON conformance. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.
 
Wanted
 
The following areas really need contribution and are always welcomed:
 
     
  • Extending the continuous integration toward more exotic compilers such as Android NDK, Intel's Compiler, or the bleeding-edge versions Clang.
    •  
  • Improving the efficiency of the JSON parser. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the json.hpp header, and I am not aware of approaches similar to re2c for parsing.
    •  
  • Extending and updating existing benchmarks to include (the most recent version of) this library. Though efficiency is not everything, speed and memory consumption are very important characteristics for C++ developers, so having proper comparisons would be interesting.
    •  
 
We look forward to your contributions and collaboration to enhance the library!
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Running make amalgamate will also apply automatic formatting to the source files using Artistic Style. This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.

  • The library’s README file is an excellent starting point to understand its functionality.
  • The documentation page is the reference documentation of the library.
  • RFC 8259 is the reference for the JavaScript Object Notation (JSON) Data Interchange Format.

Please don't...

Certain contributions are not helpful.

Break the public API

We take pride in the library being used by numerous customers across various industries. They all rely on the guarantees provided by semantic versioning. Please do not change the library such that the public API of the 3.x.y version is broken. This includes:

  • Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.
  • Removing functions.
  • Renaming functions or classes.
  • Changing exception handling.
  • Changing exception ids.
  • Changing access specifiers.
  • Changing default arguments.

Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.

Breaking changes may be introduced when they are guarded with a feature macro such as JSON_USE_IMPLICIT_CONVERSIONS which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.

Break C++11 language conformance

This library is designed to work with C++11 and later. This means that any supported C++11 compiler should compile the library without problems. Some compilers like GCC 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.

Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective JSON_HAS_CPP_14 macros.

Break JSON conformance

Please refrain from proposing changes that would break JSON conformance. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.

Wanted

The following areas really need contribution and are always welcomed:

  • Extending the continuous integration toward more exotic compilers such as Android NDK, Intel's Compiler, or the bleeding-edge versions Clang.
  • Improving the efficiency of the JSON parser. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the json.hpp header, and I am not aware of approaches similar to re2c for parsing.
  • Extending and updating existing benchmarks to include (the most recent version of) this library. Though efficiency is not everything, speed and memory consumption are very important characteristics for C++ developers, so having proper comparisons would be interesting.

We look forward to your contributions and collaboration to enhance the library!

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community/ecosystem.md b/community/ecosystem.md new file mode 100644 index 000000000..801111e7d --- /dev/null +++ b/community/ecosystem.md @@ -0,0 +1,40 @@ +# Ecosystem + +The projects below build on top of `nlohmann::json` rather than merely using it - schema validators, language +bindings, format converters, and similar building blocks. The list is not exhaustive, and is curated rather than +automatically generated. If you maintain or know of a project that belongs here, +[please let me know](mailto:mail@nlohmann.me). + +For products, applications, and organizations that use the library, see [Customers](../home/customers.md) instead. + +## Schema validation + +- [**json-schema-validator**](https://github.com/pboettch/json-schema-validator), a JSON Schema (draft 7) validator + with human-readable error messages + +## Serialization and reflection + +- [**nlohmann_json_reflect**](https://github.com/1261385937/nlohmann_json_reflect), a reflection extension for + (de)serializing nested containers-in-structs-in-containers + +## Encodings + +- [**base-encode-decode**](https://github.com/saxonnicholls/base-encode-decode), a header-only Base64/32/16/8/4/2 + (and DNA/RNA) encoding library, with an adapter that serializes binary data through `nlohmann::json` + +## Language bindings and interop + +- [**pybind11_json**](https://github.com/pybind/pybind11_json), a bidirectional type caster between + `nlohmann::json` and Python objects for [pybind11](https://github.com/pybind/pybind11) bindings +- [**nanobind_json**](https://github.com/ianhbell/nanobind_json), the same idea for + [nanobind](https://github.com/wjakob/nanobind) bindings +- [**nlohmann_json_qt**](https://github.com/dpurgin/nlohmann_json_qt), deserialization helpers for Qt types + (`QString`, `QUrl`, `QDateTime`, `QVector`, ...) from `nlohmann::json` +- [**vulkan2json**](https://github.com/Fadis/vulkan2json), serialization and deserialization of Vulkan API structs + +## Format converters + +- [**tojson**](https://github.com/mircodz/tojson), a header-only converter between YAML/XML documents and + `nlohmann::json` +- [**json2xml**](https://github.com/testillano/json2xml), a header-only converter from `nlohmann::json` to XML for + simple configuration documents diff --git a/community/ecosystem/index.html b/community/ecosystem/index.html new file mode 100644 index 000000000..bbc2030e8 --- /dev/null +++ b/community/ecosystem/index.html @@ -0,0 +1 @@ + Ecosystem - JSON for Modern C++
Skip to content

Ecosystem

The projects below build on top of nlohmann::json rather than merely using it - schema validators, language bindings, format converters, and similar building blocks. The list is not exhaustive, and is curated rather than automatically generated. If you maintain or know of a project that belongs here, please let me know.

For products, applications, and organizations that use the library, see Customers instead.

Schema validation

Serialization and reflection

  • nlohmann_json_reflect, a reflection extension for (de)serializing nested containers-in-structs-in-containers

Encodings

  • base-encode-decode, a header-only Base64/32/16/8/4/2 (and DNA/RNA) encoding library, with an adapter that serializes binary data through nlohmann::json

Language bindings and interop

Format converters

  • tojson, a header-only converter between YAML/XML documents and nlohmann::json
  • json2xml, a header-only converter from nlohmann::json to XML for simple configuration documents
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community/ecosystem/index.md b/community/ecosystem/index.md new file mode 100644 index 000000000..7be79145b --- /dev/null +++ b/community/ecosystem/index.md @@ -0,0 +1,29 @@ +# Ecosystem + +The projects below build on top of `nlohmann::json` rather than merely using it - schema validators, language bindings, format converters, and similar building blocks. The list is not exhaustive, and is curated rather than automatically generated. If you maintain or know of a project that belongs here, [please let me know](mailto:mail@nlohmann.me). + +For products, applications, and organizations that use the library, see [Customers](https://json.nlohmann.me/home/customers/index.md) instead. + +## Schema validation + +- [**json-schema-validator**](https://github.com/pboettch/json-schema-validator), a JSON Schema (draft 7) validator with human-readable error messages + +## Serialization and reflection + +- [**nlohmann_json_reflect**](https://github.com/1261385937/nlohmann_json_reflect), a reflection extension for (de)serializing nested containers-in-structs-in-containers + +## Encodings + +- [**base-encode-decode**](https://github.com/saxonnicholls/base-encode-decode), a header-only Base64/32/16/8/4/2 (and DNA/RNA) encoding library, with an adapter that serializes binary data through `nlohmann::json` + +## Language bindings and interop + +- [**pybind11_json**](https://github.com/pybind/pybind11_json), a bidirectional type caster between `nlohmann::json` and Python objects for [pybind11](https://github.com/pybind/pybind11) bindings +- [**nanobind_json**](https://github.com/ianhbell/nanobind_json), the same idea for [nanobind](https://github.com/wjakob/nanobind) bindings +- [**nlohmann_json_qt**](https://github.com/dpurgin/nlohmann_json_qt), deserialization helpers for Qt types (`QString`, `QUrl`, `QDateTime`, `QVector`, ...) from `nlohmann::json` +- [**vulkan2json**](https://github.com/Fadis/vulkan2json), serialization and deserialization of Vulkan API structs + +## Format converters + +- [**tojson**](https://github.com/mircodz/tojson), a header-only converter between YAML/XML documents and `nlohmann::json` +- [**json2xml**](https://github.com/testillano/json2xml), a header-only converter from `nlohmann::json` to XML for simple configuration documents diff --git a/community/governance/index.html b/community/governance/index.html index 134942888..07dd696be 100644 --- a/community/governance/index.html +++ b/community/governance/index.html @@ -1 +1 @@ - Governance - JSON for Modern C++
Skip to content

Governance

The governance model for the JSON for Modern C++ project is a Benevolent Dictator for Life (BDFL) structure. As the sole maintainer, Niels Lohmann is responsible for all key aspects of the project. The project governance may evolve as the project grows, but any changes will be documented here and communicated to contributors.

Overview

This project is led by a benevolent dictator, Niels Lohmann, and managed by the community. That is, the community actively contributes to the day-to-day maintenance of the project, but the general strategic line is drawn by the benevolent dictator. In case of disagreement, they have the last word. It is the benevolent dictator’s job to resolve disputes within the community and to ensure that the project is able to progress in a coordinated way. In turn, it is the community’s job to guide the decisions of the benevolent dictator through active engagement and contribution.

Roles and responsibilities

Benevolent dictator (project lead)

Typically, the benevolent dictator, or project lead, is self-appointed. However, because the community always has the ability to fork, this person is fully answerable to the community. The project lead’s role is a difficult one: they set the strategic objectives of the project and communicate these clearly to the community. They also have to understand the community as a whole and strive to satisfy as many conflicting needs as possible, while ensuring that the project survives in the long term.

In many ways, the role of the benevolent dictator is less about dictatorship and more about diplomacy. The key is to ensure that, as the project expands, the right people are given influence over it and the community rallies behind the vision of the project lead. The lead’s job is then to ensure that the committers (see below) make the right decisions on behalf of the project. Generally speaking, as long as the committers are aligned with the project’s strategy, the project lead will allow them to proceed as they desire.

Committers

Committers are contributors who have made several valuable contributions to the project and are now relied upon to both write code directly to the repository and screen the contributions of others. In many cases they are programmers but it is also possible that they contribute in a different role. Typically, a committer will focus on a specific aspect of the project, and will bring a level of expertise and understanding that earns them the respect of the community and the project lead. The role of committer is not an official one, it is simply a position that influential members of the community will find themselves in as the project lead looks to them for guidance and support.

Committers have no authority over the overall direction of the project. However, they do have the ear of the project lead. It is a committer’s job to ensure that the lead is aware of the community’s needs and collective objectives, and to help develop or elicit appropriate contributions to the project. Often, committers are given informal control over their specific areas of responsibility, and are assigned rights to directly modify certain areas of the source code. That is, although committers do not have explicit decision-making authority, they will often find that their actions are synonymous with the decisions made by the lead.

Contributors

Contributors are community members who either have no desire to become committers, or have not yet been given the opportunity by the benevolent dictator. They make valuable contributions, such as those outlined in the list below, but generally do not have the authority to make direct changes to the project code. Contributors engage with the project through communication tools, such as email lists, and via reports and patches attached to issues in the issue tracker, as detailed in our community tools document.

Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements and no selection process. To become a contributor, a community member simply has to perform one or more actions that are beneficial to the project.

Some contributors will already be engaging with the project as users, but will also find themselves doing one or more of the following:

  • supporting new users (current users often provide the most effective new user support)
  • reporting bugs
  • identifying requirements
  • supplying graphics and web design
  • programming
  • assisting with project infrastructure
  • writing documentation
  • fixing bugs
  • adding features

As contributors gain experience and familiarity with the project, they may find that the project lead starts relying on them more and more. When this begins to happen, they gradually adopt the role of committer, as described above.

Users

Users are community members who have a need for the project. They are the most important members of the community: without them, the project would have no purpose. Anyone can be a user; there are no specific requirements.

Users should be encouraged to participate in the life of the project and the community as much as possible. User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user activities include (but are not limited to):

  • evangelising about the project
  • informing developers of project strengths and weaknesses from a new user’s perspective
  • providing moral support (a ‘thank you’ goes a long way)
  • providing financial support

Users who continue to engage with the project and its community will often find themselves becoming more and more involved. Such users may then go on to become contributors, as described above.

Support

All participants in the community are encouraged to provide support for new users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognise that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a vendor. (Of course, that vendor should be an active member of the community.) However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal.

Contribution Process

Anyone can contribute to the project, regardless of their skills, as there are many ways to contribute. For instance, a contributor might be active on the project mailing list and issue tracker, or might supply patches. The various ways of contributing are described in more detail in our roles in open source document.

The developer mailing list is the most appropriate place for a contributor to ask for help when making their first contribution.

Decision-Making Process

The benevolent dictatorship model does not need a formal conflict resolution process, since the project lead’s word is final. If the community chooses to question the wisdom of the actions of a committer, the project lead can review their decisions by checking the email archives, and either uphold or reverse them.

Source

The text was taken from http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Governance - JSON for Modern C++
Skip to content

Governance

The governance model for the JSON for Modern C++ project is a Benevolent Dictator for Life (BDFL) structure. As the sole maintainer, Niels Lohmann is responsible for all key aspects of the project. The project governance may evolve as the project grows, but any changes will be documented here and communicated to contributors.

Overview

This project is led by a benevolent dictator, Niels Lohmann, and managed by the community. That is, the community actively contributes to the day-to-day maintenance of the project, but the general strategic line is drawn by the benevolent dictator. In case of disagreement, they have the last word. It is the benevolent dictator’s job to resolve disputes within the community and to ensure that the project is able to progress in a coordinated way. In turn, it is the community’s job to guide the decisions of the benevolent dictator through active engagement and contribution.

Roles and responsibilities

Benevolent dictator (project lead)

Typically, the benevolent dictator, or project lead, is self-appointed. However, because the community always has the ability to fork, this person is fully answerable to the community. The project lead’s role is a difficult one: they set the strategic objectives of the project and communicate these clearly to the community. They also have to understand the community as a whole and strive to satisfy as many conflicting needs as possible, while ensuring that the project survives in the long term.

In many ways, the role of the benevolent dictator is less about dictatorship and more about diplomacy. The key is to ensure that, as the project expands, the right people are given influence over it and the community rallies behind the vision of the project lead. The lead’s job is then to ensure that the committers (see below) make the right decisions on behalf of the project. Generally speaking, as long as the committers are aligned with the project’s strategy, the project lead will allow them to proceed as they desire.

Committers

Committers are contributors who have made several valuable contributions to the project and are now relied upon to both write code directly to the repository and screen the contributions of others. In many cases they are programmers but it is also possible that they contribute in a different role. Typically, a committer will focus on a specific aspect of the project, and will bring a level of expertise and understanding that earns them the respect of the community and the project lead. The role of committer is not an official one, it is simply a position that influential members of the community will find themselves in as the project lead looks to them for guidance and support.

Committers have no authority over the overall direction of the project. However, they do have the ear of the project lead. It is a committer’s job to ensure that the lead is aware of the community’s needs and collective objectives, and to help develop or elicit appropriate contributions to the project. Often, committers are given informal control over their specific areas of responsibility, and are assigned rights to directly modify certain areas of the source code. That is, although committers do not have explicit decision-making authority, they will often find that their actions are synonymous with the decisions made by the lead.

Contributors

Contributors are community members who either have no desire to become committers, or have not yet been given the opportunity by the benevolent dictator. They make valuable contributions, such as those outlined in the list below, but generally do not have the authority to make direct changes to the project code. Contributors engage with the project through communication tools, such as email lists, and via reports and patches attached to issues in the issue tracker, as detailed in our community tools document.

Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements and no selection process. To become a contributor, a community member simply has to perform one or more actions that are beneficial to the project.

Some contributors will already be engaging with the project as users, but will also find themselves doing one or more of the following:

  • supporting new users (current users often provide the most effective new user support)
  • reporting bugs
  • identifying requirements
  • supplying graphics and web design
  • programming
  • assisting with project infrastructure
  • writing documentation
  • fixing bugs
  • adding features

As contributors gain experience and familiarity with the project, they may find that the project lead starts relying on them more and more. When this begins to happen, they gradually adopt the role of committer, as described above.

Users

Users are community members who have a need for the project. They are the most important members of the community: without them, the project would have no purpose. Anyone can be a user; there are no specific requirements.

Users should be encouraged to participate in the life of the project and the community as much as possible. User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user activities include (but are not limited to):

  • evangelising about the project
  • informing developers of project strengths and weaknesses from a new user’s perspective
  • providing moral support (a ‘thank you’ goes a long way)
  • providing financial support

Users who continue to engage with the project and its community will often find themselves becoming more and more involved. Such users may then go on to become contributors, as described above.

Support

All participants in the community are encouraged to provide support for new users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognise that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a vendor. (Of course, that vendor should be an active member of the community.) However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal.

Contribution Process

Anyone can contribute to the project, regardless of their skills, as there are many ways to contribute. For instance, a contributor might be active on the project mailing list and issue tracker, or might supply patches. The various ways of contributing are described in more detail in our roles in open source document.

The developer mailing list is the most appropriate place for a contributor to ask for help when making their first contribution.

Decision-Making Process

The benevolent dictatorship model does not need a formal conflict resolution process, since the project lead’s word is final. If the community chooses to question the wisdom of the actions of a committer, the project lead can review their decisions by checking the email archives, and either uphold or reverse them.

Source

The text was taken from http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community/index.html b/community/index.html index d4c10fe0a..092c5624d 100644 --- a/community/index.html +++ b/community/index.html @@ -1 +1 @@ - Community - JSON for Modern C++
Skip to content
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Community - JSON for Modern C++
Skip to content
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community/index.md b/community/index.md index 75428364f..b9ea22343 100644 --- a/community/index.md +++ b/community/index.md @@ -1,5 +1,6 @@ # Community +- [Ecosystem](https://json.nlohmann.me/community/ecosystem/index.md) - third-party projects built on top of this library - [Code of Conduct](https://json.nlohmann.me/community/code_of_conduct/index.md) - the rules and norms of this project - [Contribution Guidelines](https://json.nlohmann.me/community/contribution_guidelines/index.md) - guidelines how to contribute to this project - [Governance](https://json.nlohmann.me/community/governance/index.md) - the governance model of this project diff --git a/community/quality_assurance/index.html b/community/quality_assurance/index.html index e0347bfe2..d25a32fab 100644 --- a/community/quality_assurance/index.html +++ b/community/quality_assurance/index.html @@ -1,4 +1,4 @@ - Quality assurance - JSON for Modern C++
Skip to content

Quality assurance

Ensuring quality is paramount for this project, particularly because numerous other projects depend on it. Each commit to the library undergoes rigorous checks against the following requirements, and any violations will result in a failed build.

C++ language compliance and compiler compatibility

Requirement: Compiler support

Any compiler with complete C++11 support can compile the library without warnings.

Note: C++20 modules support may hit compiler-specific issues not covered by the general compiler matrix below. See Modules for known issues and workarounds.

Note: Some modern features (like C++20 ranges or filesystem support) may be disabled on specific broken or incomplete toolchains even when standard feature-test macros indicate support. See JSON_HAS_RANGES and JSON_HAS_FILESYSTEM for details on known exclusions.

Simple integration

Requirement: Single header

The library can be used by adding a single header to a C++ project.

  • An amalgamation script is used to check if the source code is exposed as a self-contained single-header file.
  • The test suite is checked against the amalgamated source file as well as the individual source file.

Requirement: CMake as primary development tool

All library functions are exposed and usable by CMake.

  • All library options are exposed as CMake options and tested.
  • The library is tested against relevant CMake versions:
  • CMake 3.5 (the earliest supported)
  • CMake 3.31.6 (the latest 3.x release)
  • CMake 4.0.0 (a very recent release)
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/community/security_policy/index.html b/community/security_policy/index.html index 714803536..35f6e8c1e 100644 --- a/community/security_policy/index.html +++ b/community/security_policy/index.html @@ -1 +1 @@ - Security Policy - JSON for Modern C++
Skip to content

Security Policy

Reporting a Vulnerability

We value the security of our users and appreciate your efforts to responsibly disclose vulnerabilities. If you have identified a security vulnerability in this repository, please use the GitHub Security Advisory "Report a Vulnerability" tab.

Until it is published, this draft security advisory will only be visible to the maintainers of this project. Other users and teams may be added once the advisory is created.

We will send a response indicating the next steps in handling your report. After the initial reply to your report, we will keep you informed of the progress towards a fix and full announcement and may ask for additional information or guidance.

For vulnerabilities in third-party dependencies or modules, please report them directly to the respective maintainers.

Unofficial packages

This project does not publish an official npm package. The npm package nlohmann-json (or similarly named packages) is not maintained or endorsed by this project. See the package managers documentation for supported integration options.

Additional Resources

We sincerely thank you for contributing to the security and integrity of this project!

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Security Policy - JSON for Modern C++
Skip to content

Security Policy

Reporting a Vulnerability

We value the security of our users and appreciate your efforts to responsibly disclose vulnerabilities. If you have identified a security vulnerability in this repository, please use the GitHub Security Advisory "Report a Vulnerability" tab.

Until it is published, this draft security advisory will only be visible to the maintainers of this project. Other users and teams may be added once the advisory is created.

We will send a response indicating the next steps in handling your report. After the initial reply to your report, we will keep you informed of the progress towards a fix and full announcement and may ask for additional information or guidance.

For vulnerabilities in third-party dependencies or modules, please report them directly to the respective maintainers.

Unofficial packages

This project does not publish an official npm package. The npm package nlohmann-json (or similarly named packages) is not maintained or endorsed by this project. See the package managers documentation for supported integration options.

Additional Resources

We sincerely thank you for contributing to the security and integrity of this project!

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/arbitrary_types/index.html b/features/arbitrary_types/index.html index a374413e5..2fb963a9d 100644 --- a/features/arbitrary_types/index.html +++ b/features/arbitrary_types/index.html @@ -1,4 +1,4 @@ - Arbitrary Type Conversions - JSON for Modern C++
Skip to content

Arbitrary Type Conversions

Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:

namespace ns {
+ Arbitrary Type Conversions - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Arbitrary Type Conversions
 
Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:
 
namespace ns {
     // a simple struct to model a person
     struct person {
         std::string name;
@@ -204,4 +204,4 @@
       value = j.template get<T>(); // oops!
     }
 };
-
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/assertions/index.html b/features/assertions/index.html index 4d4eb37ff..cc87d995b 100644 --- a/features/assertions/index.html +++ b/features/assertions/index.html @@ -1,4 +1,4 @@ - Runtime Assertions - JSON for Modern C++
Skip to content

Runtime Assertions

The code contains numerous debug assertions to ensure class invariants are valid or to detect undefined behavior. Whereas the former class invariants are nothing to be concerned with, the latter checks for undefined behavior are to detect bugs in client code.

Switch off runtime assertions

Runtime assertions can be switched off by defining the preprocessor macro NDEBUG (see the documentation of assert) which is the default for release builds.

Change assertion behavior

The behavior of runtime assertions can be changed by defining macro JSON_ASSERT(x) before including the json.hpp header.

Function with runtime assertions

Unchecked object access to a const value

Function operator[] implements unchecked access for objects. Whereas a missing key is added in the case of non-const objects, accessing a const object with a missing key is undefined behavior (think of a dereferenced null pointer) and yields a runtime assertion.

If you are not sure whether an element in an object exists, use checked access with the at function or call the contains function before.

See also the documentation on element access.

Example 1: Missing object key

The following code will trigger an assertion at runtime:

#include <nlohmann/json.hpp>
+ Runtime Assertions - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Runtime Assertions
 
The code contains numerous debug assertions to ensure class invariants are valid or to detect undefined behavior. Whereas the former class invariants are nothing to be concerned with, the latter checks for undefined behavior are to detect bugs in client code.
 
Switch off runtime assertions
 
Runtime assertions can be switched off by defining the preprocessor macro NDEBUG (see the documentation of assert) which is the default for release builds.
 
Change assertion behavior
 
The behavior of runtime assertions can be changed by defining macro JSON_ASSERT(x) before including the json.hpp header.
 
Function with runtime assertions
 
Unchecked object access to a const value
 
Function operator[] implements unchecked access for objects. Whereas a missing key is added in the case of non-const objects, accessing a const object with a missing key is undefined behavior (think of a dereferenced null pointer) and yields a runtime assertion.
 
If you are not sure whether an element in an object exists, use checked access with the at function or call the contains function before.
 
See also the documentation on element access.
 
 Example 1: Missing object key 
The following code will trigger an assertion at runtime:
 
#include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
 
@@ -43,4 +43,4 @@
     }
 }
 
 
Output:
 
[json.exception.parse_error.101] parse error: attempting to parse an empty input; check that your input string or stream contains the expected JSON
-
 
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_formats/bjdata/index.html b/features/binary_formats/bjdata/index.html index 0dce90b63..34aff7d52 100644 --- a/features/binary_formats/bjdata/index.html +++ b/features/binary_formats/bjdata/index.html @@ -1,4 +1,4 @@ - BJData - JSON for Modern C++
Skip to content

BJData

The BJData format was derived from and improved upon Universal Binary JSON(UBJSON) specification (Draft 12). Specifically, it introduces an optimized array container for efficient storage of N-dimensional packed arrays (ND-arrays); it also adds 5 new type markers - [u] - uint16, [m] - uint32, [M] - uint64, [h] - float16 and [B] - byte - to unambiguously map common binary numeric types; furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid unnecessary conversions on commonly available platforms.

Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare combination of being both binary and quasi-human-readable. This is because all semantic elements in BJData and UBJSON, including the data-type markers and name/string types, are directly human-readable. Data stored in the BJData/UBJSON format is not only compact in size, fast to read/write, but also can be directly searched or read using simple processing.

References

Serialization

The library uses the following mapping from JSON values types to BJData types according to the BJData specification:

JSON value type value/range BJData type marker
null null null Z
boolean true true T
boolean false false F
number_integer -9223372036854775808..-2147483649 int64 L
number_integer -2147483648..-32769 int32 l
number_integer -32768..-129 int16 I
number_integer -128..127 int8 i
number_integer 128..255 uint8 U
number_integer 256..32767 int16 I
number_integer 32768..65535 uint16 u
number_integer 65536..2147483647 int32 l
number_integer 2147483648..4294967295 uint32 m
number_integer 4294967296..9223372036854775807 int64 L
number_integer 9223372036854775808..18446744073709551615 uint64 M
number_unsigned 0..127 int8 i
number_unsigned 128..255 uint8 U
number_unsigned 256..32767 int16 I
number_unsigned 32768..65535 uint16 u
number_unsigned 65536..2147483647 int32 l
number_unsigned 2147483648..4294967295 uint32 m
number_unsigned 4294967296..9223372036854775807 int64 L
number_unsigned 9223372036854775808..18446744073709551615 uint64 M
number_float any value float64 D
string with shortest length indicator string S
array see notes on optimized format/ND-array array [
object see notes on optimized format map {
binary see notes on binary values array [$B

Complete mapping

The mapping is complete in the sense that any JSON value type can be converted to a BJData value.

Any BJData output created by to_bjdata can be successfully parsed by from_bjdata.

Size constraints

The following values can not be converted to a BJData value:

  • strings with more than 18446744073709551615 bytes, i.e., 2^{64}-1 bytes (theoretical)

Unused BJData markers

The following markers are not used in the conversion:

  • Z: no-op values are not created.
  • C: single-byte strings are serialized with S markers.

NaN/infinity handling

If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the dump() function which serializes NaN or Infinity to null.

Endianness

A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data types (integers UiuImlML and floating-point values hdD) are stored in the little-endian (LE) byte order as opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on most modern computers where LE is used as the default byte order.

Optimized formats

Optimized formats for containers are supported via two parameters of to_bjdata:

  • Parameter use_size adds size information to the beginning of a container and removes the closing marker.
  • Parameter use_type further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The use_type parameter must only be used together with use_size = true.

Note that use_size = true alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed of the number of elements in the container.

ND-array optimized format

BJData extends UBJSON's optimized array size marker to support ND-arrays of uniform numerical data types (referred to as packed arrays). For example, the 2-D uint8 integer array [[1,2],[3,4],[5,6]], stored as nested optimized array in UBJSON [ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ], can be further compressed in BJData to [$U#[$i#i2 2 3 1 2 3 4 5 6 or [$U#[i2 i3] 1 2 3 4 5 6.

To maintain type and size information, ND-arrays are converted to JSON objects following the annotated array format (defined in the JData specification (Draft 3)), when parsed using from_bjdata. For example, the above 2-D uint8 array can be parsed and accessed as

{
+ BJData - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
BJData
 
The BJData format was derived from and improved upon Universal Binary JSON(UBJSON) specification (Draft 12). Specifically, it introduces an optimized array container for efficient storage of N-dimensional packed arrays (ND-arrays); it also adds 5 new type markers - [u] - uint16, [m] - uint32, [M] - uint64, [h] - float16 and [B] - byte - to unambiguously map common binary numeric types; furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid unnecessary conversions on commonly available platforms.
 
Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare combination of being both binary and quasi-human-readable. This is because all semantic elements in BJData and UBJSON, including the data-type markers and name/string types, are directly human-readable. Data stored in the BJData/UBJSON format is not only compact in size, fast to read/write, but also can be directly searched or read using simple processing.
 
 
References
  
 
Serialization
 
The library uses the following mapping from JSON values types to BJData types according to the BJData specification:
 
  
 JSON value type value/range BJData type marker 
   
 null null null Z 
 
 boolean true true T 
 
 boolean false false F 
 
 number_integer -9223372036854775808..-2147483649 int64 L 
 
 number_integer -2147483648..-32769 int32 l 
 
 number_integer -32768..-129 int16 I 
 
 number_integer -128..127 int8 i 
 
 number_integer 128..255 uint8 U 
 
 number_integer 256..32767 int16 I 
 
 number_integer 32768..65535 uint16 u 
 
 number_integer 65536..2147483647 int32 l 
 
 number_integer 2147483648..4294967295 uint32 m 
 
 number_integer 4294967296..9223372036854775807 int64 L 
 
 number_integer 9223372036854775808..18446744073709551615 uint64 M 
 
 number_unsigned 0..127 int8 i 
 
 number_unsigned 128..255 uint8 U 
 
 number_unsigned 256..32767 int16 I 
 
 number_unsigned 32768..65535 uint16 u 
 
 number_unsigned 65536..2147483647 int32 l 
 
 number_unsigned 2147483648..4294967295 uint32 m 
 
 number_unsigned 4294967296..9223372036854775807 int64 L 
 
 number_unsigned 9223372036854775808..18446744073709551615 uint64 M 
 
 number_float any value float64 D 
 
 string with shortest length indicator string S 
 
 array see notes on optimized format/ND-array array [ 
 
 object see notes on optimized format map { 
 
 binary see notes on binary values array [$B 
  
 
 
Complete mapping
 
The mapping is complete in the sense that any JSON value type can be converted to a BJData value.
 
Any BJData output created by to_bjdata can be successfully parsed by from_bjdata.
 
 
 
Size constraints
 
The following values can not be converted to a BJData value:
 
     
  • strings with more than 18446744073709551615 bytes, i.e., 2^{64}-1 bytes (theoretical)
    •  
 
 
 
Unused BJData markers
 
The following markers are not used in the conversion:
 
     
  • Z: no-op values are not created.
    •  
  • C: single-byte strings are serialized with S markers.
    •  
 
 
 
NaN/infinity handling
 
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the dump() function which serializes NaN or Infinity to null.
 
 
 
Endianness
 
A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data types (integers UiuImlML and floating-point values hdD) are stored in the little-endian (LE) byte order as opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on most modern computers where LE is used as the default byte order.
 
 
 
Optimized formats
 
Optimized formats for containers are supported via two parameters of to_bjdata:
 
     
  • Parameter use_size adds size information to the beginning of a container and removes the closing marker.
    •  
  • Parameter use_type further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The use_type parameter must only be used together with use_size = true.
    •  
 
Note that use_size = true alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed of the number of elements in the container.
 
 
 
ND-array optimized format
 
BJData extends UBJSON's optimized array size marker to support ND-arrays of uniform numerical data types (referred to as packed arrays). For example, the 2-D uint8 integer array [[1,2],[3,4],[5,6]], stored as nested optimized array in UBJSON [ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ], can be further compressed in BJData to [$U#[$i#i2 2 3 1 2 3 4 5 6 or [$U#[i2 i3] 1 2 3 4 5 6.
 
To maintain type and size information, ND-arrays are converted to JSON objects following the annotated array format (defined in the JData specification (Draft 3)), when parsed using from_bjdata. For example, the above 2-D uint8 array can be parsed and accessed as
 
{
     "_ArrayType_": "uint8",
     "_ArraySize_": [2,3],
     "_ArrayData_": [1,2,3,4,5,6]
@@ -95,4 +95,4 @@
   "compact": true,
   "schema": 0
 }
-
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_formats/bson/index.html b/features/binary_formats/bson/index.html index 4824e4cc9..4736cf5b5 100644 --- a/features/binary_formats/bson/index.html +++ b/features/binary_formats/bson/index.html @@ -1,4 +1,4 @@ - BSON - JSON for Modern C++
Skip to content

BSON

BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.

References

Serialization

The library uses the following mapping from JSON values types to BSON types:

JSON value type value/range BSON type marker
null null null 0x0A
boolean true, false boolean 0x08
number_integer -9223372036854775808..-2147483649 int64 0x12
number_integer -2147483648..2147483647 int32 0x10
number_integer 2147483648..9223372036854775807 int64 0x12
number_unsigned 0..2147483647 int32 0x10
number_unsigned 2147483648..9223372036854775807 int64 0x12
number_unsigned 9223372036854775808..18446744073709551615 uint64 0x11
number_float any value double 0x01
string any value string 0x02
array any value document 0x04
object any value document 0x03
binary any value binary 0x05

Incomplete mapping

The mapping is incomplete, since only JSON-objects (and things contained therein) can be serialized to BSON. Also, keys may not contain U+0000, since they are serialized a zero-terminated c-strings.

BSON type 0x11 interoperability

The BSON specification defines type 0x11 as a Timestamp. This library uses marker 0x11 when serializing number_unsigned values in the range 9223372036854775808..18446744073709551615. Other BSON implementations may therefore interpret these values as Timestamps instead of unsigned integers.

Binary values without a subtype

BSON requires every binary value to have a subtype. If a binary value has no subtype, this library serializes it with the generic subtype 0x00. After deserialization, has_subtype() returns true and subtype() returns 0. As a result, serializing and deserializing a JSON object containing such a value produces a different JSON object, even though the binary data is unchanged.

Example 
#include <iostream>
+ BSON - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
BSON
 
BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
 
 
References
  
 
Serialization
 
The library uses the following mapping from JSON values types to BSON types:
 
  
 JSON value type value/range BSON type marker 
   
 null null null 0x0A 
 
 boolean true, false boolean 0x08 
 
 number_integer -9223372036854775808..-2147483649 int64 0x12 
 
 number_integer -2147483648..2147483647 int32 0x10 
 
 number_integer 2147483648..9223372036854775807 int64 0x12 
 
 number_unsigned 0..2147483647 int32 0x10 
 
 number_unsigned 2147483648..9223372036854775807 int64 0x12 
 
 number_unsigned 9223372036854775808..18446744073709551615 uint64 0x11 
 
 number_float any value double 0x01 
 
 string any value string 0x02 
 
 array any value document 0x04 
 
 object any value document 0x03 
 
 binary any value binary 0x05 
  
 
 
Incomplete mapping
 
The mapping is incomplete, since only JSON-objects (and things contained therein) can be serialized to BSON. Also, keys may not contain U+0000, since they are serialized a zero-terminated c-strings.
 
 
 
BSON type 0x11 interoperability
 
The BSON specification defines type 0x11 as a Timestamp. This library uses marker 0x11 when serializing number_unsigned values in the range 9223372036854775808..18446744073709551615. Other BSON implementations may therefore interpret these values as Timestamps instead of unsigned integers.
 
 
 
Binary values without a subtype
 
BSON requires every binary value to have a subtype. If a binary value has no subtype, this library serializes it with the generic subtype 0x00. After deserialization, has_subtype() returns true and subtype() returns 0. As a result, serializing and deserializing a JSON object containing such a value produces a different JSON object, even though the binary data is unchanged.
 
 
 Example 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
 
@@ -46,4 +46,4 @@
   "compact": true,
   "schema": 0
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_formats/cbor/index.html b/features/binary_formats/cbor/index.html index e3fa72353..92b84c923 100644 --- a/features/binary_formats/cbor/index.html +++ b/features/binary_formats/cbor/index.html @@ -1,4 +1,4 @@ - CBOR - JSON for Modern C++
Skip to content

CBOR

The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code sizes, fairly small message size, and extensibility without the need for version negotiation.

References

Serialization

The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 8949):

JSON value type value/range CBOR type first byte
null null Null 0xF6
boolean true True 0xF5
boolean false False 0xF4
number_integer -9223372036854775808..-2147483649 Negative integer (8 bytes follow) 0x3B
number_integer -2147483648..-32769 Negative integer (4 bytes follow) 0x3A
number_integer -32768..-129 Negative integer (2 bytes follow) 0x39
number_integer -128..-25 Negative integer (1 byte follow) 0x38
number_integer -24..-1 Negative integer 0x20..0x37
number_integer 0..23 Integer 0x00..0x17
number_integer 24..255 Unsigned integer (1 byte follow) 0x18
number_integer 256..65535 Unsigned integer (2 bytes follow) 0x19
number_integer 65536..4294967295 Unsigned integer (4 bytes follow) 0x1A
number_integer 4294967296..18446744073709551615 Unsigned integer (8 bytes follow) 0x1B
number_unsigned 0..23 Integer 0x00..0x17
number_unsigned 24..255 Unsigned integer (1 byte follow) 0x18
number_unsigned 256..65535 Unsigned integer (2 bytes follow) 0x19
number_unsigned 65536..4294967295 Unsigned integer (4 bytes follow) 0x1A
number_unsigned 4294967296..18446744073709551615 Unsigned integer (8 bytes follow) 0x1B
number_float any value representable by a float Single-Precision Float 0xFA
number_float any value NOT representable by a float Double-Precision Float 0xFB
string length: 0..23 UTF-8 string 0x60..0x77
string length: 24..255 UTF-8 string (1 byte follow) 0x78
string length: 256..65535 UTF-8 string (2 bytes follow) 0x79
string length: 65536..4294967295 UTF-8 string (4 bytes follow) 0x7A
string length: 4294967296..18446744073709551615 UTF-8 string (8 bytes follow) 0x7B
array size: 0..23 array 0x80..0x97
array size: 24..255 array (1 byte follow) 0x98
array size: 256..65535 array (2 bytes follow) 0x99
array size: 65536..4294967295 array (4 bytes follow) 0x9A
array size: 4294967296..18446744073709551615 array (8 bytes follow) 0x9B
object size: 0..23 map 0xA0..0xB7
object size: 24..255 map (1 byte follow) 0xB8
object size: 256..65535 map (2 bytes follow) 0xB9
object size: 65536..4294967295 map (4 bytes follow) 0xBA
object size: 4294967296..18446744073709551615 map (8 bytes follow) 0xBB
binary size: 0..23 byte string 0x40..0x57
binary size: 24..255 byte string (1 byte follow) 0x58
binary size: 256..65535 byte string (2 bytes follow) 0x59
binary size: 65536..4294967295 byte string (4 bytes follow) 0x5A
binary size: 4294967296..18446744073709551615 byte string (8 bytes follow) 0x5B

Binary values with subtype are mapped to tagged values (0xD8..0xDB) depending on the subtype, followed by a byte string, see "binary" cells in the table above.

Complete mapping

The mapping is complete in the sense that any JSON value type can be converted to a CBOR value.

NaN/infinity handling

NaN, Infinity, and -Infinity are serialized as a CBOR half-precision float (type 0xF9, 3 bytes total): NaN as 0xF9 0x7E 0x00, Infinity as 0xF9 0x7C 0x00, and -Infinity as 0xF9 0xFC 0x00. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to null.

Note

Prior to version 3.13.0, NaN and Infinity were instead serialized as a CBOR double-precision float (type 0xFB, 9 bytes total), because the check used to select a smaller encoding compared magnitudes with NaN, which is always false and caused the intended half-precision path to be skipped.

Unused CBOR types

The following CBOR types are not used in the conversion:

  • UTF-8 strings terminated by "break" (0x7F)
  • arrays terminated by "break" (0x9F)
  • maps terminated by "break" (0xBF)
  • byte strings terminated by "break" (0x5F)
  • date/time (0xC0..0xC1)
  • bignum (0xC2..0xC3)
  • decimal fraction (0xC4)
  • bigfloat (0xC5)
  • expected conversions (0xD5..0xD7)
  • simple values (0xE0..0xF3, 0xF8)
  • undefined (0xF7)
  • half-precision floats (0xF9)
  • break (0xFF)

Tagged items

Binary subtypes will be serialized as tagged items. See binary values for an example.

Example 
#include <iostream>
+ CBOR - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
CBOR
 
The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code sizes, fairly small message size, and extensibility without the need for version negotiation.
 
 
References
  
 
Serialization
 
The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 8949):
 
  
 JSON value type value/range CBOR type first byte 
   
 null null Null 0xF6 
 
 boolean true True 0xF5 
 
 boolean false False 0xF4 
 
 number_integer -9223372036854775808..-2147483649 Negative integer (8 bytes follow) 0x3B 
 
 number_integer -2147483648..-32769 Negative integer (4 bytes follow) 0x3A 
 
 number_integer -32768..-129 Negative integer (2 bytes follow) 0x39 
 
 number_integer -128..-25 Negative integer (1 byte follow) 0x38 
 
 number_integer -24..-1 Negative integer 0x20..0x37 
 
 number_integer 0..23 Integer 0x00..0x17 
 
 number_integer 24..255 Unsigned integer (1 byte follow) 0x18 
 
 number_integer 256..65535 Unsigned integer (2 bytes follow) 0x19 
 
 number_integer 65536..4294967295 Unsigned integer (4 bytes follow) 0x1A 
 
 number_integer 4294967296..18446744073709551615 Unsigned integer (8 bytes follow) 0x1B 
 
 number_unsigned 0..23 Integer 0x00..0x17 
 
 number_unsigned 24..255 Unsigned integer (1 byte follow) 0x18 
 
 number_unsigned 256..65535 Unsigned integer (2 bytes follow) 0x19 
 
 number_unsigned 65536..4294967295 Unsigned integer (4 bytes follow) 0x1A 
 
 number_unsigned 4294967296..18446744073709551615 Unsigned integer (8 bytes follow) 0x1B 
 
 number_float any value representable by a float Single-Precision Float 0xFA 
 
 number_float any value NOT representable by a float Double-Precision Float 0xFB 
 
 string length: 0..23 UTF-8 string 0x60..0x77 
 
 string length: 24..255 UTF-8 string (1 byte follow) 0x78 
 
 string length: 256..65535 UTF-8 string (2 bytes follow) 0x79 
 
 string length: 65536..4294967295 UTF-8 string (4 bytes follow) 0x7A 
 
 string length: 4294967296..18446744073709551615 UTF-8 string (8 bytes follow) 0x7B 
 
 array size: 0..23 array 0x80..0x97 
 
 array size: 24..255 array (1 byte follow) 0x98 
 
 array size: 256..65535 array (2 bytes follow) 0x99 
 
 array size: 65536..4294967295 array (4 bytes follow) 0x9A 
 
 array size: 4294967296..18446744073709551615 array (8 bytes follow) 0x9B 
 
 object size: 0..23 map 0xA0..0xB7 
 
 object size: 24..255 map (1 byte follow) 0xB8 
 
 object size: 256..65535 map (2 bytes follow) 0xB9 
 
 object size: 65536..4294967295 map (4 bytes follow) 0xBA 
 
 object size: 4294967296..18446744073709551615 map (8 bytes follow) 0xBB 
 
 binary size: 0..23 byte string 0x40..0x57 
 
 binary size: 24..255 byte string (1 byte follow) 0x58 
 
 binary size: 256..65535 byte string (2 bytes follow) 0x59 
 
 binary size: 65536..4294967295 byte string (4 bytes follow) 0x5A 
 
 binary size: 4294967296..18446744073709551615 byte string (8 bytes follow) 0x5B 
  
 
Binary values with subtype are mapped to tagged values (0xD8..0xDB) depending on the subtype, followed by a byte string, see "binary" cells in the table above.
 
 
Complete mapping
 
The mapping is complete in the sense that any JSON value type can be converted to a CBOR value.
 
 
 
NaN/infinity handling
 
NaN, Infinity, and -Infinity are serialized as a CBOR half-precision float (type 0xF9, 3 bytes total): NaN as 0xF9 0x7E 0x00, Infinity as 0xF9 0x7C 0x00, and -Infinity as 0xF9 0xFC 0x00. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to null.
 
 
 
Note
 
Prior to version 3.13.0, NaN and Infinity were instead serialized as a CBOR double-precision float (type 0xFB, 9 bytes total), because the check used to select a smaller encoding compared magnitudes with NaN, which is always false and caused the intended half-precision path to be skipped.
 
 
 
Unused CBOR types
 
The following CBOR types are not used in the conversion:
 
     
  • UTF-8 strings terminated by "break" (0x7F)
    •  
  • arrays terminated by "break" (0x9F)
    •  
  • maps terminated by "break" (0xBF)
    •  
  • byte strings terminated by "break" (0x5F)
    •  
  • date/time (0xC0..0xC1)
    •  
  • bignum (0xC2..0xC3)
    •  
  • decimal fraction (0xC4)
    •  
  • bigfloat (0xC5)
    •  
  • expected conversions (0xD5..0xD7)
    •  
  • simple values (0xE0..0xF3, 0xF8)
    •  
  • undefined (0xF7)
    •  
  • half-precision floats (0xF9)
    •  
  • break (0xFF)
    •  
 
 
 
Tagged items
 
Binary subtypes will be serialized as tagged items. See binary values for an example.
 
 
 Example 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
 
@@ -45,4 +45,4 @@
   "compact": true,
   "schema": 0
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_formats/index.html b/features/binary_formats/index.html index efaf7f2ce..eb8957b83 100644 --- a/features/binary_formats/index.html +++ b/features/binary_formats/index.html @@ -1 +1 @@ - Binary Formats - JSON for Modern C++
Skip to content

Binary Formats

Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance, over a network. Hence, the library supports

to efficiently encode JSON values to byte vectors and to decode such vectors.

Comparison

Completeness

Format Serialization Deserialization
BJData complete complete
BSON incomplete: top-level value must be an object incomplete, but all JSON types are supported
CBOR complete incomplete, but all JSON types are supported
MessagePack complete complete
UBJSON complete complete

Binary values

Format Binary values Binary subtypes
BJData not supported not supported
BSON supported supported
CBOR supported supported
MessagePack supported supported
UBJSON not supported not supported

See binary values for more information.

Sizes

Format canada.json twitter.json citm_catalog.json jeopardy.json
BJData 53.2 % 91.1 % 78.1 % 96.6 %
BJData (size) 58.6 % 92.1 % 86.7 % 97.4 %
BJData (size+type) 58.6 % 92.1 % 86.5 % 97.4 %
BSON 85.8 % 95.2 % 95.8 % 106.7 %
CBOR 50.5 % 86.3 % 68.4 % 88.0 %
MessagePack 50.5 % 86.0 % 68.5 % 87.9 %
UBJSON 53.2 % 91.3 % 78.2 % 96.6 %
UBJSON (size) 58.6 % 92.3 % 86.8 % 97.4 %
UBJSON (size+type) 55.9 % 92.3 % 85.0 % 95.0 %

Sizes compared to minified JSON value.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Binary Formats - JSON for Modern C++
Skip to content

Binary Formats

Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance, over a network. Hence, the library supports

to efficiently encode JSON values to byte vectors and to decode such vectors.

Comparison

Completeness

Format Serialization Deserialization
BJData complete complete
BSON incomplete: top-level value must be an object incomplete, but all JSON types are supported
CBOR complete incomplete, but all JSON types are supported
MessagePack complete complete
UBJSON complete complete

Binary values

Format Binary values Binary subtypes
BJData not supported not supported
BSON supported supported
CBOR supported supported
MessagePack supported supported
UBJSON not supported not supported

See binary values for more information.

Sizes

Format canada.json twitter.json citm_catalog.json jeopardy.json
BJData 53.2 % 91.1 % 78.1 % 96.6 %
BJData (size) 58.6 % 92.1 % 86.7 % 97.4 %
BJData (size+type) 58.6 % 92.1 % 86.5 % 97.4 %
BSON 85.8 % 95.2 % 95.8 % 106.7 %
CBOR 50.5 % 86.3 % 68.4 % 88.0 %
MessagePack 50.5 % 86.0 % 68.5 % 87.9 %
UBJSON 53.2 % 91.3 % 78.2 % 96.6 %
UBJSON (size) 58.6 % 92.3 % 86.8 % 97.4 %
UBJSON (size+type) 55.9 % 92.3 % 85.0 % 95.0 %

Sizes compared to minified JSON value.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_formats/messagepack/index.html b/features/binary_formats/messagepack/index.html index 126240a23..907f07c85 100644 --- a/features/binary_formats/messagepack/index.html +++ b/features/binary_formats/messagepack/index.html @@ -1,4 +1,4 @@ - MessagePack - JSON for Modern C++
Skip to content

MessagePack

MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves.

References

Serialization

The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:

JSON value type value/range MessagePack type first byte
null null nil 0xC0
boolean true true 0xC3
boolean false false 0xC2
number_integer -9223372036854775808..-2147483649 int64 0xD3
number_integer -2147483648..-32769 int32 0xD2
number_integer -32768..-129 int16 0xD1
number_integer -128..-33 int8 0xD0
number_integer -32..-1 negative fixint 0xE0..0xFF
number_integer 0..127 positive fixint 0x00..0x7F
number_integer 128..255 uint 8 0xCC
number_integer 256..65535 uint 16 0xCD
number_integer 65536..4294967295 uint 32 0xCE
number_integer 4294967296..18446744073709551615 uint 64 0xCF
number_unsigned 0..127 positive fixint 0x00..0x7F
number_unsigned 128..255 uint 8 0xCC
number_unsigned 256..65535 uint 16 0xCD
number_unsigned 65536..4294967295 uint 32 0xCE
number_unsigned 4294967296..18446744073709551615 uint 64 0xCF
number_float any value representable by a float float 32 0xCA
number_float any value NOT representable by a float float 64 0xCB
string length: 0..31 fixstr 0xA0..0xBF
string length: 32..255 str 8 0xD9
string length: 256..65535 str 16 0xDA
string length: 65536..4294967295 str 32 0xDB
array size: 0..15 fixarray 0x90..0x9F
array size: 16..65535 array 16 0xDC
array size: 65536..4294967295 array 32 0xDD
object size: 0..15 fix map 0x80..0x8F
object size: 16..65535 map 16 0xDE
object size: 65536..4294967295 map 32 0xDF
binary size: 0..255 bin 8 0xC4
binary size: 256..65535 bin 16 0xC5
binary size: 65536..4294967295 bin 32 0xC6

Complete mapping

The mapping is complete in the sense that any JSON value type can be converted to a MessagePack value.

Any MessagePack output created by to_msgpack can be successfully parsed by from_msgpack.

Size constraints

The following values can not be converted to a MessagePack value:

  • strings with more than 4294967295 bytes
  • byte strings with more than 4294967295 bytes
  • arrays with more than 4294967295 elements
  • objects with more than 4294967295 elements

NaN/infinity handling

NaN, Infinity, and -Infinity are serialized as a MessagePack float 32 (type 0xCA, 5 bytes total), regardless of magnitude, in contrast to the dump function which serializes NaN or Infinity to null.

Note

Prior to version 3.13.0, NaN and Infinity were instead serialized as a MessagePack float 64 (type 0xCB, 9 bytes total), because the check used to select the smaller float 32 encoding compared magnitudes with NaN, which is always false and caused the float 32 path to be skipped.

Example 
#include <iostream>
+ MessagePack - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
MessagePack
 
MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves.
 
 
References
  
 
Serialization
 
The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:
 
  
 JSON value type value/range MessagePack type first byte 
   
 null null nil 0xC0 
 
 boolean true true 0xC3 
 
 boolean false false 0xC2 
 
 number_integer -9223372036854775808..-2147483649 int64 0xD3 
 
 number_integer -2147483648..-32769 int32 0xD2 
 
 number_integer -32768..-129 int16 0xD1 
 
 number_integer -128..-33 int8 0xD0 
 
 number_integer -32..-1 negative fixint 0xE0..0xFF 
 
 number_integer 0..127 positive fixint 0x00..0x7F 
 
 number_integer 128..255 uint 8 0xCC 
 
 number_integer 256..65535 uint 16 0xCD 
 
 number_integer 65536..4294967295 uint 32 0xCE 
 
 number_integer 4294967296..18446744073709551615 uint 64 0xCF 
 
 number_unsigned 0..127 positive fixint 0x00..0x7F 
 
 number_unsigned 128..255 uint 8 0xCC 
 
 number_unsigned 256..65535 uint 16 0xCD 
 
 number_unsigned 65536..4294967295 uint 32 0xCE 
 
 number_unsigned 4294967296..18446744073709551615 uint 64 0xCF 
 
 number_float any value representable by a float float 32 0xCA 
 
 number_float any value NOT representable by a float float 64 0xCB 
 
 string length: 0..31 fixstr 0xA0..0xBF 
 
 string length: 32..255 str 8 0xD9 
 
 string length: 256..65535 str 16 0xDA 
 
 string length: 65536..4294967295 str 32 0xDB 
 
 array size: 0..15 fixarray 0x90..0x9F 
 
 array size: 16..65535 array 16 0xDC 
 
 array size: 65536..4294967295 array 32 0xDD 
 
 object size: 0..15 fix map 0x80..0x8F 
 
 object size: 16..65535 map 16 0xDE 
 
 object size: 65536..4294967295 map 32 0xDF 
 
 binary size: 0..255 bin 8 0xC4 
 
 binary size: 256..65535 bin 16 0xC5 
 
 binary size: 65536..4294967295 bin 32 0xC6 
  
 
 
Complete mapping
 
The mapping is complete in the sense that any JSON value type can be converted to a MessagePack value.
 
Any MessagePack output created by to_msgpack can be successfully parsed by from_msgpack.
 
 
 
Size constraints
 
The following values can not be converted to a MessagePack value:
 
     
  • strings with more than 4294967295 bytes
    •  
  • byte strings with more than 4294967295 bytes
    •  
  • arrays with more than 4294967295 elements
    •  
  • objects with more than 4294967295 elements
    •  
 
 
 
NaN/infinity handling
 
NaN, Infinity, and -Infinity are serialized as a MessagePack float 32 (type 0xCA, 5 bytes total), regardless of magnitude, in contrast to the dump function which serializes NaN or Infinity to null.
 
 
 
Note
 
Prior to version 3.13.0, NaN and Infinity were instead serialized as a MessagePack float 64 (type 0xCB, 9 bytes total), because the check used to select the smaller float 32 encoding compared magnitudes with NaN, which is always false and caused the float 32 path to be skipped.
 
 
 Example 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
 
@@ -45,4 +45,4 @@
   "compact": true,
   "schema": 0
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_formats/ubjson/index.html b/features/binary_formats/ubjson/index.html index f03698421..17ef8d44d 100644 --- a/features/binary_formats/ubjson/index.html +++ b/features/binary_formats/ubjson/index.html @@ -1,4 +1,4 @@ - UBJSON - JSON for Modern C++
Skip to content

UBJSON

Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON.

References

Serialization

The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:

JSON value type value/range UBJSON type marker
null null null Z
boolean true true T
boolean false false F
number_integer -9223372036854775808..-2147483649 int64 L
number_integer -2147483648..-32769 int32 l
number_integer -32768..-129 int16 I
number_integer -128..127 int8 i
number_integer 128..255 uint8 U
number_integer 256..32767 int16 I
number_integer 32768..2147483647 int32 l
number_integer 2147483648..9223372036854775807 int64 L
number_unsigned 0..127 int8 i
number_unsigned 128..255 uint8 U
number_unsigned 256..32767 int16 I
number_unsigned 32768..2147483647 int32 l
number_unsigned 2147483648..9223372036854775807 int64 L
number_unsigned 2147483649..18446744073709551615 high-precision H
number_float any value float64 D
string with shortest length indicator string S
array see notes on optimized format array [
object see notes on optimized format map {

Complete mapping

The mapping is complete in the sense that any JSON value type can be converted to a UBJSON value.

Any UBJSON output created by to_ubjson can be successfully parsed by from_ubjson.

Size constraints

The following values can not be converted to a UBJSON value:

  • strings with more than 9223372036854775807 bytes (theoretical)

Unused UBJSON markers

The following markers are not used in the conversion:

  • Z: no-op values are not created.
  • C: single-byte strings are serialized with S markers.

NaN/infinity handling

If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the dump() function which serializes NaN or Infinity to null.

Optimized formats

The optimized formats for containers are supported: Parameter use_size adds size information to the beginning of a container and removes the closing marker. Parameter use_type further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The use_type parameter must only be used together with use_size = true.

Note that use_size = true alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed on the number of elements of the container.

Binary values

If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON documentation. In particular, this means that serialization and the deserialization of a JSON containing binary values into UBJSON and back will result in a different JSON object.

Example 
#include <iostream>
+ UBJSON - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
UBJSON
 
Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON.
 
 
References
  
 
Serialization
 
The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:
 
  
 JSON value type value/range UBJSON type marker 
   
 null null null Z 
 
 boolean true true T 
 
 boolean false false F 
 
 number_integer -9223372036854775808..-2147483649 int64 L 
 
 number_integer -2147483648..-32769 int32 l 
 
 number_integer -32768..-129 int16 I 
 
 number_integer -128..127 int8 i 
 
 number_integer 128..255 uint8 U 
 
 number_integer 256..32767 int16 I 
 
 number_integer 32768..2147483647 int32 l 
 
 number_integer 2147483648..9223372036854775807 int64 L 
 
 number_unsigned 0..127 int8 i 
 
 number_unsigned 128..255 uint8 U 
 
 number_unsigned 256..32767 int16 I 
 
 number_unsigned 32768..2147483647 int32 l 
 
 number_unsigned 2147483648..9223372036854775807 int64 L 
 
 number_unsigned 2147483649..18446744073709551615 high-precision H 
 
 number_float any value float64 D 
 
 string with shortest length indicator string S 
 
 array see notes on optimized format array [ 
 
 object see notes on optimized format map { 
  
 
 
Complete mapping
 
The mapping is complete in the sense that any JSON value type can be converted to a UBJSON value.
 
Any UBJSON output created by to_ubjson can be successfully parsed by from_ubjson.
 
 
 
Size constraints
 
The following values can not be converted to a UBJSON value:
 
     
  • strings with more than 9223372036854775807 bytes (theoretical)
    •  
 
 
 
Unused UBJSON markers
 
The following markers are not used in the conversion:
 
     
  • Z: no-op values are not created.
    •  
  • C: single-byte strings are serialized with S markers.
    •  
 
 
 
NaN/infinity handling
 
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the dump() function which serializes NaN or Infinity to null.
 
 
 
Optimized formats
 
The optimized formats for containers are supported: Parameter use_size adds size information to the beginning of a container and removes the closing marker. Parameter use_type further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The use_type parameter must only be used together with use_size = true.
 
Note that use_size = true alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed on the number of elements of the container.
 
 
 
Binary values
 
If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON documentation. In particular, this means that serialization and the deserialization of a JSON containing binary values into UBJSON and back will result in a different JSON object.
 
 
 Example 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
 
@@ -90,4 +90,4 @@
   "compact": true,
   "schema": 0
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/binary_values/index.html b/features/binary_values/index.html index 2ea4f707b..ee8506818 100644 --- a/features/binary_values/index.html +++ b/features/binary_values/index.html @@ -1,4 +1,4 @@ - Binary Values - JSON for Modern C++
Skip to content

Binary Values

The library implements several binary formats that encode JSON in an efficient way. Most of these formats support binary values; that is, values that have semantics defined outside the library and only define a sequence of bytes to be stored.

JSON itself does not have a binary value. As such, binary values are an extension that this library implements to store values received by a binary format. Binary values are never created by the JSON parser and are only part of a serialized JSON text if they have been created manually or via a binary format.

API for binary values

classDiagram
+ Binary Values - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Binary Values
 
The library implements several binary formats that encode JSON in an efficient way. Most of these formats support binary values; that is, values that have semantics defined outside the library and only define a sequence of bytes to be stored.
 
JSON itself does not have a binary value. As such, binary values are an extension that this library implements to store values received by a binary format. Binary values are never created by the JSON parser and are only part of a serialized JSON text if they have been created manually or via a binary format.
 
API for binary values
 
classDiagram
 
 class binary_t ["json::binary_t"] {
     +void set_subtype(std::uint64_t subtype)
@@ -154,4 +154,4 @@ vector <|-- binary_t
 
By default, binary values are stored as

Note that subtype (42) is not serialized and that UBJSON has no binary type, and deserializing v would yield the following value:

{
   "binary": [202, 254, 186, 190]
 }
-
\ No newline at end of file +
\ No newline at end of file diff --git a/features/comments/index.html b/features/comments/index.html index 6e7953f20..65d3706fd 100644 --- a/features/comments/index.html +++ b/features/comments/index.html @@ -1,4 +1,4 @@ - Comments - JSON for Modern C++
Skip to content

Comments

This library does not support comments by default. It does so for three reasons:

  1. Comments are not part of the JSON specification. You may argue that // or /* */ are allowed in JavaScript, but JSON is not JavaScript.

  2. This was not an oversight: Douglas Crockford wrote on this in May 2012:

    I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.

    Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.

  3. It is dangerous for interoperability if some libraries add comment support while others do not. Please check The Harmful Consequences of the Robustness Principle on this.

However, you can set parameter ignore_comments to true in the parse function to ignore // or /* */ comments. Comments will then be treated as whitespace. Combined with ignore_trailing_commas (also a parse parameter), this covers what is commonly referred to as JSONC (JSON with Comments, as used e.g. by Visual Studio Code's .jsonc files) -- comments and trailing commas, nothing more. This is a different, smaller extension than JSON5, which additionally allows unquoted keys, single-quoted strings, and other syntax changes that this library does not support.

For more information, see JSON With Commas and Comments (JWCC).

Example

Consider the following JSON with comments.

{
+ Comments - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Comments
 
This library does not support comments by default. It does so for three reasons:
 
     
  1. Comments are not part of the JSON specification. You may argue that // or /* */ are allowed in JavaScript, but JSON is not JavaScript.
    2.  
  2.  
    This was not an oversight: Douglas Crockford wrote on this in May 2012:
     
     
    I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't. 
     
    Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
     
     
    3.  
  3.  
    It is dangerous for interoperability if some libraries add comment support while others do not. Please check The Harmful Consequences of the Robustness Principle on this.
     
    4.  
 
However, you can set parameter ignore_comments to true in the parse function to ignore // or /* */ comments. Comments will then be treated as whitespace. Combined with ignore_trailing_commas (also a parse parameter), this covers what is commonly referred to as JSONC (JSON with Comments, as used e.g. by Visual Studio Code's .jsonc files) -- comments and trailing commas, nothing more. This is a different, smaller extension than JSON5, which additionally allows unquoted keys, single-quoted strings, and other syntax changes that this library does not support.
 
For more information, see JSON With Commas and Comments (JWCC).
 
 
Example
 
Consider the following JSON with comments.
 
{
     // update in 2006: removed Pluto
     "planets": ["Mercury", "Venus", "Earth", "Mars",
                 "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
@@ -45,4 +45,4 @@
     "Neptune"
   ]
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/conversions/index.html b/features/conversions/index.html index c179884a3..ba128be81 100644 --- a/features/conversions/index.html +++ b/features/conversions/index.html @@ -1,4 +1,4 @@ - Converting values - JSON for Modern C++
Skip to content

Converting values

A basic_json value stores JSON data, but most of the time you want to move that data into ordinary C++ types (an int, a std::string, a std::vector, or one of your own structs) and back. This page describes how these conversions work.

Getting values out

The get function template returns a copy of the stored value converted to the requested type:

json j = R"({"name": "Mary", "age": 42, "hobbies": ["hiking", "reading"]})"_json;
+ Converting values - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Converting values
 
A basic_json value stores JSON data, but most of the time you want to move that data into ordinary C++ types (an int, a std::string, a std::vector, or one of your own structs) and back. This page describes how these conversions work.
 
Getting values out
 
The get function template returns a copy of the stored value converted to the requested type:
 
json j = R"({"name": "Mary", "age": 42, "hobbies": ["hiking", "reading"]})"_json;
 
 auto name = j["name"].get<std::string>();               // "Mary"
 auto age  = j["age"].get<int>();                        // 42
@@ -109,4 +109,4 @@
 
 
 
Constructing from a C++20 range view
 
A json array can also be constructed directly from a C++20 range view (std::ranges::view), such as the result of std::views::filter or std::views::transform -- no intermediate container is needed:
 
std::vector<int> nums{1, 2, 37, 42, 21};
 auto filtered = nums | std::views::filter([](int i) { return i > 10; });
 json j(filtered);   // [37,42,21]
-
 
This requires JSON_HAS_RANGES to be enabled and is unavailable on MinGW due to incomplete C++20 ranges support there.
 
 
Your own types
 
The conversions above are built in for standard types. To make the same syntax work for your own types, provide to_json/from_json functions (or use one of the convenience macros). This is described in detail on the arbitrary types conversions page. Enums can be mapped to strings as described in specializing enum conversion.
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

This requires JSON_HAS_RANGES to be enabled and is unavailable on MinGW due to incomplete C++20 ranges support there.

Your own types

The conversions above are built in for standard types. To make the same syntax work for your own types, provide to_json/from_json functions (or use one of the convenience macros). This is described in detail on the arbitrary types conversions page. Enums can be mapped to strings as described in specializing enum conversion.

See also

\ No newline at end of file diff --git a/features/creating_values/index.html b/features/creating_values/index.html index 3bfaf98c8..d5ae5acf1 100644 --- a/features/creating_values/index.html +++ b/features/creating_values/index.html @@ -1,4 +1,4 @@ - Creating JSON values - JSON for Modern C++
Skip to content

Creating JSON values

There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text instead, see parsing.

From C++ values

Any value of a supported C++ type can be assigned to or used to construct a json:

json j_number  = 42;
+ Creating JSON values - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Creating JSON values
 
There are several ways to create a JSON value in memory. This page gives an overview; to read a value from JSON text instead, see parsing.
 
From C++ values
 
Any value of a supported C++ type can be assigned to or used to construct a json:
 
json j_number  = 42;
 json j_float   = 3.141;
 json j_string  = "Hello";
 json j_boolean = true;
@@ -42,4 +42,4 @@
   "answer": 42,
   "hello": "world"
 }
-
  
Note this parses the string, so "42"_json is the number 42, whereas json("42") is the JSON string "42".
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Note this parses the string, so "42"_json is the number 42, whereas json("42") is the JSON string "42".

See also

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/element_access/checked_access/index.html b/features/element_access/checked_access/index.html index 66f1a5e30..403f15b18 100644 --- a/features/element_access/checked_access/index.html +++ b/features/element_access/checked_access/index.html @@ -1,4 +1,4 @@ - Checked access: at - JSON for Modern C++
Skip to content

Checked access: at

Overview

The at member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a basic_json::out_of_range exception otherwise.

Read access

Consider the following JSON value:

{
+ Checked access: at - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Checked access: at
 
Overview
 
The at member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a basic_json::out_of_range exception otherwise.
 
 Read access 
Consider the following JSON value:
 
{
     "name": "Mary Smith",
     "age": 42,
     "hobbies": ["hiking", "reading"]
@@ -12,4 +12,4 @@
 
 
 
When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.
 
 Accessing via invalid index or missing key 
j.at("hobbies").at(3) = "cooking";
 
 
This code produces the following exception:
 
[json.exception.out_of_range.401] array index 3 is out of range
 
 
When extended diagnostic messages are enabled by defining JSON_DIAGNOSTICS, the exception further gives information where the key or index is missing or out of range.
 
[json.exception.out_of_range.401] (/hobbies) array index 3 is out of range
-
 
 
Notes
 
 
Exceptions
 
     
  • at can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a basic_json::type_error is thrown.
    •  
  • basic_json::out_of_range exception exceptions are thrown if the provided key is not found in an object or the provided index is invalid.
    •  
 
 
Summary
 
  
 scenario non-const value const value 
   
 access to existing object key reference to existing value is returned const reference to existing value is returned 
 
 access to valid array index reference to existing value is returned const reference to existing value is returned 
 
 access to non-existing object key basic_json::out_of_range exception is thrown basic_json::out_of_range exception is thrown 
 
 access to invalid array index basic_json::out_of_range exception is thrown basic_json::out_of_range exception is thrown 
  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Notes

Exceptions

  • at can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a basic_json::type_error is thrown.
  • basic_json::out_of_range exception exceptions are thrown if the provided key is not found in an object or the provided index is invalid.

Summary

scenario non-const value const value
access to existing object key reference to existing value is returned const reference to existing value is returned
access to valid array index reference to existing value is returned const reference to existing value is returned
access to non-existing object key basic_json::out_of_range exception is thrown basic_json::out_of_range exception is thrown
access to invalid array index basic_json::out_of_range exception is thrown basic_json::out_of_range exception is thrown
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/element_access/default_value/index.html b/features/element_access/default_value/index.html index 1a60cd0ae..40fe347b0 100644 --- a/features/element_access/default_value/index.html +++ b/features/element_access/default_value/index.html @@ -1,4 +1,4 @@ - Access with default value: value - JSON for Modern C++
Skip to content

Access with default value: value

Overview

In many situations, such as configuration files, missing values are not exceptional, but may be treated as if a default value was present. For this case, use value(key, default_value) which takes the key you want to access and a default value in case there is no value stored with that key. This is equivalent to Python's dict.get(key, default).

Example

Example

Consider the following JSON value:

{
+ Access with default value: value - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Access with default value: value
 
Overview
 
In many situations, such as configuration files, missing values are not exceptional, but may be treated as if a default value was present. For this case, use value(key, default_value) which takes the key you want to access and a default value in case there is no value stored with that key. This is equivalent to Python's dict.get(key, default).
 
Example
 
 Example 
Consider the following JSON value:
 
{
     "logOutput": "result.log",
     "append": true
 }
@@ -20,4 +20,4 @@
 default value (int):       -1
 default value (uint64_t):  18446744073709551615
 explicit return value type: 18446744073709551615
-
 
 
See also
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

See also

\ No newline at end of file diff --git a/features/element_access/index.html b/features/element_access/index.html index 8d45b2425..9eca466cb 100644 --- a/features/element_access/index.html +++ b/features/element_access/index.html @@ -1 +1 @@ - Element Access - JSON for Modern C++
Skip to content

Element Access

There are many ways elements in a JSON value can be accessed:

  • unchecked access via operator[]
  • checked access via at
  • access with default value via value
  • iterators
  • JSON pointers
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Element Access - JSON for Modern C++
Skip to content

Element Access

There are many ways elements in a JSON value can be accessed:

  • unchecked access via operator[]
  • checked access via at
  • access with default value via value
  • iterators
  • JSON pointers
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/element_access/unchecked_access/index.html b/features/element_access/unchecked_access/index.html index b44498ed3..8ae84d78d 100644 --- a/features/element_access/unchecked_access/index.html +++ b/features/element_access/unchecked_access/index.html @@ -1,4 +1,4 @@ - Unchecked access: operator[] - JSON for Modern C++
Skip to content

Unchecked access: operator[]

Overview

Elements in a JSON object and a JSON array can be accessed via operator[] similar to a std::map and a std::vector, respectively.

Read access

Consider the following JSON value:

{
+ Unchecked access: operator[] - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Unchecked access: operator[]
 
Overview
 
Elements in a JSON object and a JSON array can be accessed via operator[] similar to a std::map and a std::vector, respectively.
 
 Read access 
Consider the following JSON value:
 
{
     "name": "Mary Smith",
     "age": 42,
     "hobbies": ["hiking", "reading"]
@@ -24,4 +24,4 @@
 for (int i = 0; i < 1000; ++i) {
     j.push_back(i);
 }
-
 
Summary
 
  
 scenario non-const value const value 
   
 access to existing object key reference to existing value is returned const reference to existing value is returned 
 
 access to valid array index reference to existing value is returned const reference to existing value is returned 
 
 access to non-existing object key reference to newly inserted null value is returned undefined behavior; runtime assertion in debug mode 
 
 access to invalid array index reference to newly inserted null value is returned; any index between previous maximal index and passed index are filled with null undefined behavior; runtime assertion in debug mode 
  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Summary

scenario non-const value const value
access to existing object key reference to existing value is returned const reference to existing value is returned
access to valid array index reference to existing value is returned const reference to existing value is returned
access to non-existing object key reference to newly inserted null value is returned undefined behavior; runtime assertion in debug mode
access to invalid array index reference to newly inserted null value is returned; any index between previous maximal index and passed index are filled with null undefined behavior; runtime assertion in debug mode
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/enum_conversion/index.html b/features/enum_conversion/index.html index c550e3b78..c4bd4389e 100644 --- a/features/enum_conversion/index.html +++ b/features/enum_conversion/index.html @@ -1,4 +1,4 @@ - Specializing enum conversion - JSON for Modern C++
Skip to content

Specializing enum conversion

By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If the integer values of any enum values are changed after data using those enum values has been serialized to JSON, then deserializing that JSON would result in a different enum value being restored, or the value not being found at all.

It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:

// example enum type declaration
+ Specializing enum conversion - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Specializing enum conversion
 
By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If the integer values of any enum values are changed after data using those enum values has been serialized to JSON, then deserializing that JSON would result in a different enum value being restored, or the value not being found at all.
 
It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:
 
// example enum type declaration
 enum TaskState {
     TS_STOPPED,
     TS_RUNNING,
@@ -24,4 +24,4 @@
 // undefined json value to enum (where the first map entry above is the default)
 json jPi = 3.14;
 assert(jPi.get<TaskState>() == TS_INVALID );
-
 
Notes
 
Just as in Arbitrary Type Conversions above,
 
     
  • NLOHMANN_JSON_SERIALIZE_ENUM() MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it, and it will default to integer serialization.
    •  
  • It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.
    •  
 
Other Important points:
 
     
  • When using get<ENUM_TYPE>(), undefined JSON values will default to the first pair specified in your map. Select this default pair carefully. If you desire an exception in this circumstance use NLOHMANN_JSON_SERIALIZE_ENUM_STRICT() which behaves identically except for throwing an exception on unrecognized values.
    •  
  • If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
    •  
  • To disable the default serialization of enumerators as integers and force a compiler error instead, see JSON_DISABLE_ENUM_SERIALIZATION.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Notes

Just as in Arbitrary Type Conversions above,

  • NLOHMANN_JSON_SERIALIZE_ENUM() MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it, and it will default to integer serialization.
  • It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.

Other Important points:

  • When using get<ENUM_TYPE>(), undefined JSON values will default to the first pair specified in your map. Select this default pair carefully. If you desire an exception in this circumstance use NLOHMANN_JSON_SERIALIZE_ENUM_STRICT() which behaves identically except for throwing an exception on unrecognized values.
  • If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
  • To disable the default serialization of enumerators as integers and force a compiler error instead, see JSON_DISABLE_ENUM_SERIALIZATION.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/index.html b/features/index.html index ad806fe52..a0a8095d9 100644 --- a/features/index.html +++ b/features/index.html @@ -1 +1 @@ - Features - JSON for Modern C++
Skip to content

Features

This section describes the features of the library in detail. If you are new to the library, the pages below are roughly ordered along a typical workflow: create or parse a value, access and modify it, convert it to and from your own C++ types, and finally serialize it again.

Creating and reading values

Accessing and modifying values

Converting to and from C++ types

Serializing values

How values are stored and configured

Looking for a specific function?

This section gives conceptual overviews. For the precise signature, parameters, and return value of a function, see the API Documentation.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Features - JSON for Modern C++
Skip to content

Features

This section describes the features of the library in detail. If you are new to the library, the pages below are roughly ordered along a typical workflow: create or parse a value, access and modify it, convert it to and from your own C++ types, and finally serialize it again.

Creating and reading values

Accessing and modifying values

Converting to and from C++ types

Serializing values

How values are stored and configured

Looking for a specific function?

This section gives conceptual overviews. For the precise signature, parameters, and return value of a function, see the API Documentation.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/iterators/index.html b/features/iterators/index.html index 55c5e10c3..612cf6c65 100644 --- a/features/iterators/index.html +++ b/features/iterators/index.html @@ -1,4 +1,4 @@ - Iterators - JSON for Modern C++
Skip to content

Iterators

Overview

A basic_json value is a container and allows access via iterators. Depending on the value type, basic_json stores zero or more values.

As for other containers, begin() returns an iterator to the first value and end() returns an iterator to the value following the last value. The latter iterator is a placeholder and cannot be dereferenced. In case of null values, empty arrays, or empty objects, begin() will return end().

Illustration from cppreference.com

Iteration order for objects

When iterating over objects, values are ordered with respect to the object_comparator_t type which defaults to std::less. See the types documentation for more information.

Example 
// create JSON object {"one": 1, "two": 2, "three": 3}
+ Iterators - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Iterators
 
Overview
 
A basic_json value is a container and allows access via iterators. Depending on the value type, basic_json stores zero or more values.
 
As for other containers, begin() returns an iterator to the first value and end() returns an iterator to the value following the last value. The latter iterator is a placeholder and cannot be dereferenced. In case of null values, empty arrays, or empty objects, begin() will return end().
 
Illustration from cppreference.com
 
Iteration order for objects
 
When iterating over objects, values are ordered with respect to the object_comparator_t type which defaults to std::less. See the types documentation for more information.
 
 Example 
// create JSON object {"one": 1, "two": 2, "three": 3}
 json j;
 j["one"] = 1;
 j["two"] = 2;
@@ -53,4 +53,4 @@
     std::cout << *it << std::endl;
 }
 
 
Output:
 
"Hello, world"
-
 
 
Iterator invalidation
 
  
 Operations invalidated iterators 
   
 clear all 
  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Iterator invalidation

Operations invalidated iterators
clear all
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/json_patch/index.html b/features/json_patch/index.html index 687ebe7ea..ea4e23886 100644 --- a/features/json_patch/index.html +++ b/features/json_patch/index.html @@ -1,4 +1,4 @@ - JSON Patch and Diff - JSON for Modern C++
Skip to content

JSON Patch and Diff

Patches

JSON Patch (RFC 6902) defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. With the patch function, a JSON Patch is applied to the current JSON value by executing all operations from the patch.

Example

The following code shows how a JSON patch is applied to a value.

#include <iostream>
+ JSON Patch and Diff - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON Patch and Diff
 
Patches
 
JSON Patch (RFC 6902) defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. With the patch function, a JSON Patch is applied to the current JSON value by executing all operations from the patch.
 
 Example 
The following code shows how a JSON patch is applied to a value.
 
#include <iostream>
 #include <iomanip>
 #include <nlohmann/json.hpp>
 
@@ -105,4 +105,4 @@
         "world"
     ]
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/json_pointer/index.html b/features/json_pointer/index.html index 2c6f0d584..00eb52d23 100644 --- a/features/json_pointer/index.html +++ b/features/json_pointer/index.html @@ -1,4 +1,4 @@ - JSON Pointer - JSON for Modern C++
Skip to content

JSON Pointer

Introduction

The library supports JSON Pointer (RFC 6901) as an alternative means to address structured values. A JSON Pointer is a string that identifies a specific value within a JSON document.

Consider the following JSON document

{
+ JSON Pointer - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON Pointer
 
Introduction
 
The library supports JSON Pointer (RFC 6901) as an alternative means to address structured values. A JSON Pointer is a string that identifies a specific value within a JSON document.
 
Consider the following JSON document
 
{
     "array": ["A", "B", "C"],
     "nested": {
         "one": 1,
@@ -45,4 +45,4 @@
   "/nested/three/1": false
 }
 
 
The reverse function, unflatten recreates the original value.
 
auto j_original = j_flat.unflatten();
-
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/macros/index.html b/features/macros/index.html index d1f351b4e..2875b92b5 100644 --- a/features/macros/index.html +++ b/features/macros/index.html @@ -1 +1 @@ - Supported Macros - JSON for Modern C++
Skip to content

Supported Macros

Some aspects of the library can be configured by defining preprocessor macros before including the json.hpp header. See also the API documentation for macros for examples and more information.

JSON_ASSERT(x)

This macro controls which code is executed for runtime assertions of the library.

See full documentation of JSON_ASSERT(x).

JSON_BRACE_INIT_COPY_SEMANTICS

When defined to 1, single-element brace initialization of a basic_json value (e.g., json j{value};) is treated as a copy/move of the element rather than wrapping it in a single-element array. The default value is 0, which preserves the existing behavior.

See full documentation of JSON_BRACE_INIT_COPY_SEMANTICS.

JSON_CATCH_USER(exception)

This macro overrides catch calls inside the library.

See full documentation of JSON_CATCH_USER(exception).

JSON_DIAGNOSTICS

This macro enables extended diagnostics for exception messages. Possible values are 1 to enable or 0 to disable (default).

When enabled, exception messages contain a JSON Pointer to the JSON value that triggered the exception, see Extended diagnostic messages for an example. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.

The diagnostics messages can also be controlled with the CMake option JSON_Diagnostics (OFF by default) which sets JSON_DIAGNOSTICS accordingly.

See full documentation of JSON_DIAGNOSTICS.

JSON_DIAGNOSTIC_POSITIONS

When enabled, two new member functions start_pos() and end_pos() are added to basic_json values. If the value was created by calling theparse function, then these functions allow querying the byte positions of the value in the input it was parsed from. The byte positions are also used in exceptions to help locate errors.

The diagnostics positions can also be controlled with the CMake option JSON_Diagnostic_Positions (OFF by default) which sets JSON_DIAGNOSTIC_POSITIONS accordingly.

See full documentation of JSON_DIAGNOSTIC_POSITIONS

JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26

The library targets C++11, but also supports some features introduced in later C++ versions (e.g., std::string_view support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be detected incorrectly.

See full documentation of JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, and JSON_HAS_CPP_26.

JSON_HAS_FILESYSTEM, JSON_HAS_EXPERIMENTAL_FILESYSTEM

When compiling with C++17, the library provides conversions from and to std::filesystem::path. As compiler support for filesystem is limited, the library tries to detect whether <filesystem>/std::filesystem (JSON_HAS_FILESYSTEM) or <experimental/filesystem>/std::experimental::filesystem (JSON_HAS_EXPERIMENTAL_FILESYSTEM) should be used. To override the built-in check, define JSON_HAS_FILESYSTEM or JSON_HAS_EXPERIMENTAL_FILESYSTEM to 1.

See full documentation of JSON_HAS_FILESYSTEM and JSON_HAS_EXPERIMENTAL_FILESYSTEM.

JSON_NOEXCEPTION

Exceptions can be switched off by defining the symbol JSON_NOEXCEPTION.

See full documentation of JSON_NOEXCEPTION.

JSON_DISABLE_ENUM_SERIALIZATION

When defined, default parse and serialize functions for enums are excluded and have to be provided by the user, for example, using NLOHMANN_JSON_SERIALIZE_ENUM.

See full documentation of JSON_DISABLE_ENUM_SERIALIZATION.

JSON_NO_IO

When defined, headers <cstdio>, <ios>, <iosfwd>, <istream>, and <ostream> are not included and parse functions relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for security reasons (e.g., Intel Software Guard Extensions (SGX)).

See full documentation of JSON_NO_IO.

JSON_SKIP_LIBRARY_VERSION_CHECK

When defined, the library will not create a compiler warning when a different version of the library was already included.

See full documentation of JSON_SKIP_LIBRARY_VERSION_CHECK.

JSON_SKIP_UNSUPPORTED_COMPILER_CHECK

When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows using the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.

See full documentation of JSON_SKIP_UNSUPPORTED_COMPILER_CHECK.

JSON_THROW_USER(exception)

This macro overrides throw calls inside the library. The argument is the exception to be thrown.

See full documentation of JSON_THROW_USER(exception).

JSON_TRY_USER

This macro overrides try calls inside the library.

See full documentation of JSON_TRY_USER.

JSON_USE_IMPLICIT_CONVERSIONS

When defined to 0, implicit conversions are switched off. By default, implicit conversions are switched on.

See full documentation of JSON_USE_IMPLICIT_CONVERSIONS.

JSON_USE_GLOBAL_UDLS

When defined to 1 (default), the user-defined string literals operator""_json and operator""_json_pointer are placed into the global namespace instead of nlohmann::literals::json_literals.

See full documentation of JSON_USE_GLOBAL_UDLS.

JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON

When defined to 1, the library restores the legacy behavior in which a discarded value compared equal to itself. This behavior is deprecated and switched off (0) by default.

See full documentation of JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON.

NLOHMANN_DEFINE_TYPE_*(...), NLOHMANN_DEFINE_DERIVED_TYPE_*(...)

The library defines 12 macros to simplify the serialization/deserialization of types. See the page on arbitrary type conversion for a detailed discussion.

NLOHMANN_JSON_NAMESPACE, NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END, NLOHMANN_JSON_NAMESPACE_NO_VERSION

These macros relate to the versioned, inline nlohmann namespace:

  • NLOHMANN_JSON_NAMESPACE evaluates to the full name of the nlohmann namespace (including the inline ABI namespace).
  • NLOHMANN_JSON_NAMESPACE_BEGIN / NLOHMANN_JSON_NAMESPACE_END open and close the namespace (for example, to add specializations).
  • NLOHMANN_JSON_NAMESPACE_NO_VERSION, when defined to 1, omits the version component from the inline namespace.

See the nlohmann Namespace page, and the full documentation of NLOHMANN_JSON_NAMESPACE, NLOHMANN_JSON_NAMESPACE_BEGIN / NLOHMANN_JSON_NAMESPACE_END, and NLOHMANN_JSON_NAMESPACE_NO_VERSION.

NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)

This macro simplifies the serialization/deserialization of enum types. See Specializing enum conversion for more information.

See full documentation of NLOHMANN_JSON_SERIALIZE_ENUM.

A strict variant NLOHMANN_JSON_SERIALIZE_ENUM_STRICT throws an exception on undefined input instead of falling back to the first mapping.

NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH

These macros are defined by the library and contain the version numbers according to Semantic Versioning 2.0.0.

See full documentation of NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, and NLOHMANN_JSON_VERSION_PATCH.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Supported Macros - JSON for Modern C++
Skip to content

Supported Macros

Some aspects of the library can be configured by defining preprocessor macros before including the json.hpp header. See also the API documentation for macros for examples and more information.

JSON_ASSERT(x)

This macro controls which code is executed for runtime assertions of the library.

See full documentation of JSON_ASSERT(x).

JSON_BRACE_INIT_COPY_SEMANTICS

When defined to 1, single-element brace initialization of a basic_json value (e.g., json j{value};) is treated as a copy/move of the element rather than wrapping it in a single-element array. The default value is 0, which preserves the existing behavior.

See full documentation of JSON_BRACE_INIT_COPY_SEMANTICS.

JSON_CATCH_USER(exception)

This macro overrides catch calls inside the library.

See full documentation of JSON_CATCH_USER(exception).

JSON_DIAGNOSTICS

This macro enables extended diagnostics for exception messages. Possible values are 1 to enable or 0 to disable (default).

When enabled, exception messages contain a JSON Pointer to the JSON value that triggered the exception, see Extended diagnostic messages for an example. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.

The diagnostics messages can also be controlled with the CMake option JSON_Diagnostics (OFF by default) which sets JSON_DIAGNOSTICS accordingly.

See full documentation of JSON_DIAGNOSTICS.

JSON_DIAGNOSTIC_POSITIONS

When enabled, two new member functions start_pos() and end_pos() are added to basic_json values. If the value was created by calling theparse function, then these functions allow querying the byte positions of the value in the input it was parsed from. The byte positions are also used in exceptions to help locate errors.

The diagnostics positions can also be controlled with the CMake option JSON_Diagnostic_Positions (OFF by default) which sets JSON_DIAGNOSTIC_POSITIONS accordingly.

See full documentation of JSON_DIAGNOSTIC_POSITIONS

JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26

The library targets C++11, but also supports some features introduced in later C++ versions (e.g., std::string_view support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be detected incorrectly.

See full documentation of JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, and JSON_HAS_CPP_26.

JSON_HAS_FILESYSTEM, JSON_HAS_EXPERIMENTAL_FILESYSTEM

When compiling with C++17, the library provides conversions from and to std::filesystem::path. As compiler support for filesystem is limited, the library tries to detect whether <filesystem>/std::filesystem (JSON_HAS_FILESYSTEM) or <experimental/filesystem>/std::experimental::filesystem (JSON_HAS_EXPERIMENTAL_FILESYSTEM) should be used. To override the built-in check, define JSON_HAS_FILESYSTEM or JSON_HAS_EXPERIMENTAL_FILESYSTEM to 1.

See full documentation of JSON_HAS_FILESYSTEM and JSON_HAS_EXPERIMENTAL_FILESYSTEM.

JSON_NOEXCEPTION

Exceptions can be switched off by defining the symbol JSON_NOEXCEPTION.

See full documentation of JSON_NOEXCEPTION.

JSON_DISABLE_ENUM_SERIALIZATION

When defined, default parse and serialize functions for enums are excluded and have to be provided by the user, for example, using NLOHMANN_JSON_SERIALIZE_ENUM.

See full documentation of JSON_DISABLE_ENUM_SERIALIZATION.

JSON_NO_IO

When defined, headers <cstdio>, <ios>, <iosfwd>, <istream>, and <ostream> are not included and parse functions relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for security reasons (e.g., Intel Software Guard Extensions (SGX)).

See full documentation of JSON_NO_IO.

JSON_SKIP_LIBRARY_VERSION_CHECK

When defined, the library will not create a compiler warning when a different version of the library was already included.

See full documentation of JSON_SKIP_LIBRARY_VERSION_CHECK.

JSON_SKIP_UNSUPPORTED_COMPILER_CHECK

When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows using the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.

See full documentation of JSON_SKIP_UNSUPPORTED_COMPILER_CHECK.

JSON_THROW_USER(exception)

This macro overrides throw calls inside the library. The argument is the exception to be thrown.

See full documentation of JSON_THROW_USER(exception).

JSON_TRY_USER

This macro overrides try calls inside the library.

See full documentation of JSON_TRY_USER.

JSON_USE_IMPLICIT_CONVERSIONS

When defined to 0, implicit conversions are switched off. By default, implicit conversions are switched on.

See full documentation of JSON_USE_IMPLICIT_CONVERSIONS.

JSON_USE_GLOBAL_UDLS

When defined to 1 (default), the user-defined string literals operator""_json and operator""_json_pointer are placed into the global namespace instead of nlohmann::literals::json_literals.

See full documentation of JSON_USE_GLOBAL_UDLS.

JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON

When defined to 1, the library restores the legacy behavior in which a discarded value compared equal to itself. This behavior is deprecated and switched off (0) by default.

See full documentation of JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON.

NLOHMANN_DEFINE_TYPE_*(...), NLOHMANN_DEFINE_DERIVED_TYPE_*(...)

The library defines 12 macros to simplify the serialization/deserialization of types. See the page on arbitrary type conversion for a detailed discussion.

NLOHMANN_JSON_NAMESPACE, NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END, NLOHMANN_JSON_NAMESPACE_NO_VERSION

These macros relate to the versioned, inline nlohmann namespace:

  • NLOHMANN_JSON_NAMESPACE evaluates to the full name of the nlohmann namespace (including the inline ABI namespace).
  • NLOHMANN_JSON_NAMESPACE_BEGIN / NLOHMANN_JSON_NAMESPACE_END open and close the namespace (for example, to add specializations).
  • NLOHMANN_JSON_NAMESPACE_NO_VERSION, when defined to 1, omits the version component from the inline namespace.

See the nlohmann Namespace page, and the full documentation of NLOHMANN_JSON_NAMESPACE, NLOHMANN_JSON_NAMESPACE_BEGIN / NLOHMANN_JSON_NAMESPACE_END, and NLOHMANN_JSON_NAMESPACE_NO_VERSION.

NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)

This macro simplifies the serialization/deserialization of enum types. See Specializing enum conversion for more information.

See full documentation of NLOHMANN_JSON_SERIALIZE_ENUM.

A strict variant NLOHMANN_JSON_SERIALIZE_ENUM_STRICT throws an exception on undefined input instead of falling back to the first mapping.

NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH

These macros are defined by the library and contain the version numbers according to Semantic Versioning 2.0.0.

See full documentation of NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, and NLOHMANN_JSON_VERSION_PATCH.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/merge_patch/index.html b/features/merge_patch/index.html index 0d9cef301..636135ff4 100644 --- a/features/merge_patch/index.html +++ b/features/merge_patch/index.html @@ -1,4 +1,4 @@ - JSON Merge Patch - JSON for Modern C++
Skip to content

JSON Merge Patch

The library supports JSON Merge Patch (RFC 7386) as a patch format. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This function applies a merge patch to the current JSON value.

Instead of using JSON Pointer to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.

Example

The following code shows how a JSON Merge Patch is applied to a JSON document.

#include <iostream>
+ JSON Merge Patch - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON Merge Patch
 
The library supports JSON Merge Patch (RFC 7386) as a patch format. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This function applies a merge patch to the current JSON value.
 
Instead of using JSON Pointer to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
 
 Example 
The following code shows how a JSON Merge Patch is applied to a JSON document.
 
#include <iostream>
 #include <nlohmann/json.hpp>
 #include <iomanip> // for std::setw
 
@@ -50,4 +50,4 @@
     ],
     "title": "Hello!"
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/modifying_values/index.html b/features/modifying_values/index.html index 467318933..631834d5a 100644 --- a/features/modifying_values/index.html +++ b/features/modifying_values/index.html @@ -1,4 +1,4 @@ - Modifying values - JSON for Modern C++
Skip to content

Modifying values

Once a JSON value exists, its content can be changed: elements can be added, replaced, merged, and removed. This page gives an overview of the available operations. For read access, see element access.

Adding to arrays

New elements are appended to an array with push_back or constructed in place with emplace_back. If the value is null, it is converted to an array first, so these functions can also be used to build an array from scratch.

json j;                 // null
+ Modifying values - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Modifying values
 
Once a JSON value exists, its content can be changed: elements can be added, replaced, merged, and removed. This page gives an overview of the available operations. For read access, see element access.
 
Adding to arrays
 
New elements are appended to an array with push_back or constructed in place with emplace_back. If the value is null, it is converted to an array first, so these functions can also be used to build an array from scratch.
 
json j;                 // null
 j.push_back(1);         // [1]
 j.push_back(2);         // [1,2]
 j.emplace_back(3);      // [1,2,3]
@@ -54,4 +54,4 @@
 
 json a = {1, 2, 3, 4};
 a.erase(1);             // [1,3,4]  (erase by index)
-
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

See also

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/modules/index.html b/features/modules/index.html index 751f87db1..5bd142b15 100644 --- a/features/modules/index.html +++ b/features/modules/index.html @@ -1,4 +1,4 @@ - Modules - JSON for Modern C++
Skip to content

Modules

This library has experimental support for C++ modules, introduced in C++20. The library can be imported by writing import nlohmann.json; instead of #include <nlohmann/json.hpp>.

Please be aware that the module is experimental and a full test is outstanding, and the exported symbols are subject to change.

Requirements

The nlohmann.json module requires that the build system is configured to build and resolve modules when imported. Obviously, as modules were introduced in C++20, this feature can only be used in C++20 and subsequent versions.

To enable building the nlohmann.json module (which is not done by default), the macro NLOHMANN_JSON_BUILD_MODULES must be passed to the build system.

Example

When using modules rather than headers, the previous example for creating a json object through a JSON file, would instead be: 

import std;
+ Modules - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Modules
 
This library has experimental support for C++ modules, introduced in C++20. The library can be imported by writing import nlohmann.json; instead of #include <nlohmann/json.hpp>. 
 
Please be aware that the module is experimental and a full test is outstanding, and the exported symbols are subject to change.
 
Requirements
 
The nlohmann.json module requires that the build system is configured to build and resolve modules when imported. Obviously, as modules were introduced in C++20, this feature can only be used in C++20 and subsequent versions.
 
To enable building the nlohmann.json module (which is not done by default), the macro NLOHMANN_JSON_BUILD_MODULES must be passed to the build system.
 
Example
 
When using modules rather than headers, the previous example for creating a json object through a JSON file, would instead be: 
import std;
 import nlohmann.json;
 
 using json = nlohmann::json;
@@ -7,4 +7,4 @@
 
 std::ifstream f("example.json");
 json data = json::parse(f);
-
 
Modules do not export macros
 
It should be noted that as modules do not export macros, the nlohmann.json module will not export any macros.
 
Exported symbols
 
Only the following symbols are exported from nlohmann.json:
 
     
  • nlohmann::adl_serializer
    •  
  • nlohmann::basic_json
    •  
  • nlohmann::json
    •  
  • nlohmann::json_pointer
    •  
  • nlohmann::ordered_json
    •  
  • nlohmann::ordered_map
    •  
  • nlohmann::to_string
    •  
  • nlohmann::literals::json_literals::operator""_json
    •  
  • nlohmann::literals::json_literals::operator""_json_pointer
    •  
 
Additionally, the following nlohmann::detail symbols are exported, solely to work around an MSVC compilation issue (#3970). They are implementation details, not part of the public API, and should not be used directly:
 
     
  • nlohmann::detail::json_sax_dom_callback_parser
    •  
  • nlohmann::detail::unknown_size
    •  
 
Known issues
 
C++20 modules support is exercised in CI against current GCC and Clang on Ubuntu, and the default MSVC toolset on Windows Server 2022 — there is no documented minimum compiler version, unlike feature-test-macro-gated features such as JSON_HAS_RANGES.
 
 
Known compiler issues
 
     
  • GCC may emit "redefinition" errors when #include <nlohmann/json.hpp> appears in a module preamble together with other imports. This is an upstream GCC bug, not yet resolved as of GCC 16. Workarounds: include nlohmann/json.hpp before other #includes, use import nlohmann.json; instead, or upgrade GCC. (issue #5103)
    •  
  • MSVC could fail with C2039: 'json_sax_dom_callback_parser' is not a member of ... detail; fixed by exporting the required internal symbols from json.cppm (see Exported symbols above). (issue #3970)
    •  
 
If you hit a different module-related build failure, search existing issues before filing a new one.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Modules do not export macros

It should be noted that as modules do not export macros, the nlohmann.json module will not export any macros.

Exported symbols

Only the following symbols are exported from nlohmann.json:

  • nlohmann::adl_serializer
  • nlohmann::basic_json
  • nlohmann::json
  • nlohmann::json_pointer
  • nlohmann::ordered_json
  • nlohmann::ordered_map
  • nlohmann::to_string
  • nlohmann::literals::json_literals::operator""_json
  • nlohmann::literals::json_literals::operator""_json_pointer

Additionally, the following nlohmann::detail symbols are exported, solely to work around an MSVC compilation issue (#3970). They are implementation details, not part of the public API, and should not be used directly:

  • nlohmann::detail::json_sax_dom_callback_parser
  • nlohmann::detail::unknown_size

Known issues

C++20 modules support is exercised in CI against current GCC and Clang on Ubuntu, and the default MSVC toolset on Windows Server 2022 — there is no documented minimum compiler version, unlike feature-test-macro-gated features such as JSON_HAS_RANGES.

Known compiler issues

  • GCC may emit "redefinition" errors when #include <nlohmann/json.hpp> appears in a module preamble together with other imports. This is an upstream GCC bug, not yet resolved as of GCC 16. Workarounds: include nlohmann/json.hpp before other #includes, use import nlohmann.json; instead, or upgrade GCC. (issue #5103)
  • MSVC could fail with C2039: 'json_sax_dom_callback_parser' is not a member of ... detail; fixed by exporting the required internal symbols from json.cppm (see Exported symbols above). (issue #3970)

If you hit a different module-related build failure, search existing issues before filing a new one.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/namespace/index.html b/features/namespace/index.html index 778772da1..ea2d83fdc 100644 --- a/features/namespace/index.html +++ b/features/namespace/index.html @@ -1,4 +1,4 @@ - nlohmann Namespace - JSON for Modern C++
Skip to content

nlohmann Namespace

The 3.11.0 release introduced an inline namespace to allow different parts of a codebase to safely use different versions of the JSON library as long as they never exchange instances of library types.

Structure

The complete default namespace name is derived as follows:

  • The root namespace is always nlohmann.
  • The inline namespace starts with json_abi and is followed by several optional ABI tags according to the value of these ABI-affecting macros, in order:
  • The inline namespace ends with the suffix _v followed by the 3 components of the version number separated by underscores. To omit the version component, see Disabling the version component below.

For example, the namespace name for version 3.11.2 with JSON_DIAGNOSTICS defined to 1 is:

nlohmann::json_abi_diag_v3_11_2
+ nlohmann Namespace - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
nlohmann Namespace
 
The 3.11.0 release introduced an inline namespace to allow different parts of a codebase to safely use different versions of the JSON library as long as they never exchange instances of library types.
 
Structure
 
The complete default namespace name is derived as follows:
 
     
  • The root namespace is always nlohmann.
    •  
  • The inline namespace starts with json_abi and is followed by several optional ABI tags according to the value of these ABI-affecting macros, in order: 
    •  
  • The inline namespace ends with the suffix _v followed by the 3 components of the version number separated by underscores. To omit the version component, see Disabling the version component below.
    •  
 
For example, the namespace name for version 3.11.2 with JSON_DIAGNOSTICS defined to 1 is:
 
nlohmann::json_abi_diag_v3_11_2
 
 
Purpose
 
Several incompatibilities have been observed. Amongst the most common ones is linking code compiled with different definitions of JSON_DIAGNOSTICS. This is illustrated in the diagram below.
 
graph
     json["<strong>nlohmann_json (v3.10.5)</strong><br>JSON_DIAGNOSTICS=0"]
     json_diag["<strong>nlohmann_json (v3.10.5)</strong><br>JSON_DIAGNOSTICS=1"]
@@ -9,4 +9,4 @@
     app --> json_diag
     app --> library
 
In releases prior to 3.11.0, mixing any version of the JSON library with different JSON_DIAGNOSTICS settings would result in a crashing application. If some_library never passes instances of JSON library types to the application, this scenario became safe in version 3.11.0 and above due to the inline namespace yielding distinct symbol names.
 
Limitations
 
Neither the compiler nor the linker will issue as much as a warning when translation units – intended to be linked together and that include different versions and/or configurations of the JSON library – exchange and use library types.
 
There is an exception when forward declarations are used (i.e., when including json_fwd.hpp) in which case the linker may complain about undefined references.
 
Disabling the version component
 
Different versions are not necessarily ABI-incompatible, but the project does not actively track changes in the ABI and recommends that all parts of a codebase exchanging library types be built with the same version. Users can, at their own risk, disable the version component of the inline namespace, allowing different versions – but not configurations – to be used in cases where the linker would otherwise output undefined reference errors.
 
To do so, define NLOHMANN_JSON_NAMESPACE_NO_VERSION to 1.
 
This applies to version 3.11.2 and above only; versions 3.11.0 and 3.11.1 can apply the technique described in the next section to emulate the effect of the NLOHMANN_JSON_NAMESPACE_NO_VERSION macro.
 
 
Use at your own risk
 
Disabling the namespace version component and mixing ABI-incompatible versions will result in crashes or incorrect behavior. You have been warned!
 
 
Disabling the inline namespace completely
 
When interoperability with code using a pre-3.11.0 version of the library is required, users can, at their own risk restore the old namespace layout by redefining NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END as follows:
 
#define NLOHMANN_JSON_NAMESPACE_BEGIN  namespace nlohmann {
 #define NLOHMANN_JSON_NAMESPACE_END    }
-
 
 
Use at your own risk
 
Overriding the namespace and mixing ABI-incompatible versions will result in crashes or incorrect behavior. You have been warned!
 
 
Version history
 
     
  • Introduced inline namespace (json_v3_11_0[_abi-tag]*) in version 3.11.0.
    •  
  • Changed structure of inline namespace in version 3.11.2.
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Use at your own risk

Overriding the namespace and mixing ABI-incompatible versions will result in crashes or incorrect behavior. You have been warned!

Version history

  • Introduced inline namespace (json_v3_11_0[_abi-tag]*) in version 3.11.0.
  • Changed structure of inline namespace in version 3.11.2.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/object_order/index.html b/features/object_order/index.html index eed9fcd3f..4e4387c65 100644 --- a/features/object_order/index.html +++ b/features/object_order/index.html @@ -1,4 +1,4 @@ - Object Order - JSON for Modern C++
Skip to content

Object Order

The JSON standard defines objects as "an unordered collection of zero or more name/value pairs". As such, an implementation does not need to preserve any specific order of object keys.

Default behavior: sort keys

The default type nlohmann::json uses a std::map to store JSON objects, and thus stores object keys sorted alphabetically.

Example 
#include <iostream>
+ Object Order - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Object Order
 
The JSON standard defines objects as "an unordered collection of zero or more name/value pairs". As such, an implementation does not need to preserve any specific order of object keys.
 
Default behavior: sort keys
 
The default type nlohmann::json uses a std::map to store JSON objects, and thus stores object keys sorted alphabetically.
 
 Example 
#include <iostream>
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
@@ -57,4 +57,4 @@
   "three": 3,
   "two": 2
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/parsing/index.html b/features/parsing/index.html index 345d3fd26..bd77a4343 100644 --- a/features/parsing/index.html +++ b/features/parsing/index.html @@ -1,7 +1,7 @@ - Parsing - JSON for Modern C++
Skip to content

Parsing

This library can create a JSON value from a wide range of inputs. This page gives an overview of the available parsing functions and how they behave; the linked pages go into more detail.

Input

The parse function reads a JSON value from an input. The input can be

  • a string (std::string, C string, or string literal),
  • a std::istream (e.g., an std::ifstream reading from a file),
  • a FILE* pointer,
  • a pair of iterators over a contiguous range (e.g., a std::vector<std::uint8_t>), or
  • a contiguous container.
// parse from a string
+ Parsing - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Parsing
 
This library can create a JSON value from a wide range of inputs. This page gives an overview of the available parsing functions and how they behave; the linked pages go into more detail.
 
Input
 
The parse function reads a JSON value from an input. The input can be
 
     
  • a string (std::string, C string, or string literal),
    •  
  • a std::istream (e.g., an std::ifstream reading from a file),
    •  
  • a FILE* pointer,
    •  
  • a pair of iterators over a contiguous range (e.g., a std::vector<std::uint8_t>), or
    •  
  • a contiguous container.
    •  
 
// parse from a string
 json j = json::parse(R"({"happy": true, "pi": 3.141})");
 
 // parse from a file
 std::ifstream f("example.json");
 json data = json::parse(f);
-
 
The input must be encoded in UTF-8; other encodings are not supported. A single input may contain only one JSON value. Inputs consisting of multiple values separated by newlines are handled by the JSON Lines format.
 
By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the parse function — see comments and trailing commas.
 
Strictness and trailing data
 
parse reads a single JSON value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete JSON document.
 
operator>> follows relaxed std::istream semantics instead: it parses one JSON value and leaves the stream positioned right after it, without requiring the rest of the stream to be consumed. This is what makes it possible to read several concatenated values from the same stream, but it also means that "a valid document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to reject any input that is not exactly one JSON document, prefer parse.
 
When using operator>> to read several concatenated values this way, a value that is a number must be followed by whitespace, because operator>> consumes the character that terminates a number — see the operator>> notes for details and examples.
 
SAX vs. DOM parsing
 
The library offers two parsing models:
 
     
  • DOM parsing (the default): the complete input is read and stored as an in-memory basic_json value that can be traversed and modified freely. This is what parse does, and it is the right choice for most use cases.
    •  
  • SAX parsing: instead of building a value, the parser reports events (such as "a string was read" or "an object started") to a handler that you implement. This avoids building the full value in memory and is useful for very large inputs or when you only need to extract parts of the input. See the SAX interface for details and sax_parse for the API.
    •  
 
You can influence a DOM parse without switching to the SAX interface by passing a parser callback, which is called during parsing and can, for example, discard parts of the input.
 
Exceptions
 
When the input is not valid JSON, the parse function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or accept can be used to only check whether an input is valid JSON. See parsing and exceptions for the available options.
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

The input must be encoded in UTF-8; other encodings are not supported. A single input may contain only one JSON value. Inputs consisting of multiple values separated by newlines are handled by the JSON Lines format.

By default, the library rejects comments and trailing commas. Both can be enabled with parameters of the parse function — see comments and trailing commas.

Strictness and trailing data

parse reads a single JSON value and requires the whole input to be consumed: any non-whitespace data after the value is reported as a parse error. Use it when you want to guarantee that an input is exactly one complete JSON document.

operator>> follows relaxed std::istream semantics instead: it parses one JSON value and leaves the stream positioned right after it, without requiring the rest of the stream to be consumed. This is what makes it possible to read several concatenated values from the same stream, but it also means that "a valid document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to reject any input that is not exactly one JSON document, prefer parse.

When using operator>> to read several concatenated values this way, a value that is a number must be followed by whitespace, because operator>> consumes the character that terminates a number — see the operator>> notes for details and examples.

SAX vs. DOM parsing

The library offers two parsing models:

  • DOM parsing (the default): the complete input is read and stored as an in-memory basic_json value that can be traversed and modified freely. This is what parse does, and it is the right choice for most use cases.
  • SAX parsing: instead of building a value, the parser reports events (such as "a string was read" or "an object started") to a handler that you implement. This avoids building the full value in memory and is useful for very large inputs or when you only need to extract parts of the input. See the SAX interface for details and sax_parse for the API.

You can influence a DOM parse without switching to the SAX interface by passing a parser callback, which is called during parsing and can, for example, discard parts of the input.

Exceptions

When the input is not valid JSON, the parse function throws an exception by default. If exceptions are undesired or unavailable, the parser can instead return a discarded value, or accept can be used to only check whether an input is valid JSON. See parsing and exceptions for the available options.

See also

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/parsing/json_lines/index.html b/features/parsing/json_lines/index.html index de6ede1d2..42df33ad5 100644 --- a/features/parsing/json_lines/index.html +++ b/features/parsing/json_lines/index.html @@ -1,4 +1,4 @@ - JSON Lines - JSON for Modern C++
Skip to content

JSON Lines

The JSON Lines format is a text format of newline-delimited JSON. In particular:

  1. The input must be UTF-8 encoded.
  2. Every line must be a valid JSON value.
  3. The line separator must be \n. As \r is silently ignored, \r\n is also supported.
  4. The final character may be \n, but is not required to be one.

JSON Text example

{"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]}
+ JSON Lines - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
JSON Lines
 
The JSON Lines format is a text format of newline-delimited JSON. In particular:
 
     
  1. The input must be UTF-8 encoded.
    2.  
  2. Every line must be a valid JSON value.
    3.  
  3. The line separator must be \n. As \r is silently ignored, \r\n is also supported.
    4.  
  4. The final character may be \n, but is not required to be one.
    5.  
 
 
JSON Text example
 
{"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]}
 {"name": "Alexa", "wins": [["two pair", "4♠"], ["two pair", "9♠"]]}
 {"name": "May", "wins": []}
 {"name": "Deloise", "wins": [["three of a kind", "5♣"]]}
@@ -33,4 +33,4 @@
 {
     std::cout << j << std::endl;
 }
-
 
with a JSON Lines input does not work, because the parser will try to parse one value after the last one.
 
This is different from parsing a stream of concatenated (non-newline-delimited) JSON values, for which operator>> does work, provided that a value that is a number is followed by whitespace -- see its notes for details.
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

with a JSON Lines input does not work, because the parser will try to parse one value after the last one.

This is different from parsing a stream of concatenated (non-newline-delimited) JSON values, for which operator>> does work, provided that a value that is a number is followed by whitespace -- see its notes for details.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/parsing/parse_exceptions/index.html b/features/parsing/parse_exceptions/index.html index 51ba660d2..f5b4bdc26 100644 --- a/features/parsing/parse_exceptions/index.html +++ b/features/parsing/parse_exceptions/index.html @@ -1,4 +1,4 @@ - Parsing and Exceptions - JSON for Modern C++
Skip to content

Parsing and Exceptions

When the input is not valid JSON, an exception of type parse_error is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a list of examples for parse error exceptions. In case you process untrusted input, always enclose your code with a try/catch block, like

json j;
+ Parsing and Exceptions - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Parsing and Exceptions
 
When the input is not valid JSON, an exception of type parse_error is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a list of examples for parse error exceptions. In case you process untrusted input, always enclose your code with a try/catch block, like
 
json j;
 try
 {
     j = json::parse(my_input);
@@ -63,4 +63,4 @@
 last read: "3,]"
 parsing unsuccessful!
 parsed value: [1,2,3]
-
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/parsing/parser_callbacks/index.html b/features/parsing/parser_callbacks/index.html index 0c0727fe4..2bce03596 100644 --- a/features/parsing/parser_callbacks/index.html +++ b/features/parsing/parser_callbacks/index.html @@ -1,4 +1,4 @@ - Parser Callbacks - JSON for Modern C++
Skip to content

Parser Callbacks

Overview

With a parser callback function, the result of parsing a JSON text can be influenced. When passed to parse, it is called on certain events (passed as parse_event_t via parameter event) with a set recursion depth depth and context JSON value parsed. The return value of the callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.

The type of the callback function is:

template<typename BasicJsonType>
+ Parser Callbacks - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Parser Callbacks
 
Overview
 
With a parser callback function, the result of parsing a JSON text can be influenced. When passed to parse, it is called on certain events (passed as parse_event_t via parameter event) with a set recursion depth depth and context JSON value parsed. The return value of the callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
 
The type of the callback function is:
 
template<typename BasicJsonType>
 using parser_callback_t =
     std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
 
 
Callback event types
 
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values of the parameters depth, event, and parsed.
 
  
 parameter event description parameter depth parameter parsed 
   
 parse_event_t::object_start the parser read { and started to process a JSON object depth of the parent of the JSON object a JSON value with type discarded 
 
 parse_event_t::key the parser read a key of a value in an object depth of the currently parsed JSON object a JSON string containing the key 
 
 parse_event_t::object_end the parser read } and finished processing a JSON object depth of the parent of the JSON object the parsed JSON object 
 
 parse_event_t::array_start the parser read [ and started to process a JSON array depth of the parent of the JSON array a JSON value with type discarded 
 
 parse_event_t::array_end the parser read ] and finished processing a JSON array depth of the parent of the JSON array the parsed JSON array 
 
 parse_event_t::value the parser finished reading a JSON value depth of the value the parsed JSON value 
  
 
 Example 
When parsing the following JSON text,
 
{
@@ -174,4 +174,4 @@
 };
 
 json::parse(input, callback);
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/parsing/sax_interface/index.html b/features/parsing/sax_interface/index.html index 3b71a27de..835b484c0 100644 --- a/features/parsing/sax_interface/index.html +++ b/features/parsing/sax_interface/index.html @@ -1,4 +1,4 @@ - SAX Interface - JSON for Modern C++
Skip to content

SAX Interface

The library uses a SAX-like interface with the following functions:

classDiagram
+ SAX Interface - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
SAX Interface
 
The library uses a SAX-like interface with the following functions:
 
classDiagram
 
 class sax_t ["json::sax_t"] {
     <<interface>>
@@ -49,4 +49,4 @@ class sax_t ["json::sax_t"] {
 
 // called when a parse error occurs; byte position, the last token, and an exception is passed
 bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex);
-
 
The return value of each function determines whether parsing should proceed.
 
To implement your own SAX handler, proceed as follows:
 
     
  1. Implement the SAX interface in a class. You can use class nlohmann::json_sax<json> as base class, but you can also use any class where the functions described above are implemented and public.
    2.  
  2. Create an object of your SAX interface class, e.g. my_sax.
    3.  
  3. Call bool json::sax_parse(input, &my_sax); where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
    4.  
 
Note the sax_parse function only returns a bool indicating the result of the last executed SAX event. It does not return json value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your parse_error implementation. Internally, the SAX interface is used for the DOM parser (class json_sax_dom_parser) as well as the acceptor (json_sax_acceptor), see file json_sax.hpp.
 
See also
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +

The return value of each function determines whether parsing should proceed.

To implement your own SAX handler, proceed as follows:

  1. Implement the SAX interface in a class. You can use class nlohmann::json_sax<json> as base class, but you can also use any class where the functions described above are implemented and public.
  2. Create an object of your SAX interface class, e.g. my_sax.
  3. Call bool json::sax_parse(input, &my_sax); where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.

Note the sax_parse function only returns a bool indicating the result of the last executed SAX event. It does not return json value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your parse_error implementation. Internally, the SAX interface is used for the DOM parser (class json_sax_dom_parser) as well as the acceptor (json_sax_acceptor), see file json_sax.hpp.

See also

\ No newline at end of file diff --git a/features/serialization/index.html b/features/serialization/index.html index d47460f1d..74e5f72be 100644 --- a/features/serialization/index.html +++ b/features/serialization/index.html @@ -1,4 +1,4 @@ - Serialization - JSON for Modern C++
Skip to content

Serialization

Serialization is the process of turning a JSON value back into JSON text. It is the counterpart to parsing. The central function is dump, which returns the JSON text as a string.

json j = {{"pi", 3.141}, {"happy", true}};
+ Serialization - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Serialization
 
Serialization is the process of turning a JSON value back into JSON text. It is the counterpart to parsing. The central function is dump, which returns the JSON text as a string.
 
json j = {{"pi", 3.141}, {"happy", true}};
 
 std::string s = j.dump();   // {"happy":true,"pi":3.141}
 
 
To write a value directly to a stream (for example, a file or std::cout), the operator<< is provided:
 
std::cout << j << std::endl;
@@ -138,4 +138,4 @@
 
  
 
Avoiding invalid UTF-8
 
The best fix is to ensure that all strings are UTF-8 encoded before storing them. See the FAQ on non-ASCII characters for how to convert wide or Latin-1 strings.
 
 
Numbers, NaN, and binary values
 
     
  • Numbers are serialized with enough precision to round-trip; see number serialization.
    •  
  • NaN and infinity cannot be represented in JSON and are serialized as null; see NaN handling. The binary formats can preserve them.
    •  
  • Binary values have no JSON representation and are serialized as a helper object for debugging only; see binary values.
    •  
 
Using std::format, std::print, and fmt
 
Since version 3.12.0, JSON values can be formatted directly with C++20's std::format whenever the standard library provides the <format> header (controlled by JSON_HAS_STD_FORMAT). This is enabled by the std::formatter<basic_json> specialization, which also makes JSON values work with std::format_to and with C++23's std::print/std::println:
 
std::print("{}", j);      // compact, like j.dump()
 std::print("{:2}", j);    // pretty-printed with indent 2 (like j.dump(2))
 std::println("{:#}", j);  // pretty-printed with the default indent
-
 
The format spec mirrors the dump parameters: "{:#}" pretty-prints, a width such as "{:2}" sets the indent, and a fill-and-align prefix such as "{:.>#}" sets the indent character.
 
For the {fmt} library, the library ships a format_as helper. Note its behavior depends on the fmt version; see the FAQ entry for the details and a recipe for a full fmt::formatter specialization.
 
Serializing to other formats
 
Besides JSON text, a value can also be serialized to the more compact binary formats (BJData, BSON, CBOR, MessagePack, UBJSON).
 
See also
    
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

The format spec mirrors the dump parameters: "{:#}" pretty-prints, a width such as "{:2}" sets the indent, and a fill-and-align prefix such as "{:.>#}" sets the indent character.

For the {fmt} library, the library ships a format_as helper. Note its behavior depends on the fmt version; see the FAQ entry for the details and a recipe for a full fmt::formatter specialization.

Serializing to other formats

Besides JSON text, a value can also be serialized to the more compact binary formats (BJData, BSON, CBOR, MessagePack, UBJSON).

See also

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/trailing_commas/index.html b/features/trailing_commas/index.html index 079b3bc58..11153a78d 100644 --- a/features/trailing_commas/index.html +++ b/features/trailing_commas/index.html @@ -1,4 +1,4 @@ - Trailing Commas - JSON for Modern C++
Skip to content

Trailing Commas

Like comments, this library does not support trailing commas in arrays and objects by default.

You can set parameter ignore_trailing_commas to true in the parse function to allow trailing commas in arrays and objects. Note that a single comma as the only content of the array or object ([,] or {,}) is not allowed, and multiple trailing commas ([1,,]) are not allowed either.

This library does not add trailing commas when serializing JSON data.

For more information, see JSON With Commas and Comments (JWCC).

Example

Consider the following JSON with trailing commas.

{
+ Trailing Commas - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Trailing Commas
 
Like comments, this library does not support trailing commas in arrays and objects by default.
 
You can set parameter ignore_trailing_commas to true in the parse function to allow trailing commas in arrays and objects. Note that a single comma as the only content of the array or object ([,] or {,}) is not allowed, and multiple trailing commas ([1,,]) are not allowed either.
 
This library does not add trailing commas when serializing JSON data.
 
For more information, see JSON With Commas and Comments (JWCC).
 
 
Example
 
Consider the following JSON with trailing commas.
 
{
     "planets": [
         "Mercury",
         "Venus",
@@ -58,4 +58,4 @@
     "Neptune"
   ]
 }
-
 
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/features/types/index.html b/features/types/index.html index c9f21bf08..e627809ee 100644 --- a/features/types/index.html +++ b/features/types/index.html @@ -1,4 +1,4 @@ - Types - JSON for Modern C++
Skip to content

Types

This page gives an overview of how JSON values are stored and how this can be configured.

Overview

By default, JSON values are stored as follows:

JSON type C++ type
object std::map<std::string, basic_json>
array std::vector<basic_json>
null std::nullptr_t
string std::string
boolean bool
number std::int64_t, std::uint64_t, and double

Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.

Storage

classDiagram
+ Types - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Types
 
This page gives an overview of how JSON values are stored and how this can be configured.
 
Overview
 
By default, JSON values are stored as follows:
 
  
 JSON type C++ type 
   
 object std::map<std::string, basic_json> 
 
 array std::vector<basic_json> 
 
 null std::nullptr_t 
 
 string std::string 
 
 boolean bool 
 
 number std::int64_t, std::uint64_t, and double 
  
 
Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.
 
Storage
 
classDiagram
 
 class value_t {
     <<enumeration>>
@@ -80,4 +80,4 @@ basic_json .. value_t
 
Template arguments<
   basic_json, // value_type
   std::allocator<basic_json> // allocator_type
 >
-

Limits

RFC 8259 specifies:

An implementation may set limits on the maximum depth of nesting.

In this class, the array's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the max_size function of a JSON array.

Storage

Arrays are stored as pointers in a basic_json type. That is, for any access to array values, a pointer of type array_t* must be dereferenced.

Strings

RFC 8259 describes JSON strings as follows:

A string is a sequence of zero or more Unicode characters.

Unicode values are split by the JSON class into byte-sized characters during deserialization.

Default type

With the default values for StringType (std::string), the default value for string_t is std::string.

Encoding

Strings are stored in UTF-8 encoding. Therefore, functions like std::string::size() or std::string::length() return the number of bytes in the string rather than the number of characters or glyphs.

String comparison

RFC 8259 states:

Software implementations are typically required to test names of object members for equality. Implementations that transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, code unit by code unit are interoperable in the sense that implementations will agree in all cases on equality or inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not equal.

This implementation is interoperable as it does compare strings code unit by code unit.

Storage

String values are stored as pointers in a basic_json type. That is, for any access to string values, a pointer of type string_t* must be dereferenced.

Booleans

RFC 8259 implicitly describes a boolean as a type which differentiates the two literals true and false.

Default type

With the default values for BooleanType (bool), the default value for boolean_t is bool.

Storage

Boolean values are stored directly inside a basic_json type.

Numbers

See the number handling article for a detailed discussion on how numbers are handled by this library.

RFC 8259 describes numbers as follows:

The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.

This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is known whether the number is a signed integer, an unsigned integer, or a floating-point number. Therefore, three different types, number_integer_t, number_unsigned_t, and number_float_t are used.

Default types

With the default values for NumberIntegerType (std::int64_t), the default value for number_integer_t is std::int64_t. With the default values for NumberUnsignedType (std::uint64_t), the default value for number_unsigned_t is std::uint64_t. With the default values for NumberFloatType (double), the default value for number_float_t is double.

Default behavior

  • The restrictions about leading zeros are not enforced in C++. Instead, leading zeros in integer literals lead to an interpretation as an octal number. Internally, the value will be stored as a decimal number. For instance, the C++ integer literal 010 will be serialized to 8. During deserialization, leading zeros yield an error.
  • Not-a-number (NaN) values will be serialized to null.

Limits

RFC 8259 specifies:

An implementation may set limits on the range and precision of numbers.

When the default type is used, the maximal integer number that can be stored is 9223372036854775807 (INT64_MAX) and the minimal integer number that can be stored is -9223372036854775808 (INT64_MIN). Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored as number_unsigned_t or number_float_t.

When the default type is used, the maximal unsigned integer number that can be stored is 18446744073709551615 (UINT64_MAX) and the minimal integer number that can be stored is 0. Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored as number_integer_t or number_float_t.

RFC 8259 further states:

Note that when such software is used, numbers that are integers and are in the range [-2^{53}+1, 2^{53}-1] are interoperable in the sense that implementations will agree exactly on their numeric values.

As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is interoperable.

RFC 8259 states:

This specification allows implementations to set limits on the range and precision of numbers accepted. Since software that implements IEEE 754-2008 binary64 (double precision) numbers is generally available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide, in the sense that implementations will approximate JSON numbers within the expected precision.

This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values smaller than -1.79769313486232e+308 and values greater than 1.79769313486232e+308 will be stored as NaN internally and be serialized to null.

Storage

Integer number values, unsigned integer number values, and floating-point number values are stored directly inside a basic_json type.

\ No newline at end of file +

Limits

RFC 8259 specifies:

An implementation may set limits on the maximum depth of nesting.

In this class, the array's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the max_size function of a JSON array.

Storage

Arrays are stored as pointers in a basic_json type. That is, for any access to array values, a pointer of type array_t* must be dereferenced.

Strings

RFC 8259 describes JSON strings as follows:

A string is a sequence of zero or more Unicode characters.

Unicode values are split by the JSON class into byte-sized characters during deserialization.

Default type

With the default values for StringType (std::string), the default value for string_t is std::string.

Encoding

Strings are stored in UTF-8 encoding. Therefore, functions like std::string::size() or std::string::length() return the number of bytes in the string rather than the number of characters or glyphs.

String comparison

RFC 8259 states:

Software implementations are typically required to test names of object members for equality. Implementations that transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, code unit by code unit are interoperable in the sense that implementations will agree in all cases on equality or inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not equal.

This implementation is interoperable as it does compare strings code unit by code unit.

Storage

String values are stored as pointers in a basic_json type. That is, for any access to string values, a pointer of type string_t* must be dereferenced.

Booleans

RFC 8259 implicitly describes a boolean as a type which differentiates the two literals true and false.

Default type

With the default values for BooleanType (bool), the default value for boolean_t is bool.

Storage

Boolean values are stored directly inside a basic_json type.

Numbers

See the number handling article for a detailed discussion on how numbers are handled by this library.

RFC 8259 describes numbers as follows:

The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.

This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is known whether the number is a signed integer, an unsigned integer, or a floating-point number. Therefore, three different types, number_integer_t, number_unsigned_t, and number_float_t are used.

Default types

With the default values for NumberIntegerType (std::int64_t), the default value for number_integer_t is std::int64_t. With the default values for NumberUnsignedType (std::uint64_t), the default value for number_unsigned_t is std::uint64_t. With the default values for NumberFloatType (double), the default value for number_float_t is double.

Default behavior

Limits

RFC 8259 specifies:

An implementation may set limits on the range and precision of numbers.

When the default type is used, the maximal integer number that can be stored is 9223372036854775807 (INT64_MAX) and the minimal integer number that can be stored is -9223372036854775808 (INT64_MIN). Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored as number_unsigned_t or number_float_t.

When the default type is used, the maximal unsigned integer number that can be stored is 18446744073709551615 (UINT64_MAX) and the minimal integer number that can be stored is 0. Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will automatically be stored as number_integer_t or number_float_t.

RFC 8259 further states:

Note that when such software is used, numbers that are integers and are in the range [-2^{53}+1, 2^{53}-1] are interoperable in the sense that implementations will agree exactly on their numeric values.

As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is interoperable.

RFC 8259 states:

This specification allows implementations to set limits on the range and precision of numbers accepted. Since software that implements IEEE 754-2008 binary64 (double precision) numbers is generally available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide, in the sense that implementations will approximate JSON numbers within the expected precision.

This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values smaller than -1.79769313486232e+308 and values greater than 1.79769313486232e+308 will be stored as NaN internally and be serialized to null.

Storage

Integer number values, unsigned integer number values, and floating-point number values are stored directly inside a basic_json type.

\ No newline at end of file diff --git a/features/types/number_handling/index.html b/features/types/number_handling/index.html index 1ff375d29..77b43706b 100644 --- a/features/types/number_handling/index.html +++ b/features/types/number_handling/index.html @@ -1,4 +1,4 @@ - Number Handling - JSON for Modern C++
Skip to content

Number Handling

This document describes how the library is handling numbers.

Background

This section briefly summarizes how the JSON specification describes how numbers should be handled.

JSON number syntax

JSON defines the syntax of numbers as follows:

RFC 8259, Section 6

The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed.

A fraction part is a decimal point followed by one or more digits.

An exponent part begins with the letter E in uppercase or lowercase, which may be followed by a plus or minus sign. The E and optional sign are followed by one or more digits.

The following railroad diagram from json.org visualizes the number syntax:

Syntax for JSON numbers

Number interoperability

On number interoperability, the following remarks are made:

RFC 8259, Section 6

This specification allows implementations to set limits on the range and precision of numbers accepted. Since software that implements IEEE 754 binary64 (double precision) numbers [IEEE754] is generally available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide, in the sense that implementations will approximate JSON numbers within the expected precision. A JSON number such as 1E400 or 3.141592653589793238462643383279 may indicate potential interoperability problems, since it suggests that the software that created it expects receiving software to have greater capabilities for numeric magnitude and precision than is widely available.

Note that when such software is used, numbers that are integers and are in the range [-2^{53}+1, 2^{53}-1] are interoperable in the sense that implementations will agree exactly on their numeric values.

Library implementation

This section describes how this library implements the above number specification.

Number storage

In the default json type, numbers are stored as std::uint64_t, std::int64_t, and double, respectively. Thereby, std::uint64_t and std::int64_t are used only if they can store the number without loss of precision. If this is impossible (e.g., if the number is too large), the number is stored as double.

Positive integers are stored as std::uint64_t, while negative integers are stored as std::int64_t. This distinction is determined at parse time: if the JSON number has a leading minus sign, it uses signed integer storage; otherwise, it uses unsigned integer storage.

Notes

Examples

  • Integer -12345678912345789123456789 is smaller than INT64_MIN and will be stored as floating-point number -1.2345678912345788e+25.
  • Integer 1E3 will be stored as floating-point number 1000.0.

Number limits

  • Any 64-bit signed or unsigned integer can be stored without loss of precision.
  • Numbers exceeding the limits of double (i.e., numbers that after conversion via std::strtod are not satisfying std::isfinite such as 1E400) will throw exception json.exception.out_of_range.406 during parsing.
  • Floating-point numbers are rounded to the next number representable as double. For instance 3.141592653589793238462643383279 is stored as 0x400921fb54442d18. This is the same behavior as the code double x = 3.141592653589793238462643383279;.

Interoperability

  • The library is interoperable with respect to the specification, because its supported range [-2^{63}, 2^{64}-1] is larger than the described range [-2^{53}+1, 2^{53}-1].
  • All integers outside the range [-2^{63}, 2^{64}-1], as well as floating-point numbers are stored as double. This also concurs with the specification above.

Zeros

The JSON number grammar allows for different ways to express zero, and this library will store zeros differently:

Literal Stored value and type Serialization
0 std::uint64_t(0) 0
-0 std::int64_t(0) 0
0.0 double(0.0) 0.0
-0.0 double(-0.0) -0.0
0E0 double(0.0) 0.0
-0E0 double(-0.0) -0.0

That is, -0 is stored as a signed integer, but the serialization does not reproduce the -.

Number serialization

  • Integer numbers are serialized as is; that is, no scientific notation is used.
  • Floating-point numbers are serialized as specified by the %g printf modifier with std::numeric_limits<double>::max_digits10 significant digits. The rationale is to use the shortest representation while still allowing round-tripping.

Notes regarding precision of floating-point numbers

As described above, floating-point numbers are rounded to the nearest double and serialized with the shortest representation to allow round-tripping. This can yield confusing examples:

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/architecture/index.html b/home/architecture/index.html index 33a9f7ecf..730a59a8d 100644 --- a/home/architecture/index.html +++ b/home/architecture/index.html @@ -1,4 +1,4 @@ - Architecture - JSON for Modern C++
Skip to content

Architecture

Info

This page is still under construction. Its goal is to provide a high-level overview of the library's architecture. This should help new contributors to get an idea of the used concepts and where to make changes.

Overview

The main structure is class nlohmann::basic_json.

  • public API
  • container interface
  • iterators

Template specializations

Value storage

Values are stored as a tagged union of value_t and json_value.

/// the type of the current element
+ Architecture - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Architecture
 
 
Info
 
This page is still under construction. Its goal is to provide a high-level overview of the library's architecture. This should help new contributors to get an idea of the used concepts and where to make changes.
 
 
Overview
 
The main structure is class nlohmann::basic_json.
 
     
  • public API
    •  
  • container interface
    •  
  • iterators
    •  
 
Template specializations
  
Value storage
 
Values are stored as a tagged union of value_t and json_value.
 
/// the type of the current element
 value_t m_type = value_t::null;
 
 /// the value of the current element
@@ -52,4 +52,4 @@
 
 template<class T>
 void from_json(const basic_json& j, T& t);
-
 
Additional features
 
     
  • JSON Pointers
    •  
  • Binary formats
    •  
  • Custom base class
    •  
  • Conversion macros
    •  
 
Details namespace
 
     
  • C++ feature backports
    •  
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

Additional features

  • JSON Pointers
  • Binary formats
  • Custom base class
  • Conversion macros

Details namespace

  • C++ feature backports
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/customers/index.html b/home/customers/index.html index 695c36118..6a703b055 100644 --- a/home/customers/index.html +++ b/home/customers/index.html @@ -1 +1 @@ - Customers - JSON for Modern C++
Skip to content

Customers

The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know.

Space Exploration

  • Peregrine Lunar Lander Flight 01 - The library was used for payload management in the Peregrine Moon Lander, developed by Astrobotic Technology and launched as part of NASA's Commercial Lunar Payload Services (CLPS) program. After six days in orbit, the spacecraft was intentionally redirected into Earth's atmosphere, where it burned up over the Pacific Ocean on January 18, 2024.

Automotive

Gaming and Entertainment

  • Assassin's Creed: Mirage, a stealth-action game set in the Middle East, focusing on the journey of a young assassin with classic parkour and stealth mechanics
  • Chasm: The Rift, a first-person shooter blending horror and adventure, where players navigate dark realms and battle monsters
  • College Football 25, a college football simulation game featuring gameplay that mimics real-life college teams and competitions
  • Concepts, a digital sketching app designed for creative professionals, offering flexible drawing tools for illustration, design, and brainstorming
  • Depthkit, a tool for creating and capturing volumetric video, enabling immersive 3D experiences and interactive content
  • IMG.LY, a platform offering creative tools and SDKs for integrating advanced image and video editing in applications
  • LOOT, a tool for optimizing the load order of game plugins, commonly used in The Elder Scrolls and Fallout series
  • Madden NFL 25, a sports simulation game capturing the excitement of American football with realistic gameplay and team management features
  • Marne, an unofficial private server platform for hosting custom Battlefield 1 game experiences
  • Minecraft, a popular sandbox video game
  • NHL 22, a hockey simulation game offering realistic gameplay, team management, and various modes to enhance the hockey experience
  • Pixelpart, a 2D animation and video compositing software that allows users to create animated graphics and visual effects with a focus on simplicity and ease of use
  • Razer Cortex, a gaming performance optimizer and system booster designed to enhance the gaming experience
  • Red Dead Redemption II, an open-world action-adventure game following an outlaw's story in the late 1800s, emphasizing deep storytelling and immersive gameplay
  • Snapchat, a multimedia messaging and augmented reality app for communication and entertainment
  • Tactics Ogre: Reborn, a tactical role-playing game featuring strategic battles and deep storytelling elements
  • Throne and Liberty, an MMORPG that offers an expansive fantasy world with dynamic gameplay and immersive storytelling
  • Unity Vivox, a communication service that enables voice and text chat functionality in multiplayer games developed with Unity
  • Zool: Redimensioned, a modern reimagining of the classic platformer featuring fast-paced gameplay and vibrant environments
  • immersivetech, a technology company focused on immersive experiences, providing tools and solutions for virtual and augmented reality applications

Consumer Electronics

  • Audinate, a provider of networked audio solutions specializing in Dante technology, which facilitates high-quality digital audio transport over IP networks
  • Canon CanoScan LIDE, a series of flatbed scanners offering high-resolution image scanning for home and office use
  • Canon PIXMA Printers, a line of all-in-one inkjet printers known for high-quality printing and wireless connectivity
  • Cisco Webex Desk Camera, a video camera designed for professional-quality video conferencing and remote collaboration
  • Philips Hue Personal Wireless Lighting, a smart lighting system for customizable and wireless home illumination
  • Ray-Ban Meta Smart glasses, a pair of smart glasses designed for capturing photos and videos with integrated connectivity and social features
  • Razer Synapse, a unified configuration software enabling hardware customization for Razer devices
  • Siemens SINEMA Remote Connect, a remote connectivity solution for monitoring and managing industrial networks and devices securely
  • Sony PlayStation 4, a gaming console developed by Sony that offers a wide range of games and multimedia entertainment features
  • Sony Virtual Webcam Driver for Remote Camera, a software driver that enables the use of Sony cameras as virtual webcams for video conferencing and streaming

Operating Systems

  • Apple iOS and macOS, a family of operating systems developed by Apple, including iOS for mobile devices and macOS for desktop computers
  • Google Fuchsia, an open-source operating system developed by Google, designed to be secure, updatable, and adaptable across various devices
  • SerenityOS, an open-source operating system that aims to provide a simple and beautiful user experience with a focus on simplicity and elegance
  • Yocto, a Linux-based build system for creating custom operating systems and software distributions, tailored for embedded devices and IoT applications

Development Tools and IDEs

  • Accentize SpectralBalance, an adaptive speech analysis tool designed to enhance audio quality by optimizing frequency balance in recordings
  • Arm Compiler for Linux, a software development toolchain for compiling and optimizing applications on Arm-based Linux systems
  • BBEdit, a professional text and code editor for macOS
  • CoderPad, a collaborative coding platform that enables real-time code interviews and assessments for developers; the library is included in every CoderPad instance and can be accessed with a simple #include "json.hpp"
  • Compiler Explorer, a web-based tool that allows users to write, compile, and visualize the assembly output of code in various programming languages; the library is readily available and accessible with the directive #include <nlohmann/json.hpp>.
  • GitHub CodeQL, a code analysis tool used for identifying security vulnerabilities and bugs in software through semantic queries
  • Hex-Rays, a reverse engineering toolset for analyzing and decompiling binaries, primarily used for security research and vulnerability analysis
  • ImHex, a hex editor designed for reverse engineering, providing advanced features for data analysis and manipulation
  • Intel GPA Framework, a suite of cross-platform tools for capturing, analyzing, and optimizing graphics applications across different APIs
  • Intopix, a provider of advanced image processing and compression solutions used in software development and AV workflows
  • Java SE, the core Java platform that provides the libraries and runtime needed to build and run general-purpose Java applications
  • MKVToolNix, a set of tools for creating, editing, and inspecting MKV (Matroska) multimedia container files
  • Meta Yoga, a layout engine that facilitates flexible and efficient user interface design across multiple platforms
  • NVIDIA Nsight Compute, a performance analysis tool for CUDA applications that provides detailed insights into GPU performance metrics
  • Notepad++, a free source code editor that supports various programming languages
  • OpenRGB, an open source RGB lighting control that doesn't depend on manufacturer software
  • OpenTelemetry C++, a library for collecting and exporting observability data in C++, enabling developers to implement distributed tracing and metrics in their application
  • Qt Creator, an IDE for developing applications using the Qt application framework
  • Scanbot SDK, a software development kit (SDK) that provides tools for integrating advanced document scanning and barcode scanning capabilities into applications

Machine Learning and AI

  • Apple Core ML Tools, a set of tools for converting and configuring machine learning models for deployment in Apple's Core ML framework
  • Avular Mobile Robotics, a platform for developing and deploying mobile robotics solutions
  • Google gemma.cpp, a lightweight C++ inference engine designed for running AI models from the Gemma family
  • llama.cpp, a C++ library designed for efficient inference of large language models (LLMs), enabling streamlined integration into applications
  • MLX, an array framework for machine learning on Apple Silicon
  • Mozilla llamafile, a tool designed for distributing and executing large language models (LLMs) efficiently using a single file format
  • NVIDIA ACE, a suite of real-time AI solutions designed for the development of interactive avatars and digital human applications, enabling scalable and sophisticated user interactions
  • Peer, a platform offering personalized AI assistants for interactive learning and creative collaboration
  • stable-diffusion.cpp, a C++ implementation of the Stable Diffusion image generation model
  • TanvasTouch, a software development kit (SDK) that enables developers to create tactile experiences on touchscreens, allowing users to feel textures and physical sensations in a digital environment
  • TensorFlow, a machine learning framework that facilitates the development and training of models, supporting data serialization and efficient data exchange between components

Scientific Research and Analysis

  • BLACK, a bounded linear temporal logic (LTL) satisfiability checker
  • CERN Atlas Athena, a software framework used in the ATLAS experiment at the Large Hadron Collider (LHC) for performance monitoring
  • ICU, the International Components for Unicode, a mature library for software globalization and multilingual support
  • KAMERA, a platform for synchronized data collection and real-time deep learning to map marine species like polar bears and seals, aiding Arctic ecosystem research
  • KiCad, a free and open-source software suite for electronic design automation
  • Maple, a symbolic and numeric computing environment for advanced mathematical modeling and analysis
  • MeVisLab, a software framework for medical image processing and visualization.
  • OpenPMD API, a versatile programming interface for accessing and managing scientific data, designed to facilitate the efficient storage, retrieval, and sharing of simulation data across various applications and platforms
  • ParaView, an open-source tool for large-scale data visualization and analysis across various scientific domains
  • QGIS, a free and open-source geographic information system (GIS) application that allows users to create, edit, visualize, and analyze geospatial data across a variety of formats
  • VTK, a software library for 3D computer graphics, image processing, and visualization
  • VolView, a lightweight application for interactive visualization and analysis of 3D medical imaging data.

Business and Productivity Software

  • ArcGIS PRO, a desktop geographic information system (GIS) application developed by Esri for mapping and spatial analysis
  • Autodesk Desktop, a software platform developed by Autodesk for creating and managing desktop applications and services
  • Check Point, a cybersecurity company specializing in threat prevention and network security solutions, offering a range of products designed to protect enterprises from cyber threats and ensure data integrity
  • Microsoft Office for Mac, a suite of productivity applications developed by Microsoft for macOS, including tools for word processing, spreadsheets, and presentations
  • Microsoft Teams, a team collaboration application offering workspace chat and video conferencing, file storage, and integration of proprietary and third-party applications and services
  • Nexthink Infinity, a digital employee experience management platform for monitoring and improving IT performance
  • Sophos Connect Client, a secure VPN client from Sophos that allows remote users to connect to their corporate network, ensuring secure access to resources and data
  • Stonebranch, a cloud-based cybersecurity solution that integrates backup, disaster recovery, and cybersecurity features to protect data and ensure business continuity for organizations
  • Tablecruncher, a data analysis tool that allows users to import, analyze, and visualize spreadsheet data, offering interactive features for better insights and decision-making
  • magicplan, a mobile application for creating floor plans and interior designs using augmented reality

Databases and Big Data

  • ADIOS2, a data management framework designed for high-performance input and output operations
  • Cribl Stream, a real-time data processing platform that enables organizations to collect, route, and transform observability data, enhancing visibility and insights into their systems
  • DB Browser for SQLite, a visual open-source tool for creating, designing, and editing SQLite database files
  • MySQL Connector/C++, a C++ library for connecting and interacting with MySQL databases
  • MySQL NDB Cluster, a distributed database system that provides high availability and scalability for MySQL databases
  • MySQL Shell, an advanced client and code editor for interacting with MySQL servers, supporting SQL, Python, and JavaScript
  • PrestoDB, a distributed SQL query engine designed for large-scale data analytics, originally developed by Facebook
  • ROOT Data Analysis Framework, an open-source data analysis framework widely used in high-energy physics and other fields for data processing and visualization
  • WiredTiger, a high-performance storage engine for databases, offering support for compression, concurrency, and checkpointing

Simulation and Modeling

  • Arcturus HoloSuite, a software toolset for capturing, editing, and streaming volumetric video, featuring advanced compression technologies for high-quality 3D content creation
  • azul, a fast and efficient 3D city model viewer designed for visualizing urban environments and spatial data
  • Blender, a free and open-source 3D creation suite for modeling, animation, rendering, and more
  • cpplot, a library for creating interactive graphs and charts in C++, which can be viewed in web browsers
  • Foundry Nuke, a powerful node-based digital compositing and visual effects application used in film and television post-production
  • GAMS, a high-performance mathematical modeling system for optimization and decision support
  • Kitware SMTK, a software toolkit for managing simulation models and workflows in scientific and engineering applications
  • M-Star, a computational fluid dynamics software for simulating and analyzing fluid flow
  • MapleSim CAD Toolbox, a software extension for MapleSim that integrates CAD models, allowing users to import, manipulate, and analyze 3D CAD data within the MapleSim environment for enhanced modeling and simulation
  • NVIDIA Omniverse, a platform for 3D content creation and collaboration that enables real-time simulations and interactive experiences across various industries
  • Pixar Renderman, a photorealistic 3D rendering software developed by Pixar, widely used in the film industry for creating high-quality visual effects and animations
  • ROS - Robot Operating System, a set of software libraries and tools that assist in developing robot applications
  • UBS, a multinational financial services and banking company

Enterprise and Cloud Applications

  • Acronis Cyber Protect Cloud, an all-in-one data protection solution that combines backup, disaster recovery, and cybersecurity to safeguard business data from threats like ransomware
  • Baereos, a backup solution that provides data protection and recovery options for various environments, including physical and virtual systems
  • Bitdefender Home Scanner, a tool from Bitdefender that scans devices for malware and security threats, providing a safeguard against potential online dangers
  • Citrix Provisioning, a solution that streamlines the delivery of virtual desktops and applications by allowing administrators to manage and provision resources efficiently across multiple environments
  • Citrix Virtual Apps and Desktops, a solution from Citrix that delivers virtual apps and desktops
  • Cyberarc, a security solution that specializes in privileged access management, enabling organizations to control and monitor access to critical systems and data, thereby enhancing overall cybersecurity posture
  • Egnyte Desktop, a secure cloud storage solution designed for businesses, enabling file sharing, collaboration, and data management across teams while ensuring compliance and data protection
  • Elster, a digital platform developed by German tax authorities for secure and efficient electronic tax filing and management using secunet protect4use
  • Ethereum Solidity, a high-level, object-oriented programming language designed for implementing smart contracts on the Ethereum platform
  • Inciga, a monitoring tool for IT infrastructure, designed to provide insights into system performance and availability through customizable dashboards and alerts
  • Intel Accelerator Management Daemon for VMware ESXi, a management tool designed for monitoring and controlling Intel hardware accelerators within VMware ESXi environments, optimizing performance and resource allocation
  • Juniper Identity Management Service
  • Microsoft Azure IoT SDK, a collection of tools and libraries to help developers connect, build, and deploy Internet of Things (IoT) solutions on the Azure cloud platform
  • Microsoft WinGet, a command-line utility included in the Windows Package Manager
  • plexusAV, a high-performance AV-over-IP transceiver device capable of video encoding and decoding using the IPMX standard
  • Pointr, a platform for indoor positioning and navigation solutions, offering tools and SDKs for developers to create location-based applications
  • secunet protect4use, a secure, passwordless multifactor authentication solution that transforms smartphones into digital keyrings, ensuring high security for online services and digital identities
  • Sencore MRD 7000, a professional multi-channel receiver and decoder supporting UHD and HD stream decoding
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Customers - JSON for Modern C++
Skip to content

Customers

The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know.

Space Exploration

  • Peregrine Lunar Lander Flight 01 - The library was used for payload management in the Peregrine Moon Lander, developed by Astrobotic Technology and launched as part of NASA's Commercial Lunar Payload Services (CLPS) program. After six days in orbit, the spacecraft was intentionally redirected into Earth's atmosphere, where it burned up over the Pacific Ocean on January 18, 2024.

Automotive

Gaming and Entertainment

  • Assassin's Creed: Mirage, a stealth-action game set in the Middle East, focusing on the journey of a young assassin with classic parkour and stealth mechanics
  • Chasm: The Rift, a first-person shooter blending horror and adventure, where players navigate dark realms and battle monsters
  • College Football 25, a college football simulation game featuring gameplay that mimics real-life college teams and competitions
  • Concepts, a digital sketching app designed for creative professionals, offering flexible drawing tools for illustration, design, and brainstorming
  • Depthkit, a tool for creating and capturing volumetric video, enabling immersive 3D experiences and interactive content
  • IMG.LY, a platform offering creative tools and SDKs for integrating advanced image and video editing in applications
  • LOOT, a tool for optimizing the load order of game plugins, commonly used in The Elder Scrolls and Fallout series
  • Madden NFL 25, a sports simulation game capturing the excitement of American football with realistic gameplay and team management features
  • Marne, an unofficial private server platform for hosting custom Battlefield 1 game experiences
  • Minecraft, a popular sandbox video game
  • NHL 22, a hockey simulation game offering realistic gameplay, team management, and various modes to enhance the hockey experience
  • Pixelpart, a 2D animation and video compositing software that allows users to create animated graphics and visual effects with a focus on simplicity and ease of use
  • Razer Cortex, a gaming performance optimizer and system booster designed to enhance the gaming experience
  • Red Dead Redemption II, an open-world action-adventure game following an outlaw's story in the late 1800s, emphasizing deep storytelling and immersive gameplay
  • Snapchat, a multimedia messaging and augmented reality app for communication and entertainment
  • Tactics Ogre: Reborn, a tactical role-playing game featuring strategic battles and deep storytelling elements
  • Throne and Liberty, an MMORPG that offers an expansive fantasy world with dynamic gameplay and immersive storytelling
  • Unity Vivox, a communication service that enables voice and text chat functionality in multiplayer games developed with Unity
  • Zool: Redimensioned, a modern reimagining of the classic platformer featuring fast-paced gameplay and vibrant environments
  • immersivetech, a technology company focused on immersive experiences, providing tools and solutions for virtual and augmented reality applications

Consumer Electronics

  • Audinate, a provider of networked audio solutions specializing in Dante technology, which facilitates high-quality digital audio transport over IP networks
  • Canon CanoScan LIDE, a series of flatbed scanners offering high-resolution image scanning for home and office use
  • Canon PIXMA Printers, a line of all-in-one inkjet printers known for high-quality printing and wireless connectivity
  • Cisco Webex Desk Camera, a video camera designed for professional-quality video conferencing and remote collaboration
  • Philips Hue Personal Wireless Lighting, a smart lighting system for customizable and wireless home illumination
  • Ray-Ban Meta Smart glasses, a pair of smart glasses designed for capturing photos and videos with integrated connectivity and social features
  • Razer Synapse, a unified configuration software enabling hardware customization for Razer devices
  • Siemens SINEMA Remote Connect, a remote connectivity solution for monitoring and managing industrial networks and devices securely
  • Sony PlayStation 4, a gaming console developed by Sony that offers a wide range of games and multimedia entertainment features
  • Sony Virtual Webcam Driver for Remote Camera, a software driver that enables the use of Sony cameras as virtual webcams for video conferencing and streaming

Operating Systems

  • Apple iOS and macOS, a family of operating systems developed by Apple, including iOS for mobile devices and macOS for desktop computers
  • Google Fuchsia, an open-source operating system developed by Google, designed to be secure, updatable, and adaptable across various devices
  • SerenityOS, an open-source operating system that aims to provide a simple and beautiful user experience with a focus on simplicity and elegance
  • Yocto, a Linux-based build system for creating custom operating systems and software distributions, tailored for embedded devices and IoT applications

Development Tools and IDEs

  • Accentize SpectralBalance, an adaptive speech analysis tool designed to enhance audio quality by optimizing frequency balance in recordings
  • Arm Compiler for Linux, a software development toolchain for compiling and optimizing applications on Arm-based Linux systems
  • BBEdit, a professional text and code editor for macOS
  • CoderPad, a collaborative coding platform that enables real-time code interviews and assessments for developers; the library is included in every CoderPad instance and can be accessed with a simple #include "json.hpp"
  • Compiler Explorer, a web-based tool that allows users to write, compile, and visualize the assembly output of code in various programming languages; the library is readily available and accessible with the directive #include <nlohmann/json.hpp>.
  • GitHub CodeQL, a code analysis tool used for identifying security vulnerabilities and bugs in software through semantic queries
  • Hex-Rays, a reverse engineering toolset for analyzing and decompiling binaries, primarily used for security research and vulnerability analysis
  • ImHex, a hex editor designed for reverse engineering, providing advanced features for data analysis and manipulation
  • Intel GPA Framework, a suite of cross-platform tools for capturing, analyzing, and optimizing graphics applications across different APIs
  • Intopix, a provider of advanced image processing and compression solutions used in software development and AV workflows
  • Java SE, the core Java platform that provides the libraries and runtime needed to build and run general-purpose Java applications
  • MKVToolNix, a set of tools for creating, editing, and inspecting MKV (Matroska) multimedia container files
  • Meta Yoga, a layout engine that facilitates flexible and efficient user interface design across multiple platforms
  • NVIDIA Nsight Compute, a performance analysis tool for CUDA applications that provides detailed insights into GPU performance metrics
  • Notepad++, a free source code editor that supports various programming languages
  • OpenRGB, an open source RGB lighting control that doesn't depend on manufacturer software
  • OpenTelemetry C++, a library for collecting and exporting observability data in C++, enabling developers to implement distributed tracing and metrics in their application
  • Qt Creator, an IDE for developing applications using the Qt application framework
  • Scanbot SDK, a software development kit (SDK) that provides tools for integrating advanced document scanning and barcode scanning capabilities into applications

Machine Learning and AI

  • Apple Core ML Tools, a set of tools for converting and configuring machine learning models for deployment in Apple's Core ML framework
  • Avular Mobile Robotics, a platform for developing and deploying mobile robotics solutions
  • Google gemma.cpp, a lightweight C++ inference engine designed for running AI models from the Gemma family
  • llama.cpp, a C++ library designed for efficient inference of large language models (LLMs), enabling streamlined integration into applications
  • MLX, an array framework for machine learning on Apple Silicon
  • Mozilla llamafile, a tool designed for distributing and executing large language models (LLMs) efficiently using a single file format
  • NVIDIA ACE, a suite of real-time AI solutions designed for the development of interactive avatars and digital human applications, enabling scalable and sophisticated user interactions
  • Peer, a platform offering personalized AI assistants for interactive learning and creative collaboration
  • stable-diffusion.cpp, a C++ implementation of the Stable Diffusion image generation model
  • TanvasTouch, a software development kit (SDK) that enables developers to create tactile experiences on touchscreens, allowing users to feel textures and physical sensations in a digital environment
  • TensorFlow, a machine learning framework that facilitates the development and training of models, supporting data serialization and efficient data exchange between components

Scientific Research and Analysis

  • BLACK, a bounded linear temporal logic (LTL) satisfiability checker
  • CERN Atlas Athena, a software framework used in the ATLAS experiment at the Large Hadron Collider (LHC) for performance monitoring
  • ICU, the International Components for Unicode, a mature library for software globalization and multilingual support
  • KAMERA, a platform for synchronized data collection and real-time deep learning to map marine species like polar bears and seals, aiding Arctic ecosystem research
  • KiCad, a free and open-source software suite for electronic design automation
  • Maple, a symbolic and numeric computing environment for advanced mathematical modeling and analysis
  • MeVisLab, a software framework for medical image processing and visualization.
  • OpenPMD API, a versatile programming interface for accessing and managing scientific data, designed to facilitate the efficient storage, retrieval, and sharing of simulation data across various applications and platforms
  • ParaView, an open-source tool for large-scale data visualization and analysis across various scientific domains
  • QGIS, a free and open-source geographic information system (GIS) application that allows users to create, edit, visualize, and analyze geospatial data across a variety of formats
  • VTK, a software library for 3D computer graphics, image processing, and visualization
  • VolView, a lightweight application for interactive visualization and analysis of 3D medical imaging data.

Business and Productivity Software

  • ArcGIS PRO, a desktop geographic information system (GIS) application developed by Esri for mapping and spatial analysis
  • Autodesk Desktop, a software platform developed by Autodesk for creating and managing desktop applications and services
  • Check Point, a cybersecurity company specializing in threat prevention and network security solutions, offering a range of products designed to protect enterprises from cyber threats and ensure data integrity
  • Microsoft Office for Mac, a suite of productivity applications developed by Microsoft for macOS, including tools for word processing, spreadsheets, and presentations
  • Microsoft Teams, a team collaboration application offering workspace chat and video conferencing, file storage, and integration of proprietary and third-party applications and services
  • Nexthink Infinity, a digital employee experience management platform for monitoring and improving IT performance
  • Sophos Connect Client, a secure VPN client from Sophos that allows remote users to connect to their corporate network, ensuring secure access to resources and data
  • Stonebranch, a cloud-based cybersecurity solution that integrates backup, disaster recovery, and cybersecurity features to protect data and ensure business continuity for organizations
  • Tablecruncher, a data analysis tool that allows users to import, analyze, and visualize spreadsheet data, offering interactive features for better insights and decision-making
  • magicplan, a mobile application for creating floor plans and interior designs using augmented reality

Databases and Big Data

  • ADIOS2, a data management framework designed for high-performance input and output operations
  • Cribl Stream, a real-time data processing platform that enables organizations to collect, route, and transform observability data, enhancing visibility and insights into their systems
  • DB Browser for SQLite, a visual open-source tool for creating, designing, and editing SQLite database files
  • MySQL Connector/C++, a C++ library for connecting and interacting with MySQL databases
  • MySQL NDB Cluster, a distributed database system that provides high availability and scalability for MySQL databases
  • MySQL Shell, an advanced client and code editor for interacting with MySQL servers, supporting SQL, Python, and JavaScript
  • PrestoDB, a distributed SQL query engine designed for large-scale data analytics, originally developed by Facebook
  • ROOT Data Analysis Framework, an open-source data analysis framework widely used in high-energy physics and other fields for data processing and visualization
  • WiredTiger, a high-performance storage engine for databases, offering support for compression, concurrency, and checkpointing

Simulation and Modeling

  • Arcturus HoloSuite, a software toolset for capturing, editing, and streaming volumetric video, featuring advanced compression technologies for high-quality 3D content creation
  • azul, a fast and efficient 3D city model viewer designed for visualizing urban environments and spatial data
  • Blender, a free and open-source 3D creation suite for modeling, animation, rendering, and more
  • cpplot, a library for creating interactive graphs and charts in C++, which can be viewed in web browsers
  • Foundry Nuke, a powerful node-based digital compositing and visual effects application used in film and television post-production
  • GAMS, a high-performance mathematical modeling system for optimization and decision support
  • Kitware SMTK, a software toolkit for managing simulation models and workflows in scientific and engineering applications
  • M-Star, a computational fluid dynamics software for simulating and analyzing fluid flow
  • MapleSim CAD Toolbox, a software extension for MapleSim that integrates CAD models, allowing users to import, manipulate, and analyze 3D CAD data within the MapleSim environment for enhanced modeling and simulation
  • NVIDIA Omniverse, a platform for 3D content creation and collaboration that enables real-time simulations and interactive experiences across various industries
  • Pixar Renderman, a photorealistic 3D rendering software developed by Pixar, widely used in the film industry for creating high-quality visual effects and animations
  • ROS - Robot Operating System, a set of software libraries and tools that assist in developing robot applications
  • UBS, a multinational financial services and banking company

Enterprise and Cloud Applications

  • Acronis Cyber Protect Cloud, an all-in-one data protection solution that combines backup, disaster recovery, and cybersecurity to safeguard business data from threats like ransomware
  • Baereos, a backup solution that provides data protection and recovery options for various environments, including physical and virtual systems
  • Bitdefender Home Scanner, a tool from Bitdefender that scans devices for malware and security threats, providing a safeguard against potential online dangers
  • Citrix Provisioning, a solution that streamlines the delivery of virtual desktops and applications by allowing administrators to manage and provision resources efficiently across multiple environments
  • Citrix Virtual Apps and Desktops, a solution from Citrix that delivers virtual apps and desktops
  • Cyberarc, a security solution that specializes in privileged access management, enabling organizations to control and monitor access to critical systems and data, thereby enhancing overall cybersecurity posture
  • Egnyte Desktop, a secure cloud storage solution designed for businesses, enabling file sharing, collaboration, and data management across teams while ensuring compliance and data protection
  • Elster, a digital platform developed by German tax authorities for secure and efficient electronic tax filing and management using secunet protect4use
  • Ethereum Solidity, a high-level, object-oriented programming language designed for implementing smart contracts on the Ethereum platform
  • Inciga, a monitoring tool for IT infrastructure, designed to provide insights into system performance and availability through customizable dashboards and alerts
  • Intel Accelerator Management Daemon for VMware ESXi, a management tool designed for monitoring and controlling Intel hardware accelerators within VMware ESXi environments, optimizing performance and resource allocation
  • Juniper Identity Management Service
  • Microsoft Azure IoT SDK, a collection of tools and libraries to help developers connect, build, and deploy Internet of Things (IoT) solutions on the Azure cloud platform
  • Microsoft WinGet, a command-line utility included in the Windows Package Manager
  • plexusAV, a high-performance AV-over-IP transceiver device capable of video encoding and decoding using the IPMX standard
  • Pointr, a platform for indoor positioning and navigation solutions, offering tools and SDKs for developers to create location-based applications
  • secunet protect4use, a secure, passwordless multifactor authentication solution that transforms smartphones into digital keyrings, ensuring high security for online services and digital identities
  • Sencore MRD 7000, a professional multi-channel receiver and decoder supporting UHD and HD stream decoding
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/debugging/index.html b/home/debugging/index.html index e65066bfa..077c08f10 100644 --- a/home/debugging/index.html +++ b/home/debugging/index.html @@ -1 +1 @@ - Debugging - JSON for Modern C++
Skip to content

Debugging

This page collects the library's built-in debugger integrations and other debugging-related features. They are not linked from a single place elsewhere in the docs, so are collected here.

Visual Studio (natvis)

The repository ships nlohmann_json.natvis at its root, a Natvis file that gives json/ordered_json values a friendly, key/value debugger view instead of showing raw internal fields, when debugging with the MSVC debug engine (cppvsdbg) in Visual Studio or VS Code.

Debug engines that wrap LLDB instead of the MSVC debug engine (for example, codelldb in VS Code) only have partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the .natvis file present. Switching to cppvsdbg where available, or checking your debug extension's own Natvis support/version, are the next things to try if this happens. There is currently no bundled LLDB-native pretty-printer script in this repository.

GDB

The repository ships a GDB Python pretty printer under tools/gdb_pretty_printer, with its own usage instructions in that directory's README.md.

Extended exception diagnostics

Defining JSON_DIAGNOSTICS before including the library augments type_error/out_of_range-style exceptions with a JSON Pointer to the offending value, which can help pinpoint where in a large document a runtime error occurred. This only applies to exceptions thrown after a value exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not covered by this mechanism -- see Parsing and exceptions for how parse errors report their own location instead.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Debugging - JSON for Modern C++
Skip to content

Debugging

This page collects the library's built-in debugger integrations and other debugging-related features. They are not linked from a single place elsewhere in the docs, so are collected here.

Visual Studio (natvis)

The repository ships nlohmann_json.natvis at its root, a Natvis file that gives json/ordered_json values a friendly, key/value debugger view instead of showing raw internal fields, when debugging with the MSVC debug engine (cppvsdbg) in Visual Studio or VS Code.

Debug engines that wrap LLDB instead of the MSVC debug engine (for example, codelldb in VS Code) only have partial/experimental Natvis support, and commonly fall back to showing raw internal fields even with the .natvis file present. Switching to cppvsdbg where available, or checking your debug extension's own Natvis support/version, are the next things to try if this happens. There is currently no bundled LLDB-native pretty-printer script in this repository.

GDB

The repository ships a GDB Python pretty printer under tools/gdb_pretty_printer, with its own usage instructions in that directory's README.md.

Extended exception diagnostics

Defining JSON_DIAGNOSTICS before including the library augments type_error/out_of_range-style exceptions with a JSON Pointer to the offending value, which can help pinpoint where in a large document a runtime error occurred. This only applies to exceptions thrown after a value exists (e.g. during element access); parse errors, which happen before any value exists to point at, are not covered by this mechanism -- see Parsing and exceptions for how parse errors report their own location instead.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/design_goals/index.html b/home/design_goals/index.html index 6761b5fbe..4f06d50ac 100644 --- a/home/design_goals/index.html +++ b/home/design_goals/index.html @@ -1 +1 @@ - Design goals - JSON for Modern C++
Skip to content

Design goals

There are myriads of JSON libraries out there, and each may even have its reason to exist. Our class had these design goals:

  • Intuitive syntax. In languages such as Python, JSON feels like a first-class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code.

  • Trivial integration. Our whole code consists of a single header file json.hpp. That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.

  • Serious testing. Our class is heavily unit-tested and covers 100% of the code, including all exceptional behavior. Furthermore, we checked with Valgrind and the Clang Sanitizers that there are no memory leaks. Google OSS-Fuzz additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the Core Infrastructure Initiative (CII) best practices.

Other aspects were not so important to us:

  • Memory efficiency. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). The default generalization uses the following C++ data types: std::string for strings, int64_t, uint64_t or double for numbers, std::map for objects, std::vector for arrays, and bool for Booleans. However, you can template the generalized class basic_json to your needs.

  • Speed. There are certainly faster JSON libraries out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a std::vector or std::map, you are already set.

See the contribution guidelines for more information.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Design goals - JSON for Modern C++
Skip to content

Design goals

There are myriads of JSON libraries out there, and each may even have its reason to exist. Our class had these design goals:

  • Intuitive syntax. In languages such as Python, JSON feels like a first-class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code.

  • Trivial integration. Our whole code consists of a single header file json.hpp. That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.

  • Serious testing. Our class is heavily unit-tested and covers 100% of the code, including all exceptional behavior. Furthermore, we checked with Valgrind and the Clang Sanitizers that there are no memory leaks. Google OSS-Fuzz additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the Core Infrastructure Initiative (CII) best practices.

Other aspects were not so important to us:

  • Memory efficiency. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). The default generalization uses the following C++ data types: std::string for strings, int64_t, uint64_t or double for numbers, std::map for objects, std::vector for arrays, and bool for Booleans. However, you can template the generalized class basic_json to your needs.

  • Speed. There are certainly faster JSON libraries out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a std::vector or std::map, you are already set.

See the contribution guidelines for more information.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/exceptions/index.html b/home/exceptions/index.html index ccc2e0a0c..918498fcb 100644 --- a/home/exceptions/index.html +++ b/home/exceptions/index.html @@ -1,4 +1,4 @@ - Exceptions - JSON for Modern C++
Skip to content

Exceptions

Overview

Base type

All exceptions inherit from class json::exception (which in turn inherits from std::exception). It is used as the base class for all exceptions thrown by the basic_json class. This class can hence be used as "wildcard" to catch exceptions.

classDiagram
+ Exceptions - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Exceptions
 
Overview
 
Base type
 
All exceptions inherit from class json::exception (which in turn inherits from std::exception). It is used as the base class for all exceptions thrown by the basic_json class. This class can hence be used as "wildcard" to catch exceptions.
 
classDiagram
   direction LR
     class `std::exception` {
         <<interface>>
@@ -290,4 +290,4 @@ array index 18446744073709551616 exceeds size_type
 
 
Output:
 
message: [json.exception.other_error.501] unsuccessful: {"op":"test","path":"/best_biscuit/name","value":"Choco Leibniz"}
 exception id: 501
 
  
json.exception.other_error.501
 
A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.
 
 
Example message
 
Executing {"op":"test", "path":"/baz", "value":"bar"} on {"baz": "qux"}:
 
[json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
-
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file +
\ No newline at end of file diff --git a/home/faq/index.html b/home/faq/index.html index b880a7549..72da2fdf1 100644 --- a/home/faq/index.html +++ b/home/faq/index.html @@ -1,4 +1,4 @@ - FAQ - JSON for Modern C++
Skip to content

Frequently Asked Questions (FAQ)

Known bugs

Brace initialization yields arrays

Question

Why does

json j{true};
+ FAQ - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Frequently Asked Questions (FAQ)
 
Known bugs
 
Brace initialization yields arrays
 
 
Question
 
Why does
 
json j{true};
 
 
and
 
json j(true);
 
 
yield different results ([true] vs. true)?
 
 
This is a known issue, and -- even worse -- the behavior differs between GCC and Clang. The "culprit" for this is the library's constructor overloads for initializer lists to allow syntax like
 
json array = {1, 2, 3, 4};
 
 
for arrays and
 
json object = {{"one", 1}, {"two", 2}}; 
@@ -34,4 +34,4 @@
 
 
Using JSON values with std::format or fmt
 
 
Question
 
     
  • Can I use std::format("{}", j) on a JSON value?
    •  
  • Can I use fmt::format("{}", j) or fmt::print("{}", j) (the {fmt} library) on a JSON value?
    •  
 
 
std::format works out of the box since version 3.13.0, as long as the standard library provides <format> (see JSON_HAS_STD_FORMAT); see std::formatter<basic_json> for details, including the "{:#}" pretty-print spec, indent widths ("{:2}"), and custom indent characters ("{:.>#}").
 
For fmt, the library ships format_as, a small customization point fmt looks for via argument-dependent lookup. It only has an effect on fmt 10.0.0 through 11.0.2 — from fmt 11.1.0 onwards, fmt no longer picks up a format_as overload that returns a std::string. On such versions (or any version, if you also want the same "{:#}"/width/fill-and-align spec support that std::formatter<basic_json> has), define your own fmt::formatter specialization; see format_as for a recipe that mirrors it.
 
If you get ambiguous-overload errors when passing a JSON value to fmt::format/fmt::print without any fmt::formatter<json> specialization in scope, that's fmt picking up basic_json's implicit operator ValueType() conversion operator (see #964 and #958); disabling it via JSON_USE_IMPLICIT_CONVERSIONS 0 avoids the ambiguity.
 
Compilation issues
 
Android SDK
 
 
Question
 
Why does the code not compile with Android SDK?
 
 
Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your Application.mk. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
 
APP_STL := c++_shared
 NDK_TOOLCHAIN_VERSION := clang3.6
 APP_CPPFLAGS += -frtti -fexceptions
-
 
The code compiles successfully with Android NDK, Revision 9 - 11 (and possibly later) and CrystaX's Android NDK version 10.
 
Missing STL function
 
 
Questions
 
     
  • Why do I get a compilation error 'to_string' is not a member of 'std' (or similarly, for strtod or strtof)?
    •  
  • Why does the code not compile with MinGW or Android SDK?
    •  
 
 
This is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to this site and this discussion for information on how to fix this bug. For Android NDK using APP_STL := gnustl_static, please refer to this discussion.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

The code compiles successfully with Android NDK, Revision 9 - 11 (and possibly later) and CrystaX's Android NDK version 10.

Missing STL function

Questions

  • Why do I get a compilation error 'to_string' is not a member of 'std' (or similarly, for strtod or strtof)?
  • Why does the code not compile with MinGW or Android SDK?

This is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to this site and this discussion for information on how to fix this bug. For Android NDK using APP_STL := gnustl_static, please refer to this discussion.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/license/index.html b/home/license/index.html index e9fced8ca..38201acff 100644 --- a/home/license/index.html +++ b/home/license/index.html @@ -1 +1 @@ - License - JSON for Modern C++
Skip to content

License

The class is licensed under the MIT License:

Copyright © 2013-2026 Niels Lohmann

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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed under the MIT License (see above). Copyright © 2008-2009 Björn Hoehrmann bjoern@hoehrmann.de

The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the MIT License (see above). Copyright © 2009 Florian Loitsch

The class contains a copy of Hedley from Evan Nemerson which is licensed as CC0-1.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + License - JSON for Modern C++
Skip to content

License

The class is licensed under the MIT License:

Copyright © 2013-2026 Niels Lohmann

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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The class contains the UTF-8 Decoder from Bjoern Hoehrmann which is licensed under the MIT License (see above). Copyright © 2008-2009 Björn Hoehrmann bjoern@hoehrmann.de

The class contains a slightly modified version of the Grisu2 algorithm from Florian Loitsch which is licensed under the MIT License (see above). Copyright © 2009 Florian Loitsch

The class contains a copy of Hedley from Evan Nemerson which is licensed as CC0-1.0.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/releases/index.html b/home/releases/index.html index 09e587d4d..709b32556 100644 --- a/home/releases/index.html +++ b/home/releases/index.html @@ -1 +1 @@ - Releases - JSON for Modern C++
Skip to content

Releases

This page summarizes the notable changes of every release and links to the relevant documentation. The complete release notes — including all changes, the download files, and their checksums — are published on the GitHub releases page.

v3.12.0 (2025-04-11)

Fixes bugs found in 3.11.3 and adds several features. All changes are backward-compatible.

Full release notes.

v3.11.3 (2023-11-28)

Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible.

  • Adds a custom base class as a node customization point.
  • Adds serialization-only conversion macros (NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE and NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE) and a clearer parse error for empty input.
  • Adds Bazel and Swift Package Manager build support.
  • Fixes custom allocators, a memory leak in adl_serializer's to_json, initializer-list construction when size_type is not int, and many compiler warnings.

Full release notes.

v3.11.2 (2022-08-12)

Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible.

  • Fixes the value function (broken for strings, size types, and nullptr in 3.11.0) and makes json_fwd.hpp self-contained.
  • Restores using json_pointer as a key in associative containers and comparing it with strings.
  • Restructures the inline namespace and allows disabling the version component, and avoids heap allocations in the BJData parser.

Full release notes.

v3.11.1 (2022-08-01)

Fixes a regression from 3.11.0. All changes are backward-compatible.

Full release notes.

v3.11.0 (2022-08-01)

One of the largest releases ever. All changes are backward-compatible.

This release introduced a UDL regression that was fixed in 3.11.1. Full release notes.

v3.10.5 (2022-01-03)

Bug-fix release. All changes are backward-compatible.

  • Guards the std::filesystem conversions behind compiler-support checks (JSON_HAS_FILESYSTEM), which can be set to 0 to disable them altogether.

Full release notes.

v3.10.4 (2021-10-16)

Fixes regressions introduced in 3.10.0. All changes are backward-compatible.

  • Fixes the std::filesystem::path conversion (which could trigger a stack overflow and broke compilation on Windows).
  • Fixes compilation for types with an explicit defaulted constructor and for code relying on the return values of std::find and std::remove.

Full release notes.

v3.10.3 (2021-10-08)

Fixes more regressions from 3.10.0. All changes are backward-compatible.

  • Fixes extended-diagnostics assertions triggered by update and by inserting into arrays.
  • Supports custom allocators when writing binary formats into a std::vector, and allows conversion from types that only provide begin()/end().

Full release notes.

v3.10.2 (2021-08-26)

Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. All changes are backward-compatible. Full release notes.

v3.10.1 (2021-08-24)

Fixes a regression from 3.10.0. All changes are backward-compatible.

Full release notes.

v3.10.0 (2021-08-17)

Feature release. All changes are backward-compatible.

  • Adds extended diagnostic messages (JSON_DIAGNOSTICS) that prepend a JSON pointer to exception messages to pinpoint the offending value.
  • Adds a GDB pretty-printer and a cbor_tag_handler_t store option to keep CBOR tags as binary subtypes.
  • Supports containers with non-default-constructible types and parsing from std::byte.
  • Adds JSON_NO_IO to exclude the I/O headers and the JSON_HAS_CPP_* macros to override the detected C++ standard.

Full release notes.

v3.9.1 (2020-08-06)

Fixes two regressions from 3.9.0. All changes are backward-compatible.

Full release notes.

v3.9.0 (2020-07-27)

Feature release adding four long-requested features. All changes are backward-compatible.

Full release notes.

v3.8.0 (2020-06-14)

Feature release. All changes are backward-compatible.

  • Introduces a binary value type that is read from and written to CBOR, BSON, and MessagePack, and can be shared between formats.
  • Generalizes the input adapters to read from any LegacyInputIterator container (3–10 % faster parsing).
  • Fixes contains for JSON pointers and makes the binary from_cbor/from_msgpack/etc. functions respect allow_exceptions.

Full release notes.

v3.7.3 (2019-11-17)

Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes are backward-compatible. Full release notes.

v3.7.2 (2019-11-10)

Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing is now bounded only by available memory. All changes are backward-compatible. Full release notes.

v3.7.1 (2019-11-06)

Bug-fix release. All changes are backward-compatible.

  • Fixes a segmentation fault when serializing the std::int64_t minimum value and fixes contains for JSON pointers.
  • Allows items with a custom string type and makes json_pointer::back const.

Full release notes.

v3.7.0 (2019-07-28)

Convenience features and house-keeping. All changes are backward-compatible.

  • Adds a contains overload that checks a JSON pointer without throwing, a generic to_string, and a return value for emplace_back.

Full release notes.

v3.6.1 (2019-03-20)

Fixes a regression (GCC 7/8 compilation) and a <Windows.h> build error introduced in 3.6.0. All changes are backward-compatible. Full release notes.

v3.6.0 (2019-03-20)

Feature release. All changes are backward-compatible.

  • Reworks the JSON pointer interface (operator/, push_back, parent_pointer, …).
  • Adds a contains function to test for an object key and greatly improves the performance of integer serialization.

Full release notes.

v3.5.0 (2018-12-22)

Feature release. All changes are backward-compatible.

  • Adds structured-binding support via the items function and reading from FILE* in the parse function.
  • Fixes the eofbit handling on input streams and a bug in the BSON SAX parser.

Full release notes.

v3.4.0 (2018-10-30)

Feature release. All changes are backward-compatible.

Full release notes.

v3.3.0 (2018-10-05)

Feature release. All changes are backward-compatible.

  • Adds GCC 4.8 support, the get_to function, and an overhauled and documented CMake integration.

Full release notes.

v3.2.0 (2018-08-20)

Feature release. All changes are backward-compatible.

  • Adds a SAX interface and a non-recursive parser.
  • Adds parsing from wide-string types (std::wstring, std::u16string, std::u32string) and std::string_view (C++17), and round-tripping of std::map/std::unordered_map with non-string keys.

Full release notes.

v3.1.2 (2018-03-14)

Bug-fix release. All changes are backward-compatible.

  • Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser and serializer.

Full release notes.

v3.1.1 (2018-02-13)

Bug-fix release. All changes are backward-compatible.

  • Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and overflow detection for UBJSON containers.

Full release notes.

v3.1.0 (2018-02-01)

Feature release. All changes are backward-compatible.

Full release notes.

v3.0.1 (2017-12-29)

Fixes small issues in the JSON Pointer and JSON Patch implementations (invalid "copy" targets and non-integer array indices). All changes are backward-compatible. Full release notes.

v3.0.0 (2017-12-17)

First 3.x release — a major release with breaking changes (see the migration guide).

  • Introduces user-defined exceptions (json::exception and subtypes, each with an identifier).
  • Adds a non-throwing accept function and an allow_exceptions flag for parse, and an update function to merge objects.
  • Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
  • Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.

Full release notes.

v2.1.1 (2017-02-25)

Bug-fix release. All changes are backward-compatible.

  • Makes number parsing and serialization locale-independent with correct floating-point round-tripping; released files are now GPG-signed.

Full release notes.

v2.1.0 (2017-01-28)

Feature release. All changes are backward-compatible.

Full release notes.

v2.0.10 (2017-01-02)

Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All changes are backward-compatible. Full release notes.

v2.0.9 (2016-12-16)

Adds the CBOR and MessagePack binary formats. All changes are backward-compatible. Full release notes.

v2.0.8 (2016-12-02)

Adds the emplace and emplace_back functions and improves parsing and serialization performance. All changes are backward-compatible. Full release notes.

v2.0.7 (2016-11-02)

Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding detection, surrogate pairs). All changes are backward-compatible. Full release notes.

v2.0.6 (2016-10-15)

Fixes operator[] for JSON pointers so that it creates missing values like the other overloads. All changes are backward-compatible. Full release notes.

v2.0.5 (2016-09-14)

Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. Full release notes.

v2.0.4 (2016-09-11)

Fixes stream end-of-file detection in the parser. All changes are backward-compatible. Full release notes.

v2.0.3 (2016-08-31)

Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the input-stream constructor in favor of the parse function. All changes are backward-compatible. Full release notes.

v2.0.2 (2016-07-31)

Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and cleans up the code. All changes are backward-compatible. Full release notes.

v2.0.1 (2016-06-28)

Fixes a performance regression in the dump function by adjusting the stream locale once per serialization. All changes are backward-compatible. Full release notes.

v2.0.0 (2016-06-24)

Feature release with a minor (potentially non-backward-compatible) API change from added noexcept and constexpr specifiers.

Full release notes.

v1.1.0 (2016-01-24)

Bug-fix and feature release. All changes are backward-compatible.

  • Improves floating-point round-tripping, adds a get_ref accessor for stored values, and introduces runtime assertions.

Full release notes.

v1.0.0 (2015-12-28)

First official release. Full release notes.

See also

  • Migration Guide — how to future-proof your code for the next major version and replace deprecated functions.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Releases - JSON for Modern C++
Skip to content

Releases

This page summarizes the notable changes of every release and links to the relevant documentation. The complete release notes — including all changes, the download files, and their checksums — are published on the GitHub releases page.

v3.12.0 (2025-04-11)

Fixes bugs found in 3.11.3 and adds several features. All changes are backward-compatible.

Full release notes.

v3.11.3 (2023-11-28)

Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible.

  • Adds a custom base class as a node customization point.
  • Adds serialization-only conversion macros (NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE and NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE) and a clearer parse error for empty input.
  • Adds Bazel and Swift Package Manager build support.
  • Fixes custom allocators, a memory leak in adl_serializer's to_json, initializer-list construction when size_type is not int, and many compiler warnings.

Full release notes.

v3.11.2 (2022-08-12)

Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible.

  • Fixes the value function (broken for strings, size types, and nullptr in 3.11.0) and makes json_fwd.hpp self-contained.
  • Restores using json_pointer as a key in associative containers and comparing it with strings.
  • Restructures the inline namespace and allows disabling the version component, and avoids heap allocations in the BJData parser.

Full release notes.

v3.11.1 (2022-08-01)

Fixes a regression from 3.11.0. All changes are backward-compatible.

Full release notes.

v3.11.0 (2022-08-01)

One of the largest releases ever. All changes are backward-compatible.

This release introduced a UDL regression that was fixed in 3.11.1. Full release notes.

v3.10.5 (2022-01-03)

Bug-fix release. All changes are backward-compatible.

  • Guards the std::filesystem conversions behind compiler-support checks (JSON_HAS_FILESYSTEM), which can be set to 0 to disable them altogether.

Full release notes.

v3.10.4 (2021-10-16)

Fixes regressions introduced in 3.10.0. All changes are backward-compatible.

  • Fixes the std::filesystem::path conversion (which could trigger a stack overflow and broke compilation on Windows).
  • Fixes compilation for types with an explicit defaulted constructor and for code relying on the return values of std::find and std::remove.

Full release notes.

v3.10.3 (2021-10-08)

Fixes more regressions from 3.10.0. All changes are backward-compatible.

  • Fixes extended-diagnostics assertions triggered by update and by inserting into arrays.
  • Supports custom allocators when writing binary formats into a std::vector, and allows conversion from types that only provide begin()/end().

Full release notes.

v3.10.2 (2021-08-26)

Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. All changes are backward-compatible. Full release notes.

v3.10.1 (2021-08-24)

Fixes a regression from 3.10.0. All changes are backward-compatible.

Full release notes.

v3.10.0 (2021-08-17)

Feature release. All changes are backward-compatible.

  • Adds extended diagnostic messages (JSON_DIAGNOSTICS) that prepend a JSON pointer to exception messages to pinpoint the offending value.
  • Adds a GDB pretty-printer and a cbor_tag_handler_t store option to keep CBOR tags as binary subtypes.
  • Supports containers with non-default-constructible types and parsing from std::byte.
  • Adds JSON_NO_IO to exclude the I/O headers and the JSON_HAS_CPP_* macros to override the detected C++ standard.

Full release notes.

v3.9.1 (2020-08-06)

Fixes two regressions from 3.9.0. All changes are backward-compatible.

Full release notes.

v3.9.0 (2020-07-27)

Feature release adding four long-requested features. All changes are backward-compatible.

Full release notes.

v3.8.0 (2020-06-14)

Feature release. All changes are backward-compatible.

  • Introduces a binary value type that is read from and written to CBOR, BSON, and MessagePack, and can be shared between formats.
  • Generalizes the input adapters to read from any LegacyInputIterator container (3–10 % faster parsing).
  • Fixes contains for JSON pointers and makes the binary from_cbor/from_msgpack/etc. functions respect allow_exceptions.

Full release notes.

v3.7.3 (2019-11-17)

Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes are backward-compatible. Full release notes.

v3.7.2 (2019-11-10)

Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing is now bounded only by available memory. All changes are backward-compatible. Full release notes.

v3.7.1 (2019-11-06)

Bug-fix release. All changes are backward-compatible.

  • Fixes a segmentation fault when serializing the std::int64_t minimum value and fixes contains for JSON pointers.
  • Allows items with a custom string type and makes json_pointer::back const.

Full release notes.

v3.7.0 (2019-07-28)

Convenience features and house-keeping. All changes are backward-compatible.

  • Adds a contains overload that checks a JSON pointer without throwing, a generic to_string, and a return value for emplace_back.

Full release notes.

v3.6.1 (2019-03-20)

Fixes a regression (GCC 7/8 compilation) and a <Windows.h> build error introduced in 3.6.0. All changes are backward-compatible. Full release notes.

v3.6.0 (2019-03-20)

Feature release. All changes are backward-compatible.

  • Reworks the JSON pointer interface (operator/, push_back, parent_pointer, …).
  • Adds a contains function to test for an object key and greatly improves the performance of integer serialization.

Full release notes.

v3.5.0 (2018-12-22)

Feature release. All changes are backward-compatible.

  • Adds structured-binding support via the items function and reading from FILE* in the parse function.
  • Fixes the eofbit handling on input streams and a bug in the BSON SAX parser.

Full release notes.

v3.4.0 (2018-10-30)

Feature release. All changes are backward-compatible.

Full release notes.

v3.3.0 (2018-10-05)

Feature release. All changes are backward-compatible.

  • Adds GCC 4.8 support, the get_to function, and an overhauled and documented CMake integration.

Full release notes.

v3.2.0 (2018-08-20)

Feature release. All changes are backward-compatible.

  • Adds a SAX interface and a non-recursive parser.
  • Adds parsing from wide-string types (std::wstring, std::u16string, std::u32string) and std::string_view (C++17), and round-tripping of std::map/std::unordered_map with non-string keys.

Full release notes.

v3.1.2 (2018-03-14)

Bug-fix release. All changes are backward-compatible.

  • Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser and serializer.

Full release notes.

v3.1.1 (2018-02-13)

Bug-fix release. All changes are backward-compatible.

  • Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and overflow detection for UBJSON containers.

Full release notes.

v3.1.0 (2018-02-01)

Feature release. All changes are backward-compatible.

Full release notes.

v3.0.1 (2017-12-29)

Fixes small issues in the JSON Pointer and JSON Patch implementations (invalid "copy" targets and non-integer array indices). All changes are backward-compatible. Full release notes.

v3.0.0 (2017-12-17)

First 3.x release — a major release with breaking changes (see the migration guide).

  • Introduces user-defined exceptions (json::exception and subtypes, each with an identifier).
  • Adds a non-throwing accept function and an allow_exceptions flag for parse, and an update function to merge objects.
  • Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
  • Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.

Full release notes.

v2.1.1 (2017-02-25)

Bug-fix release. All changes are backward-compatible.

  • Makes number parsing and serialization locale-independent with correct floating-point round-tripping; released files are now GPG-signed.

Full release notes.

v2.1.0 (2017-01-28)

Feature release. All changes are backward-compatible.

Full release notes.

v2.0.10 (2017-01-02)

Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All changes are backward-compatible. Full release notes.

v2.0.9 (2016-12-16)

Adds the CBOR and MessagePack binary formats. All changes are backward-compatible. Full release notes.

v2.0.8 (2016-12-02)

Adds the emplace and emplace_back functions and improves parsing and serialization performance. All changes are backward-compatible. Full release notes.

v2.0.7 (2016-11-02)

Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding detection, surrogate pairs). All changes are backward-compatible. Full release notes.

v2.0.6 (2016-10-15)

Fixes operator[] for JSON pointers so that it creates missing values like the other overloads. All changes are backward-compatible. Full release notes.

v2.0.5 (2016-09-14)

Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. Full release notes.

v2.0.4 (2016-09-11)

Fixes stream end-of-file detection in the parser. All changes are backward-compatible. Full release notes.

v2.0.3 (2016-08-31)

Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the input-stream constructor in favor of the parse function. All changes are backward-compatible. Full release notes.

v2.0.2 (2016-07-31)

Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and cleans up the code. All changes are backward-compatible. Full release notes.

v2.0.1 (2016-06-28)

Fixes a performance regression in the dump function by adjusting the stream locale once per serialization. All changes are backward-compatible. Full release notes.

v2.0.0 (2016-06-24)

Feature release with a minor (potentially non-backward-compatible) API change from added noexcept and constexpr specifiers.

Full release notes.

v1.1.0 (2016-01-24)

Bug-fix and feature release. All changes are backward-compatible.

  • Improves floating-point round-tripping, adds a get_ref accessor for stored values, and introduces runtime assertions.

Full release notes.

v1.0.0 (2015-12-28)

First official release. Full release notes.

See also

  • Migration Guide — how to future-proof your code for the next major version and replace deprecated functions.
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/home/sponsors/index.html b/home/sponsors/index.html index f9d046756..2778ed55c 100644 --- a/home/sponsors/index.html +++ b/home/sponsors/index.html @@ -1 +1 @@ - Sponsors - JSON for Modern C++
Skip to content
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + Sponsors - JSON for Modern C++
Skip to content
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/index.html b/index.html index 2c71f0e5f..779631983 100644 --- a/index.html +++ b/index.html @@ -1 +1 @@ - JSON for Modern C++ - JSON for Modern C++
Skip to content

JSON for Modern C++

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file + JSON for Modern C++ - JSON for Modern C++
Skip to content

JSON for Modern C++

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/integration/cmake/index.html b/integration/cmake/index.html index af404d1ca..645948614 100644 --- a/integration/cmake/index.html +++ b/integration/cmake/index.html @@ -1,4 +1,4 @@ - CMake - JSON for Modern C++
Skip to content

CMake

Integration

You can use the nlohmann_json::nlohmann_json interface target in CMake. This target populates the appropriate usage requirements for INTERFACE_INCLUDE_DIRECTORIES to point to the appropriate include directories and INTERFACE_COMPILE_FEATURES for the necessary C++11 flags.

External

To use this library from a CMake project, you can locate it directly with find_package() and use the namespaced imported target from the generated package configuration:

Example

CMakeLists.txt
cmake_minimum_required(VERSION 3.5)
+ CMake - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
CMake
 
Integration
 
You can use the nlohmann_json::nlohmann_json interface target in CMake. This target populates the appropriate usage requirements for INTERFACE_INCLUDE_DIRECTORIES to point to the appropriate include directories and INTERFACE_COMPILE_FEATURES for the necessary C++11 flags.
 
External
 
To use this library from a CMake project, you can locate it directly with find_package() and use the namespaced imported target from the generated package configuration:
 
 
Example
 
CMakeLists.txt
cmake_minimum_required(VERSION 3.5)
 project(ExampleProject LANGUAGES CXX)
 
 find_package(nlohmann_json 3.12.0 REQUIRED)
@@ -55,4 +55,4 @@
 add_executable(myproject main.cpp)
 target_link_libraries(myproject PRIVATE nlohmann_json_modules)
 target_compile_definitions(myproject PRIVATE NLOHMANN_JSON_BUILD_MODULES)
-
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+
Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/integration/index.html b/integration/index.html index 58bde638f..7eaaa407e 100644 --- a/integration/index.html +++ b/integration/index.html @@ -1,5 +1,5 @@ - Header only - JSON for Modern C++
Skip to content

Header only

json.hpp is the single required file in single_include/nlohmann or released here. You need to add

#include <nlohmann/json.hpp>
+ Header only - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Header only
 
json.hpp is the single required file in single_include/nlohmann or released here. You need to add
 
#include <nlohmann/json.hpp>
 
 // for convenience
 using json = nlohmann::json;
-
 
to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., -std=c++11 for GCC and Clang).
 
You can further use file single_include/nlohmann/json_fwd.hpp for forward declarations.
   
 
   
  
 
 
 
 
 
 Copyright © 2013-2026 Niels Lohmann 
 
 
             
 
 
 
 
 
 
 
     
\ No newline at end of file
+

to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., -std=c++11 for GCC and Clang).

You can further use file single_include/nlohmann/json_fwd.hpp for forward declarations.

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/integration/migration_guide/index.html b/integration/migration_guide/index.html index 7f990aa5f..69210191e 100644 --- a/integration/migration_guide/index.html +++ b/integration/migration_guide/index.html @@ -1,4 +1,4 @@ - Migration Guide - JSON for Modern C++
Skip to content

Migration Guide

This page collects some guidelines on how to future-proof your code for future versions of this library.

Replace deprecated functions

The following functions have been deprecated and will be removed in the next major version (i.e., 4.0.0). All deprecations are annotated with HEDLEY_DEPRECATED_FOR to report which function to use instead.

Parsing

Copyright © 2013-2026 Niels Lohmann
\ No newline at end of file diff --git a/integration/package_managers/index.html b/integration/package_managers/index.html index 293830cf6..bbd494f0e 100644 --- a/integration/package_managers/index.html +++ b/integration/package_managers/index.html @@ -1,4 +1,4 @@ - Package Managers - JSON for Modern C++
Skip to content

Package Managers

Homebrew Homebrew nlohmann-json   Meson Meson nlohmann_json   Bazel Bazel nlohmann_json
Conan Conan nlohmann_json   Spack Spack nlohmann-json   Hunter nlohmann_json
vcpkg vcpkg nlohmann-json   cget nlohmann/json   Swift Package Manager Swift Package Manager nlohmann/json
Nuget NuGet nlohmann.json   Conda Conda nlohmann_json   MacPorts MacPorts nlohmann-json
cpm.cmake CPM.cmake gh:nlohmann/json   xmake xmake nlohmann_json

Running example

Throughout this page, we will describe how to compile the example file example.cpp below.

#include <nlohmann/json.hpp>
+ Package Managers - JSON for Modern C++      
 
 
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
       
Package Managers
 
 Homebrew Homebrew nlohmann-json   Meson Meson nlohmann_json   Bazel Bazel nlohmann_json
 Conan Conan nlohmann_json   Spack Spack nlohmann-json   Hunter nlohmann_json
 vcpkg vcpkg nlohmann-json   cget nlohmann/json   Swift Package Manager Swift Package Manager nlohmann/json
 Nuget NuGet nlohmann.json   Conda Conda nlohmann_json   MacPorts MacPorts nlohmann-json
 cpm.cmake CPM.cmake gh:nlohmann/json   xmake xmake nlohmann_json 
 
Running example
 
Throughout this page, we will describe how to compile the example file example.cpp below.
 
#include <nlohmann/json.hpp>
 #include <iostream>
 #include <iomanip>
 
@@ -416,4 +416,4 @@ cmake --build build
     set_languages("cxx11")
 
  
  •  
    Build
     
    xmake
 
     
    •  
  •  
    Run
     
    xmake run
-
     
    •    
     
    Other package managers
     
    The library is also contained in many other package repositories: Packaging status
     
     Package version overview 
    Packaging status
     
     
     
    Buckaroo
     
    If you are using Buckaroo, you can install this library's module with buckaroo add github.com/buckaroo-pm/nlohmann-json. There is a demo repo here.
     
     
    Warning
     
    The module is outdated as the respective repository has not been updated in years.
     
     
    CocoaPods
     
    If you are using CocoaPods, you can use the library by adding pod "nlohmann_json", '~>3.1.2' to your podfile (see an example). Please file issues here.
     
    npm
     
    This project does not publish an official npm package. The npm package nlohmann-json (or similarly named packages) is not maintained or endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.
     
    ESP-IDF and PlatformIO
     
    There is no official package published to the ESP-IDF Component Registry or the PlatformIO Registry. A community-maintained fork, Johboh/nlohmann-json, publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its include/ directory to your component's/project's include paths, like any other integration method described on this page.
     
     
     
    Warning
     
    The module is outdated as the respective pod has not been updated in years.
     
       
     
       
      
     
     
     
     
     
     Copyright © 2013-2026 Niels Lohmann 
     
     
                 
     
     
     
     
     
     
     
         
\ No newline at end of file
+

    Other package managers

    The library is also contained in many other package repositories: Packaging status

    Package version overview

    Packaging status

    Buckaroo

    If you are using Buckaroo, you can install this library's module with buckaroo add github.com/buckaroo-pm/nlohmann-json. There is a demo repo here.

    Warning

    The module is outdated as the respective repository has not been updated in years.

    CocoaPods

    If you are using CocoaPods, you can use the library by adding pod "nlohmann_json", '~>3.1.2' to your podfile (see an example). Please file issues here.

    npm

    This project does not publish an official npm package. The npm package nlohmann-json (or similarly named packages) is not maintained or endorsed by this project. Use one of the package managers listed above, or integrate the single header directly.

    ESP-IDF and PlatformIO

    There is no official package published to the ESP-IDF Component Registry or the PlatformIO Registry. A community-maintained fork, Johboh/nlohmann-json, publishes this library to both registries on each new release and can be used as an unofficial component/package for ESP-IDF and PlatformIO projects. As the library is header-only, it can otherwise be used directly by adding its include/ directory to your component's/project's include paths, like any other integration method described on this page.

    Warning

    The module is outdated as the respective pod has not been updated in years.

    Copyright © 2013-2026 Niels Lohmann
    \ No newline at end of file diff --git a/integration/pkg-config/index.html b/integration/pkg-config/index.html index 2812ca5a5..f9d6588fb 100644 --- a/integration/pkg-config/index.html +++ b/integration/pkg-config/index.html @@ -1,3 +1,3 @@ - Pkg-config - JSON for Modern C++
    Skip to content

    Pkg-config

    If you are using bare Makefiles, you can use pkg-config to generate the include flags that point to where the library is installed:

    pkg-config nlohmann_json --cflags
+ Pkg-config - JSON for Modern C++      
     
     
      
     
      
     
     
     
     
      
     
     
     
     
     
      
     
     
     
     
           
    Pkg-config
     
    If you are using bare Makefiles, you can use pkg-config to generate the include flags that point to where the library is installed:
     
    pkg-config nlohmann_json --cflags
 
     
    Users of the Meson build system will also be able to use a system-wide library, which will be found by pkg-config:
     
    json = dependency('nlohmann_json', required: true)
-
       
     
       
      
     
     
     
     
     
     Copyright © 2013-2026 Niels Lohmann 
     
     
                 
     
     
     
     
     
     
     
         
\ No newline at end of file
+
    Copyright © 2013-2026 Niels Lohmann
    \ No newline at end of file diff --git a/llms.txt b/llms.txt index 881db2621..1bab38143 100644 --- a/llms.txt +++ b/llms.txt @@ -266,6 +266,7 @@ JSON for Modern C++ is a C++11 header-only library implementing a JSON value typ - [Community](https://json.nlohmann.me/community/index.md) - [Code of Conduct](https://json.nlohmann.me/community/code_of_conduct/index.md) - [Contribution Guidelines](https://json.nlohmann.me/community/contribution_guidelines/index.md) +- [Ecosystem](https://json.nlohmann.me/community/ecosystem/index.md) - [Governance](https://json.nlohmann.me/community/governance/index.md) - [Quality assurance](https://json.nlohmann.me/community/quality_assurance/index.md) - [Security Policy](https://json.nlohmann.me/community/security_policy/index.md) diff --git a/search/search_index.json b/search/search_index.json index 96c1c7f54..b9eb252ec 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":""},{"location":"api/json/","title":"nlohmann::json","text":"
    using json = basic_json<>;\n

    This type is the default specialization of the basic_json class which uses the standard template types.

    "},{"location":"api/json/#examples","title":"Examples","text":"Example

    The example below demonstrates how to use the type nlohmann::json.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j =\n    {\n        {\"pi\", 3.141},\n        {\"happy\", true},\n        {\"name\", \"Niels\"},\n        {\"nothing\", nullptr},\n        {\n            \"answer\", {\n                {\"everything\", 42}\n            }\n        },\n        {\"list\", {1, 0, 2}},\n        {\n            \"object\", {\n                {\"currency\", \"USD\"},\n                {\"value\", 42.99}\n            }\n        }\n    };\n\n    // add new values\n    j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n    // count elements\n    auto s = j.size();\n    j[\"size\"] = s;\n\n    // pretty print with indent of 4 spaces\n    std::cout << std::setw(4) << j << '\\n';\n}\n

    Output:

    {\n    \"answer\": {\n        \"everything\": 42\n    },\n    \"happy\": true,\n    \"list\": [\n        1,\n        0,\n        2\n    ],\n    \"name\": \"Niels\",\n    \"new\": {\n        \"key\": {\n            \"value\": [\n                \"another\",\n                \"list\"\n            ]\n        }\n    },\n    \"nothing\": null,\n    \"object\": {\n        \"currency\": \"USD\",\n        \"value\": 42.99\n    },\n    \"pi\": 3.141,\n    \"size\": 8\n}\n
    "},{"location":"api/json/#version-history","title":"Version history","text":"

    Since version 1.0.0.

    "},{"location":"api/operator_gtgt/","title":"nlohmann::operator>>(basic_json)","text":"
    std::istream& operator>>(std::istream& i, basic_json& j);\n

    Deserializes an input stream to a JSON value.

    "},{"location":"api/operator_gtgt/#parameters","title":"Parameters","text":"i (in, out) input stream to read a serialized JSON value from j (in, out) JSON value to write the deserialized input to"},{"location":"api/operator_gtgt/#return-value","title":"Return value","text":"

    the stream i

    "},{"location":"api/operator_gtgt/#exceptions","title":"Exceptions","text":""},{"location":"api/operator_gtgt/#complexity","title":"Complexity","text":"

    Linear in the length of the input. The parser is a predictive LL(1) parser.

    "},{"location":"api/operator_gtgt/#notes","title":"Notes","text":"

    A UTF-8 byte order mark is silently ignored.

    Invalid Unicode escapes and unpaired surrogates in the input are reported as parse_error.101 with a detailed message.

    operator>> parses exactly one JSON value, so it can be called repeatedly to read a sequence of concatenated JSON values from the same stream:

    json j1, j2;\ninput >> j1;  // parses the first value\ninput >> j2;  // parses the next value\n

    A number must be followed by whitespace

    A number is only terminated by the character that follows it. That character is read from the stream to detect the end of the number, and it is not put back. When a value that is a number is immediately followed by the next value, the first character of that next value is lost:

    std::istringstream input(\"1true\");\njson j1, j2;\ninput >> j1;  // j1 == 1\ninput >> j2;  // throws parse_error.101: the stream now starts at \"rue\"\n

    Separating the values with whitespace avoids this, because the character that is eaten is then the separator:

    std::istringstream input(\"1 true\");\njson j1, j2;\ninput >> j1;  // j1 == 1\ninput >> j2;  // j2 == true\n

    Only numbers are affected. Values ending in a self-delimiting character do not read past themselves, so truefalse, [1][2], {\"a\":1}{\"b\":2}, and \"a\"\"b\" can be read back to back without a separator.

    This is tracked in #5340.

    Note that reading concatenated values does not work for JSON Lines (newline-delimited JSON) input -- see that page for why and for the recommended alternative.

    Deprecation

    This function replaces function std::istream& operator<<(basic_json& j, std::istream& i) which has been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like j << i; with i >> j;.

    "},{"location":"api/operator_gtgt/#examples","title":"Examples","text":"Example

    The example below shows how a JSON value is constructed by reading a serialization from a stream.

    #include <iostream>\n#include <iomanip>\n#include <sstream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create stream with serialized JSON\n    std::stringstream ss;\n    ss << R\"({\n        \"number\": 23,\n        \"string\": \"Hello, world!\",\n        \"array\": [1, 2, 3, 4, 5],\n        \"boolean\": false,\n        \"null\": null\n    })\";\n\n    // create JSON value and read the serialization from the stream\n    json j;\n    ss >> j;\n\n    // serialize JSON\n    std::cout << std::setw(2) << j << '\\n';\n}\n

    Output:

    {\n  \"array\": [\n    1,\n    2,\n    3,\n    4,\n    5\n  ],\n  \"boolean\": false,\n  \"null\": null,\n  \"number\": 23,\n  \"string\": \"Hello, world!\"\n}\n
    "},{"location":"api/operator_gtgt/#see-also","title":"See also","text":""},{"location":"api/operator_gtgt/#version-history","title":"Version history","text":""},{"location":"api/operator_literal_json/","title":"nlohmann::operator\"\"_json","text":"
    json operator \"\"_json(const char* s, std::size_t n);\njson operator \"\"_json(const char8_t* s, std::size_t n);  // since C++20\n

    This operator implements a user-defined string literal for JSON objects. It can be used by adding _json to a string literal and returns a json object if no parse error occurred.

    It is recommended to bring the operator into scope using any of the following lines: 

    using nlohmann::literals::operator \"\"_json;\nusing namespace nlohmann::literals;\nusing namespace nlohmann::json_literals;\nusing namespace nlohmann::literals::json_literals;\nusing namespace nlohmann;\n

    This is suggested to ease migration to the next major version release of the library. See JSON_USE_GLOBAL_UDLS for details.

    "},{"location":"api/operator_literal_json/#parameters","title":"Parameters","text":"s (in) a string representation of a JSON object n (in) length of string s"},{"location":"api/operator_literal_json/#return-value","title":"Return value","text":"

    json value parsed from s

    "},{"location":"api/operator_literal_json/#exceptions","title":"Exceptions","text":"

    The function can throw anything that parse(s, s+n) would throw.

    "},{"location":"api/operator_literal_json/#complexity","title":"Complexity","text":"

    Linear.

    "},{"location":"api/operator_literal_json/#examples","title":"Examples","text":"Example

    The following code shows how to create JSON values from string literals.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    json j = R\"( {\"hello\": \"world\", \"answer\": 42} )\"_json;\n\n    std::cout << std::setw(2) << j << '\\n';\n}\n

    Output:

    {\n  \"answer\": 42,\n  \"hello\": \"world\"\n}\n
    "},{"location":"api/operator_literal_json/#see-also","title":"See also","text":""},{"location":"api/operator_literal_json/#version-history","title":"Version history","text":""},{"location":"api/operator_literal_json_pointer/","title":"nlohmann::operator\"\"_json_pointer","text":"
    json_pointer operator \"\"_json_pointer(const char* s, std::size_t n);\njson_pointer operator \"\"_json_pointer(const char8_t* s, std::size_t n);  // since C++20\n

    This operator implements a user-defined string literal for JSON Pointers. It can be used by adding _json_pointer to a string literal and returns a json_pointer object if no parse error occurred.

    It is recommended to bring the operator into scope using any of the following lines: 

    using nlohmann::literals::operator \"\"_json_pointer;\nusing namespace nlohmann::literals;\nusing namespace nlohmann::json_literals;\nusing namespace nlohmann::literals::json_literals;\nusing namespace nlohmann;\n
    This is suggested to ease migration to the next major version release of the library. See JSON_USE_GLOBAL_UDLS for details.

    "},{"location":"api/operator_literal_json_pointer/#parameters","title":"Parameters","text":"s (in) a string representation of a JSON Pointer n (in) length of string s"},{"location":"api/operator_literal_json_pointer/#return-value","title":"Return value","text":"

    json_pointer value parsed from s

    "},{"location":"api/operator_literal_json_pointer/#exceptions","title":"Exceptions","text":"

    The function can throw anything that json_pointer::json_pointer would throw.

    "},{"location":"api/operator_literal_json_pointer/#complexity","title":"Complexity","text":"

    Linear.

    "},{"location":"api/operator_literal_json_pointer/#examples","title":"Examples","text":"Example

    The following code shows how to create JSON Pointers from string literals.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    json j = R\"( {\"hello\": \"world\", \"answer\": 42} )\"_json;\n    auto val = j[\"/hello\"_json_pointer];\n\n    std::cout << std::setw(2) << val << '\\n';\n}\n

    Output:

    \"world\"\n
    "},{"location":"api/operator_literal_json_pointer/#see-also","title":"See also","text":""},{"location":"api/operator_literal_json_pointer/#version-history","title":"Version history","text":""},{"location":"api/operator_ltlt/","title":"nlohmann::operator<<(basic_json), nlohmann::operator<<(json_pointer)","text":"
    std::ostream& operator<<(std::ostream& o, const basic_json& j);      // (1)\n\nstd::ostream& operator<<(std::ostream& o, const json_pointer& ptr);  // (2)\n
    1. Serialize the given JSON value j to the output stream o. The JSON value will be serialized using the dump member function.
      • The indentation of the output can be controlled with the member variable width of the output stream o. For instance, using the manipulator std::setw(4) on o sets the indentation level to 4 and the serialization result is the same as calling dump(4).
      • The indentation character can be controlled with the member variable fill of the output stream o. For instance, the manipulator std::setfill('\\\\t') sets indentation to use a tab character rather than the default space character.
    2. Write a string representation of the given JSON pointer ptr to the output stream o. The string representation is obtained using the to_string member function.
    "},{"location":"api/operator_ltlt/#parameters","title":"Parameters","text":"o (in, out) stream to write to j (in) JSON value to serialize ptr (in) JSON pointer to write"},{"location":"api/operator_ltlt/#return-value","title":"Return value","text":"

    the stream o

    "},{"location":"api/operator_ltlt/#exceptions","title":"Exceptions","text":"
    1. Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded. Note that unlike the dump member functions, no error_handler can be set.
    2. None.
    "},{"location":"api/operator_ltlt/#complexity","title":"Complexity","text":"

    Linear.

    "},{"location":"api/operator_ltlt/#notes","title":"Notes","text":"

    Deprecation

    Function std::ostream& operator<<(std::ostream& o, const basic_json& j) replaces function std::ostream& operator>>(const basic_json& j, std::ostream& o) which has been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like j >> o; with o << j;.

    "},{"location":"api/operator_ltlt/#examples","title":"Examples","text":"Example: (1) serialize JSON value to stream

    The example below shows the serialization with different parameters to width to adjust the indentation level.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_array = {1, 2, 4, 8, 16};\n\n    // serialize without indentation\n    std::cout << j_object << \"\\n\\n\";\n    std::cout << j_array << \"\\n\\n\";\n\n    // serialize with indentation\n    std::cout << std::setw(4) << j_object << \"\\n\\n\";\n    std::cout << std::setw(2) << j_array << \"\\n\\n\";\n    std::cout << std::setw(1) << std::setfill('\\t') << j_object << \"\\n\\n\";\n}\n

    Output:

    {\"one\":1,\"two\":2}\n\n[1,2,4,8,16]\n\n{\n    \"one\": 1,\n    \"two\": 2\n}\n\n[\n  1,\n  2,\n  4,\n  8,\n  16\n]\n\n{\n    \"one\": 1,\n    \"two\": 2\n}\n
    Example: (2) write JSON pointer to stream

    The example below shows how to write a JSON pointer to a stream.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON pointer\n    json::json_pointer ptr(\"/foo/bar/baz\");\n\n    // write string representation to stream\n    std::cout << ptr << std::endl;\n}\n

    Output:

    /foo/bar/baz\n
    "},{"location":"api/operator_ltlt/#see-also","title":"See also","text":""},{"location":"api/operator_ltlt/#version-history","title":"Version history","text":"
    1. Added in version 1.0.0. Added support for indentation character and deprecated std::ostream& operator>>(const basic_json& j, std::ostream& o) in version 3.0.0.
    2. Added in version 3.11.0.
    "},{"location":"api/ordered_json/","title":"nlohmann::ordered_json","text":"
    using ordered_json = basic_json<ordered_map>;\n

    This type preserves the insertion order of object keys.

    "},{"location":"api/ordered_json/#iterator-invalidation","title":"Iterator invalidation","text":"

    The type is based on ordered_map which in turn uses a std::vector to store object elements. Therefore, adding object elements can yield a reallocation in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Also, any iterator or reference after the insertion point will point to the same index, which is now a different value.

    "},{"location":"api/ordered_json/#complexity","title":"Complexity","text":"

    ordered_map has no lookup index: every key-based object operation is a linear scan, so building or parsing an object of n keys costs O(n\u00b2) rather than O(n log n). See ordered_map complexity for the per-operation table and for measured numbers.

    "},{"location":"api/ordered_json/#examples","title":"Examples","text":"Example

    The example below demonstrates how ordered_json preserves the insertion order of object keys.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing ordered_json = nlohmann::ordered_json;\n\nint main()\n{\n    ordered_json j;\n    j[\"one\"] = 1;\n    j[\"two\"] = 2;\n    j[\"three\"] = 3;\n\n    std::cout << j.dump(2) << '\\n';\n}\n

    Output:

    {\n  \"one\": 1,\n  \"two\": 2,\n  \"three\": 3\n}\n
    "},{"location":"api/ordered_json/#see-also","title":"See also","text":""},{"location":"api/ordered_json/#version-history","title":"Version history","text":"

    Since version 3.9.0.

    "},{"location":"api/ordered_map/","title":"nlohmann::ordered_map","text":"
    template<class Key, class T, class IgnoredLess = std::less<Key>,\n         class Allocator = std::allocator<std::pair<const Key, T>>>\nstruct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;\n

    A minimal map-like container that preserves insertion order for use within nlohmann::ordered_json (nlohmann::basic_json<ordered_map>).

    "},{"location":"api/ordered_map/#template-parameters","title":"Template parameters","text":"Key key type T mapped type IgnoredLess comparison function (ignored and only added to ensure compatibility with std::map) Allocator allocator type"},{"location":"api/ordered_map/#iterator-invalidation","title":"Iterator invalidation","text":"

    The type uses a std::vector to store object elements. Therefore, adding elements can yield a reallocation in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

    "},{"location":"api/ordered_map/#member-types","title":"Member types","text":""},{"location":"api/ordered_map/#member-functions","title":"Member functions","text":""},{"location":"api/ordered_map/#complexity","title":"Complexity","text":"

    Because the elements are stored in a std::vector in insertion order, there is no index to look a key up by. Every key-based operation performs a linear scan over the stored elements. With n denoting the number of elements in the container:

    Operation Complexity Note emplace O(n) scans for an existing key, then appends (amortized O(1)) operator[] O(n) delegates to emplace (non-const) or at (const) at O(n) throws std::out_of_range if the key is not found find O(n) count O(n) the result is always 0 or 1 erase(key) O(n) scan, then move the remaining elements one position down erase(pos), erase(first, last) O(n) moves all elements after the erased range insert(value) O(n) equivalent to emplace insert(first, last) O((n + m) * m) for m inserted elements

    This differs from std::map, where the same operations are O(log n).

    Quadratic cost of building large objects

    Because every insertion scans all elements inserted so far, building an object of n distinct keys costs O(n\u00b2) in total. This applies to filling an ordered_json object key by key as well as to parsing one, since the parser inserts each key as it is read.

    The cost is negligible for the object sizes typically found in configuration files or API payloads, but it grows steeply for machine-generated objects with many thousands of keys. Measured with -O2 -DNDEBUG for parsing a flat object of n keys, relative to nlohmann::json (which uses std::map):

    n json ordered_json factor 2000 0.7 ms 3.6 ms 5\u00d7 4000 0.8 ms 14.0 ms 19\u00d7 8000 1.6 ms 67.8 ms 43\u00d7 16 000 3.3 ms 181.6 ms 54\u00d7

    If key order matters for objects of that size, consider a container with a lookup index, such as tsl::ordered_map (integration), as the object type -- see object order.

    "},{"location":"api/ordered_map/#examples","title":"Examples","text":"Example

    The example shows the different behavior of std::map and nlohmann::ordered_map.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\n// simple output function\ntemplate<typename Map>\nvoid output(const char* prefix, const Map& m)\n{\n    std::cout << prefix << \" = { \";\n    for (auto& element : m)\n    {\n        std::cout << element.first << \":\" << element.second << ' ';\n    }\n    std::cout << \"}\" << std::endl;\n}\n\nint main()\n{\n    // create and fill two maps\n    nlohmann::ordered_map<std::string, std::string> m_ordered;\n    m_ordered[\"one\"] = \"eins\";\n    m_ordered[\"two\"] = \"zwei\";\n    m_ordered[\"three\"] = \"drei\";\n\n    std::map<std::string, std::string> m_std;\n    m_std[\"one\"] = \"eins\";\n    m_std[\"two\"] = \"zwei\";\n    m_std[\"three\"] = \"drei\";\n\n    // output: m_ordered is ordered by insertion order, m_std is ordered by key\n    output(\"m_ordered\", m_ordered);\n    output(\"m_std\", m_std);\n\n    // erase and re-add \"one\" key\n    m_ordered.erase(\"one\");\n    m_ordered[\"one\"] = \"eins\";\n\n    m_std.erase(\"one\");\n    m_std[\"one\"] = \"eins\";\n\n    // output: m_ordered shows newly added key at the end; m_std is again ordered by key\n    output(\"m_ordered\", m_ordered);\n    output(\"m_std\", m_std);\n}\n

    Output:

    m_ordered = { one:eins two:zwei three:drei }\nm_std = { one:eins three:drei two:zwei }\nm_ordered = { two:zwei three:drei one:eins }\nm_std = { one:eins three:drei two:zwei }\n
    "},{"location":"api/ordered_map/#see-also","title":"See also","text":""},{"location":"api/ordered_map/#version-history","title":"Version history","text":""},{"location":"api/adl_serializer/","title":"nlohmann::adl_serializer","text":"
    template<typename, typename>\nstruct adl_serializer;\n

    Serializer that uses ADL (Argument-Dependent Lookup) to choose to_json/from_json functions from the types' namespaces.

    It is implemented similarly to

    template<typename ValueType>\nstruct adl_serializer {\n    template<typename BasicJsonType>\n    static void to_json(BasicJsonType& j, const T& value) {\n        // calls the \"to_json\" method in T's namespace\n    }\n\n    template<typename BasicJsonType>\n    static void from_json(const BasicJsonType& j, T& value) {\n        // same thing, but with the \"from_json\" method\n    }\n};\n
    "},{"location":"api/adl_serializer/#member-functions","title":"Member functions","text":""},{"location":"api/adl_serializer/#version-history","title":"Version history","text":""},{"location":"api/adl_serializer/from_json/","title":"nlohmann::adl_serializer::from_json","text":"
    // (1)\ntemplate<typename BasicJsonType, typename TargetType = ValueType>\nstatic auto from_json(BasicJsonType && j, TargetType& val) noexcept(\n    noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))\n-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), val), void())\n\n// (2)\ntemplate<typename BasicJsonType, typename TargetType = ValueType>\nstatic auto from_json(BasicJsonType && j) noexcept(\nnoexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))\n-> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {}))\n

    This function is usually called by the get() function of the basic_json class (either explicitly or via the conversion operators).

    1. This function is chosen for default-constructible value types.
    2. This function is chosen for value types which are not default-constructible.
    "},{"location":"api/adl_serializer/from_json/#parameters","title":"Parameters","text":"j (in) JSON value to read from val (out) value to write to"},{"location":"api/adl_serializer/from_json/#return-value","title":"Return value","text":"
    1. (none) -- the converted value is written to the output parameter val.
    2. the JSON value j converted to TargetType
    "},{"location":"api/adl_serializer/from_json/#examples","title":"Examples","text":"Example: (1) Default-constructible type

    The example below shows how a from_json function can be implemented for a user-defined type. This function is called by the adl_serializer when get<ns::person>() is called.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nnamespace ns\n{\n// a simple struct to model a person\nstruct person\n{\n    std::string name;\n    std::string address;\n    int age;\n};\n} // namespace ns\n\nnamespace ns\n{\nvoid from_json(const json& j, person& p)\n{\n    j.at(\"name\").get_to(p.name);\n    j.at(\"address\").get_to(p.address);\n    j.at(\"age\").get_to(p.age);\n}\n} // namespace ns\n\nint main()\n{\n    json j;\n    j[\"name\"] = \"Ned Flanders\";\n    j[\"address\"] = \"744 Evergreen Terrace\";\n    j[\"age\"] = 60;\n\n    auto p = j.get<ns::person>();\n\n    std::cout << p.name << \" (\" << p.age << \") lives in \" << p.address << std::endl;\n}\n

    Output:

    Ned Flanders (60) lives in 744 Evergreen Terrace\n
    Example: (2) Non-default-constructible type

    The example below shows how a from_json is implemented as part of a specialization of the adl_serializer to realize the conversion of a non-default-constructible type.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nnamespace ns\n{\n// a simple struct to model a person (not default constructible)\nstruct person\n{\n    person(std::string n, std::string a, int aa)\n        : name(std::move(n)), address(std::move(a)), age(aa)\n    {}\n\n    std::string name;\n    std::string address;\n    int age;\n};\n} // namespace ns\n\nnamespace nlohmann\n{\ntemplate <>\nstruct adl_serializer<ns::person>\n{\n    static ns::person from_json(const json& j)\n    {\n        return {j.at(\"name\"), j.at(\"address\"), j.at(\"age\")};\n    }\n\n    // Here's the catch! You must provide a to_json method! Otherwise, you\n    // will not be able to convert person to json, since you fully\n    // specialized adl_serializer on that type\n    static void to_json(json& j, ns::person p)\n    {\n        j[\"name\"] = p.name;\n        j[\"address\"] = p.address;\n        j[\"age\"] = p.age;\n    }\n};\n} // namespace nlohmann\n\nint main()\n{\n    json j;\n    j[\"name\"] = \"Ned Flanders\";\n    j[\"address\"] = \"744 Evergreen Terrace\";\n    j[\"age\"] = 60;\n\n    auto p = j.get<ns::person>();\n\n    std::cout << p.name << \" (\" << p.age << \") lives in \" << p.address << std::endl;\n}\n

    Output:

    Ned Flanders (60) lives in 744 Evergreen Terrace\n
    "},{"location":"api/adl_serializer/from_json/#see-also","title":"See also","text":""},{"location":"api/adl_serializer/from_json/#version-history","title":"Version history","text":""},{"location":"api/adl_serializer/to_json/","title":"nlohmann::adl_serializer::to_json","text":"
    template<typename BasicJsonType, typename TargetType = ValueType>\nstatic auto to_json(BasicJsonType& j, TargetType && val) noexcept(\n    noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))\n-> decltype(::nlohmann::to_json(j, std::forward<TargetType>(val)), void())\n

    This function is usually called by the constructors of the basic_json class.

    "},{"location":"api/adl_serializer/to_json/#parameters","title":"Parameters","text":"j (out) JSON value to write to val (in) value to read from"},{"location":"api/adl_serializer/to_json/#examples","title":"Examples","text":"Example

    The example below shows how a to_json function can be implemented for a user-defined type. This function is called by the adl_serializer when the constructor basic_json(ns::person) is called.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nnamespace ns\n{\n// a simple struct to model a person\nstruct person\n{\n    std::string name;\n    std::string address;\n    int age;\n};\n} // namespace ns\n\nnamespace ns\n{\nvoid to_json(json& j, const person& p)\n{\n    j = json{ {\"name\", p.name}, {\"address\", p.address}, {\"age\", p.age} };\n}\n} // namespace ns\n\nint main()\n{\n    ns::person p = {\"Ned Flanders\", \"744 Evergreen Terrace\", 60};\n\n    json j = p;\n\n    std::cout << j << std::endl;\n}\n

    Output:

    {\"address\":\"744 Evergreen Terrace\",\"age\":60,\"name\":\"Ned Flanders\"}\n
    "},{"location":"api/adl_serializer/to_json/#see-also","title":"See also","text":""},{"location":"api/adl_serializer/to_json/#version-history","title":"Version history","text":""},{"location":"api/basic_json/","title":"nlohmann::basic_json","text":"

    Defined in header <nlohmann/json.hpp>

    template<\n    template<typename U, typename V, typename... Args> class ObjectType = std::map,\n    template<typename U, typename... Args> class ArrayType = std::vector,\n    class StringType = std::string,\n    class BooleanType = bool,\n    class NumberIntegerType = std::int64_t,\n    class NumberUnsignedType = std::uint64_t,\n    class NumberFloatType = double,\n    template<typename U> class AllocatorType = std::allocator,\n    template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer,\n    class BinaryType = std::vector<std::uint8_t>,\n    class CustomBaseClass = void\n>\nclass basic_json;\n
    "},{"location":"api/basic_json/#template-parameters","title":"Template parameters","text":"Template parameter Description Derived type ObjectType type for JSON objects object_t ArrayType type for JSON arrays array_t StringType type for JSON strings and object keys string_t BooleanType type for JSON booleans boolean_t NumberIntegerType type for JSON integer numbers number_integer_t NumberUnsignedType type for JSON unsigned integer numbers number_unsigned_t NumberFloatType type for JSON floating-point numbers number_float_t AllocatorType type of the allocator to use JSONSerializer the serializer to resolve internal calls to to_json() and from_json() json_serializer BinaryType type for binary arrays binary_t CustomBaseClass extension point for user code json_base_class_t"},{"location":"api/basic_json/#specializations","title":"Specializations","text":""},{"location":"api/basic_json/#iterator-invalidation","title":"Iterator invalidation","text":"

    All operations that add values to an array (push_back , operator+=, emplace_back, insert, and operator[] for a non-existing index) can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

    For ordered_json, also all operations that add a value to an object (push_back, operator+=, emplace, insert, update, and operator[] for a non-existing key) can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

    "},{"location":"api/basic_json/#requirements","title":"Requirements","text":"

    The class satisfies the following concept requirements:

    "},{"location":"api/basic_json/#basic","title":"Basic","text":""},{"location":"api/basic_json/#layout","title":"Layout","text":""},{"location":"api/basic_json/#library-wide","title":"Library-wide","text":""},{"location":"api/basic_json/#container","title":"Container","text":""},{"location":"api/basic_json/#member-types","title":"Member types","text":""},{"location":"api/basic_json/#exceptions","title":"Exceptions","text":""},{"location":"api/basic_json/#container-types","title":"Container types","text":"Type Definition value_type basic_json reference value_type& const_reference const value_type& difference_type std::ptrdiff_t size_type std::size_t allocator_type AllocatorType<basic_json> pointer std::allocator_traits<allocator_type>::pointer const_pointer std::allocator_traits<allocator_type>::const_pointer iterator LegacyBidirectionalIterator const_iterator constant LegacyBidirectionalIterator reverse_iterator reverse iterator, derived from iterator const_reverse_iterator reverse iterator, derived from const_iterator iteration_proxy helper type for items function"},{"location":"api/basic_json/#json-value-data-types","title":"JSON value data types","text":""},{"location":"api/basic_json/#parser-callback","title":"Parser callback","text":""},{"location":"api/basic_json/#member-functions","title":"Member functions","text":""},{"location":"api/basic_json/#object-inspection","title":"Object inspection","text":"

    Functions to inspect the type of a JSON value.

    Optional functions to access the diagnostic positions.

    "},{"location":"api/basic_json/#value-access","title":"Value access","text":"

    Direct access to the stored value of a JSON value.

    "},{"location":"api/basic_json/#element-access","title":"Element access","text":"

    Access to the JSON value

    "},{"location":"api/basic_json/#lookup","title":"Lookup","text":""},{"location":"api/basic_json/#iterators","title":"Iterators","text":""},{"location":"api/basic_json/#capacity","title":"Capacity","text":""},{"location":"api/basic_json/#modifiers","title":"Modifiers","text":""},{"location":"api/basic_json/#lexicographical-comparison-operators","title":"Lexicographical comparison operators","text":""},{"location":"api/basic_json/#serialization-dumping","title":"Serialization / Dumping","text":""},{"location":"api/basic_json/#deserialization-parsing","title":"Deserialization / Parsing","text":""},{"location":"api/basic_json/#json-pointer-functions","title":"JSON Pointer functions","text":""},{"location":"api/basic_json/#json-patch-functions","title":"JSON Patch functions","text":""},{"location":"api/basic_json/#json-merge-patch-functions","title":"JSON Merge Patch functions","text":""},{"location":"api/basic_json/#static-functions","title":"Static functions","text":""},{"location":"api/basic_json/#binary-formats","title":"Binary formats","text":""},{"location":"api/basic_json/#non-member-functions","title":"Non-member functions","text":""},{"location":"api/basic_json/#literals","title":"Literals","text":""},{"location":"api/basic_json/#helper-classes","title":"Helper classes","text":""},{"location":"api/basic_json/#examples","title":"Examples","text":"Example

    The example shows how the library is used.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j =\n    {\n        {\"pi\", 3.141},\n        {\"happy\", true},\n        {\"name\", \"Niels\"},\n        {\"nothing\", nullptr},\n        {\n            \"answer\", {\n                {\"everything\", 42}\n            }\n        },\n        {\"list\", {1, 0, 2}},\n        {\n            \"object\", {\n                {\"currency\", \"USD\"},\n                {\"value\", 42.99}\n            }\n        }\n    };\n\n    // add new values\n    j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n    // count elements\n    auto s = j.size();\n    j[\"size\"] = s;\n\n    // pretty print with indent of 4 spaces\n    std::cout << std::setw(4) << j << '\\n';\n}\n

    Output:

    {\n    \"answer\": {\n        \"everything\": 42\n    },\n    \"happy\": true,\n    \"list\": [\n        1,\n        0,\n        2\n    ],\n    \"name\": \"Niels\",\n    \"new\": {\n        \"key\": {\n            \"value\": [\n                \"another\",\n                \"list\"\n            ]\n        }\n    },\n    \"nothing\": null,\n    \"object\": {\n        \"currency\": \"USD\",\n        \"value\": 42.99\n    },\n    \"pi\": 3.141,\n    \"size\": 8\n}\n
    "},{"location":"api/basic_json/#see-also","title":"See also","text":""},{"location":"api/basic_json/#version-history","title":"Version history","text":""},{"location":"api/basic_json/accept/","title":"nlohmann::basic_json::accept","text":"
    // (1)\ntemplate<typename InputType>\nstatic bool accept(InputType&& i,\n                   const bool ignore_comments = false,\n                   const bool ignore_trailing_commas = false);\n\n// (2)\ntemplate<typename IteratorType, typename SentinelType = IteratorType>\nstatic bool accept(IteratorType first, SentinelType last,\n                   const bool ignore_comments = false,\n                   const bool ignore_trailing_commas = false);\n

    Checks whether the input is valid JSON.

    1. Reads from a compatible input.

    2. Reads from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)

      The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32. If SentinelType differs from IteratorType, it must be comparable to the iterator type with operator!=.

    Unlike the parse() function, this function neither throws an exception in case of invalid JSON input (i.e., a parse error) nor creates diagnostic information.

    "},{"location":"api/basic_json/accept/#template-parameters","title":"Template parameters","text":"InputType

    A compatible input, for instance:

    IteratorType

    a compatible iterator type, for instance.

    SentinelType

    defaults to IteratorType; may be a different type comparable to IteratorType via operator!=, for instance.

    "},{"location":"api/basic_json/accept/#parameters","title":"Parameters","text":"i (in) Input to parse from. ignore_comments (in) whether comments should be ignored and treated like whitespace (true) or yield a parse error (false); (optional, false by default) ignore_trailing_commas (in) whether trailing commas in arrays or objects should be ignored and treated like whitespace (true) or yield a parse error (false); (optional, false by default) first (in) iterator to the start of the character range last (in) iterator to the end of the character range, or a sentinel value that compares equal to the end iterator with operator!="},{"location":"api/basic_json/accept/#return-value","title":"Return value","text":"

    Whether the input is valid JSON.

    "},{"location":"api/basic_json/accept/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

    "},{"location":"api/basic_json/accept/#exceptions","title":"Exceptions","text":"

    Throws parse_error.101 in case of an empty input like a null FILE* or char* pointer.

    "},{"location":"api/basic_json/accept/#complexity","title":"Complexity","text":"

    Linear in the length of the input. The parser is a predictive LL(1) parser.

    "},{"location":"api/basic_json/accept/#notes","title":"Notes","text":"

    A UTF-8 byte order mark is silently ignored.

    "},{"location":"api/basic_json/accept/#examples","title":"Examples","text":"Example

    The example below demonstrates the accept() function reading from a string.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // a valid JSON text\n    auto valid_text = R\"(\n    {\n        \"numbers\": [1, 2, 3]\n    }\n    )\";\n\n    // an invalid JSON text\n    auto invalid_text = R\"(\n    {\n        \"strings\": [\"extra\", \"comma\", ]\n    }\n    )\";\n\n    std::cout << std::boolalpha\n              << json::accept(valid_text) << ' '\n              << json::accept(invalid_text) << '\\n';\n}\n

    Output:

    true false\n
    "},{"location":"api/basic_json/accept/#see-also","title":"See also","text":""},{"location":"api/basic_json/accept/#version-history","title":"Version history","text":"

    Deprecation

    Overload (2) replaces calls to accept with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like accept({ptr, ptr+len}, ...); with accept(ptr, ptr+len, ...);.

    You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

    "},{"location":"api/basic_json/array/","title":"nlohmann::basic_json::array","text":"
    static basic_json array(initializer_list_t init = {});\n

    Creates a JSON array value from a given initializer list. That is, given a list of values a, b, c, creates the JSON value [a, b, c]. If the initializer list is empty, the empty array [] is created.

    "},{"location":"api/basic_json/array/#parameters","title":"Parameters","text":"init (in) initializer list with JSON values to create an array from (optional)"},{"location":"api/basic_json/array/#return-value","title":"Return value","text":"

    JSON array value

    "},{"location":"api/basic_json/array/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

    "},{"location":"api/basic_json/array/#complexity","title":"Complexity","text":"

    Linear in the size of init.

    "},{"location":"api/basic_json/array/#notes","title":"Notes","text":"

    This function is only needed to express two edge cases that cannot be realized with the initializer list constructor (basic_json(initializer_list_t, bool, value_t)). These cases are:

    1. creating an array whose elements are all pairs whose first element is a string -- in this case, the initializer list constructor would create an object, taking the first elements as keys
    2. creating an empty array -- passing the empty initializer list to the initializer list constructor yields an empty object
    "},{"location":"api/basic_json/array/#examples","title":"Examples","text":"Example

    The following code shows an example for the array function.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON arrays\n    json j_no_init_list = json::array();\n    json j_empty_init_list = json::array({});\n    json j_nonempty_init_list = json::array({1, 2, 3, 4});\n    json j_list_of_pairs = json::array({ {\"one\", 1}, {\"two\", 2} });\n\n    // serialize the JSON arrays\n    std::cout << j_no_init_list << '\\n';\n    std::cout << j_empty_init_list << '\\n';\n    std::cout << j_nonempty_init_list << '\\n';\n    std::cout << j_list_of_pairs << '\\n';\n}\n

    Output:

    []\n[]\n[1,2,3,4]\n[[\"one\",1],[\"two\",2]]\n
    "},{"location":"api/basic_json/array/#see-also","title":"See also","text":""},{"location":"api/basic_json/array/#version-history","title":"Version history","text":""},{"location":"api/basic_json/array_t/","title":"nlohmann::basic_json::array_t","text":"
    using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;\n

    The type used to store JSON arrays.

    RFC 8259 describes JSON arrays as follows:

    An array is an ordered sequence of zero or more values.

    To store objects in C++, a type is defined by the template parameters explained below.

    "},{"location":"api/basic_json/array_t/#template-parameters","title":"Template parameters","text":"ArrayType container type to store arrays (e.g., std::vector or std::list) AllocatorType the allocator to use for objects (e.g., std::allocator)"},{"location":"api/basic_json/array_t/#notes","title":"Notes","text":""},{"location":"api/basic_json/array_t/#default-type","title":"Default type","text":"

    With the default values for ArrayType (std::vector) and AllocatorType (std::allocator), the default value for array_t is:

    std::vector<\n  basic_json, // value_type\n  std::allocator<basic_json> // allocator_type\n>\n
    "},{"location":"api/basic_json/array_t/#limits","title":"Limits","text":"

    RFC 8259 specifies:

    An implementation may set limits on the maximum depth of nesting.

    In this class, the array's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the max_size function of a JSON array.

    "},{"location":"api/basic_json/array_t/#storage","title":"Storage","text":"

    Arrays are stored as pointers in a basic_json type. That is, for any access to array values, a pointer of type array_t* must be dereferenced.

    "},{"location":"api/basic_json/array_t/#examples","title":"Examples","text":"Example

    The following code shows that array_t is by default, a typedef to std::vector<nlohmann::json>.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    std::cout << std::boolalpha << std::is_same<std::vector<json>, json::array_t>::value << std::endl;\n}\n

    Output:

    true\n
    "},{"location":"api/basic_json/array_t/#version-history","title":"Version history","text":""},{"location":"api/basic_json/at/","title":"nlohmann::basic_json::at","text":"
    // (1)\nreference at(size_type idx);\nconst_reference at(size_type idx) const;\n\n// (2)\nreference at(const typename object_t::key_type& key);\nconst_reference at(const typename object_t::key_type& key) const;\n\n// (3)\ntemplate<typename KeyType>\nreference at(KeyType&& key);\ntemplate<typename KeyType>\nconst_reference at(KeyType&& key) const;\n\n// (4)\nreference at(const json_pointer& ptr);\nconst_reference at(const json_pointer& ptr) const;\n
    1. Returns a reference to the array element at specified location idx, with bounds checking.
    2. Returns a reference to the object element with specified key key, with bounds checking.
    3. See 2. This overload is only available if KeyType is comparable with typename object_t::key_type and typename object_comparator_t::is_transparent denotes a type.
    4. Returns a reference to the element at specified JSON pointer ptr, with bounds checking.
    "},{"location":"api/basic_json/at/#template-parameters","title":"Template parameters","text":"KeyType A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17)."},{"location":"api/basic_json/at/#parameters","title":"Parameters","text":"idx (in) index of the element to access key (in) object key of the elements to access ptr (in) JSON pointer to the desired element"},{"location":"api/basic_json/at/#return-value","title":"Return value","text":"
    1. reference to the element at index idx
    2. reference to the element at key key
    3. reference to the element at key key
    4. reference to the element pointed to by ptr
    "},{"location":"api/basic_json/at/#exception-safety","title":"Exception safety","text":"

    Strong exception safety: if an exception occurs, the original value stays intact.

    "},{"location":"api/basic_json/at/#exceptions","title":"Exceptions","text":"
    1. The function can throw the following exceptions:
      • Throws type_error.304 if the JSON value is not an array; in this case, calling at with an index makes no sense. See the example below.
      • Throws out_of_range.401 if the index idx is out of range of the array; that is, idx >= size(). See the example below.
    2. The function can throw the following exceptions:
      • Throws type_error.304 if the JSON value is not an object; in this case, calling at with a key makes no sense. See the example below.
      • Throws out_of_range.403 if the key key is not stored in the object; that is, find(key) == end(). See the example below.
    3. See 2.
    4. The function can throw the following exceptions:
      • Throws parse_error.106 if an array index in the passed JSON pointer ptr begins with '0'. See the example below.
      • Throws parse_error.109 if an array index in the passed JSON pointer ptr is not a number. See the example below.
      • Throws out_of_range.401 if an array index in the passed JSON pointer ptr is out of range. See the example below.
      • Throws out_of_range.402 if the array index '-' is used in the passed JSON pointer ptr. As at provides checked access (and no elements are implicitly inserted), the index '-' is always invalid. See the example below.
      • Throws out_of_range.403 if the JSON pointer describes a key of an object which cannot be found. See the example below.
      • Throws out_of_range.404 if the JSON pointer ptr can not be resolved. See the example below.
      • Throws out_of_range.410 if an array index in the passed JSON pointer ptr exceeds the range of size_type (e.g., on 32-bit platforms).
    "},{"location":"api/basic_json/at/#complexity","title":"Complexity","text":"
    1. Constant.
    2. Logarithmic in the size of the container.
    3. Logarithmic in the size of the container.
    4. Logarithmic in the size of the container.
    "},{"location":"api/basic_json/at/#examples","title":"Examples","text":"Example: (1) access specified array element with bounds checking

    The example below shows how array elements can be read and written using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON array\n    json array = {\"first\", \"2nd\", \"third\", \"fourth\"};\n\n    // output element at index 2 (third element)\n    std::cout << array.at(2) << '\\n';\n\n    // change element at index 1 (second element) to \"second\"\n    array.at(1) = \"second\";\n\n    // output changed array\n    std::cout << array << '\\n';\n\n    // exception type_error.304\n    try\n    {\n        // use at() on a non-array type\n        json str = \"I am a string\";\n        str.at(0) = \"Another string\";\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // exception out_of_range.401\n    try\n    {\n        // try to write beyond the array limit\n        array.at(5) = \"sixth\";\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    \"third\"\n[\"first\",\"second\",\"third\",\"fourth\"]\n[json.exception.type_error.304] cannot use at() with string\n[json.exception.out_of_range.401] array index 5 is out of range\n
    Example: (1) access specified array element with bounds checking

    The example below shows how array elements can be read using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON array\n    const json array = {\"first\", \"2nd\", \"third\", \"fourth\"};\n\n    // output element at index 2 (third element)\n    std::cout << array.at(2) << '\\n';\n\n    // exception type_error.304\n    try\n    {\n        // use at() on a non-array type\n        const json str = \"I am a string\";\n        std::cout << str.at(0) << '\\n';\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // exception out_of_range.401\n    try\n    {\n        // try to read beyond the array limit\n        std::cout << array.at(5) << '\\n';\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    \"third\"\n[json.exception.type_error.304] cannot use at() with string\n[json.exception.out_of_range.401] array index 5 is out of range\n
    Example: (2) access specified object element with bounds checking

    The example below shows how object elements can be read and written using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON object\n    json object =\n    {\n        {\"the good\", \"il buono\"},\n        {\"the bad\", \"il cattivo\"},\n        {\"the ugly\", \"il brutto\"}\n    };\n\n    // output element with key \"the ugly\"\n    std::cout << object.at(\"the ugly\") << '\\n';\n\n    // change element with key \"the bad\"\n    object.at(\"the bad\") = \"il cattivo\";\n\n    // output changed array\n    std::cout << object << '\\n';\n\n    // exception type_error.304\n    try\n    {\n        // use at() on a non-object type\n        json str = \"I am a string\";\n        str.at(\"the good\") = \"Another string\";\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // exception out_of_range.401\n    try\n    {\n        // try to write at a nonexisting key\n        object.at(\"the fast\") = \"il rapido\";\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    \"il brutto\"\n{\"the bad\":\"il cattivo\",\"the good\":\"il buono\",\"the ugly\":\"il brutto\"}\n[json.exception.type_error.304] cannot use at() with string\n[json.exception.out_of_range.403] key 'the fast' not found\n
    Example: (2) access specified object element with bounds checking

    The example below shows how object elements can be read using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON object\n    const json object =\n    {\n        {\"the good\", \"il buono\"},\n        {\"the bad\", \"il cattivo\"},\n        {\"the ugly\", \"il brutto\"}\n    };\n\n    // output element with key \"the ugly\"\n    std::cout << object.at(\"the ugly\") << '\\n';\n\n    // exception type_error.304\n    try\n    {\n        // use at() on a non-object type\n        const json str = \"I am a string\";\n        std::cout << str.at(\"the good\") << '\\n';\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // exception out_of_range.401\n    try\n    {\n        // try to read from a nonexisting key\n        std::cout << object.at(\"the fast\") << '\\n';\n    }\n    catch (const json::out_of_range)\n    {\n        std::cout << \"out of range\" << '\\n';\n    }\n}\n

    Output:

    \"il brutto\"\n[json.exception.type_error.304] cannot use at() with string\nout of range\n
    Example: (3) access specified object element using string_view with bounds checking

    The example below shows how object elements can be read and written using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <string_view>\n#include <nlohmann/json.hpp>\n\nusing namespace std::string_view_literals;\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON object\n    json object =\n    {\n        {\"the good\", \"il buono\"},\n        {\"the bad\", \"il cattivo\"},\n        {\"the ugly\", \"il brutto\"}\n    };\n\n    // output element with key \"the ugly\" using string_view\n    std::cout << object.at(\"the ugly\"sv) << '\\n';\n\n    // change element with key \"the bad\" using string_view\n    object.at(\"the bad\"sv) = \"il cattivo\";\n\n    // output changed array\n    std::cout << object << '\\n';\n\n    // exception type_error.304\n    try\n    {\n        // use at() with string_view on a non-object type\n        json str = \"I am a string\";\n        str.at(\"the good\"sv) = \"Another string\";\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // exception out_of_range.401\n    try\n    {\n        // try to write at a nonexisting key using string_view\n        object.at(\"the fast\"sv) = \"il rapido\";\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    \"il brutto\"\n{\"the bad\":\"il cattivo\",\"the good\":\"il buono\",\"the ugly\":\"il brutto\"}\n[json.exception.type_error.304] cannot use at() with string\n[json.exception.out_of_range.403] key 'the fast' not found\n
    Example: (3) access specified object element using string_view with bounds checking

    The example below shows how object elements can be read using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <string_view>\n#include <nlohmann/json.hpp>\n\nusing namespace std::string_view_literals;\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON object\n    const json object =\n    {\n        {\"the good\", \"il buono\"},\n        {\"the bad\", \"il cattivo\"},\n        {\"the ugly\", \"il brutto\"}\n    };\n\n    // output element with key \"the ugly\" using string_view\n    std::cout << object.at(\"the ugly\"sv) << '\\n';\n\n    // exception type_error.304\n    try\n    {\n        // use at() with string_view on a non-object type\n        const json str = \"I am a string\";\n        std::cout << str.at(\"the good\"sv) << '\\n';\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // exception out_of_range.401\n    try\n    {\n        // try to read from a nonexisting key using string_view\n        std::cout << object.at(\"the fast\"sv) << '\\n';\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << \"out of range\" << '\\n';\n    }\n}\n

    Output:

    \"il brutto\"\n[json.exception.type_error.304] cannot use at() with string\nout of range\n
    Example: (4) access specified element via JSON Pointer

    The example below shows how object elements can be read and written using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    // create a JSON value\n    json j =\n    {\n        {\"number\", 1}, {\"string\", \"foo\"}, {\"array\", {1, 2}}\n    };\n\n    // read-only access\n\n    // output element with JSON pointer \"/number\"\n    std::cout << j.at(\"/number\"_json_pointer) << '\\n';\n    // output element with JSON pointer \"/string\"\n    std::cout << j.at(\"/string\"_json_pointer) << '\\n';\n    // output element with JSON pointer \"/array\"\n    std::cout << j.at(\"/array\"_json_pointer) << '\\n';\n    // output element with JSON pointer \"/array/1\"\n    std::cout << j.at(\"/array/1\"_json_pointer) << '\\n';\n\n    // writing access\n\n    // change the string\n    j.at(\"/string\"_json_pointer) = \"bar\";\n    // output the changed string\n    std::cout << j[\"string\"] << '\\n';\n\n    // change an array element\n    j.at(\"/array/1\"_json_pointer) = 21;\n    // output the changed array\n    std::cout << j[\"array\"] << '\\n';\n\n    // out_of_range.106\n    try\n    {\n        // try to use an array index with leading '0'\n        json::reference ref = j.at(\"/array/01\"_json_pointer);\n    }\n    catch (const json::parse_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.109\n    try\n    {\n        // try to use an array index that is not a number\n        json::reference ref = j.at(\"/array/one\"_json_pointer);\n    }\n    catch (const json::parse_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.401\n    try\n    {\n        // try to use an invalid array index\n        json::reference ref = j.at(\"/array/4\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.402\n    try\n    {\n        // try to use the array index '-'\n        json::reference ref = j.at(\"/array/-\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.403\n    try\n    {\n        // try to use a JSON pointer to a nonexistent object key\n        json::const_reference ref = j.at(\"/foo\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.404\n    try\n    {\n        // try to use a JSON pointer that cannot be resolved\n        json::reference ref = j.at(\"/number/foo\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    1\n\"foo\"\n[1,2]\n2\n\"bar\"\n[1,21]\n[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'\n[json.exception.parse_error.109] parse error: array index 'one' is not a number\n[json.exception.out_of_range.401] array index 4 is out of range\n[json.exception.out_of_range.402] array index '-' (2) is out of range\n[json.exception.out_of_range.403] key 'foo' not found\n[json.exception.out_of_range.404] unresolved reference token 'foo'\n
    Example: (4) access specified element via JSON Pointer

    The example below shows how object elements can be read using at(). It also demonstrates the different exceptions that can be thrown.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    // create a JSON value\n    const json j =\n    {\n        {\"number\", 1}, {\"string\", \"foo\"}, {\"array\", {1, 2}}\n    };\n\n    // read-only access\n\n    // output element with JSON pointer \"/number\"\n    std::cout << j.at(\"/number\"_json_pointer) << '\\n';\n    // output element with JSON pointer \"/string\"\n    std::cout << j.at(\"/string\"_json_pointer) << '\\n';\n    // output element with JSON pointer \"/array\"\n    std::cout << j.at(\"/array\"_json_pointer) << '\\n';\n    // output element with JSON pointer \"/array/1\"\n    std::cout << j.at(\"/array/1\"_json_pointer) << '\\n';\n\n    // out_of_range.109\n    try\n    {\n        // try to use an array index that is not a number\n        json::const_reference ref = j.at(\"/array/one\"_json_pointer);\n    }\n    catch (const json::parse_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.401\n    try\n    {\n        // try to use an invalid array index\n        json::const_reference ref = j.at(\"/array/4\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.402\n    try\n    {\n        // try to use the array index '-'\n        json::const_reference ref = j.at(\"/array/-\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.403\n    try\n    {\n        // try to use a JSON pointer to a nonexistent object key\n        json::const_reference ref = j.at(\"/foo\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    // out_of_range.404\n    try\n    {\n        // try to use a JSON pointer that cannot be resolved\n        json::const_reference ref = j.at(\"/number/foo\"_json_pointer);\n    }\n    catch (const json::out_of_range& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    1\n\"foo\"\n[1,2]\n2\n[json.exception.parse_error.109] parse error: array index 'one' is not a number\n[json.exception.out_of_range.401] array index 4 is out of range\n[json.exception.out_of_range.402] array index '-' (2) is out of range\n[json.exception.out_of_range.403] key 'foo' not found\n[json.exception.out_of_range.404] unresolved reference token 'foo'\n
    "},{"location":"api/basic_json/at/#see-also","title":"See also","text":""},{"location":"api/basic_json/at/#version-history","title":"Version history","text":"
    1. Added in version 1.0.0.
    2. Added in version 1.0.0.
    3. Added in version 3.11.0.
    4. Added in version 2.0.0.
    "},{"location":"api/basic_json/back/","title":"nlohmann::basic_json::back","text":"
    reference back();\n\nconst_reference back() const;\n

    Returns a reference to the last element in the container. For a JSON container c, the expression c.back() is equivalent to

    auto tmp = c.end();\n--tmp;\nreturn *tmp;\n
    "},{"location":"api/basic_json/back/#return-value","title":"Return value","text":"

    In the case of a structured type (array or object), a reference to the last element is returned. In the case of number, string, boolean, or binary values, a reference to the value is returned.

    "},{"location":"api/basic_json/back/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

    "},{"location":"api/basic_json/back/#exceptions","title":"Exceptions","text":"

    If the JSON value is null, exception invalid_iterator.214 is thrown.

    "},{"location":"api/basic_json/back/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/back/#notes","title":"Notes","text":"

    Precondition

    The array or object must not be empty. Calling back on an empty array or object yields undefined behavior.

    "},{"location":"api/basic_json/back/#examples","title":"Examples","text":"Example

    The following code shows an example for back().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_boolean = true;\n    json j_number_integer = 17;\n    json j_number_float = 23.42;\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_object_empty(json::value_t::object);\n    json j_array = {1, 2, 4, 8, 16};\n    json j_array_empty(json::value_t::array);\n    json j_string = \"Hello, world\";\n\n    // call back()\n    std::cout << j_boolean.back() << '\\n';\n    std::cout << j_number_integer.back() << '\\n';\n    std::cout << j_number_float.back() << '\\n';\n    std::cout << j_object.back() << '\\n';\n    //std::cout << j_object_empty.back() << '\\n';  // undefined behavior\n    std::cout << j_array.back() << '\\n';\n    //std::cout << j_array_empty.back() << '\\n';   // undefined behavior\n    std::cout << j_string.back() << '\\n';\n\n    // back() called on a null value\n    try\n    {\n        json j_null;\n        j_null.back();\n    }\n    catch (const json::invalid_iterator& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    true\n17\n23.42\n2\n16\n\"Hello, world\"\n[json.exception.invalid_iterator.214] cannot get value\n
    "},{"location":"api/basic_json/back/#see-also","title":"See also","text":""},{"location":"api/basic_json/back/#version-history","title":"Version history","text":""},{"location":"api/basic_json/basic_json/","title":"nlohmann::basic_json::basic_json","text":"
    // (1)\nbasic_json(const value_t v);\n\n// (2)\nbasic_json(std::nullptr_t = nullptr) noexcept;\n\n// (3)\ntemplate<typename CompatibleType>\nbasic_json(CompatibleType&& val) noexcept(noexcept(\n           JSONSerializer<U>::to_json(std::declval<basic_json_t&>(),\n                                      std::forward<CompatibleType>(val))));\n\n// (4)\ntemplate<typename BasicJsonType>\nbasic_json(const BasicJsonType& val);\n\n// (5)\nbasic_json(initializer_list_t init,\n           bool type_deduction = true,\n           value_t manual_type = value_t::array);\n\n// (6)\nbasic_json(size_type cnt, const basic_json& val);\n\n// (7)\nbasic_json(iterator first, iterator last);\nbasic_json(const_iterator first, const_iterator last);\n\n// (8)\nbasic_json(const basic_json& other);\n\n// (9)\nbasic_json(basic_json&& other) noexcept;\n

    1. Create an empty JSON value with a given type. The value will be default initialized with an empty value which depends on the type:

      Value type initial value null null boolean false string \"\" number 0 object {} array [] binary empty array

      The postcondition of this constructor can be restored by calling clear().

    2. Create a null JSON value. It either takes a null pointer as parameter (explicitly creating null) or no parameter (implicitly creating null). The passed null pointer itself is not read -- it is only used to choose the right constructor.

    3. This is a \"catch all\" constructor for all compatible JSON types; that is, types for which a to_json() method exists. The constructor forwards the parameter val to that method (to json_serializer<U>::to_json method with U = uncvref_t<CompatibleType>, to be exact).

      Template type CompatibleType includes, but is not limited to, the following types:

      • arrays: array_t and all kinds of compatible containers such as std::vector, std::deque, std::list, std::forward_list, std::array, std::valarray, std::set, std::unordered_set, std::multiset, and std::unordered_multiset with a value_type from which a basic_json value can be constructed.
      • objects: object_t and all kinds of compatible associative containers such as std::map, std::unordered_map, std::multimap, and std::unordered_multimap with a key_type compatible to string_t and a value_type from which a basic_json value can be constructed.
      • strings: string_t, string literals, and all compatible string containers can be used.
      • numbers: number_integer_t, number_unsigned_t, number_float_t, and all convertible number types such as int, size_t, int64_t, float or double can be used.
      • boolean: boolean_t / bool can be used.
      • binary: binary_t / std::vector<uint8_t> may be used; unfortunately because string literals cannot be distinguished from binary character arrays by the C++ type system, all types compatible with const char* will be directed to the string constructor instead. This is both for backwards compatibility and due to the fact that a binary type is not a standard JSON type.

      See the examples below.

    4. This is a constructor for existing basic_json types. It does not hijack copy/move constructors, since the parameter has different template arguments than the current ones.

      The constructor tries to convert the internal m_value of the parameter. Each member value (object, array, string, etc.) is serialized via the corresponding to_json() overload. For objects and strings, the conversion requires that the target basic_json type's object_t::key_type (or string_t) be directly constructible from the source type's corresponding member type via is_constructible. If this requirement is not met, the conversion does not fail to compile; instead, it silently falls back to the array-conversion path, which represents objects as arrays of [key, value] pairs and strings as arrays of character codes. This is a known limitation tracked in issue #3425.

    5. Creates a JSON value of type array or object from the passed initializer list init. In case type_deduction is true (default), the type of the JSON value to be created is deducted from the initializer list init according to the following rules:

      1. If the list is empty, an empty JSON object value {} is created.
      2. If the list consists of pairs whose first element is a string, a JSON object value is created where the first elements of the pairs are treated as keys and the second elements are as values.
      3. In all other cases, an array is created.

      The rules aim to create the best fit between a C++ initializer list and JSON values. The rationale is as follows:

      1. The empty initializer list is written as {} which is exactly an empty JSON object.
      2. C++ has no way of describing mapped types other than to list a list of pairs. As JSON requires that keys must be of type string, rule 2 is the weakest constraint one can pose on initializer lists to interpret them as an object.
      3. In all other cases, the initializer list could not be interpreted as a JSON object type, so interpreting it as a JSON array type is safe.

      With the rules described above, the following JSON values cannot be expressed by an initializer list:

      • the empty array ([]): use array(initializer_list_t) with an empty initializer list in this case
      • arrays whose elements satisfy rule 2: use array(initializer_list_t) with the same initializer list in this case

      Function array() and object() force array and object creation from initializer lists, respectively.

      Brace initialization yields arrays

      Because this constructor takes an initializer_list_t, brace-initializing a json/ordered_json from another json value wraps it in a single-element array rather than copying it:

      json j1 = \"hello\";\njson j2{j1};   // [!] j2 is [\"hello\"], NOT a copy of j1\njson j3(j1);   // j3 is \"hello\" -- parentheses copy as expected\n

      See the FAQ entry on brace initialization for the full explanation, an opt-in macro to change this behavior, and how to explicitly create a single-element array (json::array({value})) if that is what you want.

    6. Constructs a JSON array value by creating cnt copies of a passed value. In case cnt is 0, an empty array is created.

    7. Constructs the JSON value with the contents of the range [first, last). The semantics depend on the different types a JSON value can have:

      • In case of a null type, invalid_iterator.206 is thrown.
      • In case of other primitive types (number, boolean, or string), first must be begin() and last must be end(). In this case, the value is copied. Otherwise, invalid_iterator.204 is thrown.
      • In case of structured types (array, object), the constructor behaves as similar versions for std::vector or std::map; that is, a JSON array or object is constructed from the values in the range.

    8. Creates a copy of a given JSON value.

    9. Move constructor. Constructs a JSON value with the contents of the given value other using move semantics. It \"steals\" the resources from other and leaves it as JSON null value.

    "},{"location":"api/basic_json/basic_json/#template-parameters","title":"Template parameters","text":"CompatibleType

    a type such that:

    BasicJsonType:

    a type such that:

    Note: For cross-basic_json conversions to produce correct results, the target basic_json's object_t::key_type and string_t must be directly constructible from the source basic_json's corresponding types. See the description of overload (4) above for details on what happens when this requirement is not met.

    U: uncvref_t<CompatibleType>"},{"location":"api/basic_json/basic_json/#parameters","title":"Parameters","text":"v (in) the type of the value to create val (in) the value to be forwarded to the respective constructor init (in) initializer list with JSON values type_deduction (in) internal parameter; when set to true, the type of the JSON value is deducted from the initializer list init; when set to false, the type provided via manual_type is forced. This mode is used by the functions array(initializer_list_t) and object(initializer_list_t). manual_type (in) internal parameter; when type_deduction is set to false, the created JSON value will use the provided type (only value_t::array and value_t::object are valid); when type_deduction is set to true, this parameter has no effect cnt (in) the number of JSON copies of val to create first (in) the beginning of the range to copy from (included) last (in) the end of the range to copy from (excluded) other (in) the JSON value to copy/move"},{"location":"api/basic_json/basic_json/#exception-safety","title":"Exception safety","text":"
    1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
    2. No-throw guarantee: this constructor never throws exceptions.
    3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no to_json() function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
    4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no to_json() function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any JSON value.
    5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
    6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
    7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
    8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
    9. No-throw guarantee: this constructor never throws exceptions.
    "},{"location":"api/basic_json/basic_json/#exceptions","title":"Exceptions","text":"
    1. (none)
    2. The function does not throw exceptions.
    3. (none)
    4. (none)
    5. The function can throw the following exceptions:
      • Throws type_error.301 if type_deduction is false, manual_type is value_t::object, but init contains an element which is not a pair whose first element is a string. In this case, the constructor could not create an object. If type_deduction would have been true, an array would have been created. See object(initializer_list_t) for an example.
    6. (none)
    7. The function can throw the following exceptions:
      • Throws invalid_iterator.201 if iterators first and last are not compatible (i.e., do not belong to the same JSON value). In this case, the range [first, last) is undefined.
      • Throws invalid_iterator.204 if iterators first and last belong to a primitive type (number, boolean, or string), but first does not point to the first element anymore. In this case, the range [first, last) is undefined. See the example code below.
      • Throws invalid_iterator.206 if iterators first and last belong to a null value. In this case, the range [first, last) is undefined.
    8. (none)
    9. The function does not throw exceptions.
    "},{"location":"api/basic_json/basic_json/#complexity","title":"Complexity","text":"
    1. Constant.
    2. Constant.
    3. Usually linear in the size of the passed val, also depending on the implementation of the called to_json() method.
    4. Usually linear in the size of the passed val, also depending on the implementation of the called to_json() method.
    5. Linear in the size of the initializer list init.
    6. Linear in cnt.
    7. Linear in distance between first and last.
    8. Linear in the size of other.
    9. Constant.
    "},{"location":"api/basic_json/basic_json/#notes","title":"Notes","text":""},{"location":"api/basic_json/basic_json/#examples","title":"Examples","text":"Example: (1) create an empty value with a given type

    The following code shows the constructor for different value_t values.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create the different JSON values with default values\n    json j_null(json::value_t::null);\n    json j_boolean(json::value_t::boolean);\n    json j_number_integer(json::value_t::number_integer);\n    json j_number_float(json::value_t::number_float);\n    json j_object(json::value_t::object);\n    json j_array(json::value_t::array);\n    json j_string(json::value_t::string);\n\n    // serialize the JSON values\n    std::cout << j_null << '\\n';\n    std::cout << j_boolean << '\\n';\n    std::cout << j_number_integer << '\\n';\n    std::cout << j_number_float << '\\n';\n    std::cout << j_object << '\\n';\n    std::cout << j_array << '\\n';\n    std::cout << j_string << '\\n';\n}\n

    Output:

    null\nfalse\n0\n0.0\n{}\n[]\n\"\"\n
    Example: (2) create a null object

    The following code shows the constructor with and without a null pointer parameter.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // implicitly create a JSON null value\n    json j1;\n\n    // explicitly create a JSON null value\n    json j2(nullptr);\n\n    // serialize the JSON null value\n    std::cout << j1 << '\\n' << j2 << '\\n';\n}\n

    Output:

    null\nnull\n
    Example: (3) create a JSON value from compatible types

    The following code shows the constructor with several compatible types.

    #include <iostream>\n#include <deque>\n#include <list>\n#include <forward_list>\n#include <set>\n#include <unordered_map>\n#include <unordered_set>\n#include <valarray>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // ============\n    // object types\n    // ============\n\n    // create an object from an object_t value\n    json::object_t object_value = { {\"one\", 1}, {\"two\", 2} };\n    json j_object_t(object_value);\n\n    // create an object from std::map\n    std::map<std::string, int> c_map\n    {\n        {\"one\", 1}, {\"two\", 2}, {\"three\", 3}\n    };\n    json j_map(c_map);\n\n    // create an object from std::unordered_map\n    std::unordered_map<const char*, double> c_umap\n    {\n        {\"one\", 1.2}, {\"two\", 2.3}, {\"three\", 3.4}\n    };\n    json j_umap(c_umap);\n\n    // create an object from std::multimap\n    std::multimap<std::string, bool> c_mmap\n    {\n        {\"one\", true}, {\"two\", true}, {\"three\", false}, {\"three\", true}\n    };\n    json j_mmap(c_mmap); // only one entry for key \"three\" is used\n\n    // create an object from std::unordered_multimap\n    std::unordered_multimap<std::string, bool> c_ummap\n    {\n        {\"one\", true}, {\"two\", true}, {\"three\", false}, {\"three\", true}\n    };\n    json j_ummap(c_ummap); // only one entry for key \"three\" is used\n\n    // serialize the JSON objects\n    std::cout << j_object_t << '\\n';\n    std::cout << j_map << '\\n';\n    std::cout << j_umap << '\\n';\n    std::cout << j_mmap << '\\n';\n    std::cout << j_ummap << \"\\n\\n\";\n\n    // ===========\n    // array types\n    // ===========\n\n    // create an array from an array_t value\n    json::array_t array_value = {\"one\", \"two\", 3, 4.5, false};\n    json j_array_t(array_value);\n\n    // create an array from std::vector\n    std::vector<int> c_vector {1, 2, 3, 4};\n    json j_vec(c_vector);\n\n    // create an array from std::valarray\n    std::valarray<short> c_valarray {10, 9, 8, 7};\n    json j_valarray(c_valarray);\n\n    // create an array from std::deque\n    std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};\n    json j_deque(c_deque);\n\n    // create an array from std::list\n    std::list<bool> c_list {true, true, false, true};\n    json j_list(c_list);\n\n    // create an array from std::forward_list\n    std::forward_list<std::int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};\n    json j_flist(c_flist);\n\n    // create an array from std::array\n    std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};\n    json j_array(c_array);\n\n    // create an array from std::set\n    std::set<std::string> c_set {\"one\", \"two\", \"three\", \"four\", \"one\"};\n    json j_set(c_set); // only one entry for \"one\" is used\n\n    // create an array from std::unordered_set\n    std::unordered_set<std::string> c_uset {\"one\", \"two\", \"three\", \"four\", \"one\"};\n    json j_uset(c_uset); // only one entry for \"one\" is used\n\n    // create an array from std::multiset\n    std::multiset<std::string> c_mset {\"one\", \"two\", \"one\", \"four\"};\n    json j_mset(c_mset); // both entries for \"one\" are used\n\n    // create an array from std::unordered_multiset\n    std::unordered_multiset<std::string> c_umset {\"one\", \"two\", \"one\", \"four\"};\n    json j_umset(c_umset); // both entries for \"one\" are used\n\n    // serialize the JSON arrays\n    std::cout << j_array_t << '\\n';\n    std::cout << j_vec << '\\n';\n    std::cout << j_valarray << '\\n';\n    std::cout << j_deque << '\\n';\n    std::cout << j_list << '\\n';\n    std::cout << j_flist << '\\n';\n    std::cout << j_array << '\\n';\n    std::cout << j_set << '\\n';\n    std::cout << j_uset << '\\n';\n    std::cout << j_mset << '\\n';\n    std::cout << j_umset << \"\\n\\n\";\n\n    // ============\n    // string types\n    // ============\n\n    // create string from a string_t value\n    json::string_t string_value = \"The quick brown fox jumps over the lazy dog.\";\n    json j_string_t(string_value);\n\n    // create a JSON string directly from a string literal\n    json j_string_literal(\"The quick brown fox jumps over the lazy dog.\");\n\n    // create string from std::string\n    std::string s_stdstring = \"The quick brown fox jumps over the lazy dog.\";\n    json j_stdstring(s_stdstring);\n\n    // serialize the JSON strings\n    std::cout << j_string_t << '\\n';\n    std::cout << j_string_literal << '\\n';\n    std::cout << j_stdstring << \"\\n\\n\";\n\n    // ============\n    // number types\n    // ============\n\n    // create a JSON number from number_integer_t\n    json::number_integer_t value_integer_t = -42;\n    json j_integer_t(value_integer_t);\n\n    // create a JSON number from number_unsigned_t\n    json::number_integer_t value_unsigned_t = 17;\n    json j_unsigned_t(value_unsigned_t);\n\n    // create a JSON number from an anonymous enum\n    enum { enum_value = 17 };\n    json j_enum(enum_value);\n\n    // create values of different integer types\n    short n_short = 42;\n    int n_int = -23;\n    long n_long = 1024;\n    int_least32_t n_int_least32_t = -17;\n    uint8_t n_uint8_t = 8;\n\n    // create (integer) JSON numbers\n    json j_short(n_short);\n    json j_int(n_int);\n    json j_long(n_long);\n    json j_int_least32_t(n_int_least32_t);\n    json j_uint8_t(n_uint8_t);\n\n    // create values of different floating-point types\n    json::number_float_t v_ok = 3.141592653589793;\n    json::number_float_t v_nan = NAN;\n    json::number_float_t v_infinity = INFINITY;\n\n    // create values of different floating-point types\n    float n_float = 42.23;\n    float n_float_nan = 1.0f / 0.0f;\n    double n_double = 23.42;\n\n    // create (floating point) JSON numbers\n    json j_ok(v_ok);\n    json j_nan(v_nan);\n    json j_infinity(v_infinity);\n    json j_float(n_float);\n    json j_float_nan(n_float_nan);\n    json j_double(n_double);\n\n    // serialize the JSON numbers\n    std::cout << j_integer_t << '\\n';\n    std::cout << j_unsigned_t << '\\n';\n    std::cout << j_enum << '\\n';\n    std::cout << j_short << '\\n';\n    std::cout << j_int << '\\n';\n    std::cout << j_long << '\\n';\n    std::cout << j_int_least32_t << '\\n';\n    std::cout << j_uint8_t << '\\n';\n    std::cout << j_ok << '\\n';\n    std::cout << j_nan << '\\n';\n    std::cout << j_infinity << '\\n';\n    std::cout << j_float << '\\n';\n    std::cout << j_float_nan << '\\n';\n    std::cout << j_double << \"\\n\\n\";\n\n    // =============\n    // boolean types\n    // =============\n\n    // create boolean values\n    json j_truth = true;\n    json j_falsity = false;\n\n    // serialize the JSON booleans\n    std::cout << j_truth << '\\n';\n    std::cout << j_falsity << '\\n';\n}\n

    Output:

    {\"one\":1,\"two\":2}\n{\"one\":1,\"three\":3,\"two\":2}\n{\"one\":1.2,\"three\":3.4,\"two\":2.3}\n{\"one\":true,\"three\":false,\"two\":true}\n{\"one\":true,\"three\":false,\"two\":true}\n\n[\"one\",\"two\",3,4.5,false]\n[1,2,3,4]\n[10,9,8,7]\n[1.2,2.3,3.4,5.6]\n[true,true,false,true]\n[12345678909876,23456789098765,34567890987654,45678909876543]\n[1,2,3,4]\n[\"four\",\"one\",\"three\",\"two\"]\n[\"four\",\"three\",\"two\",\"one\"]\n[\"four\",\"one\",\"one\",\"two\"]\n[\"four\",\"two\",\"one\",\"one\"]\n\n\"The quick brown fox jumps over the lazy dog.\"\n\"The quick brown fox jumps over the lazy dog.\"\n\"The quick brown fox jumps over the lazy dog.\"\n\n-42\n17\n17\n42\n-23\n1024\n-17\n8\n3.141592653589793\nnull\nnull\n42.22999954223633\nnull\n23.42\n\ntrue\nfalse\n

    Note the output is platform-dependent.

    Example: (5) create a container (array or object) from an initializer list

    The example below shows how JSON values are created from initializer lists.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_empty_init_list = json({});\n    json j_object = { {\"one\", 1}, {\"two\", 2} };\n    json j_array = {1, 2, 3, 4};\n    json j_nested_object = { {\"one\", {1}}, {\"two\", {1, 2}} };\n    json j_nested_array = { {{1}, \"one\"}, {{1, 2}, \"two\"} };\n\n    // serialize the JSON value\n    std::cout << j_empty_init_list << '\\n';\n    std::cout << j_object << '\\n';\n    std::cout << j_array << '\\n';\n    std::cout << j_nested_object << '\\n';\n    std::cout << j_nested_array << '\\n';\n}\n

    Output:

    {}\n{\"one\":1,\"two\":2}\n[1,2,3,4]\n{\"one\":[1],\"two\":[1,2]}\n[[[1],\"one\"],[[1,2],\"two\"]]\n
    Example: (6) construct an array with count copies of a given value

    The following code shows examples for creating arrays with several copies of a given value.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array by creating copies of a JSON value\n    json value = \"Hello\";\n    json array_0 = json(0, value);\n    json array_1 = json(1, value);\n    json array_5 = json(5, value);\n\n    // serialize the JSON arrays\n    std::cout << array_0 << '\\n';\n    std::cout << array_1 << '\\n';\n    std::cout << array_5 << '\\n';\n}\n

    Output:

    []\n[\"Hello\"]\n[\"Hello\",\"Hello\",\"Hello\",\"Hello\",\"Hello\"]\n
    Example: (7) construct a JSON container given an iterator range

    The example below shows several ways to create JSON values by specifying a subrange with iterators.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_array = {\"alpha\", \"bravo\", \"charly\", \"delta\", \"easy\"};\n    json j_number = 42;\n    json j_object = {{\"one\", \"eins\"}, {\"two\", \"zwei\"}};\n\n    // create copies using iterators\n    json j_array_range(j_array.begin() + 1, j_array.end() - 2);\n    json j_number_range(j_number.begin(), j_number.end());\n    json j_object_range(j_object.begin(), j_object.find(\"two\"));\n\n    // serialize the values\n    std::cout << j_array_range << '\\n';\n    std::cout << j_number_range << '\\n';\n    std::cout << j_object_range << '\\n';\n\n    // example for an exception\n    try\n    {\n        json j_invalid(j_number.begin() + 1, j_number.end());\n    }\n    catch (const json::invalid_iterator& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    [\"bravo\",\"charly\"]\n42\n{\"one\":\"eins\"}\n[json.exception.invalid_iterator.204] iterators out of range\n
    Example: (8) copy constructor

    The following code shows an example for the copy constructor.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON array\n    json j1 = {\"one\", \"two\", 3, 4.5, false};\n\n    // create a copy\n    json j2(j1);\n\n    // serialize the JSON array\n    std::cout << j1 << \" = \" << j2 << '\\n';\n    std::cout << std::boolalpha << (j1 == j2) << '\\n';\n}\n

    Output:

    [\"one\",\"two\",3,4.5,false] = [\"one\",\"two\",3,4.5,false]\ntrue\n
    Example: (9) move constructor

    The code below shows the move constructor explicitly called via std::move.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON value\n    json a = 23;\n\n    // move contents of a to b\n    json b(std::move(a));\n\n    // serialize the JSON arrays\n    std::cout << a << '\\n';\n    std::cout << b << '\\n';\n}\n

    Output:

    null\n23\n
    "},{"location":"api/basic_json/basic_json/#version-history","title":"Version history","text":"
    1. Since version 1.0.0.
    2. Since version 1.0.0.
    3. Since version 2.1.0.
    4. Since version 3.2.0.
    5. Since version 1.0.0.
    6. Since version 1.0.0.
    7. Since version 1.0.0.
    8. Since version 1.0.0.
    9. Since version 1.0.0.
    "},{"location":"api/basic_json/begin/","title":"nlohmann::basic_json::begin","text":"
    iterator begin() noexcept;\nconst_iterator begin() const noexcept;\n

    Returns an iterator to the first element.

    "},{"location":"api/basic_json/begin/#return-value","title":"Return value","text":"

    iterator to the first element

    "},{"location":"api/basic_json/begin/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/begin/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/begin/#examples","title":"Examples","text":"Example

    The following code shows an example for begin().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array value\n    json array = {1, 2, 3, 4, 5};\n\n    // get an iterator to the first element\n    json::iterator it = array.begin();\n\n    // serialize the element that the iterator points to\n    std::cout << *it << '\\n';\n}\n

    Output:

    1\n
    "},{"location":"api/basic_json/begin/#version-history","title":"Version history","text":""},{"location":"api/basic_json/binary/","title":"nlohmann::basic_json::binary","text":"
    // (1)\nstatic basic_json binary(const typename binary_t::container_type& init);\nstatic basic_json binary(typename binary_t::container_type&& init);\n\n// (2)\nstatic basic_json binary(const typename binary_t::container_type& init,\n                         std::uint8_t subtype);\nstatic basic_json binary(typename binary_t::container_type&& init,\n                         std::uint8_t subtype);\n
    1. Creates a JSON binary array value from a given binary container.
    2. Creates a JSON binary array value from a given binary container with subtype.

    Binary values are part of various binary formats, such as CBOR, MessagePack, and BSON. This constructor is used to create a value for serialization to those formats.

    "},{"location":"api/basic_json/binary/#parameters","title":"Parameters","text":"init (in) container containing bytes to use as a binary type subtype (in) subtype to use in CBOR, MessagePack, and BSON"},{"location":"api/basic_json/binary/#return-value","title":"Return value","text":"

    JSON binary array value

    "},{"location":"api/basic_json/binary/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

    "},{"location":"api/basic_json/binary/#complexity","title":"Complexity","text":"

    Linear in the size of init; constant for typename binary_t::container_type&& init versions.

    "},{"location":"api/basic_json/binary/#notes","title":"Notes","text":"

    Note, this function exists because of the difficulty in correctly specifying the correct template overload in the standard value ctor, as both JSON arrays and JSON binary arrays are backed with some form of a std::vector. Because JSON binary arrays are a non-standard extension, it was decided that it would be best to prevent automatic initialization of a binary array type, for backwards compatibility and so it does not happen on accident.

    "},{"location":"api/basic_json/binary/#examples","title":"Examples","text":"Example

    The following code shows how to create a binary value.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a binary vector\n    std::vector<std::uint8_t> vec = {0xCA, 0xFE, 0xBA, 0xBE};\n\n    // create a binary JSON value with subtype 42\n    json j = json::binary(vec, 42);\n\n    // output type and subtype\n    std::cout << \"type: \" << j.type_name() << \", subtype: \" << j.get_binary().subtype() << std::endl;\n}\n

    Output:

    type: binary, subtype: 42\n
    "},{"location":"api/basic_json/binary/#version-history","title":"Version history","text":""},{"location":"api/basic_json/binary_t/","title":"nlohmann::basic_json::binary_t","text":"
    using binary_t = byte_container_with_subtype<BinaryType>;\n

    This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.

    Additionally, as an implementation detail, the subtype of the binary data is carried around as a std::uint64_t, which is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is incompatible with each other, and it is up to the user to translate between them). The subtype is added to BinaryType via the helper type byte_container_with_subtype.

    CBOR's RFC 8949 describes this type as:

    Major type 2: A byte string. The number of bytes in the string is equal to the argument.

    MessagePack's documentation on the bin type family describes this type as:

    Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.

    BSON's specifications describe several binary types; however, this type is intended to represent the generic binary type which has the description:

    Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and tools.

    None of these impose any limitations on the internal representation other than the basic unit of storage be some type of array whose parts are decomposable into bytes.

    The default representation of this binary format is a std::vector<std::uint8_t>, which is a very common way to represent a byte array in modern C++.

    "},{"location":"api/basic_json/binary_t/#template-parameters","title":"Template parameters","text":"BinaryType

    container type to store arrays

    Although not formally expressed as a C++ concept, BinaryType must be default-constructible, copy/move-constructible, and support push_back(), .data(), and .size(), because byte_container_with_subtype derives directly from it. Its value_type must additionally be exactly one byte wide (e.g., std::uint8_t/char/std::byte): the binary serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via reinterpret_cast, which is only correct for byte-sized elements -- a container like std::vector<std::intptr_t> will not work as BinaryType.

    "},{"location":"api/basic_json/binary_t/#notes","title":"Notes","text":""},{"location":"api/basic_json/binary_t/#default-type","title":"Default type","text":"

    The default values for BinaryType is std::vector<std::uint8_t>.

    "},{"location":"api/basic_json/binary_t/#custom-binarytype-behavior","title":"Custom BinaryType behavior","text":"

    When a custom BinaryType is configured (other than the default std::vector<std::uint8_t>), you can assign values of that type directly to a basic_json instance, and they will automatically be recognized as binary values rather than arrays:

    using custom_json = nlohmann::basic_json<\n    nlohmann::ordered_map,  // ObjectType\n    std::vector,            // ArrayType\n    std::string,            // StringType\n    bool,                   // BooleanType\n    std::int64_t,           // NumberIntegerType\n    std::uint64_t,          // NumberUnsignedType\n    double,                 // NumberFloatType\n    std::allocator,         // AllocatorType\n    nlohmann::adl_serializer,\n    std::vector<std::byte>  // Custom BinaryType\n>;\n\nstd::vector<std::byte> data{std::byte{1}, std::byte{2}, std::byte{3}};\ncustom_json j = data;  // Creates a binary value, not an array\nassert(j.is_binary());\n\n// Round-tripping works seamlessly\nauto extracted = j.get<std::vector<std::byte>>();\nassert(extracted == data);\n

    This automatic type detection is a convenience feature that only applies to custom (non-default) BinaryType configurations. The default nlohmann::json continues to treat std::vector<std::uint8_t> as arrays for backward compatibility.

    "},{"location":"api/basic_json/binary_t/#storage","title":"Storage","text":"

    Binary Arrays are stored as pointers in a basic_json type. That is, for any access to array values, a pointer of the type binary_t* must be dereferenced.

    "},{"location":"api/basic_json/binary_t/#notes-on-subtypes","title":"Notes on subtypes","text":""},{"location":"api/basic_json/binary_t/#examples","title":"Examples","text":"Example

    The following code shows that binary_t is by default, a typedef to nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    std::cout << std::boolalpha << std::is_same<nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>, json::binary_t>::value << std::endl;\n}\n

    Output:

    true\n
    "},{"location":"api/basic_json/binary_t/#see-also","title":"See also","text":""},{"location":"api/basic_json/binary_t/#version-history","title":"Version history","text":""},{"location":"api/basic_json/boolean_t/","title":"nlohmann::basic_json::boolean_t","text":"
    using boolean_t = BooleanType;\n

    The type used to store JSON booleans.

    RFC 8259 implicitly describes a boolean as a type which differentiates the two literals true and false.

    To store boolean values in C++, a type is defined by the template parameter BooleanType which chooses the type to use.

    "},{"location":"api/basic_json/boolean_t/#notes","title":"Notes","text":""},{"location":"api/basic_json/boolean_t/#default-type","title":"Default type","text":"

    With the default values for BooleanType (bool), the default value for boolean_t is bool.

    "},{"location":"api/basic_json/boolean_t/#storage","title":"Storage","text":"

    Boolean values are stored directly inside a basic_json type.

    "},{"location":"api/basic_json/boolean_t/#examples","title":"Examples","text":"Example

    The following code shows that boolean_t is by default, a typedef to bool.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    std::cout << std::boolalpha << std::is_same<bool, json::boolean_t>::value << std::endl;\n}\n

    Output:

    true\n
    "},{"location":"api/basic_json/boolean_t/#version-history","title":"Version history","text":""},{"location":"api/basic_json/cbegin/","title":"nlohmann::basic_json::cbegin","text":"
    const_iterator cbegin() const noexcept;\n

    Returns an iterator to the first element.

    "},{"location":"api/basic_json/cbegin/#return-value","title":"Return value","text":"

    iterator to the first element

    "},{"location":"api/basic_json/cbegin/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/cbegin/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/cbegin/#examples","title":"Examples","text":"Example

    The following code shows an example for cbegin().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array value\n    const json array = {1, 2, 3, 4, 5};\n\n    // get an iterator to the first element\n    json::const_iterator it = array.cbegin();\n\n    // serialize the element that the iterator points to\n    std::cout << *it << '\\n';\n}\n

    Output:

    1\n
    "},{"location":"api/basic_json/cbegin/#version-history","title":"Version history","text":""},{"location":"api/basic_json/cbor_tag_handler_t/","title":"nlohmann::basic_json::cbor_tag_handler_t","text":"
    enum class cbor_tag_handler_t\n{\n    error,\n    ignore,\n    store\n};\n

    This enumeration is used in the from_cbor function to choose how to treat tags:

    error throw a parse_error exception in case of a tag ignore ignore tags store store tagged values as binary container with subtype (for bytes 0xd8..0xdb)"},{"location":"api/basic_json/cbor_tag_handler_t/#examples","title":"Examples","text":"Example

    The example below shows how the different values of the cbor_tag_handler_t influence the behavior of from_cbor when reading a tagged byte string.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // tagged byte string\n    std::vector<std::uint8_t> vec = {{0xd8, 0x42, 0x44, 0xcA, 0xfe, 0xba, 0xbe}};\n\n    // cbor_tag_handler_t::error throws\n    try\n    {\n        auto b_throw_on_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::error);\n    }\n    catch (const json::parse_error& e)\n    {\n        std::cout << e.what() << std::endl;\n    }\n\n    // cbor_tag_handler_t::ignore ignores the tag\n    auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);\n    std::cout << b_ignore_tag << std::endl;\n\n    // cbor_tag_handler_t::store stores the tag as binary subtype\n    auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);\n    std::cout << b_store_tag << std::endl;\n}\n

    Output:

    [json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8\n{\"bytes\":[202,254,186,190],\"subtype\":null}\n{\"bytes\":[202,254,186,190],\"subtype\":66}\n
    "},{"location":"api/basic_json/cbor_tag_handler_t/#version-history","title":"Version history","text":""},{"location":"api/basic_json/cend/","title":"nlohmann::basic_json::cend","text":"
    const_iterator cend() const noexcept;\n

    Returns an iterator to one past the last element.

    "},{"location":"api/basic_json/cend/#return-value","title":"Return value","text":"

    iterator one past the last element

    "},{"location":"api/basic_json/cend/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/cend/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/cend/#examples","title":"Examples","text":"Example

    The following code shows an example for cend().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array value\n    json array = {1, 2, 3, 4, 5};\n\n    // get an iterator to one past the last element\n    json::const_iterator it = array.cend();\n\n    // decrement the iterator to point to the last element\n    --it;\n\n    // serialize the element that the iterator points to\n    std::cout << *it << '\\n';\n}\n

    Output:

    5\n
    "},{"location":"api/basic_json/cend/#version-history","title":"Version history","text":""},{"location":"api/basic_json/clear/","title":"nlohmann::basic_json::clear","text":"
    void clear() noexcept;\n

    Clears the content of a JSON value and resets it to the default value as if basic_json(value_t) would have been called with the current value type from type():

    Value type initial value null null boolean false string \"\" number 0 binary An empty byte vector object {} array []

    Has the same effect as calling

    *this = basic_json(type());\n
    "},{"location":"api/basic_json/clear/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this function never throws exceptions.

    "},{"location":"api/basic_json/clear/#complexity","title":"Complexity","text":"

    Linear in the size of the JSON value.

    "},{"location":"api/basic_json/clear/#notes","title":"Notes","text":"

    All iterators, pointers, and references related to this container are invalidated.

    "},{"location":"api/basic_json/clear/#examples","title":"Examples","text":"Example

    The example below shows the effect of clear() to different JSON types.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_null;\n    json j_boolean = true;\n    json j_number_integer = 17;\n    json j_number_float = 23.42;\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_array = {1, 2, 4, 8, 16};\n    json j_string = \"Hello, world\";\n\n    // call clear()\n    j_null.clear();\n    j_boolean.clear();\n    j_number_integer.clear();\n    j_number_float.clear();\n    j_object.clear();\n    j_array.clear();\n    j_string.clear();\n\n    // serialize the cleared values()\n    std::cout << j_null << '\\n';\n    std::cout << j_boolean << '\\n';\n    std::cout << j_number_integer << '\\n';\n    std::cout << j_number_float << '\\n';\n    std::cout << j_object << '\\n';\n    std::cout << j_array << '\\n';\n    std::cout << j_string << '\\n';\n}\n

    Output:

    null\nfalse\n0\n0.0\n{}\n[]\n\"\"\n
    "},{"location":"api/basic_json/clear/#version-history","title":"Version history","text":""},{"location":"api/basic_json/contains/","title":"nlohmann::basic_json::contains","text":"
    // (1)\nbool contains(const typename object_t::key_type& key) const;\n\n// (2)\ntemplate<typename KeyType>\nbool contains(KeyType&& key) const;\n\n// (3)\nbool contains(const json_pointer& ptr) const;\n
    1. Check whether an element exists in a JSON object with a key equivalent to key. If the element is not found or the JSON value is not an object, false is returned.
    2. See 1. This overload is only available if KeyType is comparable with typename object_t::key_type and typename object_comparator_t::is_transparent denotes a type.
    3. Check whether the given JSON pointer ptr can be resolved in the current JSON value.
    "},{"location":"api/basic_json/contains/#template-parameters","title":"Template parameters","text":"KeyType A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17)."},{"location":"api/basic_json/contains/#parameters","title":"Parameters","text":"key (in) key value to check its existence. ptr (in) JSON pointer to check its existence."},{"location":"api/basic_json/contains/#return-value","title":"Return value","text":"
    1. true if an element with specified key exists. If no such element with such a key is found or the JSON value is not an object, false is returned.
    2. See 1.
    3. true if the JSON pointer can be resolved to a stored value, false otherwise.
    "},{"location":"api/basic_json/contains/#exception-safety","title":"Exception safety","text":"

    Strong exception safety: if an exception occurs, the original value stays intact.

    "},{"location":"api/basic_json/contains/#exceptions","title":"Exceptions","text":"
    1. The function does not throw exceptions.
    2. The function does not throw exceptions.
    3. The function does not throw exceptions.
    "},{"location":"api/basic_json/contains/#complexity","title":"Complexity","text":"

    Logarithmic in the size of the JSON object.

    "},{"location":"api/basic_json/contains/#notes","title":"Notes","text":"

    Postconditions

    If j.contains(x) returns true for a key or JSON pointer x, then it is safe to call j[x].

    "},{"location":"api/basic_json/contains/#examples","title":"Examples","text":"Example: (1) check with key

    The example shows how contains() is used.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    // create some JSON values\n    json j_object = R\"( {\"key\": \"value\"} )\"_json;\n    json j_array = R\"( [1, 2, 3] )\"_json;\n\n    // call contains\n    std::cout << std::boolalpha <<\n              \"j_object contains 'key': \" << j_object.contains(\"key\") << '\\n' <<\n              \"j_object contains 'another': \" << j_object.contains(\"another\") << '\\n' <<\n              \"j_array contains 'key': \" << j_array.contains(\"key\") << std::endl;\n}\n

    Output:

    j_object contains 'key': true\nj_object contains 'another': false\nj_array contains 'key': false\n
    Example: (2) check with key using string_view

    The example shows how contains() is used.

    #include <iostream>\n#include <string_view>\n#include <nlohmann/json.hpp>\n\nusing namespace std::string_view_literals;\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    // create some JSON values\n    json j_object = R\"( {\"key\": \"value\"} )\"_json;\n    json j_array = R\"( [1, 2, 3] )\"_json;\n\n    // call contains\n    std::cout << std::boolalpha <<\n              \"j_object contains 'key': \" << j_object.contains(\"key\"sv) << '\\n' <<\n              \"j_object contains 'another': \" << j_object.contains(\"another\"sv) << '\\n' <<\n              \"j_array contains 'key': \" << j_array.contains(\"key\"sv) << std::endl;\n}\n

    Output:

    j_object contains 'key': true\nj_object contains 'another': false\nj_array contains 'key': false\n
    Example: (3) check with JSON pointer

    The example shows how contains() is used.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    // create a JSON value\n    json j =\n    {\n        {\"number\", 1}, {\"string\", \"foo\"}, {\"array\", {1, 2}}\n    };\n\n    std::cout << std::boolalpha\n              << j.contains(\"/number\"_json_pointer) << '\\n'\n              << j.contains(\"/string\"_json_pointer) << '\\n'\n              << j.contains(\"/array\"_json_pointer) << '\\n'\n              << j.contains(\"/array/1\"_json_pointer) << '\\n'\n              << j.contains(\"/array/-\"_json_pointer) << '\\n'\n              << j.contains(\"/array/4\"_json_pointer) << '\\n'\n              << j.contains(\"/baz\"_json_pointer) << std::endl;\n\n    try\n    {\n        // try to use an array index with leading '0'\n        j.contains(\"/array/01\"_json_pointer);\n    }\n    catch (const json::parse_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n\n    try\n    {\n        // try to use an array index that is not a number\n        j.contains(\"/array/one\"_json_pointer);\n    }\n    catch (const json::parse_error& e)\n    {\n        std::cout << e.what() << '\\n';\n    }\n}\n

    Output:

    true\ntrue\ntrue\ntrue\nfalse\nfalse\nfalse\n
    "},{"location":"api/basic_json/contains/#see-also","title":"See also","text":""},{"location":"api/basic_json/contains/#version-history","title":"Version history","text":"
    1. Added in version 3.11.0.
    2. Added in version 3.6.0. Extended template KeyType to support comparable types in version 3.11.0.
    3. Added in version 3.7.0.
    "},{"location":"api/basic_json/count/","title":"nlohmann::basic_json::count","text":"
    // (1)\nsize_type count(const typename object_t::key_type& key) const;\n\n// (2)\ntemplate<typename KeyType>\nsize_type count(KeyType&& key) const;\n
    1. Returns the number of elements with key key. If ObjectType is the default std::map type, the return value will always be 0 (key was not found) or 1 (key was found).
    2. See 1. This overload is only available if KeyType is comparable with typename object_t::key_type and typename object_comparator_t::is_transparent denotes a type.
    "},{"location":"api/basic_json/count/#template-parameters","title":"Template parameters","text":"KeyType A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17)."},{"location":"api/basic_json/count/#parameters","title":"Parameters","text":"key (in) key value of the element to count."},{"location":"api/basic_json/count/#return-value","title":"Return value","text":"

    Number of elements with key key. If the JSON value is not an object, the return value will be 0.

    "},{"location":"api/basic_json/count/#exception-safety","title":"Exception safety","text":"

    Strong exception safety: if an exception occurs, the original value stays intact.

    "},{"location":"api/basic_json/count/#complexity","title":"Complexity","text":"

    Logarithmic in the size of the JSON object.

    "},{"location":"api/basic_json/count/#notes","title":"Notes","text":"

    This method always returns 0 when executed on a JSON type that is not an object.

    "},{"location":"api/basic_json/count/#examples","title":"Examples","text":"Example: (1) count number of elements

    The example shows how count() is used.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n\n    // call count()\n    auto count_two = j_object.count(\"two\");\n    auto count_three = j_object.count(\"three\");\n\n    // print values\n    std::cout << \"number of elements with key \\\"two\\\": \" << count_two << '\\n';\n    std::cout << \"number of elements with key \\\"three\\\": \" << count_three << '\\n';\n}\n

    Output:

    number of elements with key \"two\": 1\nnumber of elements with key \"three\": 0\n
    Example: (2) count number of elements using string_view

    The example shows how count() is used.

    #include <iostream>\n#include <string_view>\n#include <nlohmann/json.hpp>\n\nusing namespace std::string_view_literals;\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n\n    // call count()\n    auto count_two = j_object.count(\"two\"sv);\n    auto count_three = j_object.count(\"three\"sv);\n\n    // print values\n    std::cout << \"number of elements with key \\\"two\\\": \" << count_two << '\\n';\n    std::cout << \"number of elements with key \\\"three\\\": \" << count_three << '\\n';\n}\n

    Output:

    number of elements with key \"two\": 1\nnumber of elements with key \"three\": 0\n
    "},{"location":"api/basic_json/count/#see-also","title":"See also","text":""},{"location":"api/basic_json/count/#version-history","title":"Version history","text":"
    1. Added in version 3.11.0.
    2. Added in version 1.0.0. Changed parameter key type to KeyType&& in version 3.11.0.
    "},{"location":"api/basic_json/crbegin/","title":"nlohmann::basic_json::crbegin","text":"
    const_reverse_iterator crbegin() const noexcept;\n

    Returns an iterator to the reverse-beginning; that is, the last element.

    "},{"location":"api/basic_json/crbegin/#return-value","title":"Return value","text":"

    reverse iterator to the last element

    "},{"location":"api/basic_json/crbegin/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/crbegin/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/crbegin/#examples","title":"Examples","text":"Example

    The following code shows an example for crbegin().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array value\n    json array = {1, 2, 3, 4, 5};\n\n    // get an iterator to the reverse-beginning\n    json::const_reverse_iterator it = array.crbegin();\n\n    // serialize the element that the iterator points to\n    std::cout << *it << '\\n';\n}\n

    Output:

    5\n
    "},{"location":"api/basic_json/crbegin/#version-history","title":"Version history","text":""},{"location":"api/basic_json/crend/","title":"nlohmann::basic_json::crend","text":"
    const_reverse_iterator crend() const noexcept;\n

    Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, attempting to access it results in undefined behavior.

    "},{"location":"api/basic_json/crend/#return-value","title":"Return value","text":"

    reverse iterator to the element following the last element

    "},{"location":"api/basic_json/crend/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/crend/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/crend/#examples","title":"Examples","text":"Example

    The following code shows an example for crend().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array value\n    json array = {1, 2, 3, 4, 5};\n\n    // get an iterator to the reverse-end\n    json::const_reverse_iterator it = array.crend();\n\n    // increment the iterator to point to the first element\n    --it;\n\n    // serialize the element that the iterator points to\n    std::cout << *it << '\\n';\n}\n

    Output:

    1\n
    "},{"location":"api/basic_json/crend/#version-history","title":"Version history","text":""},{"location":"api/basic_json/default_object_comparator_t/","title":"nlohmann::basic_json::default_object_comparator_t","text":"
    using default_object_comparator_t = std::less<StringType>;  // until C++14\n\nusing default_object_comparator_t = std::less<>;            // since C++14\n

    The default comparator used by object_t.

    Since C++14 a transparent comparator is used which prevents unnecessary string construction when looking up a key in an object.

    The actual comparator used depends on object_t and can be obtained via object_comparator_t.

    "},{"location":"api/basic_json/default_object_comparator_t/#examples","title":"Examples","text":"Example

    The example below demonstrates the default comparator.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    std::cout << std::boolalpha\n              << \"one < two : \" << json::default_object_comparator_t{}(\"one\", \"two\") << \"\\n\"\n              << \"three < four : \" << json::default_object_comparator_t{}(\"three\", \"four\") << std::endl;\n}\n

    Output:

    one < two : true\nthree < four : false\n
    "},{"location":"api/basic_json/default_object_comparator_t/#version-history","title":"Version history","text":""},{"location":"api/basic_json/diff/","title":"nlohmann::basic_json::diff","text":"
    static basic_json diff(const basic_json& source,\n                       const basic_json& target);\n

    Creates a JSON Patch so that value source can be changed into the value target by calling patch function.

    For two JSON values source and target, the following code yields always true: 

    source.patch(diff(source, target)) == target;\n

    "},{"location":"api/basic_json/diff/#parameters","title":"Parameters","text":"source (in) JSON value to compare from target (in) JSON value to compare against"},{"location":"api/basic_json/diff/#return-value","title":"Return value","text":"

    a JSON patch to convert the source to target

    "},{"location":"api/basic_json/diff/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

    "},{"location":"api/basic_json/diff/#complexity","title":"Complexity","text":"

    Linear in the lengths of source and target.

    "},{"location":"api/basic_json/diff/#notes","title":"Notes","text":"

    Currently, only remove, add, and replace operations are generated.

    "},{"location":"api/basic_json/diff/#examples","title":"Examples","text":"Example

    The following code shows how a JSON patch is created as a diff for two JSON values.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\nusing namespace nlohmann::literals;\n\nint main()\n{\n    // the source document\n    json source = R\"(\n        {\n            \"baz\": \"qux\",\n            \"foo\": \"bar\"\n        }\n    )\"_json;\n\n    // the target document\n    json target = R\"(\n        {\n            \"baz\": \"boo\",\n            \"hello\": [\n                \"world\"\n            ]\n        }\n    )\"_json;\n\n    // create the patch\n    json patch = json::diff(source, target);\n\n    // roundtrip\n    json patched_source = source.patch(patch);\n\n    // output patch and roundtrip result\n    std::cout << std::setw(4) << patch << \"\\n\\n\"\n              << std::setw(4) << patched_source << std::endl;\n}\n

    Output:

    [\n    {\n        \"op\": \"replace\",\n        \"path\": \"/baz\",\n        \"value\": \"boo\"\n    },\n    {\n        \"op\": \"remove\",\n        \"path\": \"/foo\"\n    },\n    {\n        \"op\": \"add\",\n        \"path\": \"/hello\",\n        \"value\": [\n            \"world\"\n        ]\n    }\n]\n\n{\n    \"baz\": \"boo\",\n    \"hello\": [\n        \"world\"\n    ]\n}\n
    "},{"location":"api/basic_json/diff/#see-also","title":"See also","text":""},{"location":"api/basic_json/diff/#version-history","title":"Version history","text":""},{"location":"api/basic_json/dump/","title":"nlohmann::basic_json::dump","text":"
    string_t dump(const int indent = -1,\n              const char indent_char = ' ',\n              const bool ensure_ascii = false,\n              const error_handler_t error_handler = error_handler_t::strict) const;\n

    Serialization function for JSON values. The function tries to mimic Python's json.dumps() function, and currently supports its indent and ensure_ascii parameters.

    "},{"location":"api/basic_json/dump/#parameters","title":"Parameters","text":"indent (in) If indent is nonnegative, then array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. -1 (the default) selects the most compact representation. indent_char (in) The character to use for indentation if indent is greater than 0. The default is (space). ensure_ascii (in) If ensure_ascii is true, all non-ASCII characters in the output are escaped with \\uXXXX sequences, and the result consists of ASCII characters only. error_handler (in) how to react on decoding errors; there are three possible values (see error_handler_t: strict (throws an exception in case a decoding error occurs; default), replace (replace invalid UTF-8 sequences with U+FFFD), and ignore (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the output unchanged, and invalid bytes are dropped))."},{"location":"api/basic_json/dump/#return-value","title":"Return value","text":"

    string containing the serialization of the JSON value

    "},{"location":"api/basic_json/dump/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

    "},{"location":"api/basic_json/dump/#exceptions","title":"Exceptions","text":"

    Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded and error_handler is set to strict

    Serializing untrusted input

    When serializing values that may contain invalid or untrusted UTF-8 (e.g., bytes taken directly from network input), dump() throws type_error.316 in the default strict mode. To serialize such data without throwing, pass error_handler_t::replace (substitutes U+FFFD) or error_handler_t::ignore. Callers that serialize untrusted input on a crash-sensitive path should either choose a non-strict error handler or wrap dump() in a try/catch.

    See the FAQ for details.

    "},{"location":"api/basic_json/dump/#complexity","title":"Complexity","text":"

    Linear.

    "},{"location":"api/basic_json/dump/#notes","title":"Notes","text":"

    Binary values are serialized as an object containing two keys:

    "},{"location":"api/basic_json/dump/#examples","title":"Examples","text":"Example

    The following example shows the effect of different indent, indent_char, and ensure_ascii parameters to the result of the serialization.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_array = {1, 2, 4, 8, 16};\n    json j_string = \"Hell\u00f6 \ud83d\ude00!\";\n\n    // call dump()\n    std::cout << \"objects:\" << '\\n'\n              << j_object.dump() << \"\\n\\n\"\n              << j_object.dump(-1) << \"\\n\\n\"\n              << j_object.dump(0) << \"\\n\\n\"\n              << j_object.dump(4) << \"\\n\\n\"\n              << j_object.dump(1, '\\t') << \"\\n\\n\";\n\n    std::cout << \"arrays:\" << '\\n'\n              << j_array.dump() << \"\\n\\n\"\n              << j_array.dump(-1) << \"\\n\\n\"\n              << j_array.dump(0) << \"\\n\\n\"\n              << j_array.dump(4) << \"\\n\\n\"\n              << j_array.dump(1, '\\t') << \"\\n\\n\";\n\n    std::cout << \"strings:\" << '\\n'\n              << j_string.dump() << '\\n'\n              << j_string.dump(-1, ' ', true) << '\\n';\n\n    // create JSON value with invalid UTF-8 byte sequence\n    json j_invalid = \"\u00e4\\xA9\u00fc\";\n    try\n    {\n        std::cout << j_invalid.dump() << std::endl;\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << std::endl;\n    }\n\n    std::cout << \"string with replaced invalid characters: \"\n              << j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)\n              << \"\\nstring with ignored invalid characters: \"\n              << j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)\n              << '\\n';\n}\n

    Output:

    objects:\n{\"one\":1,\"two\":2}\n\n{\"one\":1,\"two\":2}\n\n{\n\"one\": 1,\n\"two\": 2\n}\n\n{\n    \"one\": 1,\n    \"two\": 2\n}\n\n{\n    \"one\": 1,\n    \"two\": 2\n}\n\narrays:\n[1,2,4,8,16]\n\n[1,2,4,8,16]\n\n[\n1,\n2,\n4,\n8,\n16\n]\n\n[\n    1,\n    2,\n    4,\n    8,\n    16\n]\n\n[\n    1,\n    2,\n    4,\n    8,\n    16\n]\n\nstrings:\n\"Hell\u00f6 \ud83d\ude00!\"\n\"Hell\\u00f6 \\ud83d\\ude00!\"\n[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9\nstring with replaced invalid characters: \"\u00e4\ufffd\u00fc\"\nstring with ignored invalid characters: \"\u00e4\u00fc\"\n
    "},{"location":"api/basic_json/dump/#see-also","title":"See also","text":""},{"location":"api/basic_json/dump/#version-history","title":"Version history","text":""},{"location":"api/basic_json/emplace/","title":"nlohmann::basic_json::emplace","text":"
    template<class... Args>\nstd::pair<iterator, bool> emplace(Args&& ... args);\n

    Inserts a new element into a JSON object constructed in-place with the given args if there is no element with the key in the container. If the function is called on a JSON null value, an empty object is created before appending the value created from args.

    "},{"location":"api/basic_json/emplace/#template-parameters","title":"Template parameters","text":"Args compatible types to create a basic_json object"},{"location":"api/basic_json/emplace/#iterator-invalidation","title":"Iterator invalidation","text":"

    For ordered_json, adding a value to an object can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

    "},{"location":"api/basic_json/emplace/#parameters","title":"Parameters","text":"args (in) arguments to forward to a constructor of basic_json"},{"location":"api/basic_json/emplace/#return-value","title":"Return value","text":"

    a pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.

    "},{"location":"api/basic_json/emplace/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

    "},{"location":"api/basic_json/emplace/#exceptions","title":"Exceptions","text":"

    Throws type_error.311 when called on a type other than JSON object or null; example: \"cannot use emplace() with number\"

    "},{"location":"api/basic_json/emplace/#complexity","title":"Complexity","text":"

    Logarithmic in the size of the container, O(log(size())).

    "},{"location":"api/basic_json/emplace/#examples","title":"Examples","text":"Example

    The example shows how emplace() can be used to add elements to a JSON object. Note how the null value was silently converted to a JSON object. Further note how no value is added if there was already one value stored with the same key.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json object = {{\"one\", 1}, {\"two\", 2}};\n    json null;\n\n    // print values\n    std::cout << object << '\\n';\n    std::cout << null << '\\n';\n\n    // add values\n    auto res1 = object.emplace(\"three\", 3);\n    null.emplace(\"A\", \"a\");\n    null.emplace(\"B\", \"b\");\n\n    // the following call will not add an object, because there is already\n    // a value stored at key \"B\"\n    auto res2 = null.emplace(\"B\", \"c\");\n\n    // print values\n    std::cout << object << '\\n';\n    std::cout << *res1.first << \" \" << std::boolalpha << res1.second << '\\n';\n\n    std::cout << null << '\\n';\n    std::cout << *res2.first << \" \" << std::boolalpha << res2.second << '\\n';\n}\n

    Output:

    {\"one\":1,\"two\":2}\nnull\n{\"one\":1,\"three\":3,\"two\":2}\n3 true\n{\"A\":\"a\",\"B\":\"b\"}\n\"b\" false\n
    "},{"location":"api/basic_json/emplace/#see-also","title":"See also","text":""},{"location":"api/basic_json/emplace/#version-history","title":"Version history","text":""},{"location":"api/basic_json/emplace_back/","title":"nlohmann::basic_json::emplace_back","text":"
    template<class... Args>\nreference emplace_back(Args&& ... args);\n

    Creates a JSON value from the passed parameters args to the end of the JSON value. If the function is called on a JSON null value, an empty array is created before appending the value created from args.

    "},{"location":"api/basic_json/emplace_back/#template-parameters","title":"Template parameters","text":"Args compatible types to create a basic_json object"},{"location":"api/basic_json/emplace_back/#iterator-invalidation","title":"Iterator invalidation","text":"

    By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise, only the end() iterator is invalidated.

    "},{"location":"api/basic_json/emplace_back/#parameters","title":"Parameters","text":"args (in) arguments to forward to a constructor of basic_json"},{"location":"api/basic_json/emplace_back/#return-value","title":"Return value","text":"

    reference to the inserted element

    "},{"location":"api/basic_json/emplace_back/#exceptions","title":"Exceptions","text":"

    Throws type_error.311 when called on a type other than JSON array or null; example: \"cannot use emplace_back() with number\"

    "},{"location":"api/basic_json/emplace_back/#complexity","title":"Complexity","text":"

    Amortized constant.

    "},{"location":"api/basic_json/emplace_back/#examples","title":"Examples","text":"Example

    The example shows how emplace_back() can be used to add elements to a JSON array. Note how the null value was silently converted to a JSON array.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json array = {1, 2, 3, 4, 5};\n    json null;\n\n    // print values\n    std::cout << array << '\\n';\n    std::cout << null << '\\n';\n\n    // add values\n    array.emplace_back(6);\n    null.emplace_back(\"first\");\n    null.emplace_back(3, \"second\");\n\n    // print values\n    std::cout << array << '\\n';\n    std::cout << null << '\\n';\n}\n

    Output:

    [1,2,3,4,5]\nnull\n[1,2,3,4,5,6]\n[\"first\",[\"second\",\"second\",\"second\"]]\n
    "},{"location":"api/basic_json/emplace_back/#see-also","title":"See also","text":""},{"location":"api/basic_json/emplace_back/#version-history","title":"Version history","text":""},{"location":"api/basic_json/empty/","title":"nlohmann::basic_json::empty","text":"
    bool empty() const noexcept;\n

    Checks if a JSON value has no elements (i.e., whether its size() is 0).

    "},{"location":"api/basic_json/empty/#return-value","title":"Return value","text":"

    The return value depends on the different types and is defined as follows:

    Value type return value null true boolean false string false number false binary false object result of function object_t::empty() array result of function array_t::empty()"},{"location":"api/basic_json/empty/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this function never throws exceptions.

    "},{"location":"api/basic_json/empty/#complexity","title":"Complexity","text":"

    Constant, as long as array_t and object_t satisfy the Container concept; that is, their empty() functions have constant complexity.

    "},{"location":"api/basic_json/empty/#possible-implementation","title":"Possible implementation","text":"
    bool empty() const noexcept\n{\n    return size() == 0;\n}\n
    "},{"location":"api/basic_json/empty/#notes","title":"Notes","text":"

    This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container itself is empty which is false in the case of a string.

    "},{"location":"api/basic_json/empty/#examples","title":"Examples","text":"Example

    The following code uses empty() to check if a JSON object contains any elements.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_null;\n    json j_boolean = true;\n    json j_number_integer = 17;\n    json j_number_float = 23.42;\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_object_empty(json::value_t::object);\n    json j_array = {1, 2, 4, 8, 16};\n    json j_array_empty(json::value_t::array);\n    json j_string = \"Hello, world\";\n\n    // call empty()\n    std::cout << std::boolalpha;\n    std::cout << j_null.empty() << '\\n';\n    std::cout << j_boolean.empty() << '\\n';\n    std::cout << j_number_integer.empty() << '\\n';\n    std::cout << j_number_float.empty() << '\\n';\n    std::cout << j_object.empty() << '\\n';\n    std::cout << j_object_empty.empty() << '\\n';\n    std::cout << j_array.empty() << '\\n';\n    std::cout << j_array_empty.empty() << '\\n';\n    std::cout << j_string.empty() << '\\n';\n}\n

    Output:

    true\nfalse\nfalse\nfalse\nfalse\ntrue\nfalse\ntrue\nfalse\n
    "},{"location":"api/basic_json/empty/#version-history","title":"Version history","text":""},{"location":"api/basic_json/end/","title":"nlohmann::basic_json::end","text":"
    iterator end() noexcept;\nconst_iterator end() const noexcept;\n

    Returns an iterator to one past the last element.

    "},{"location":"api/basic_json/end/#return-value","title":"Return value","text":"

    iterator one past the last element

    "},{"location":"api/basic_json/end/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/end/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/end/#examples","title":"Examples","text":"Example

    The following code shows an example for end().

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create an array value\n    json array = {1, 2, 3, 4, 5};\n\n    // get an iterator to one past the last element\n    json::iterator it = array.end();\n\n    // decrement the iterator to point to the last element\n    --it;\n\n    // serialize the element that the iterator points to\n    std::cout << *it << '\\n';\n}\n

    Output:

    5\n
    "},{"location":"api/basic_json/end/#version-history","title":"Version history","text":""},{"location":"api/basic_json/end_pos/","title":"nlohmann::basic_json::end_pos","text":"
    #if JSON_DIAGNOSTIC_POSITIONS\nconstexpr std::size_t end_pos() const noexcept;\n#endif\n

    Returns the position immediately following the last character of the JSON string from which the value was parsed from.

    JSON type return value object position after the closing } array position after the closing ] string position after the closing \" number position after the last character boolean position after e null position after l"},{"location":"api/basic_json/end_pos/#return-value","title":"Return value","text":"

    the position of the character following the last character of the given value in the parsed JSON string, if the value was created by the parse function, or std::string::npos if the value was constructed otherwise

    "},{"location":"api/basic_json/end_pos/#exception-safety","title":"Exception safety","text":"

    No-throw guarantee: this member function never throws exceptions.

    "},{"location":"api/basic_json/end_pos/#complexity","title":"Complexity","text":"

    Constant.

    "},{"location":"api/basic_json/end_pos/#notes","title":"Notes","text":"

    Note

    The function is only available if macro JSON_DIAGNOSTIC_POSITIONS has been defined to 1 before including the library header.

    Invalidation

    The returned positions are only valid as long as the JSON value is not changed. The positions are not updated when the JSON value is changed.

    "},{"location":"api/basic_json/end_pos/#examples","title":"Examples","text":"Example 
    #include <iostream>\n\n#define JSON_DIAGNOSTIC_POSITIONS 1\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    std::string json_string = R\"(\n    {\n        \"address\": {\n            \"street\": \"Fake Street\",\n            \"housenumber\": 1\n        }\n    }\n    )\";\n    json j = json::parse(json_string);\n\n    std::cout << \"Root diagnostic positions: \\n\";\n    std::cout << \"\\tstart_pos: \" << j.start_pos() << '\\n';\n    std::cout << \"\\tend_pos:\" << j.end_pos() << \"\\n\";\n    std::cout << \"Original string: \\n\";\n    std::cout << \"{\\n        \\\"address\\\": {\\n            \\\"street\\\": \\\"Fake Street\\\",\\n            \\\"housenumber\\\": 1\\n        }\\n    }\" << \"\\n\";\n    std::cout << \"Parsed string: \\n\";\n    std::cout << json_string.substr(j.start_pos(), j.end_pos() - j.start_pos()) << \"\\n\\n\";\n\n    std::cout << \"address diagnostic positions: \\n\";\n    std::cout << \"\\tstart_pos:\" << j[\"address\"].start_pos() << '\\n';\n    std::cout << \"\\tend_pos:\" << j[\"address\"].end_pos() << \"\\n\\n\";\n    std::cout << \"Original string: \\n\";\n    std::cout << \"{            \\\"street\\\": \\\"Fake Street\\\",\\n            \\\"housenumber\\\": 1\\n        }\" << \"\\n\";\n    std::cout << \"Parsed string: \\n\";\n    std::cout << json_string.substr(j[\"address\"].start_pos(), j[\"address\"].end_pos() - j[\"address\"].start_pos()) << \"\\n\\n\";\n\n    std::cout << \"street diagnostic positions: \\n\";\n    std::cout << \"\\tstart_pos:\" << j[\"address\"][\"street\"].start_pos() << '\\n';\n    std::cout << \"\\tend_pos:\" << j[\"address\"][\"street\"].end_pos() << \"\\n\\n\";\n    std::cout << \"Original string: \\n\";\n    std::cout << \"\\\"Fake Street\\\"\" << \"\\n\";\n    std::cout << \"Parsed string: \\n\";\n    std::cout << json_string.substr(j[\"address\"][\"street\"].start_pos(), j[\"address\"][\"street\"].end_pos() - j[\"address\"][\"street\"].start_pos()) << \"\\n\\n\";\n\n    std::cout << \"housenumber diagnostic positions: \\n\";\n    std::cout << \"\\tstart_pos:\" << j[\"address\"][\"housenumber\"].start_pos() << '\\n';\n    std::cout << \"\\tend_pos:\" << j[\"address\"][\"housenumber\"].end_pos() << \"\\n\\n\";\n    std::cout << \"Original string: \\n\";\n    std::cout << \"1\" << \"\\n\";\n    std::cout << \"Parsed string: \\n\";\n    std::cout << json_string.substr(j[\"address\"][\"housenumber\"].start_pos(), j[\"address\"][\"housenumber\"].end_pos() - j[\"address\"][\"housenumber\"].start_pos()) << \"\\n\\n\";\n}\n

    Output:

    Root diagnostic positions: \n    start_pos: 5\n    end_pos:109\nOriginal string: \n{\n        \"address\": {\n            \"street\": \"Fake Street\",\n            \"housenumber\": 1\n        }\n    }\nParsed string: \n{\n        \"address\": {\n            \"street\": \"Fake Street\",\n            \"housenumber\": 1\n        }\n    }\n\naddress diagnostic positions: \n    start_pos:26\n    end_pos:103\n\nOriginal string: \n{            \"street\": \"Fake Street\",\n            \"housenumber\": 1\n        }\nParsed string: \n{\n            \"street\": \"Fake Street\",\n            \"housenumber\": 1\n        }\n\nstreet diagnostic positions: \n    start_pos:50\n    end_pos:63\n\nOriginal string: \n\"Fake Street\"\nParsed string: \n\"Fake Street\"\n\nhousenumber diagnostic positions: \n    start_pos:92\n    end_pos:93\n\nOriginal string: \n1\nParsed string: \n1\n

    The output shows the start/end positions of all the objects and fields in the JSON string.

    "},{"location":"api/basic_json/end_pos/#see-also","title":"See also","text":""},{"location":"api/basic_json/end_pos/#version-history","title":"Version history","text":""},{"location":"api/basic_json/erase/","title":"nlohmann::basic_json::erase","text":"
    // (1)\niterator erase(iterator pos);\nconst_iterator erase(const_iterator pos);\n\n// (2)\niterator erase(iterator first, iterator last);\nconst_iterator erase(const_iterator first, const_iterator last);\n\n// (3)\nsize_type erase(const typename object_t::key_type& key);\n\n// (4)\ntemplate<typename KeyType>\nsize_type erase(KeyType&& key);\n\n// (5)\nvoid erase(const size_type idx);\n

    1. Removes an element from a JSON value specified by iterator pos. The iterator pos must be valid and dereferenceable. Thus, the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

      If called on a primitive type other than null, the resulting JSON value will be null.

    2. Remove an element range specified by [first; last) from a JSON value. The iterator first does not need to be dereferenceable if first == last: erasing an empty range is a no-op.

      If called on a primitive type other than null, the resulting JSON value will be null.

    3. Removes an element from a JSON object by key.

    4. See 3. This overload is only available if KeyType is comparable with typename object_t::key_type and typename object_comparator_t::is_transparent denotes a type.

    5. Removes an element from a JSON array by index.

    "},{"location":"api/basic_json/erase/#template-parameters","title":"Template parameters","text":"KeyType A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17)."},{"location":"api/basic_json/erase/#parameters","title":"Parameters","text":"pos (in) iterator to the element to remove first (in) iterator to the beginning of the range to remove last (in) iterator past the end of the range to remove key (in) object key of the elements to remove idx (in) array index of the element to remove"},{"location":"api/basic_json/erase/#return-value","title":"Return value","text":"
    1. Iterator following the last removed element. If the iterator pos refers to the last element, the end() iterator is returned.
    2. Iterator following the last removed element. If the iterator last refers to the last element, the end() iterator is returned.
    3. Number of elements removed. If ObjectType is the default std::map type, the return value will always be 0 (key was not found) or 1 (key was found).
    4. See 3.
    5. (none)
    "},{"location":"api/basic_json/erase/#exception-safety","title":"Exception safety","text":"

    Strong exception safety: if an exception occurs, the original value stays intact.

    "},{"location":"api/basic_json/erase/#exceptions","title":"Exceptions","text":"
    1. The function can throw the following exceptions:
      • Throws type_error.307 if called on a null value; example: \"cannot use erase() with null\"
      • Throws invalid_iterator.202 if called on an iterator which does not belong to the current JSON value; example: \"iterator does not fit current value\"
      • Throws invalid_iterator.205 if called on a primitive type with invalid iterator (i.e., any iterator which is not begin()); example: \"iterator out of range\"
    2. The function can throw the following exceptions:
      • Throws type_error.307 if called on a null value; example: \"cannot use erase() with null\"
      • Throws invalid_iterator.203 if called on iterators which does not belong to the current JSON value; example: \"iterators do not fit current value\"
      • Throws invalid_iterator.204 if called on a primitive type with invalid iterators (i.e., if first != begin() and last != end()); example: \"iterators out of range\"
    3. The function can throw the following exceptions:
      • Throws type_error.307 when called on a type other than JSON object; example: \"cannot use erase() with null\"
    4. See 3.
    5. The function can throw the following exceptions:
      • Throws type_error.307 when called on a type other than JSON array; example: \"cannot use erase() with null\"
      • Throws out_of_range.401 when idx >= size(); example: \"array index 17 is out of range\"
    "},{"location":"api/basic_json/erase/#complexity","title":"Complexity","text":"
    1. The complexity depends on the type:
      • objects: amortized constant
      • arrays: linear in distance between pos and the end of the container
      • strings and binary: linear in the length of the member
      • other types: constant
    2. The complexity depends on the type:
      • objects: log(size()) + std::distance(first, last)
      • arrays: linear in the distance between first and last, plus linear in the distance between last and end of the container
      • strings and binary: linear in the length of the member
      • other types: constant
    3. log(size()) + count(key)
    4. log(size()) + count(key)
    5. Linear in distance between idx and the end of the container.
    "},{"location":"api/basic_json/erase/#notes","title":"Notes","text":"
    1. Invalidates iterators and references at or after the point of the erase, including the end() iterator.
    2. (none)
    3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
    4. See 3.
    5. (none)
    "},{"location":"api/basic_json/erase/#examples","title":"Examples","text":"Example: (1) remove element given an iterator

    The example shows the effect of erase() for different JSON types using an iterator.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_boolean = true;\n    json j_number_integer = 17;\n    json j_number_float = 23.42;\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_array = {1, 2, 4, 8, 16};\n    json j_string = \"Hello, world\";\n\n    // call erase()\n    j_boolean.erase(j_boolean.begin());\n    j_number_integer.erase(j_number_integer.begin());\n    j_number_float.erase(j_number_float.begin());\n    j_object.erase(j_object.find(\"two\"));\n    j_array.erase(j_array.begin() + 2);\n    j_string.erase(j_string.begin());\n\n    // print values\n    std::cout << j_boolean << '\\n';\n    std::cout << j_number_integer << '\\n';\n    std::cout << j_number_float << '\\n';\n    std::cout << j_object << '\\n';\n    std::cout << j_array << '\\n';\n    std::cout << j_string << '\\n';\n}\n

    Output:

    null\nnull\nnull\n{\"one\":1}\n[1,2,8,16]\nnull\n
    Example: (2) remove elements given an iterator range

    The example shows the effect of erase() for different JSON types using an iterator range.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON values\n    json j_boolean = true;\n    json j_number_integer = 17;\n    json j_number_float = 23.42;\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n    json j_array = {1, 2, 4, 8, 16};\n    json j_string = \"Hello, world\";\n\n    // call erase()\n    j_boolean.erase(j_boolean.begin(), j_boolean.end());\n    j_number_integer.erase(j_number_integer.begin(), j_number_integer.end());\n    j_number_float.erase(j_number_float.begin(), j_number_float.end());\n    j_object.erase(j_object.find(\"two\"), j_object.end());\n    j_array.erase(j_array.begin() + 1, j_array.begin() + 3);\n    j_string.erase(j_string.begin(), j_string.end());\n\n    // print values\n    std::cout << j_boolean << '\\n';\n    std::cout << j_number_integer << '\\n';\n    std::cout << j_number_float << '\\n';\n    std::cout << j_object << '\\n';\n    std::cout << j_array << '\\n';\n    std::cout << j_string << '\\n';\n}\n

    Output:

    null\nnull\nnull\n{\"one\":1}\n[1,8,16]\nnull\n
    Example: (3) remove element from a JSON object given a key

    The example shows the effect of erase() for different JSON types using an object key.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n\n    // call erase()\n    auto count_one = j_object.erase(\"one\");\n    auto count_three = j_object.erase(\"three\");\n\n    // print values\n    std::cout << j_object << '\\n';\n    std::cout << count_one << \" \" << count_three << '\\n';\n}\n

    Output:

    {\"two\":2}\n1 0\n
    Example: (4) remove element from a JSON object given a key using string_view

    The example shows the effect of erase() for different JSON types using an object key.

    #include <iostream>\n#include <string_view>\n#include <nlohmann/json.hpp>\n\nusing namespace std::string_view_literals;\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n\n    // call erase()\n    auto count_one = j_object.erase(\"one\"sv);\n    auto count_three = j_object.erase(\"three\"sv);\n\n    // print values\n    std::cout << j_object << '\\n';\n    std::cout << count_one << \" \" << count_three << '\\n';\n}\n

    Output:

    {\"two\":2}\n1 0\n
    Example: (5) remove element from a JSON array given an index

    The example shows the effect of erase() using an array index.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON array\n    json j_array = {0, 1, 2, 3, 4, 5};\n\n    // call erase()\n    j_array.erase(2);\n\n    // print values\n    std::cout << j_array << '\\n';\n}\n

    Output:

    [0,1,3,4,5]\n
    "},{"location":"api/basic_json/erase/#see-also","title":"See also","text":""},{"location":"api/basic_json/erase/#version-history","title":"Version history","text":"
    1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
    2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
    3. Added in version 1.0.0.
    4. Added in version 3.11.0.
    5. Added in version 1.0.0.
    "},{"location":"api/basic_json/error_handler_t/","title":"nlohmann::basic_json::error_handler_t","text":"
    enum class error_handler_t {\n    strict,\n    replace,\n    ignore\n};\n

    This enumeration is used in the dump function to choose how to treat decoding errors while serializing a basic_json value. Three values are differentiated:

    strict throw a type_error exception in case of invalid UTF-8 replace replace invalid UTF-8 sequences with U+FFFD (\ufffd REPLACEMENT CHARACTER) ignore ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped"},{"location":"api/basic_json/error_handler_t/#examples","title":"Examples","text":"Example

    The example below shows how the different values of the error_handler_t influence the behavior of dump when reading serializing an invalid UTF-8 sequence.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON value with invalid UTF-8 byte sequence\n    json j_invalid = \"\u00e4\\xA9\u00fc\";\n    try\n    {\n        std::cout << j_invalid.dump() << std::endl;\n    }\n    catch (const json::type_error& e)\n    {\n        std::cout << e.what() << std::endl;\n    }\n\n    std::cout << \"string with replaced invalid characters: \"\n              << j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)\n              << \"\\nstring with ignored invalid characters: \"\n              << j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)\n              << '\\n';\n}\n

    Output:

    [json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9\nstring with replaced invalid characters: \"\u00e4\ufffd\u00fc\"\nstring with ignored invalid characters: \"\u00e4\u00fc\"\n
    "},{"location":"api/basic_json/error_handler_t/#version-history","title":"Version history","text":""},{"location":"api/basic_json/exception/","title":"nlohmann::basic_json::exception","text":"
    class exception : public std::exception;\n

    This class is an extension of std::exception objects with a member id for exception ids. It is used as the base class for all exceptions thrown by the basic_json class. This class can hence be used as \"wildcard\" to catch exceptions, see example below.

    classDiagram\n  direction LR\n\n    class std_exception [\"std::exception\"] {\n        <<interface>>\n    }\n\n    class json_exception [\"basic_json::exception\"] {\n        +const int id\n        +const char* what() const\n    }\n\n    class json_parse_error [\"basic_json::parse_error\"] {\n        +const std::size_t byte\n    }\n\n    class json_invalid_iterator [\"basic_json::invalid_iterator\"]\n    class json_type_error [\"basic_json::type_error\"]\n    class json_out_of_range [\"basic_json::out_of_range\"]\n    class json_other_error [\"basic_json::other_error\"]\n\n    std_exception <|-- json_exception\n    json_exception <|-- json_parse_error\n    json_exception <|-- json_invalid_iterator\n    json_exception <|-- json_type_error\n    json_exception <|-- json_out_of_range\n    json_exception <|-- json_other_error\n\n    style json_exception fill:#CCCCFF

    Subclasses:

    "},{"location":"api/basic_json/exception/#member-functions","title":"Member functions","text":""},{"location":"api/basic_json/exception/#member-variables","title":"Member variables","text":""},{"location":"api/basic_json/exception/#notes","title":"Notes","text":"

    To have nothrow-copy-constructible exceptions, we internally use std::runtime_error which can cope with arbitrary-length error messages. Intermediate strings are built with static functions and then passed to the actual constructor.

    "},{"location":"api/basic_json/exception/#examples","title":"Examples","text":"Example

    The following code shows how arbitrary library exceptions can be caught.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    try\n    {\n        // calling at() for a non-existing key\n        json j = {{\"foo\", \"bar\"}};\n        json k = j.at(\"non-existing\");\n    }\n    catch (const json::exception& e)\n    {\n        // output exception information\n        std::cout << \"message: \" << e.what() << '\\n'\n                  << \"exception id: \" << e.id << std::endl;\n    }\n}\n

    Output:

    message: [json.exception.out_of_range.403] key 'non-existing' not found\nexception id: 403\n
    "},{"location":"api/basic_json/exception/#see-also","title":"See also","text":"

    List of exceptions

    "},{"location":"api/basic_json/exception/#version-history","title":"Version history","text":""},{"location":"api/basic_json/find/","title":"nlohmann::basic_json::find","text":"
    // (1)\niterator find(const typename object_t::key_type& key);\nconst_iterator find(const typename object_t::key_type& key) const;\n\n// (2)\ntemplate<typename KeyType>\niterator find(KeyType&& key);\ntemplate<typename KeyType>\nconst_iterator find(KeyType&& key) const;\n
    1. Finds an element in a JSON object with a key equivalent to key. If the element is not found or the JSON value is not an object, end() is returned.
    2. See 1. This overload is only available if KeyType is comparable with typename object_t::key_type and typename object_comparator_t::is_transparent denotes a type.
    "},{"location":"api/basic_json/find/#template-parameters","title":"Template parameters","text":"KeyType A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17)."},{"location":"api/basic_json/find/#parameters","title":"Parameters","text":"key (in) key value of the element to search for."},{"location":"api/basic_json/find/#return-value","title":"Return value","text":"

    Iterator to an element with a key equivalent to key. If no such element is found or the JSON value is not an object, a past-the-end iterator (see end()) is returned.

    "},{"location":"api/basic_json/find/#exception-safety","title":"Exception safety","text":"

    Strong exception safety: if an exception occurs, the original value stays intact.

    "},{"location":"api/basic_json/find/#complexity","title":"Complexity","text":"

    Logarithmic in the size of the JSON object.

    "},{"location":"api/basic_json/find/#notes","title":"Notes","text":"

    This method always returns end() when executed on a JSON type that is not an object.

    "},{"location":"api/basic_json/find/#examples","title":"Examples","text":"Example: (1) find object element by key

    The example shows how find() is used.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n\n    // call find\n    auto it_two = j_object.find(\"two\");\n    auto it_three = j_object.find(\"three\");\n\n    // print values\n    std::cout << std::boolalpha;\n    std::cout << \"\\\"two\\\" was found: \" << (it_two != j_object.end()) << '\\n';\n    std::cout << \"value at key \\\"two\\\": \" << *it_two << '\\n';\n    std::cout << \"\\\"three\\\" was found: \" << (it_three != j_object.end()) << '\\n';\n}\n

    Output:

    \"two\" was found: true\nvalue at key \"two\": 2\n\"three\" was found: false\n
    Example: (2) find object element by key using string_view

    The example shows how find() is used.

    #include <iostream>\n#include <string_view>\n#include <nlohmann/json.hpp>\n\nusing namespace std::string_view_literals;\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON object\n    json j_object = {{\"one\", 1}, {\"two\", 2}};\n\n    // call find\n    auto it_two = j_object.find(\"two\"sv);\n    auto it_three = j_object.find(\"three\"sv);\n\n    // print values\n    std::cout << std::boolalpha;\n    std::cout << \"\\\"two\\\" was found: \" << (it_two != j_object.end()) << '\\n';\n    std::cout << \"value at key \\\"two\\\": \" << *it_two << '\\n';\n    std::cout << \"\\\"three\\\" was found: \" << (it_three != j_object.end()) << '\\n';\n}\n

    Output:

    \"two\" was found: true\nvalue at key \"two\": 2\n\"three\" was found: false\n
    "},{"location":"api/basic_json/find/#see-also","title":"See also","text":""},{"location":"api/basic_json/find/#version-history","title":"Version history","text":"
    1. Added in version 3.11.0.
    2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
    "},{"location":"api/basic_json/flatten/","title":"nlohmann::basic_json::flatten","text":"
    basic_json flatten() const;\n

    The function creates a JSON object whose keys are JSON pointers (see RFC 6901) and whose values are all primitive (see is_primitive() for more information). The original JSON value can be restored using the unflatten() function.

    "},{"location":"api/basic_json/flatten/#return-value","title":"Return value","text":"

    an object that maps JSON pointers to primitive values

    "},{"location":"api/basic_json/flatten/#exception-safety","title":"Exception safety","text":"

    Strong exception safety: if an exception occurs, the original value stays intact.

    "},{"location":"api/basic_json/flatten/#complexity","title":"Complexity","text":"

    Linear in the size of the JSON value.

    "},{"location":"api/basic_json/flatten/#notes","title":"Notes","text":"

    Empty objects and arrays are flattened to null and will not be reconstructed correctly by the unflatten() function.

    "},{"location":"api/basic_json/flatten/#examples","title":"Examples","text":"Example

    The following code shows how a JSON object is flattened to an object whose keys consist of JSON pointers.

    #include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create JSON value\n    json j =\n    {\n        {\"pi\", 3.141},\n        {\"happy\", true},\n        {\"name\", \"Niels\"},\n        {\"nothing\", nullptr},\n        {\n            \"answer\", {\n                {\"everything\", 42}\n            }\n        },\n        {\"list\", {1, 0, 2}},\n        {\n            \"object\", {\n                {\"currency\", \"USD\"},\n                {\"value\", 42.99}\n            }\n        }\n    };\n\n    // call flatten()\n    std::cout << std::setw(4) << j.flatten() << '\\n';\n}\n

    Output:

    {\n    \"/answer/everything\": 42,\n    \"/happy\": true,\n    \"/list/0\": 1,\n    \"/list/1\": 0,\n    \"/list/2\": 2,\n    \"/name\": \"Niels\",\n    \"/nothing\": null,\n    \"/object/currency\": \"USD\",\n    \"/object/value\": 42.99,\n    \"/pi\": 3.141\n}\n
    "},{"location":"api/basic_json/flatten/#see-also","title":"See also","text":""},{"location":"api/basic_json/flatten/#version-history","title":"Version history","text":""},{"location":"api/basic_json/format_as/","title":"format_as(basic_json)","text":"
    template <typename BasicJsonType>\nstd::string format_as(const BasicJsonType& j);\n

    This function implements the format_as customization point used by the {fmt} library (fmtlib). It has no dependency on any fmt header and no effect at all unless a caller's translation unit also includes fmt and calls fmt::format/fmt::print on a JSON value.

    "},{"location":"api/basic_json/format_as/#template-parameters","title":"Template parameters","text":"BasicJsonType a specialization of basic_json"},{"location":"api/basic_json/format_as/#return-value","title":"Return value","text":"

    string containing the serialization of the JSON value (same as dump())

    "},{"location":"api/basic_json/format_as/#exception-safety","title":"Exception safety","text":"

    Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

    "},{"location":"api/basic_json/format_as/#exceptions","title":"Exceptions","text":"

    Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded

    "},{"location":"api/basic_json/format_as/#complexity","title":"Complexity","text":"

    Linear.

    "},{"location":"api/basic_json/format_as/#possible-implementation","title":"Possible implementation","text":"
    template <typename BasicJsonType>\nstd::string format_as(const BasicJsonType& j)\n{\n    return j.dump();\n}\n
    "},{"location":"api/basic_json/format_as/#notes","title":"Notes","text":"

    Version-dependent effect on fmt

    fmt only picks up a format_as overload that returns a std::string in fmt 10.0.0 through 11.0.2. Starting with fmt 11.1.0, fmt restricts automatic format_as pickup to overloads that return an arithmetic type, so this function has no effect there (it is simply unused, not a compile error).

    If you use fmt >= 11.1.0, or want the same pretty-print spec support that std::formatter<basic_json> has (\"{:#}\", a width to set the indent such as \"{:2}\"/\"{:#2}\", and fill-and-align to pick the indent character such as \"{:.>#}\"), define your own fmt::formatter specialization mirroring the same logic:

    template <>\nstruct fmt::formatter<nlohmann::json>\n{\n    // -1 means compact output (dump()); any value >= 0 means pretty-printed\n    // output with that many spaces (or indent_char) per level.\n    int indent = -1;\n    char indent_char = ' ';\n\n    constexpr auto parse(format_parse_context& ctx) -> format_parse_context::iterator\n    {\n        auto it = ctx.begin();\n        const auto end = ctx.end();\n        constexpr auto is_align = [](char c)\n        {\n            return c == '<' || c == '>' || c == '^';\n        };\n\n        // [[fill] align] - repurposed here to pick a custom indent character\n        if (it != end && it + 1 != end && is_align(it[1]))\n        {\n            indent_char = *it;\n            it += 2;\n        }\n        else if (it != end && is_align(*it))\n        {\n            ++it;\n        }\n\n        // ['#'] - \"alternate form\", used here to request pretty-printing with a\n        // default indent of 4 (overridden by an explicit width below, if given)\n        if (it != end && *it == '#')\n        {\n            indent = 4;\n            ++it;\n        }\n\n        // [width] - repurposed here to pick the indent size; a width without '#'\n        // implies pretty-printing since an indent otherwise has no meaning\n        if (it != end && *it >= '1' && *it <= '9')\n        {\n            indent = 0;\n            while (it != end && *it >= '0' && *it <= '9')\n            {\n                indent = (indent * 10) + (*it - '0');\n                ++it;\n            }\n        }\n\n        if (it != end && *it != '}')\n        {\n            throw fmt::format_error(\"invalid format args for nlohmann::json\");\n        }\n\n        return it;\n    }\n\n    auto format(const nlohmann::json& j, format_context& ctx) const\n    {\n        const auto dumped = j.dump(indent, indent_char);\n        return fmt::format_to(ctx.out(), \"{}\", dumped);\n    }\n};\n

    This recipe isn't shipped by the library itself, since doing so would make fmt a build dependency (see the FAQ entry on using JSON values with std::format or fmt for more background) \u2014 but it is compiled and exercised against a real, current fmt release as part of the library's own test suite (tests/fmt_formatter, via CMake FetchContent), so it's kept in sync with std::formatter<basic_json> and verified to actually work, not just illustrative.

    "},{"location":"api/basic_json/format_as/#examples","title":"Examples","text":"Example

    The following code shows how the library's format_as() function integrates with fmt::format, allowing argument-dependent lookup.

    #include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n    // create a JSON value\n    json j = {{\"one\", 1}, {\"two\", 2}};\n\n    // format_as() is found via argument-dependent lookup, the same way\n    // fmt::format/fmt::print would find it\n    auto j_str = format_as(j);\n\n    std::cout << j_str << std::endl;\n}\n

    Output:

    {\"one\":1,\"two\":2}\n
    "},{"location":"api/basic_json/format_as/#see-also","title":"See also","text":"