weaselab/weaseljson
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More clarifications in README

Browse Source
This commit is contained in:
Andrew Noyes
2025-08-25 16:19:34 -04:00
parent 81814fa590
commit f2bb72b3dc
1 changed files with 6 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
README.md
View File

@@ -31,7 +31,7 @@ flowchart TD
D -->|No| E[SimdJSON DOM<br/>Easy to use<br/>Good performance] D -->|No| E[SimdJSON DOM<br/>Easy to use<br/>Good performance]
D -->|Yes| F[SimdJSON On-Demand<br/>Fastest option<br/>Forward-only traversal] D -->|Yes| F[SimdJSON On-Demand<br/>Very fast<br/>Forward-only traversal]
``` ```
## When to Use What ## When to Use What
@@ -40,19 +40,22 @@ flowchart TD
- You want to write `obj["key"]` and have it just work - You want to write `obj["key"]` and have it just work
- JSON files are reasonably sized (but you still want decent performance) - JSON files are reasonably sized (but you still want decent performance)
- You care about getting things done - You care about getting things done
- You need full document validation upfront
### Use **SimdJSON On-Demand** when: ### Use **SimdJSON On-Demand** when:
- Performance is critical and your data fits in memory - Performance is critical and your data fits in memory
- You can work with forward-only traversal (no random access or backtracking) - You can work with forward-only traversal (no random access or backtracking)
- You need maximum speed but still want a usable API - You need maximum speed but still want a usable API
- Your JSON structure is consistent and you control both generation and parsing - Your JSON structure is consistent and you control both generation and parsing
- You're okay with partial validation (only validates parts you actually access)
- Your JSON keys don't contain escape sequences (OnDemand matches raw keys without unescaping)
### Use **WeaselJSON** when: ### Use **WeaselJSON** when:
- You absolutely cannot load the whole JSON into memory - You absolutely cannot load the whole JSON into memory
- You're processing huge JSON files (multiple gigabytes) - You're processing huge JSON files (multiple gigabytes)
- You want to parse just part of a JSON file without reading the rest - You want to parse just part of a JSON file without reading the rest
- You need to convert JSON into some other format as you parse it - You need to convert JSON into some other format as you parse it
- You can't risk accidentally slow performance - You need predictable performance characteristics
- Writing stateful callbacks is your idea of fun - Writing stateful callbacks is your idea of fun
## The Reality ## The Reality
@@ -70,7 +73,7 @@ The parser represents excellent engineering work and occupies a useful niche. It
- No memory allocations during parsing - No memory allocations during parsing
- O(1) memory usage regardless of input size - O(1) memory usage regardless of input size
- Streaming API - no need to buffer the entire document in memory. Parsing is resumed when more data is available - Streaming API - no need to buffer the entire document in memory. Parsing is resumed when more data is available
- Strings are unescaped in place before they're presented. No unicode normalization is performed - Strings are unescaped in place before they're presented (modifies your input buffer unless WeaselJsonRaw flag is used). No unicode normalization is performed
- Robust to crashes with untrusted input - Robust to crashes with untrusted input
- SIMD optimizations for string scanning and validation - SIMD optimizations for string scanning and validation