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