字符串
头文件
mln_string.h
模块名
string
主要数据结构
typedef struct {
mln_u8ptr_t data; //数据存放的内存起始地址
mln_u64_t len; //数据字节长度
mln_uauto_t data_ref:1; //data是否是引用
mln_uauto_t pool:1; //本结构是否是由内存池分配
mln_uauto_t ref:30; //本结构所被引用的次数
} mln_string_t;
函数/宏列表
mln_string
mln_string(str)
描述：利用字符串常量str创建一个mln_string_t对象。用于定义mln_string_t变量的同时对其进行初始化。
返回值：mln_string_t类型结构体
举例：
void foo()
{
mln_string_t s = mln_string("Hello");
}
mln_string_set
mln_string_set(pstr, s)
描述：用于将s这个字符串赋值给pstr这个mln_string_t指针所指向的结构。此时，data_ref成员会被置1。
返回值：无
举例：
void foo()
{
char text[] = "hello";
mln_string_t s;
mln_string_set(&s, text);
}
mln_string_nset
mln_string_nset(pstr, s, n)
描述：与mln_string_set功能一样，只是pstr所指向的mln_string_t仅记录了s的前n个字节。
返回值：无
举例：
void foo()
{
char text[] = "hello world";
mln_string_t s;
mln_string_nset(&s, text, 5); //利用mln_log的%S进行输出时，仅会输出hello
}
mln_string_ref
mln_string_ref(pstr)
描述：将pstr所指向的mln_string_t结构的ref成员累加1，用于直接引用pstr这个内存结构。在释放内存时，引用计数大于1时是不会实际释放内存的。
返回值：mln_string_t类型指针
void foo(mln_string_t s)
{
mln_string_t *ref = mln_string_ref(s); //此时ref与s的内存地址完全相同
...
}
mln_string_free
mln_string_free(pstr)
描述：释放ptrs所指向的mln_string_t结构内存，若ref大于1则仅递减引用计数，若data_ref为1，则不释放data成员指向的内存，否则释放data成员内存，随后释放pstr内存。释放时，会根据pool成员判断是释放回内存池，还是返还malloc库。
返回值：无
mln_string_new
mln_string_t *mln_string_new(const char *s);
描述：根据字符串常量s创建字符串结构，此时新字符串结构及其数据部分内存均由malloc库进行分配，并将s的内容拷贝进data成员中。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_pool_new
mln_string_t *mln_string_pool_new(mln_alloc_t *pool, const char *s);
描述：与mln_string_new功能一致，仅内存是由pool所指向的内存池中分配而来。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_buf_new
mln_string_t *mln_string_buf_new(mln_u8ptr_t buf, mln_u64_t len);
描述：利用buf和len作为字符串内容，创建一个字符串结构。注意：buf应是通过malloc族函数进行分配而来的，且不可在外部进行释放。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_buf_pool_new
mln_string_t *mln_string_buf_pool_new(mln_alloc_t *pool, mln_u8ptr_t buf, mln_u64_t len);
描述：利用buf和len作为字符串内容，创建一个字符串结构。注意：buf应是从pool中分配而来的，且不可在外部进行释放。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_dup
mln_string_t *mln_string_dup(mln_string_t *str);
描述：完全复制一份str，其内存均由malloc进行分配。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_pool_dup
mln_string_t *mln_string_pool_dup(mln_alloc_t *pool, mln_string_t *str);
描述：与mln_string_dup功能一致，仅内存是从pool所指向的内存池中分配而来。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_alloc
mln_string_t *mln_string_alloc(mln_s32_t size);
描述：创建一个新字符串对象，并预分配size字节的缓冲区。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_pool_alloc
mln_string_t *mln_string_pool_alloc(mln_alloc_t *pool, mln_s32_t size);
描述：创建一个新字符串对象，并预分配size字节的缓冲区。与mln_string_alloc的差异在于所有内存均从内存池pool中分配。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_const_ndup
mln_string_t *mln_string_const_ndup(char *str, mln_s32_t size);
描述：创建一个新字符串对象，并仅复制str中前size个字节数据。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_ref_dup
mln_string_t *mln_string_ref_dup(mln_string_t *str);
描述：创建一个新的字符串结构，但结构中的data成员指向str中data成员所指向的地址，且新结构中data_ref会被置位。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_const_ref_dup
mln_string_t *mln_string_const_ref_dup(char *s);
描述：创建一个新的字符串结构，但结构中的data成员指向s，且新结构中data_ref会被置位。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_concat
mln_string_t *mln_string_concat(mln_string_t *s1, mln_string_t *s2, mln_string_t *sep);
描述：将字符串s1和s2拼接起来，并在中加增加sep作为分隔。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_pool_concat
mln_string_t *mln_string_pool_concat(mln_alloc_t *pool, mln_string_t *s1, mln_string_t *s2, mln_string_t *sep);
描述：将字符串s1和s2拼接起来，并在中加增加sep作为分隔。返回值指针及其数据所使用的内存均使用pool指定的内存池分配。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_strseqcmp
int mln_string_strseqcmp(mln_string_t *s1, mln_string_t *s2);
描述：比较s1与s2的数据，如果短的一方刚好与长的一方的前面完全匹配，则长的一方大于短的一方。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
举例：
int main(void)
{
mln_string_t s1 = mln_string("abcd");
mln_string_t s2 = mln_string("abcdefg");
printf("%d", mln_string_strseqcmp(&s1, &s2)); //-1
return 0;
}
mln_string_strcmp
int mln_string_strcmp(mln_string_t *s1, mln_string_t *s2);
描述：比较s1与s2中数据的大小。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_const_strcmp
int mln_string_const_strcmp(mln_string_t *s1, char *s2);
描述：比较s1所记录的数据与s2的大小。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_strncmp
int mln_string_strncmp(mln_string_t *s1, mln_string_t *s2, mln_u32_t n);
描述：比较s1与s2的前n个字节的大小。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_const_strncmp
int mln_string_const_strncmp(mln_string_t *s1, char *s2, mln_u32_t n);
描述：比较s1所记录的数据与s2的前n个字节的大小。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_strcasecmp
int mln_string_strcasecmp(mln_string_t *s1, mln_string_t *s2);
描述：比较s1与s2数据的大小，且忽略大小写。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_const_strcasecmp
int mln_string_const_strcasecmp(mln_string_t *s1, char *s2);
描述：比较s1所记录的数据与s2的大小，且忽略大小写。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_const_strncasecmp
int mln_string_const_strncasecmp(mln_string_t *s1, char *s2, mln_u32_t n);
描述：比较s1所记录的数据与s2的前n个字节的大小，且忽略大小写。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_strncasecmp
int mln_string_strncasecmp(mln_string_t *s1, mln_string_t *s2, mln_u32_t n);
描述：比较s1与s2所记录数据的前n个字节的大小，且忽略大小写。
返回值：
- -1 -
s1比s2小 - 1 -
s1比s2大 - 0 - 二者相同
mln_string_strstr
char *mln_string_strstr(mln_string_t *text, mln_string_t *pattern);
描述：匹配text所记录的数据中与pattern中数据一样的起始地址。
返回值：若匹配成功，则返回text的data成员所指向地址中的对应地址；否则返回NULL。
mln_string_const_strstr
char *mln_string_const_strstr(mln_string_t *text, char *pattern);
描述：匹配text所记录的数据中与pattern一样的起始地址。
返回值：若匹配成功，则返回text的data成员所指向地址中的对应地址；否则返回NULL。
mln_string_new_strstr
mln_string_t *mln_string_new_strstr(mln_string_t *text, mln_string_t *pattern);
描述：与mln_string_strstr功能一致，但返回的是由mln_string_t结构包装后的字符串。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_new_const_strstr
mln_string_t *mln_string_new_const_strstr(mln_string_t *text, char *pattern);
描述：与mln_string_const_strstr功能一致，但返回的是由mln_string_t结构包装后的字符串。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_kmp
char *mln_string_kmp(mln_string_t *text, mln_string_t *pattern);
描述：与mln_string_strstr功能一致，但是是由KMP算法实现的。KMP算法适用场景是，text中有较多与pattern前缀相同的字符串的情况。例如: text中包含aaaaaaaaaabc，pattern中包含ab，此时，KMP算法性能将高于朴素算法。
返回值：若匹配成功，则返回text的data成员所指向地址中的对应地址；否则返回NULL。
mln_string_const_kmp
char *mln_string_const_kmp(mln_string_t *text, char *pattern);
描述：与mln_string_kmp功能一致，但pattern为字符指针类型。
返回值：若匹配成功，则返回text的data成员所指向地址中的对应地址；否则返回NULL。
mln_string_new_kmp
mln_string_t *mln_string_new_kmp(mln_string_t *text, mln_string_t *pattern);
描述：与mln_string_kmp功能一致，但返回的是由mln_string_t结构包装后的数据。
返回值：成功则返回mln_string_t指针，失败则返回NULL。
mln_string_new_const_kmp
mln_string_t *mln_string_new_const_kmp(mln_string_t *text, char *pattern);
描述：与mln_string_const_kmp功能一致，但返回的是由mln_string_t结构包装后的数据。
返回值：成功则返回mln_string_t指针，失败则返回NULL。
mln_string_slice
mln_string_t *mln_string_slice(mln_string_t *s, const char *sep_array/*ended by \0*/);
描述：seq_array是一个字符数组且以0结尾，该数组的每一个字符都是一个分隔标志。函数会扫描s的数据部分，当数据中遇到seq_array中的任意一个字符时都会被进行分割，连续遇到多个时仅分割一次，且分割后，分隔符不会出现在被分割后的字符串中。
返回值：成功则返回mln_string_t数组，否则返回NULL。数组的最后一个元素的len为0。
举例：
int main(void)
{
mln_string_t s = mln_string("abc-def-=ghi");
mln_string_t *str, *arr = mln_string_slice(&s, "-=");
for (str = arr; str->len; ++str) {
mln_log(debug, "%S", str);
}
mln_string_slice_free(arr);
return 0;
}
mln_string_slice_free
void mln_string_slice_free(mln_string_t *array);
描述：释放由mln_string_slice函数创建的mln_string_t数组。
返回值：无
mln_string_strcat
mln_string_t *mln_string_strcat(mln_string_t *s1, mln_string_t *s2);
描述：创建一个新的mln_string_t结构，其数据为s1和s2依此顺序拼接后的结果。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_pool_strcat
mln_string_t *mln_string_pool_strcat(mln_alloc_t *pool, mln_string_t *s1, mln_string_t *s2);
描述：与mln_string_strcat功能一致，仅新的结构所使用内存由pool指向的内存池分配。
返回值：成功则返回mln_string_t指针，否则返回NULL。
mln_string_trim
mln_string_t *mln_string_trim(mln_string_t *s, mln_string_t *mask);
描述：去除字符串首尾处的由mask指定的空白字符（或者其他字符）。
返回值：由堆上分配的去除后的字符串mln_string_t指针。
mln_string_pool_trim
mln_string_t *mln_string_pool_trim(mln_alloc_t *pool, mln_string_t *s, mln_string_t *mask);
描述：与mln_string_trim功能相同。
返回值：由pool指定的内存池上分配的去除后的字符串mln_string_t指针。
mln_string_upper
void mln_string_upper(mln_string_t *s);
描述：将字符串s中的所有英文字母转换为大写。
返回值：无
mln_string_lower
void mln_string_lower(mln_string_t *s);
描述：将字符串s中的所有英文字母转换为小写。
返回值：无