Update folly/docs/Synchronized.md
[folly.git] / 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`.