ceph/src/s3select/rapidjson/doc/features.md

   1 # Features
   2
   3 ## General
   4
   5 * Cross-platform
   6  * Compilers: Visual Studio, gcc, clang, etc.
   7  * Architectures: x86, x64, ARM, etc.
   8  * Operating systems: Windows, Mac OS X, Linux, iOS, Android, etc.
   9 * Easy installation
  10  * Header files only library. Just copy the headers to your project.
  11 * Self-contained, minimal dependences
  12  * No STL, BOOST, etc.
  13  * Only included `<cstdio>`, `<cstdlib>`, `<cstring>`, `<inttypes.h>`, `<new>`, `<stdint.h>`.
  14 * Without C++ exception, RTTI
  15 * High performance
  16  * Use template and inline functions to reduce function call overheads.
  17  * Internal optimized Grisu2 and floating point parsing implementations.
  18  * Optional SSE2/SSE4.2 support.
  19
  20 ## Standard compliance
  21
  22 * RapidJSON should be fully RFC4627/ECMA-404 compliance.
  23 * Support JSON Pointer (RFC6901).
  24 * Support JSON Schema Draft v4.
  25 * Support Unicode surrogate.
  26 * Support null character (`"\u0000"`)
  27  * For example, `["Hello\u0000World"]` can be parsed and handled gracefully. There is API for getting/setting lengths of string.
  28 * Support optional relaxed syntax.
  29  * Single line (`// ...`) and multiple line (`/* ... */`) comments (`kParseCommentsFlag`).
  30  * Trailing commas at the end of objects and arrays (`kParseTrailingCommasFlag`).
  31  * `NaN`, `Inf`, `Infinity`, `-Inf` and `-Infinity` as `double` values (`kParseNanAndInfFlag`)
  32 * [NPM compliant](http://github.com/Tencent/rapidjson/blob/master/doc/npm.md).
  33
  34 ## Unicode
  35
  36 * Support UTF-8, UTF-16, UTF-32 encodings, including little endian and big endian.
  37  * These encodings are used in input/output streams and in-memory representation.
  38 * Support automatic detection of encodings in input stream.
  39 * Support transcoding between encodings internally.
  40  * For example, you can read a UTF-8 file and let RapidJSON transcode the JSON strings into UTF-16 in the DOM.
  41 * Support encoding validation internally.
  42  * For example, you can read a UTF-8 file, and let RapidJSON check whether all JSON strings are valid UTF-8 byte sequence.
  43 * Support custom character types.
  44  * By default the character types are `char` for UTF8, `wchar_t` for UTF16, `uint32_t` for UTF32.
  45 * Support custom encodings.
  46
  47 ## API styles
  48
  49 * SAX (Simple API for XML) style API
  50  * Similar to [SAX](http://en.wikipedia.org/wiki/Simple_API_for_XML), RapidJSON provides a event sequential access parser API (`rapidjson::GenericReader`). It also provides a generator API (`rapidjson::Writer`) which consumes the same set of events.
  51 * DOM (Document Object Model) style API
  52  * Similar to [DOM](http://en.wikipedia.org/wiki/Document_Object_Model) for HTML/XML, RapidJSON can parse JSON into a DOM representation (`rapidjson::GenericDocument`), for easy manipulation, and finally stringify back to JSON if needed.
  53  * The DOM style API (`rapidjson::GenericDocument`) is actually implemented with SAX style API (`rapidjson::GenericReader`). SAX is faster but sometimes DOM is easier. Users can pick their choices according to scenarios.
  54
  55 ## Parsing
  56
  57 * Recursive (default) and iterative parser
  58  * Recursive parser is faster but prone to stack overflow in extreme cases.
  59  * Iterative parser use custom stack to keep parsing state.
  60 * Support *in situ* parsing.
  61  * Parse JSON string values in-place at the source JSON, and then the DOM points to addresses of those strings.
  62  * Faster than convention parsing: no allocation for strings, no copy (if string does not contain escapes), cache-friendly.
  63 * Support 32-bit/64-bit signed/unsigned integer and `double` for JSON number type.
  64 * Support parsing multiple JSONs in input stream (`kParseStopWhenDoneFlag`).
  65 * Error Handling
  66  * Support comprehensive error code if parsing failed.
  67  * Support error message localization.
  68
  69 ## DOM (Document)
  70
  71 * RapidJSON checks range of numerical values for conversions.
  72 * Optimization for string literal
  73  * Only store pointer instead of copying
  74 * Optimization for "short" strings
  75  * Store short string in `Value` internally without additional allocation.
  76  * For UTF-8 string: maximum 11 characters in 32-bit, 21 characters in 64-bit (13 characters in x86-64).
  77 * Optionally support `std::string` (define `RAPIDJSON_HAS_STDSTRING=1`)
  78
  79 ## Generation
  80
  81 * Support `rapidjson::PrettyWriter` for adding newlines and indentations.
  82
  83 ## Stream
  84
  85 * Support `rapidjson::GenericStringBuffer` for storing the output JSON as string.
  86 * Support `rapidjson::FileReadStream` and `rapidjson::FileWriteStream` for input/output `FILE` object.
  87 * Support custom streams.
  88
  89 ## Memory
  90
  91 * Minimize memory overheads for DOM.
  92  * Each JSON value occupies exactly 16/20 bytes for most 32/64-bit machines (excluding text string).
  93 * Support fast default allocator.
  94  * A stack-based allocator (allocate sequentially, prohibit to free individual allocations, suitable for parsing).
  95  * User can provide a pre-allocated buffer. (Possible to parse a number of JSONs without any CRT allocation)
  96 * Support standard CRT(C-runtime) allocator.
  97 * Support custom allocators.
  98
  99 ## Miscellaneous
 100
 101 * Some C++11 support (optional)
 102  * Rvalue reference
 103  * `noexcept` specifier
 104  * Range-based for loop