1 #pragma once 2 3 #include <exception> // exception 4 #include <stdexcept> // runtime_error 5 #include <string> // to_string 6 7 #include <nlohmann/detail/input/position_t.hpp> 8 #include <nlohmann/detail/macro_scope.hpp> 9 10 namespace nlohmann 11 { 12 namespace detail 13 { 14 //////////////// 15 // exceptions // 16 //////////////// 17 18 /*! 19 @brief general exception of the @ref basic_json class 20 21 This class is an extension of `std::exception` objects with a member @a id for 22 exception ids. It is used as the base class for all exceptions thrown by the 23 @ref basic_json class. This class can hence be used as "wildcard" to catch 24 exceptions. 25 26 Subclasses: 27 - @ref parse_error for exceptions indicating a parse error 28 - @ref invalid_iterator for exceptions indicating errors with iterators 29 - @ref type_error for exceptions indicating executing a member function with 30 a wrong type 31 - @ref out_of_range for exceptions indicating access out of the defined range 32 - @ref other_error for exceptions indicating other library errors 33 34 @internal 35 @note To have nothrow-copy-constructible exceptions, we internally use 36 `std::runtime_error` which can cope with arbitrary-length error messages. 37 Intermediate strings are built with static functions and then passed to 38 the actual constructor. 39 @endinternal 40 41 @liveexample{The following code shows how arbitrary library exceptions can be 42 caught.,exception} 43 44 @since version 3.0.0 45 */ 46 class exception : public std::exception 47 { 48 public: 49 /// returns the explanatory string 50 JSON_HEDLEY_RETURNS_NON_NULL what() const51 const char* what() const noexcept override 52 { 53 return m.what(); 54 } 55 56 /// the id of the exception 57 const int id; 58 59 protected: 60 JSON_HEDLEY_NON_NULL(3) exception(int id_,const char * what_arg)61 exception(int id_, const char* what_arg) : id(id_), m(what_arg) {} 62 name(const std::string & ename,int id_)63 static std::string name(const std::string& ename, int id_) 64 { 65 return "[json.exception." + ename + "." + std::to_string(id_) + "] "; 66 } 67 68 private: 69 /// an exception object as storage for error messages 70 std::runtime_error m; 71 }; 72 73 /*! 74 @brief exception indicating a parse error 75 76 This exception is thrown by the library when a parse error occurs. Parse errors 77 can occur during the deserialization of JSON text, CBOR, MessagePack, as well 78 as when using JSON Patch. 79 80 Member @a byte holds the byte index of the last read character in the input 81 file. 82 83 Exceptions have ids 1xx. 84 85 name / id | example message | description 86 ------------------------------ | --------------- | ------------------------- 87 json.exception.parse_error.101 | parse error at 2: unexpected end of input; expected string literal | This error indicates a syntax error while deserializing a JSON text. The error message describes that an unexpected token (character) was encountered, and the member @a byte indicates the error position. 88 json.exception.parse_error.102 | parse error at 14: missing or wrong low surrogate | JSON uses the `\uxxxx` format to describe Unicode characters. Code points above above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point. 89 json.exception.parse_error.103 | parse error: code points above 0x10FFFF are invalid | Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid. 90 json.exception.parse_error.104 | parse error: JSON patch must be an array of objects | [RFC 6902](https://tools.ietf.org/html/rfc6902) requires a JSON Patch document to be a JSON document that represents an array of objects. 91 json.exception.parse_error.105 | parse error: operation must have string member 'op' | An operation of a JSON Patch document must contain exactly one "op" member, whose value indicates the operation to perform. Its value must be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors. 92 json.exception.parse_error.106 | parse error: array index '01' must not begin with '0' | An array index in a JSON Pointer ([RFC 6901](https://tools.ietf.org/html/rfc6901)) may be `0` or any number without a leading `0`. 93 json.exception.parse_error.107 | parse error: JSON pointer must be empty or begin with '/' - was: 'foo' | A JSON Pointer must be a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a `/` character. 94 json.exception.parse_error.108 | parse error: escape character '~' must be followed with '0' or '1' | In a JSON Pointer, only `~0` and `~1` are valid escape sequences. 95 json.exception.parse_error.109 | parse error: array index 'one' is not a number | A JSON Pointer array index must be a number. 96 json.exception.parse_error.110 | parse error at 1: cannot read 2 bytes from vector | When parsing CBOR or MessagePack, the byte vector ends before the complete value has been read. 97 json.exception.parse_error.112 | parse error at 1: error reading CBOR; last byte: 0xF8 | Not all types of CBOR or MessagePack are supported. This exception occurs if an unsupported byte was read. 98 json.exception.parse_error.113 | parse error at 2: expected a CBOR string; last byte: 0x98 | While parsing a map key, a value that is not a string has been read. 99 json.exception.parse_error.114 | parse error: Unsupported BSON record type 0x0F | The parsing of the corresponding BSON record type is not implemented (yet). 100 json.exception.parse_error.115 | parse error at byte 5: syntax error while parsing UBJSON high-precision number: invalid number text: 1A | A UBJSON high-precision number could not be parsed. 101 102 @note For an input with n bytes, 1 is the index of the first character and n+1 103 is the index of the terminating null byte or the end of file. This also 104 holds true when reading a byte vector (CBOR or MessagePack). 105 106 @liveexample{The following code shows how a `parse_error` exception can be 107 caught.,parse_error} 108 109 @sa - @ref exception for the base class of the library exceptions 110 @sa - @ref invalid_iterator for exceptions indicating errors with iterators 111 @sa - @ref type_error for exceptions indicating executing a member function with 112 a wrong type 113 @sa - @ref out_of_range for exceptions indicating access out of the defined range 114 @sa - @ref other_error for exceptions indicating other library errors 115 116 @since version 3.0.0 117 */ 118 class parse_error : public exception 119 { 120 public: 121 /*! 122 @brief create a parse error exception 123 @param[in] id_ the id of the exception 124 @param[in] pos the position where the error occurred (or with 125 chars_read_total=0 if the position cannot be 126 determined) 127 @param[in] what_arg the explanatory string 128 @return parse_error object 129 */ create(int id_,const position_t & pos,const std::string & what_arg)130 static parse_error create(int id_, const position_t& pos, const std::string& what_arg) 131 { 132 std::string w = exception::name("parse_error", id_) + "parse error" + 133 position_string(pos) + ": " + what_arg; 134 return parse_error(id_, pos.chars_read_total, w.c_str()); 135 } 136 create(int id_,std::size_t byte_,const std::string & what_arg)137 static parse_error create(int id_, std::size_t byte_, const std::string& what_arg) 138 { 139 std::string w = exception::name("parse_error", id_) + "parse error" + 140 (byte_ != 0 ? (" at byte " + std::to_string(byte_)) : "") + 141 ": " + what_arg; 142 return parse_error(id_, byte_, w.c_str()); 143 } 144 145 /*! 146 @brief byte index of the parse error 147 148 The byte index of the last read character in the input file. 149 150 @note For an input with n bytes, 1 is the index of the first character and 151 n+1 is the index of the terminating null byte or the end of file. 152 This also holds true when reading a byte vector (CBOR or MessagePack). 153 */ 154 const std::size_t byte; 155 156 private: parse_error(int id_,std::size_t byte_,const char * what_arg)157 parse_error(int id_, std::size_t byte_, const char* what_arg) 158 : exception(id_, what_arg), byte(byte_) {} 159 position_string(const position_t & pos)160 static std::string position_string(const position_t& pos) 161 { 162 return " at line " + std::to_string(pos.lines_read + 1) + 163 ", column " + std::to_string(pos.chars_read_current_line); 164 } 165 }; 166 167 /*! 168 @brief exception indicating errors with iterators 169 170 This exception is thrown if iterators passed to a library function do not match 171 the expected semantics. 172 173 Exceptions have ids 2xx. 174 175 name / id | example message | description 176 ----------------------------------- | --------------- | ------------------------- 177 json.exception.invalid_iterator.201 | iterators are not compatible | The iterators passed to constructor @ref basic_json(InputIT first, InputIT last) are not compatible, meaning they do not belong to the same container. Therefore, the range (@a first, @a last) is invalid. 178 json.exception.invalid_iterator.202 | iterator does not fit current value | In an erase or insert function, the passed iterator @a pos does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion. 179 json.exception.invalid_iterator.203 | iterators do not fit current value | Either iterator passed to function @ref erase(IteratorType first, IteratorType last) does not belong to the JSON value from which values shall be erased. It hence does not define a valid range to delete values from. 180 json.exception.invalid_iterator.204 | iterators out of range | When an iterator range for a primitive type (number, boolean, or string) is passed to a constructor or an erase function, this range has to be exactly (@ref begin(), @ref end()), because this is the only way the single stored value is expressed. All other ranges are invalid. 181 json.exception.invalid_iterator.205 | iterator out of range | When an iterator for a primitive type (number, boolean, or string) is passed to an erase function, the iterator has to be the @ref begin() iterator, because it is the only way to address the stored value. All other iterators are invalid. 182 json.exception.invalid_iterator.206 | cannot construct with iterators from null | The iterators passed to constructor @ref basic_json(InputIT first, InputIT last) belong to a JSON null value and hence to not define a valid range. 183 json.exception.invalid_iterator.207 | cannot use key() for non-object iterators | The key() member function can only be used on iterators belonging to a JSON object, because other types do not have a concept of a key. 184 json.exception.invalid_iterator.208 | cannot use operator[] for object iterators | The operator[] to specify a concrete offset cannot be used on iterators belonging to a JSON object, because JSON objects are unordered. 185 json.exception.invalid_iterator.209 | cannot use offsets with object iterators | The offset operators (+, -, +=, -=) cannot be used on iterators belonging to a JSON object, because JSON objects are unordered. 186 json.exception.invalid_iterator.210 | iterators do not fit | The iterator range passed to the insert function are not compatible, meaning they do not belong to the same container. Therefore, the range (@a first, @a last) is invalid. 187 json.exception.invalid_iterator.211 | passed iterators may not belong to container | The iterator range passed to the insert function must not be a subrange of the container to insert to. 188 json.exception.invalid_iterator.212 | cannot compare iterators of different containers | When two iterators are compared, they must belong to the same container. 189 json.exception.invalid_iterator.213 | cannot compare order of object iterators | The order of object iterators cannot be compared, because JSON objects are unordered. 190 json.exception.invalid_iterator.214 | cannot get value | Cannot get value for iterator: Either the iterator belongs to a null value or it is an iterator to a primitive type (number, boolean, or string), but the iterator is different to @ref begin(). 191 192 @liveexample{The following code shows how an `invalid_iterator` exception can be 193 caught.,invalid_iterator} 194 195 @sa - @ref exception for the base class of the library exceptions 196 @sa - @ref parse_error for exceptions indicating a parse error 197 @sa - @ref type_error for exceptions indicating executing a member function with 198 a wrong type 199 @sa - @ref out_of_range for exceptions indicating access out of the defined range 200 @sa - @ref other_error for exceptions indicating other library errors 201 202 @since version 3.0.0 203 */ 204 class invalid_iterator : public exception 205 { 206 public: create(int id_,const std::string & what_arg)207 static invalid_iterator create(int id_, const std::string& what_arg) 208 { 209 std::string w = exception::name("invalid_iterator", id_) + what_arg; 210 return invalid_iterator(id_, w.c_str()); 211 } 212 213 private: 214 JSON_HEDLEY_NON_NULL(3) invalid_iterator(int id_,const char * what_arg)215 invalid_iterator(int id_, const char* what_arg) 216 : exception(id_, what_arg) {} 217 }; 218 219 /*! 220 @brief exception indicating executing a member function with a wrong type 221 222 This exception is thrown in case of a type error; that is, a library function is 223 executed on a JSON value whose type does not match the expected semantics. 224 225 Exceptions have ids 3xx. 226 227 name / id | example message | description 228 ----------------------------- | --------------- | ------------------------- 229 json.exception.type_error.301 | cannot create object from initializer list | To create an object from an initializer list, the initializer list must consist only of a list of pairs whose first element is a string. When this constraint is violated, an array is created instead. 230 json.exception.type_error.302 | type must be object, but is array | During implicit or explicit value conversion, the JSON type must be compatible to the target type. For instance, a JSON string can only be converted into string types, but not into numbers or boolean types. 231 json.exception.type_error.303 | incompatible ReferenceType for get_ref, actual type is object | To retrieve a reference to a value stored in a @ref basic_json object with @ref get_ref, the type of the reference must match the value type. For instance, for a JSON array, the @a ReferenceType must be @ref array_t &. 232 json.exception.type_error.304 | cannot use at() with string | The @ref at() member functions can only be executed for certain JSON types. 233 json.exception.type_error.305 | cannot use operator[] with string | The @ref operator[] member functions can only be executed for certain JSON types. 234 json.exception.type_error.306 | cannot use value() with string | The @ref value() member functions can only be executed for certain JSON types. 235 json.exception.type_error.307 | cannot use erase() with string | The @ref erase() member functions can only be executed for certain JSON types. 236 json.exception.type_error.308 | cannot use push_back() with string | The @ref push_back() and @ref operator+= member functions can only be executed for certain JSON types. 237 json.exception.type_error.309 | cannot use insert() with | The @ref insert() member functions can only be executed for certain JSON types. 238 json.exception.type_error.310 | cannot use swap() with number | The @ref swap() member functions can only be executed for certain JSON types. 239 json.exception.type_error.311 | cannot use emplace_back() with string | The @ref emplace_back() member function can only be executed for certain JSON types. 240 json.exception.type_error.312 | cannot use update() with string | The @ref update() member functions can only be executed for certain JSON types. 241 json.exception.type_error.313 | invalid value to unflatten | The @ref unflatten function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well defined. 242 json.exception.type_error.314 | only objects can be unflattened | The @ref unflatten function only works for an object whose keys are JSON Pointers. 243 json.exception.type_error.315 | values in object must be primitive | The @ref unflatten function only works for an object whose keys are JSON Pointers and whose values are primitive. 244 json.exception.type_error.316 | invalid UTF-8 byte at index 10: 0x7E | The @ref dump function only works with UTF-8 encoded strings; that is, if you assign a `std::string` to a JSON value, make sure it is UTF-8 encoded. | 245 json.exception.type_error.317 | JSON value cannot be serialized to requested format | The dynamic type of the object cannot be represented in the requested serialization format (e.g. a raw `true` or `null` JSON object cannot be serialized to BSON) | 246 247 @liveexample{The following code shows how a `type_error` exception can be 248 caught.,type_error} 249 250 @sa - @ref exception for the base class of the library exceptions 251 @sa - @ref parse_error for exceptions indicating a parse error 252 @sa - @ref invalid_iterator for exceptions indicating errors with iterators 253 @sa - @ref out_of_range for exceptions indicating access out of the defined range 254 @sa - @ref other_error for exceptions indicating other library errors 255 256 @since version 3.0.0 257 */ 258 class type_error : public exception 259 { 260 public: create(int id_,const std::string & what_arg)261 static type_error create(int id_, const std::string& what_arg) 262 { 263 std::string w = exception::name("type_error", id_) + what_arg; 264 return type_error(id_, w.c_str()); 265 } 266 267 private: 268 JSON_HEDLEY_NON_NULL(3) type_error(int id_,const char * what_arg)269 type_error(int id_, const char* what_arg) : exception(id_, what_arg) {} 270 }; 271 272 /*! 273 @brief exception indicating access out of the defined range 274 275 This exception is thrown in case a library function is called on an input 276 parameter that exceeds the expected range, for instance in case of array 277 indices or nonexisting object keys. 278 279 Exceptions have ids 4xx. 280 281 name / id | example message | description 282 ------------------------------- | --------------- | ------------------------- 283 json.exception.out_of_range.401 | array index 3 is out of range | The provided array index @a i is larger than @a size-1. 284 json.exception.out_of_range.402 | array index '-' (3) is out of range | The special array index `-` in a JSON Pointer never describes a valid element of the array, but the index past the end. That is, it can only be used to add elements at this position, but not to read it. 285 json.exception.out_of_range.403 | key 'foo' not found | The provided key was not found in the JSON object. 286 json.exception.out_of_range.404 | unresolved reference token 'foo' | A reference token in a JSON Pointer could not be resolved. 287 json.exception.out_of_range.405 | JSON pointer has no parent | The JSON Patch operations 'remove' and 'add' can not be applied to the root element of the JSON value. 288 json.exception.out_of_range.406 | number overflow parsing '10E1000' | A parsed number could not be stored as without changing it to NaN or INF. 289 json.exception.out_of_range.407 | number overflow serializing '9223372036854775808' | UBJSON and BSON only support integer numbers up to 9223372036854775807. (until version 3.8.0) | 290 json.exception.out_of_range.408 | excessive array size: 8658170730974374167 | The size (following `#`) of an UBJSON array or object exceeds the maximal capacity. | 291 json.exception.out_of_range.409 | BSON key cannot contain code point U+0000 (at byte 2) | Key identifiers to be serialized to BSON cannot contain code point U+0000, since the key is stored as zero-terminated c-string | 292 293 @liveexample{The following code shows how an `out_of_range` exception can be 294 caught.,out_of_range} 295 296 @sa - @ref exception for the base class of the library exceptions 297 @sa - @ref parse_error for exceptions indicating a parse error 298 @sa - @ref invalid_iterator for exceptions indicating errors with iterators 299 @sa - @ref type_error for exceptions indicating executing a member function with 300 a wrong type 301 @sa - @ref other_error for exceptions indicating other library errors 302 303 @since version 3.0.0 304 */ 305 class out_of_range : public exception 306 { 307 public: create(int id_,const std::string & what_arg)308 static out_of_range create(int id_, const std::string& what_arg) 309 { 310 std::string w = exception::name("out_of_range", id_) + what_arg; 311 return out_of_range(id_, w.c_str()); 312 } 313 314 private: 315 JSON_HEDLEY_NON_NULL(3) out_of_range(int id_,const char * what_arg)316 out_of_range(int id_, const char* what_arg) : exception(id_, what_arg) {} 317 }; 318 319 /*! 320 @brief exception indicating other library errors 321 322 This exception is thrown in case of errors that cannot be classified with the 323 other exception types. 324 325 Exceptions have ids 5xx. 326 327 name / id | example message | description 328 ------------------------------ | --------------- | ------------------------- 329 json.exception.other_error.501 | unsuccessful: {"op":"test","path":"/baz", "value":"bar"} | A JSON Patch operation 'test' failed. The unsuccessful operation is also printed. 330 331 @sa - @ref exception for the base class of the library exceptions 332 @sa - @ref parse_error for exceptions indicating a parse error 333 @sa - @ref invalid_iterator for exceptions indicating errors with iterators 334 @sa - @ref type_error for exceptions indicating executing a member function with 335 a wrong type 336 @sa - @ref out_of_range for exceptions indicating access out of the defined range 337 338 @liveexample{The following code shows how an `other_error` exception can be 339 caught.,other_error} 340 341 @since version 3.0.0 342 */ 343 class other_error : public exception 344 { 345 public: create(int id_,const std::string & what_arg)346 static other_error create(int id_, const std::string& what_arg) 347 { 348 std::string w = exception::name("other_error", id_) + what_arg; 349 return other_error(id_, w.c_str()); 350 } 351 352 private: 353 JSON_HEDLEY_NON_NULL(3) other_error(int id_,const char * what_arg)354 other_error(int id_, const char* what_arg) : exception(id_, what_arg) {} 355 }; 356 } // namespace detail 357 } // namespace nlohmann 358