1# subjson - quickly manipulate JSON subfields
3This is high performance string library which can manipulate JSON documents.
4It does so by performing simple string substitutions on _regions_ of the
7This library uses the fast [jsonsl](https://github.com/mnunberg/jsonsl) parser
8to obtain regions of the document which should be replaced, and outputs a small,
9fixed array of `iovec` like structures (buffer-length regions) which consist
10of the new document.
12## Performance Characteristics
14Because the library does not actually build a JSON tree, the memory usage and
15CPU consumption is constant, regardless of the size of the actual JSON object
16being operated upon, and thus the only variable performance factor is the
17amount of actual time the library can seek to the location in the document to
20On a single Xeon E5520 core, this library can process about 150MB/s-300MB/s
21of JSON. This processing includes the search logic as well as any replacement
24The above speed is rather misleading, as this is often quicker, since the
25document is only parsed until the relevant match sections have been found.
26This means that even for large inputs, only _n_ bytes of the data is actually
27parsed, where _n_ is the position in the file where the match itself ends.
29Performance may also depend on how deep and/or long the path is (since string
30comparison must be done occasionally on the relevant path components).
34 $ mkdir build
35 $ cd build
36 $ cmake .. -DCMAKE_BUILD_TYPE=RELEASE -DSUBJSON_GTEST=/path/to/gtest
37 $ make
38 $ make test
39 $ ./bin/bench --help
41Note that to run the tests you will need to have a copy of gtest. A minified
42version may be found [here](https://github.com/couchbasedeps/gtest).
44## Testing commands
46The build will produce a `bench` program in the `$build/bin` directory,
47where `$build` is the directory from which CMake was run.
49The basic syntax of `bench` is:
51 ./bin/bench -c <COMMAND> -f <JSON FILE> -p <PATH> [ -v <VALUE> ]
53You can use `./bin/bench -c help` to show a list of commands.
55For commands which perform mutations, the `-v` argument is required, and
56must contain a string which will evaluate as valid JSON within the context
57of the operation. In most cases this is just a simple JSON value; in the case
58of list operations this may also be a series of JSON values separated by
61Note that if inserting a string, the string must be specified with surrounding
62quotes. For example
65 ./bin/bench -f ../jsondata/brewery_5k.json -v '"CENSORED DUE TO PROHIBITION"' -p description -c replace