c_cpp/lib/cstring/README.md

   1 # cstring 库
   2
   3 C 语言没有原生的 string 类型，这使得 string 的管理非常麻烦。cstring 是一个简单的 string 库，它主要解决以下几个问题：
   4
   5 * 对于短字符串（小于 32 字节），进行 string interning 。这可以在文本处理时节约不少内存。短 string 相当于 symbol 类型，对它做比较操作的代价可以减少到 O(1) 。
   6 * 对于临时字符串，如果长度不大（小于 128 字节），尽可能的放在 stack 上，避免动态内存分配。
   7 * 支持常量字符串，对于常量短字符串只做一次 string interning 操作。
   8 * 使用引用计数管理相同的字符串，减少字符串的拷贝。
   9 * 短字符串，常量字符串，以及引用次数非常多（大于 64K 次）的字符串可以不动态释放，简化生命期管理。
  10 * 惰性计算，以及缓存字符串的 hash 值，以方便实现 hashmap 。
  11 * 这个库是线程安全的。
  12
  13 # cstring_buffer
  14
  15 不要直接定义 cstring_buffer 类型，而应该用 CSTRING_BUFFER(var) 声明，它相当于声明了一个名为 var 的 cstring_buffer 对象。
  16
  17 cstring_buffer 位于栈上，通常不需要回收。但是在函数结束时，应该使用 CSTRING_CLOSE(var) 关闭它。
  18
  19 新声明的 cstring_buffer 对象是一个空字符串，可以用下面两个 api 修改它。
  20
  21 ```C
  22 cstring cstring_cat(cstring_buffer sb, const char * str);
  23 cstring cstring_printf(cstring_buffer sb, const char * format, ...);
  24 ```
  25
  26 # cstring
  27
  28 如果需要把字符串做参数传递，就应该使用 cstring 类型，而不是 cstring_buffer 类型。CSTRING(var) 可以把 var 这个 cstring_buffer 对象，转换为 cstring 类型。
  29
  30 但是，在对 cstring_buffer 对象做新的操作后，这个 cstring 可能无效。所以每次传递 cstring_buffer 内的值，最好都重新用 CSTRING 宏取一次。
  31
  32 函数调用的参数以及返回值，都应该使用 cstring 类型。如果 cstring 是由外部传入的，无法确定它的数据在栈上还是堆上，所以不能长期持有。如果需要把 cstring 保存在数据结构中，可以使用这对 API :
  33 ```C
  34 cstring cstring_grab(cstring s);
  35 void cstring_release(cstring s);
  36 ```
  37
  38 把 cstring 转化为标准的 const char * ，只需要用 s->cstr 即可。
  39
  40 cstring 的比较操作以及 hash 操作都比 const char * 廉价，所以，请使用以下 API :
  41 ```C
  42 int cstring_equal(cstring a, cstring b);
  43 uint32_t cstring_hash(cstring s);
  44 ```
  45
  46 # literal
  47
  48 CSTRING_LITERAL(var, literal) 可以声明一个常量 cstring 。这里 literal 必须是一个 " 引起的字符串常量。
  49
  50