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
10namespace nlohmann
11{
12namespace detail
13{
14////////////////
15// exceptions //
16////////////////
17
18/*!
19@brief general exception of the @ref basic_json class
20
21This class is an extension of `std::exception` objects with a member @a id for
22exception 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
24exceptions.
25
26Subclasses:
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
42caught.,exception}
43
44@since version 3.0.0
45*/
46class exception : public std::exception
47{
48 public:
49 /// returns the explanatory string
50 JSON_HEDLEY_RETURNS_NON_NULL
51 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)
61 exception(int id_, const char* what_arg) : id(id_), m(what_arg) {}
62
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
76This exception is thrown by the library when a parse error occurs. Parse errors
77can occur during the deserialization of JSON text, CBOR, MessagePack, as well
78as when using JSON Patch.
79
80Member @a byte holds the byte index of the last read character in the input
81file.
82
83Exceptions have ids 1xx.
84
85name / id | example message | description
86------------------------------ | --------------- | -------------------------
87json.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.
88json.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.
89json.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.
90json.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.
91json.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.
92json.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`.
93json.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.
94json.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.
95json.exception.parse_error.109 | parse error: array index 'one' is not a number | A JSON Pointer array index must be a number.
96json.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.
97json.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.
98json.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.
99json.exception.parse_error.114 | parse error: Unsupported BSON record type 0x0F | The parsing of the corresponding BSON record type is not implemented (yet).
100
101@note For an input with n bytes, 1 is the index of the first character and n+1
102 is the index of the terminating null byte or the end of file. This also
103 holds true when reading a byte vector (CBOR or MessagePack).
104
105@liveexample{The following code shows how a `parse_error` exception can be
106caught.,parse_error}
107
108@sa - @ref exception for the base class of the library exceptions
109@sa - @ref invalid_iterator for exceptions indicating errors with iterators
110@sa - @ref type_error for exceptions indicating executing a member function with
111 a wrong type
112@sa - @ref out_of_range for exceptions indicating access out of the defined range
113@sa - @ref other_error for exceptions indicating other library errors
114
115@since version 3.0.0
116*/
117class parse_error : public exception
118{
119 public:
120 /*!
121 @brief create a parse error exception
122 @param[in] id_ the id of the exception
123 @param[in] pos the position where the error occurred (or with
124 chars_read_total=0 if the position cannot be
125 determined)
126 @param[in] what_arg the explanatory string
127 @return parse_error object
128 */
129 static parse_error create(int id_, const position_t& pos, const std::string& what_arg)
130 {
131 std::string w = exception::name("parse_error", id_) + "parse error" +
132 position_string(pos) + ": " + what_arg;
133 return parse_error(id_, pos.chars_read_total, w.c_str());
134 }
135
136 static parse_error create(int id_, std::size_t byte_, const std::string& what_arg)
137 {
138 std::string w = exception::name("parse_error", id_) + "parse error" +
139 (byte_ != 0 ? (" at byte " + std::to_string(byte_)) : "") +
140 ": " + what_arg;
141 return parse_error(id_, byte_, w.c_str());
142 }
143
144 /*!
145 @brief byte index of the parse error
146
147 The byte index of the last read character in the input file.
148
149 @note For an input with n bytes, 1 is the index of the first character and
150 n+1 is the index of the terminating null byte or the end of file.
151 This also holds true when reading a byte vector (CBOR or MessagePack).
152 */
153 const std::size_t byte;
154
155 private:
156 parse_error(int id_, std::size_t byte_, const char* what_arg)
157 : exception(id_, what_arg), byte(byte_) {}
158
159 static std::string position_string(const position_t& pos)
160 {
161 return " at line " + std::to_string(pos.lines_read + 1) +
162 ", column " + std::to_string(pos.chars_read_current_line);
163 }
164};
165
166/*!
167@brief exception indicating errors with iterators
168
169This exception is thrown if iterators passed to a library function do not match
170the expected semantics.
171
172Exceptions have ids 2xx.
173
174name / id | example message | description
175----------------------------------- | --------------- | -------------------------
176json.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.
177json.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.
178json.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.
179json.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.
180json.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.
181json.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.
182json.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.
183json.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.
184json.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.
185json.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.
186json.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.
187json.exception.invalid_iterator.212 | cannot compare iterators of different containers | When two iterators are compared, they must belong to the same container.
188json.exception.invalid_iterator.213 | cannot compare order of object iterators | The order of object iterators cannot be compared, because JSON objects are unordered.
189json.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().
190
191@liveexample{The following code shows how an `invalid_iterator` exception can be
192caught.,invalid_iterator}
193
194@sa - @ref exception for the base class of the library exceptions
195@sa - @ref parse_error for exceptions indicating a parse error
196@sa - @ref type_error for exceptions indicating executing a member function with
197 a wrong type
198@sa - @ref out_of_range for exceptions indicating access out of the defined range
199@sa - @ref other_error for exceptions indicating other library errors
200
201@since version 3.0.0
202*/
203class invalid_iterator : public exception
204{
205 public:
206 static invalid_iterator create(int id_, const std::string& what_arg)
207 {
208 std::string w = exception::name("invalid_iterator", id_) + what_arg;
209 return invalid_iterator(id_, w.c_str());
210 }
211
212 private:
213 JSON_HEDLEY_NON_NULL(3)
214 invalid_iterator(int id_, const char* what_arg)
215 : exception(id_, what_arg) {}
216};
217
218/*!
219@brief exception indicating executing a member function with a wrong type
220
221This exception is thrown in case of a type error; that is, a library function is
222executed on a JSON value whose type does not match the expected semantics.
223
224Exceptions have ids 3xx.
225
226name / id | example message | description
227----------------------------- | --------------- | -------------------------
228json.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.
229json.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.
230json.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 &.
231json.exception.type_error.304 | cannot use at() with string | The @ref at() member functions can only be executed for certain JSON types.
232json.exception.type_error.305 | cannot use operator[] with string | The @ref operator[] member functions can only be executed for certain JSON types.
233json.exception.type_error.306 | cannot use value() with string | The @ref value() member functions can only be executed for certain JSON types.
234json.exception.type_error.307 | cannot use erase() with string | The @ref erase() member functions can only be executed for certain JSON types.
235json.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.
236json.exception.type_error.309 | cannot use insert() with | The @ref insert() member functions can only be executed for certain JSON types.
237json.exception.type_error.310 | cannot use swap() with number | The @ref swap() member functions can only be executed for certain JSON types.
238json.exception.type_error.311 | cannot use emplace_back() with string | The @ref emplace_back() member function can only be executed for certain JSON types.
239json.exception.type_error.312 | cannot use update() with string | The @ref update() member functions can only be executed for certain JSON types.
240json.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.
241json.exception.type_error.314 | only objects can be unflattened | The @ref unflatten function only works for an object whose keys are JSON Pointers.
242json.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.
243json.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. |
244json.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) |
245
246@liveexample{The following code shows how a `type_error` exception can be
247caught.,type_error}
248
249@sa - @ref exception for the base class of the library exceptions
250@sa - @ref parse_error for exceptions indicating a parse error
251@sa - @ref invalid_iterator for exceptions indicating errors with iterators
252@sa - @ref out_of_range for exceptions indicating access out of the defined range
253@sa - @ref other_error for exceptions indicating other library errors
254
255@since version 3.0.0
256*/
257class type_error : public exception
258{
259 public:
260 static type_error create(int id_, const std::string& what_arg)
261 {
262 std::string w = exception::name("type_error", id_) + what_arg;
263 return type_error(id_, w.c_str());
264 }
265
266 private:
267 JSON_HEDLEY_NON_NULL(3)
268 type_error(int id_, const char* what_arg) : exception(id_, what_arg) {}
269};
270
271/*!
272@brief exception indicating access out of the defined range
273
274This exception is thrown in case a library function is called on an input
275parameter that exceeds the expected range, for instance in case of array
276indices or nonexisting object keys.
277
278Exceptions have ids 4xx.
279
280name / id | example message | description
281------------------------------- | --------------- | -------------------------
282json.exception.out_of_range.401 | array index 3 is out of range | The provided array index @a i is larger than @a size-1.
283json.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.
284json.exception.out_of_range.403 | key 'foo' not found | The provided key was not found in the JSON object.
285json.exception.out_of_range.404 | unresolved reference token 'foo' | A reference token in a JSON Pointer could not be resolved.
286json.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.
287json.exception.out_of_range.406 | number overflow parsing '10E1000' | A parsed number could not be stored as without changing it to NaN or INF.
288json.exception.out_of_range.407 | number overflow serializing '9223372036854775808' | UBJSON and BSON only support integer numbers up to 9223372036854775807. |
289json.exception.out_of_range.408 | excessive array size: 8658170730974374167 | The size (following `#`) of an UBJSON array or object exceeds the maximal capacity. |
290json.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 |
291
292@liveexample{The following code shows how an `out_of_range` exception can be
293caught.,out_of_range}
294
295@sa - @ref exception for the base class of the library exceptions
296@sa - @ref parse_error for exceptions indicating a parse error
297@sa - @ref invalid_iterator for exceptions indicating errors with iterators
298@sa - @ref type_error for exceptions indicating executing a member function with
299 a wrong type
300@sa - @ref other_error for exceptions indicating other library errors
301
302@since version 3.0.0
303*/
304class out_of_range : public exception
305{
306 public:
307 static out_of_range create(int id_, const std::string& what_arg)
308 {
309 std::string w = exception::name("out_of_range", id_) + what_arg;
310 return out_of_range(id_, w.c_str());
311 }
312
313 private:
314 JSON_HEDLEY_NON_NULL(3)
315 out_of_range(int id_, const char* what_arg) : exception(id_, what_arg) {}
316};
317
318/*!
319@brief exception indicating other library errors
320
321This exception is thrown in case of errors that cannot be classified with the
322other exception types.
323
324Exceptions have ids 5xx.
325
326name / id | example message | description
327------------------------------ | --------------- | -------------------------
328json.exception.other_error.501 | unsuccessful: {"op":"test","path":"/baz", "value":"bar"} | A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.
329
330@sa - @ref exception for the base class of the library exceptions
331@sa - @ref parse_error for exceptions indicating a parse error
332@sa - @ref invalid_iterator for exceptions indicating errors with iterators
333@sa - @ref type_error for exceptions indicating executing a member function with
334 a wrong type
335@sa - @ref out_of_range for exceptions indicating access out of the defined range
336
337@liveexample{The following code shows how an `other_error` exception can be
338caught.,other_error}
339
340@since version 3.0.0
341*/
342class other_error : public exception
343{
344 public:
345 static other_error create(int id_, const std::string& what_arg)
346 {
347 std::string w = exception::name("other_error", id_) + what_arg;
348 return other_error(id_, w.c_str());
349 }
350
351 private:
352 JSON_HEDLEY_NON_NULL(3)
353 other_error(int id_, const char* what_arg) : exception(id_, what_arg) {}
354};
355} // namespace detail
356} // namespace nlohmann
357