Skip to content

Commit 7c560fa

Browse files
committed
Cleaning documentation.
1 parent 178a084 commit 7c560fa

File tree

2 files changed

+58
-9
lines changed

2 files changed

+58
-9
lines changed

README.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -401,6 +401,55 @@ In C++, given a `ParsedJson`, we can move to a node with the `move_to` method, p
401401

402402
## Navigating the parsed document
403403

404+
405+
406+
From a `simdjson::ParsedJson` instance, you can create an iterator (of type `simdjson::ParsedJson::Iterator` which is in fact `simdjson::ParsedJson::BasicIterator<DEFAULT_MAX_DEPTH>` ) via a constructor:
407+
408+
```
409+
ParsedJson::Iterator pjh(pj); // pj is a ParsedJSON
410+
```
411+
412+
You then have access to the following methods on the resulting `simdjson::ParsedJson::Iterator` instance:
413+
414+
* `bool is_ok() const`: whether you have a valid iterator, will be false if your parent parsed ParsedJson is not a valid JSON.
415+
* `size_t get_depth() const`: returns the current depth (start at 1 with 0 reserved for the fictitious root node)
416+
* `int8_t get_scope_type() const`: a scope is a series of nodes at the same depth, typically it is either an object (`{`) or an array (`[`). The root node has type 'r'.
417+
* `bool move_forward()`: move forward in document order
418+
* `uint8_t get_type() const`: retrieve the character code of what we're looking at: `[{"slutfn` are the possibilities
419+
* `int64_t get_integer() const`: get the int64_t value at this node; valid only if get_type() is "l"
420+
* `uint64_t get_unsigned_integer() const`: get the value as uint64; valid only if get_type() is "u"
421+
* `const char *get_string() const`: get the string value at this node (NULL ended); valid only if get_type() is ", note that tabs, and line endings are escaped in the returned value, return value is valid UTF-8, it may contain NULL chars, get_string_length() determines the true string length.
422+
* `uint32_t get_string_length() const`: return the length of the string in bytes
423+
* `double get_double() const`: get the double value at this node; valid only if gettype() is "d"
424+
* `bool is_object_or_array() const`: self-explanatory
425+
* `bool is_object() const`: self-explanatory
426+
* `bool is_array() const`: self-explanatory
427+
* `bool is_string() const`: self-explanatory
428+
* `bool is_integer() const`: self-explanatory
429+
* `bool is_unsigned_integer() const`: Returns true if the current type of node is an unsigned integer. You can get its value with `get_unsigned_integer()`. Only a large value, which is out of range of a 64-bit signed integer, is represented internally as an unsigned node. On the other hand, a typical positive integer, such as 1, 42, or 1000000, is as a signed node. Be aware this function returns false for a signed node.
430+
* `bool is_double() const`: self-explanatory
431+
* `bool is_number() const`: self-explanatory
432+
* `bool is_true() const`: self-explanatory
433+
* `bool is_false() const`: self-explanatory
434+
* `bool is_null() const`: self-explanatory
435+
* `bool is_number() const`: self-explanatory
436+
* `bool move_to_key(const char *key)`: when at {, go one level deep, looking for a given key, if successful, we are left pointing at the value, if not, we are still pointing at the object ({) (in case of repeated keys, this only finds the first one). We seek the key using C's strcmp so if your JSON strings contain NULL chars, this would trigger a false positive: if you expect that to be the case, take extra precautions. Furthermore, we do the comparison character-by-character without taking into account Unicode equivalence.
437+
* `bool move_to_key_insensitive(const char *key)`: as above, but case insensitive lookup
438+
* `bool move_to_key(const char *key, uint32_t length)`: as above except that the target can contain NULL characters
439+
* `void move_to_value()`: when at a key location within an object, this moves to the accompanying, value (located next to it). This is equivalent but much faster than calling `next()`.
440+
* `bool move_to_index(uint32_t index)`: when at `[`, go one level deep, and advance to the given index, if successful, we are left pointing at the value,i f not, we are still pointing at the array
441+
* `bool move_to(const char *pointer, uint32_t length)`: Moves the iterator to the value correspoding to the json pointer. Always search from the root of the document. If successful, we are left pointing at the value, if not, we are still pointing the same value we were pointing before the call. The json pointer follows the rfc6901 standard's syntax: https://tools.ietf.org/html/rfc6901
442+
* `bool move_to(const std::string &pointer) `: same as above but with a std::string parameter
443+
* `bool next()`: Withing a given scope (series of nodes at the same depth within either an array or an object), we move forward. Thus, given [true, null, {"a":1}, [1,2]], we would visit true, null, { and [. At the object ({) or at the array ([), you can issue a "down" to visit their content. valid if we're not at the end of a scope (returns true).
444+
* `bool prev()`: Within a given scope (series of nodes at the same depth within either an
445+
array or an object), we move backward.
446+
* `bool up()`: moves back to either the containing array or object (type { or [) from within a contained scope.
447+
* `bool down()`: moves us to start of that deeper scope if it not empty. Thus, given [true, null, {"a":1}, [1,2]], if we are at the { node, we would move to the "a" node.
448+
* `void to_start_scope()`: move us to the start of our current scope, a scope is a series of nodes at the same level
449+
* `void rewind()`: repeatedly calls up until we are at the root of the document
450+
* `bool print(std::ostream &os, bool escape_strings = true) const`: print the node we are currently pointing at
451+
452+
404453
Here is a code sample to dump back the parsed JSON to a string:
405454

406455
```c

include/simdjson/parsedjsoniterator.h

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,30 +37,30 @@ template <size_t max_depth> class ParsedJson::BasicIterator {
3737
inline bool move_forward();
3838

3939
// retrieve the character code of what we're looking at:
40-
// [{"sltfn are the possibilities
40+
// [{"slutfn are the possibilities
4141
inline uint8_t get_type() const {
4242
return current_type; // short functions should be inlined!
4343
}
4444

45-
// get the int64_t value at this node; valid only if we're at "l"
45+
// get the int64_t value at this node; valid only if get_type is "l"
4646
inline int64_t get_integer() const {
4747
if (location + 1 >= tape_length) {
4848
return 0; // default value in case of error
4949
}
5050
return static_cast<int64_t>(pj->tape[location + 1]);
5151
}
5252

53-
// get the value as uint64
53+
// get the value as uint64; valid only if if get_type is "u"
5454
inline uint64_t get_unsigned_integer() const {
5555
if (location + 1 >= tape_length) {
5656
return 0; // default value in case of error
5757
}
5858
return pj->tape[location + 1];
5959
}
6060

61-
// get the string value at this node (NULL ended); valid only if we're at "
61+
// get the string value at this node (NULL ended); valid only if get_type is "
6262
// note that tabs, and line endings are escaped in the returned value (see
63-
// print_with_escapes) return value is valid UTF-8 It may contain NULL chars
63+
// print_with_escapes) return value is valid UTF-8, it may contain NULL chars
6464
// within the string: get_string_length determines the true string length.
6565
inline const char *get_string() const {
6666
return reinterpret_cast<const char *>(
@@ -78,7 +78,7 @@ template <size_t max_depth> class ParsedJson::BasicIterator {
7878
}
7979

8080
// get the double value at this node; valid only if
81-
// we're at "d"
81+
// get_type() is "d"
8282
inline double get_double() const {
8383
if (location + 1 >= tape_length) {
8484
return std::numeric_limits<double>::quiet_NaN(); // default value in
@@ -151,7 +151,7 @@ template <size_t max_depth> class ParsedJson::BasicIterator {
151151
inline bool move_to_key(const char *key, uint32_t length);
152152

153153
// when at a key location within an object, this moves to the accompanying
154-
// value (located next to it). this is equivalent but much faster than
154+
// value (located next to it). This is equivalent but much faster than
155155
// calling "next()".
156156
inline void move_to_value();
157157

@@ -207,7 +207,7 @@ template <size_t max_depth> class ParsedJson::BasicIterator {
207207
// true).
208208
inline bool next();
209209

210-
// Withing a given scope (series of nodes at the same depth within either an
210+
// Within a given scope (series of nodes at the same depth within either an
211211
// array or an object), we move backward.
212212
// Thus, given [true, null, {"a":1}, [1,2]], we would visit ], }, null, true
213213
// when starting at the end of the scope. At the object ({) or at the array
@@ -239,7 +239,7 @@ template <size_t max_depth> class ParsedJson::BasicIterator {
239239
// void to_end_scope(); // move us to
240240
// the start of our current scope; always succeeds
241241

242-
// print the thing we're currently pointing at
242+
// print the node we are currently pointing at
243243
bool print(std::ostream &os, bool escape_strings = true) const;
244244
typedef struct {
245245
size_t start_of_scope;

0 commit comments

Comments
 (0)