folly/docs/FBString.md

   1 `folly/FBString.h`
   2 ------------------
   3
   4 `fbstring` is a drop-in replacement for `std::string`. The main
   5 benefit of `fbstring` is significantly increased performance on
   6 virtually all important primitives. This is achieved by using a
   7 three-tiered storage strategy and by cooperating with the memory
   8 allocator. In particular, `fbstring` is designed to detect use of
   9 jemalloc and cooperate with it to achieve significant improvements in
  10 speed and memory usage.
  11
  12 `fbstring` supports x32 and x64 architectures. Porting it to big endian
  13 architectures would require some changes.
  14
  15 ### Storage strategies
  16 ***
  17
  18 * Small strings (<= 23 chars) are stored in-situ without memory
  19   allocation.
  20
  21 * Medium strings (24 - 255 chars) are stored in malloc-allocated
  22   memory and copied eagerly.
  23
  24 * Large strings (> 255 chars) are stored in malloc-allocated memory and
  25   copied lazily.
  26
  27 ### Implementation highlights
  28 ***
  29
  30 * 100% compatible with `std::string`.
  31
  32 * Thread-safe reference counted copy-on-write for strings "large"
  33   strings (> 255 chars).
  34
  35 * Uses `malloc` instead of allocators.
  36
  37 * Jemalloc-friendly. `fbstring` automatically detects if application
  38   uses jemalloc and if so, significantly improves allocation
  39   strategy by using non-standard jemalloc extensions.
  40
  41 * `find()` is implemented using simplified Boyer-Moore
  42   algorithm. Casual tests indicate a 30x speed improvement over
  43   `string::find()` for successful searches and a 1.5x speed
  44   improvement for failed searches.
  45
  46 * Offers conversions to and from `std::string`.