• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# basic_json::parse
2
3```cpp
4// (1)
5template<typename InputType>
6static basic_json parse(InputType&& i,
7                        const parser_callback_t cb = nullptr,
8                        const bool allow_exceptions = true,
9                        const bool ignore_comments = false);
10
11// (2)
12template<typename IteratorType>
13static basic_json parse(IteratorType first, IteratorType last,
14                        const parser_callback_t cb = nullptr,
15                        const bool allow_exceptions = true,
16                        const bool ignore_comments = false);
17```
18
191. Deserialize from a compatible input.
202. Deserialize from a pair of character iterators
21
22    The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
23    respectively as UTF-8, UTF-16 and UTF-32.
24
25## Template parameters
26
27`InputType`
28:   A compatible input, for instance:
29
30    - an `std::istream` object
31    - a `FILE` pointer
32    - a C-style array of characters
33    - a pointer to a null-terminated string of single byte characters
34    - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
35
36`IteratorType`
37:   a compatible iterator type
38
39## Parameters
40
41`i` (in)
42:   Input to parse from.
43
44`cb` (in)
45:   a parser callback function of type [`parser_callback_t`](parser_callback_t.md) which is used to control the
46    deserialization by filtering unwanted values (optional)
47
48`allow_exceptions` (in)
49:    whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
50
51`ignore_comments` (in)
52:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
53    (`#!cpp false`); (optional, `#!cpp false` by default)
54
55`first` (in)
56:   iterator to start of character range
57
58`last` (in)
59:   iterator to end of character range
60
61## Return value
62
63Deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
64`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
65
66## Exception safety
67
68Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
69
70## Complexity
71
72Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the parser
73callback function `cb` or reading from (1) the input `i` or (2) the iterator range [`first`, `last`] has a
74super-linear complexity.
75
76## Notes
77
78(1) A UTF-8 byte order mark is silently ignored.
79
80## Examples
81
82??? example "Parsing from a character array"
83
84    The example below demonstrates the `parse()` function reading from an array.
85
86    ```cpp
87    --8<-- "examples/parse__array__parser_callback_t.cpp"
88    ```
89
90    Output:
91
92    ```json
93    --8<-- "examples/parse__array__parser_callback_t.output"
94    ```
95
96??? example "Parsing from a string"
97
98    The example below demonstrates the `parse()` function with and without callback function.
99
100    ```cpp
101    --8<-- "examples/parse__string__parser_callback_t.cpp"
102    ```
103
104    Output:
105
106    ```json
107    --8<-- "examples/parse__string__parser_callback_t.output"
108    ```
109
110??? example "Parsing from an input stream"
111
112    The example below demonstrates the `parse()` function with and without callback function.
113
114    ```cpp
115    --8<-- "examples/parse__istream__parser_callback_t.cpp"
116    ```
117
118    Output:
119
120    ```json
121    --8<-- "examples/parse__istream__parser_callback_t.output"
122    ```
123
124??? example "Parsing from a contiguous container"
125
126    The example below demonstrates the `parse()` function reading from a contiguous container.
127
128    ```cpp
129    --8<-- "examples/parse__contiguouscontainer__parser_callback_t.cpp"
130    ```
131
132    Output:
133
134    ```json
135    --8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
136    ```
137
138??? example "Effect of `allow_exceptions` parameter"
139
140    The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.
141
142    ```cpp
143    --8<-- "examples/parse__allow_exceptions.cpp"
144    ```
145
146    Output:
147
148    ```json
149    --8<-- "examples/parse__allow_exceptions.output"
150    ```
151
152## Version history
153
154- Added in version 1.0.0.
155- Overload for contiguous containers (1) added in version 2.0.3.
156- Ignoring comments via `ignore_comments` added in version 3.9.0.
157