Skip to content

Commit 652a410

Browse files
jkeiserjkeiser
committed
Add API docs, ensure parser and field methods called with &
1 parent 45bccad commit 652a410

14 files changed

+560
-50
lines changed

‎include/simdjson/dom/array.h

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ class array {
3434
* Get the next value.
3535
*
3636
* Part of the std::iterator interface.
37-
*
3837
*/
3938
inline iterator& operator++() noexcept;
4039
/**

‎include/simdjson/dom/parser.h

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -24,28 +24,28 @@ class element;
2424
static constexpr size_t DEFAULT_BATCH_SIZE = 1000000;
2525

2626
/**
27-
* A persistent document parser.
28-
*
29-
* The parser is designed to be reused, holding the internal buffers necessary to do parsing,
30-
* as well as memory for a single document. The parsed document is overwritten on each parse.
31-
*
32-
* This class cannot be copied, only moved, to avoid unintended allocations.
33-
*
34-
* @note This is not thread safe: one parser cannot produce two documents at the same time!
35-
*/
27+
* A persistent document parser.
28+
*
29+
* The parser is designed to be reused, holding the internal buffers necessary to do parsing,
30+
* as well as memory for a single document. The parsed document is overwritten on each parse.
31+
*
32+
* This class cannot be copied, only moved, to avoid unintended allocations.
33+
*
34+
* @note This is not thread safe: one parser cannot produce two documents at the same time!
35+
*/
3636
class parser {
3737
public:
3838
/**
39-
* Create a JSON parser.
40-
*
41-
* The new parser will have zero capacity.
42-
*
43-
* @param max_capacity The maximum document length the parser can automatically handle. The parser
44-
* will allocate more capacity on an as needed basis (when it sees documents too big to handle)
45-
* up to this amount. The parser still starts with zero capacity no matter what this number is:
46-
* to allocate an initial capacity, call allocate() after constructing the parser.
47-
* Defaults to SIMDJSON_MAXSIZE_BYTES (the largest single document simdjson can process).
48-
*/
39+
* Create a JSON parser.
40+
*
41+
* The new parser will have zero capacity.
42+
*
43+
* @param max_capacity The maximum document length the parser can automatically handle. The parser
44+
* will allocate more capacity on an as needed basis (when it sees documents too big to handle)
45+
* up to this amount. The parser still starts with zero capacity no matter what this number is:
46+
* to allocate an initial capacity, call allocate() after constructing the parser.
47+
* Defaults to SIMDJSON_MAXSIZE_BYTES (the largest single document simdjson can process).
48+
*/
4949
simdjson_really_inline explicit parser(size_t max_capacity = SIMDJSON_MAXSIZE_BYTES) noexcept;
5050
/**
5151
* Take another parser's buffers and state.

‎include/simdjson/generic/ondemand/array.h

Lines changed: 31 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,45 +12,67 @@ class document;
1212
*/
1313
class array {
1414
public:
15+
/**
16+
* Create a new invalid array.
17+
*
18+
* Exists so you can declare a variable and later assign to it before use.
19+
*/
1520
simdjson_really_inline array() noexcept = default;
1621
simdjson_really_inline array(array &&other) noexcept = default;
1722
simdjson_really_inline array &operator=(array &&other) noexcept = default;
1823
array(const array &) = delete;
1924
array &operator=(const array &) = delete;
2025

26+
/**
27+
* Finishes iterating the array if it is not already fully iterated.
28+
*/
2129
simdjson_really_inline ~array() noexcept;
2230

31+
/**
32+
* Begin array iteration.
33+
*
34+
* Part of the std::iterable interface.
35+
*/
2336
simdjson_really_inline array_iterator begin() & noexcept;
37+
/**
38+
* Sentinel representing the end of the array.
39+
*
40+
* Part of the std::iterable interface.
41+
*/
2442
simdjson_really_inline array_iterator end() & noexcept;
2543

2644
protected:
2745
/**
2846
* Begin array iteration.
2947
*
30-
* @param doc The document containing the array.
48+
* @param iter The iterator. Must be where the initial [ is expected. Will be *moved* into the
49+
* resulting array.
3150
* @error INCORRECT_TYPE if the iterator is not at [.
3251
*/
3352
static simdjson_really_inline simdjson_result<array> start(json_iterator_ref &&iter) noexcept;
3453
/**
3554
* Begin array iteration.
55+
*
56+
* This version of the method should be called after the initial [ has been verified, and is
57+
* intended for use by switch statements that check the type of a value.
3658
*
37-
* @param doc The document containing the array. The iterator must be just after the opening `[`.
59+
* @param iter The iterator. Must be after the initial [. Will be *moved* into the resulting array.
3860
*/
3961
static simdjson_really_inline array started(json_iterator_ref &&iter) noexcept;
4062

4163
/**
42-
* Internal array creation. Call array::start() or array::started() instead of this.
64+
* Create an array at the given Internal array creation. Call array::start() or array::started() instead of this.
4365
*
44-
* @param doc The document containing the array. iter->depth must already be incremented to
45-
* reflect the array's depth. The iterator must be just after the opening `[`.
66+
* @param iter The iterator. Must either be at the start of the first element with iter.is_alive()
67+
* == true, or past the [] with is_alive() == false if the array is empty. Will be *moved*
68+
* into the resulting array.
4669
*/
4770
simdjson_really_inline array(json_iterator_ref &&iter) noexcept;
4871

4972
/**
50-
* Document containing this array.
51-
*
52-
* PERF NOTE: expected to be elided in favor of the parent document: this is set when the array
53-
* is first used, and never changes afterwards.
73+
* Iterator marking current position.
74+
*
75+
* iter.is_alive() == false indicates iteration is complete.
5476
*/
5577
json_iterator_ref iter{};
5678

‎include/simdjson/generic/ondemand/array_iterator.h

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,15 @@ class document;
1010

1111
/**
1212
* A forward-only JSON array.
13+
*
14+
* This is an input_iterator, meaning:
15+
* - It is forward-only
16+
* - * must be called exactly once per element.
17+
* - ++ must be called exactly once in between each * (*, ++, *, ++, * ...)
1318
*/
1419
class array_iterator {
1520
public:
21+
/** Create a new, invalid array iterator. */
1622
simdjson_really_inline array_iterator() noexcept = default;
1723
simdjson_really_inline array_iterator(const array_iterator &a) noexcept = default;
1824
simdjson_really_inline array_iterator &operator=(const array_iterator &a) noexcept = default;
@@ -21,14 +27,35 @@ class array_iterator {
2127
// Iterator interface
2228
//
2329

24-
// Reads key and value, yielding them to the user.
30+
/**
31+
* Get the current element.
32+
*
33+
* Part of the std::iterator interface.
34+
*/
2535
simdjson_really_inline simdjson_result<value> operator*() noexcept; // MUST ONLY BE CALLED ONCE PER ITERATION.
26-
// Assumes it's being compared with the end. true if depth < iter->depth.
36+
/**
37+
* Check if we are at the end of the JSON.
38+
*
39+
* Part of the std::iterator interface.
40+
*
41+
* @return true if there are no more elements in the JSON array.
42+
*/
2743
simdjson_really_inline bool operator==(const array_iterator &) noexcept;
28-
// Assumes it's being compared with the end. true if depth >= iter->depth.
44+
/**
45+
* Check if there are more elements in the JSON array.
46+
*
47+
* Part of the std::iterator interface.
48+
*
49+
* @return true if there are more elements in the JSON array.
50+
*/
2951
simdjson_really_inline bool operator!=(const array_iterator &) noexcept;
30-
// Checks for ']' and ','
52+
/**
53+
* Move to the next element.
54+
*
55+
* Part of the std::iterator interface.
56+
*/
3157
simdjson_really_inline array_iterator &operator++() noexcept;
58+
3259
private:
3360
json_iterator_ref *iter{};
3461
/**
@@ -68,13 +95,9 @@ struct simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::array_iterator> : publ
6895
// Iterator interface
6996
//
7097

71-
// Reads key and value, yielding them to the user.
7298
simdjson_really_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::value> operator*() noexcept; // MUST ONLY BE CALLED ONCE PER ITERATION.
73-
// Assumes it's being compared with the end. true if depth < iter->depth.
7499
simdjson_really_inline bool operator==(const simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::array_iterator> &) noexcept;
75-
// Assumes it's being compared with the end. true if depth >= iter->depth.
76100
simdjson_really_inline bool operator!=(const simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::array_iterator> &) noexcept;
77-
// Checks for ']' and ','
78101
simdjson_really_inline simdjson_result<SIMDJSON_IMPLEMENTATION::ondemand::array_iterator> &operator++() noexcept;
79102
};
80103

‎include/simdjson/generic/ondemand/document.h

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,36 +22,177 @@ class document {
2222
simdjson_really_inline document(document &&other) noexcept = default;
2323
simdjson_really_inline document &operator=(document &&other) noexcept = default;
2424

25+
/**
26+
* Create a new invalid document.
27+
*
28+
* Exists so you can declare a variable and later assign to it before use.
29+
*/
2530
simdjson_really_inline document() noexcept = default;
2631
simdjson_really_inline document(const document &other) = delete;
2732
simdjson_really_inline document &operator=(const document &other) = delete;
33+
/**
34+
* Finishes logging (if logging is enabled).
35+
*/
2836
simdjson_really_inline ~document() noexcept;
2937

38+
/**
39+
* Cast this JSON value to an array.
40+
*
41+
* @returns An object that can be used to iterate the array.
42+
* @returns INCORRECT_TYPE If the JSON value is not an array.
43+
*/
3044
simdjson_really_inline simdjson_result<array> get_array() & noexcept;
45+
/**
46+
* Cast this JSON value to an object.
47+
*
48+
* @returns An object that can be used to look up or iterate fields.
49+
* @returns INCORRECT_TYPE If the JSON value is not an object.
50+
*/
3151
simdjson_really_inline simdjson_result<object> get_object() & noexcept;
52+
/**
53+
* Cast this JSON value to an unsigned integer.
54+
*
55+
* @returns A signed 64-bit integer.
56+
* @returns INCORRECT_TYPE If the JSON value is not a 64-bit unsigned integer.
57+
*/
3258
simdjson_really_inline simdjson_result<uint64_t> get_uint64() noexcept;
59+
/**
60+
* Cast this JSON value to a signed integer.
61+
*
62+
* @returns A signed 64-bit integer.
63+
* @returns INCORRECT_TYPE If the JSON value is not a 64-bit integer.
64+
*/
3365
simdjson_really_inline simdjson_result<int64_t> get_int64() noexcept;
66+
/**
67+
* Cast this JSON value to a double.
68+
*
69+
* @returns A double.
70+
* @returns INCORRECT_TYPE If the JSON value is not a valid floating-point number.
71+
*/
3472
simdjson_really_inline simdjson_result<double> get_double() noexcept;
73+
/**
74+
* Cast this JSON value to a string.
75+
*
76+
* The string is guaranteed to be valid UTF-8.
77+
*
78+
* Equivalent to get<std::string_view>().
79+
*
80+
* @returns An UTF-8 string. The string is stored in the parser and will be invalidated the next
81+
* time it parses a document or when it is destroyed.
82+
* @returns INCORRECT_TYPE if the JSON value is not a string.
83+
*/
3584
simdjson_really_inline simdjson_result<std::string_view> get_string() & noexcept;
85+
/**
86+
* Cast this JSON value to a raw_json_string.
87+
*
88+
* The string is guaranteed to be valid UTF-8, and may have escapes in it (e.g. \\ or \n).
89+
*
90+
* @returns A pointer to the raw JSON for the given string.
91+
* @returns INCORRECT_TYPE if the JSON value is not a string.
92+
*/
3693
simdjson_really_inline simdjson_result<raw_json_string> get_raw_json_string() & noexcept;
94+
/**
95+
* Cast this JSON value to a bool.
96+
*
97+
* @returns A bool value.
98+
* @returns INCORRECT_TYPE if the JSON value is not true or false.
99+
*/
37100
simdjson_really_inline simdjson_result<bool> get_bool() noexcept;
101+
/**
102+
* Checks if this JSON value is null.
103+
*
104+
* @returns Whether the value is null.
105+
*/
38106
simdjson_really_inline bool is_null() noexcept;
39107

40108
#if SIMDJSON_EXCEPTIONS
109+
/**
110+
* Cast this JSON value to an array.
111+
*
112+
* @returns An object that can be used to iterate the array.
113+
* @exception simdjson_error(INCORRECT_TYPE) If the JSON value is not an array.
114+
*/
41115
simdjson_really_inline operator array() & noexcept(false);
116+
/**
117+
* Cast this JSON value to an object.
118+
*
119+
* @returns An object that can be used to look up or iterate fields.
120+
* @exception simdjson_error(INCORRECT_TYPE) If the JSON value is not an object.
121+
*/
42122
simdjson_really_inline operator object() & noexcept(false);
123+
/**
124+
* Cast this JSON value to an unsigned integer.
125+
*
126+
* @returns A signed 64-bit integer.
127+
* @exception simdjson_error(INCORRECT_TYPE) If the JSON value is not a 64-bit unsigned integer.
128+
*/
43129
simdjson_really_inline operator uint64_t() noexcept(false);
130+
/**
131+
* Cast this JSON value to a signed integer.
132+
*
133+
* @returns A signed 64-bit integer.
134+
* @exception simdjson_error(INCORRECT_TYPE) If the JSON value is not a 64-bit integer.
135+
*/
44136
simdjson_really_inline operator int64_t() noexcept(false);
137+
/**
138+
* Cast this JSON value to a double.
139+
*
140+
* @returns A double.
141+
* @exception simdjson_error(INCORRECT_TYPE) If the JSON value is not a valid floating-point number.
142+
*/
45143
simdjson_really_inline operator double() noexcept(false);
144+
/**
145+
* Cast this JSON value to a string.
146+
*
147+
* The string is guaranteed to be valid UTF-8.
148+
*
149+
* Equivalent to get<std::string_view>().
150+
*
151+
* @returns An UTF-8 string. The string is stored in the parser and will be invalidated the next
152+
* time it parses a document or when it is destroyed.
153+
* @exception simdjson_error(INCORRECT_TYPE) if the JSON value is not a string.
154+
*/
46155
simdjson_really_inline operator std::string_view() & noexcept(false);
156+
/**
157+
* Cast this JSON value to a raw_json_string.
158+
*
159+
* The string is guaranteed to be valid UTF-8, and may have escapes in it (e.g. \\ or \n).
160+
*
161+
* @returns A pointer to the raw JSON for the given string.
162+
* @exception simdjson_error(INCORRECT_TYPE) if the JSON value is not a string.
163+
*/
47164
simdjson_really_inline operator raw_json_string() & noexcept(false);
165+
/**
166+
* Cast this JSON value to a bool.
167+
*
168+
* @returns A bool value.
169+
* @exception simdjson_error(INCORRECT_TYPE) if the JSON value is not true or false.
170+
*/
48171
simdjson_really_inline operator bool() noexcept(false);
49172
#endif
50173

51174
// We don't have an array_iterator that can point at an owned json_iterator
52175
// simdjson_really_inline simdjson_result<array::iterator> begin() & noexcept;
53176
// simdjson_really_inline simdjson_result<array::iterator> end() & noexcept;
177+
/**
178+
* Look up a field by name on an object.
179+
*
180+
* This method may only be called once on a given value. If you want to look up multiple fields,
181+
* you must first get the object using value.get_object() or object(value).
182+
*
183+
* @param key The key to look up.
184+
* @returns INCORRECT_TYPE If the JSON value is not an array.
185+
*/
54186
simdjson_really_inline simdjson_result<value> operator[](std::string_view key) & noexcept;
187+
/**
188+
* Look up a field by name on an object.
189+
*
190+
* This method may only be called once on a given value. If you want to look up multiple fields,
191+
* you must first get the object using value.get_object() or object(value).
192+
*
193+
* @param key The key to look up.
194+
* @returns INCORRECT_TYPE If the JSON value is not an array.
195+
*/
55196
simdjson_really_inline simdjson_result<value> operator[](const char *key) & noexcept;
56197

57198
protected:

‎include/simdjson/generic/ondemand/field-inl.h

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,14 @@ simdjson_really_inline raw_json_string field::key() const noexcept {
2525
return first;
2626
}
2727

28-
simdjson_really_inline value &field::value() noexcept {
28+
simdjson_really_inline value &field::value() & noexcept {
2929
return second;
3030
}
3131

32+
simdjson_really_inline value field::value() && noexcept {
33+
return std::forward<field>(*this).second;
34+
}
35+
3236
} // namespace ondemand
3337
} // namespace SIMDJSON_IMPLEMENTATION
3438
} // namespace simdjson

0 commit comments

Comments
 (0)