Redis源码笔记_sds.h

  1 /* SDSLib, A C dynamic strings library
  2  *
  3  * Copyright (c) 2006-2010, Salvatore Sanfilippo <antirez at gmail dot com>
  4  * All rights reserved.
  5  *
  6  * Redistribution and use in source and binary forms, with or without
  7  * modification, are permitted provided that the following conditions are met:
  8  *
  9  *   * Redistributions of source code must retain the above copyright notice,
 10  *     this list of conditions and the following disclaimer.
 11  *   * Redistributions in binary form must reproduce the above copyright
 12  *     notice, this list of conditions and the following disclaimer in the
 13  *     documentation and/or other materials provided with the distribution.
 14  *   * Neither the name of Redis nor the names of its contributors may be used
 15  *     to endorse or promote products derived from this software without
 16  *     specific prior written permission.
 17  *
 18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 28  * POSSIBILITY OF SUCH DAMAGE.
 29  */
 30 
 31 #ifndef __SDS_H
 32 #define __SDS_H
 33 
 34 #define SDS_MAX_PREALLOC (1024*1024)    /* 1M空间 */
 35 
 36 #include <sys/types.h>
 37 #include <stdarg.h>
 38 
 39 /* sds抽象数据类型,底层实现由char*实现 */
 40 typedef char *sds;
 41 
 42 struct sdshdr {
 43     int len;    /* buf已占用长度 */
 44     int free;    /* buf剩余可用长度 */
 45     char buf[];    /* 实际保存字符串数据的地方 */
 46 };
 47 
 48 static inline size_t sdslen(const sds s) {
 49     /* s - (sizeof(struct sdshdr)) 表示将指针向前移动到struct sdshdr的起点，从而得出一个指向sdshdr结构的指针 */
 50     struct sdshdr *sh = (void*)(s-(sizeof(struct sdshdr)));
 51     
 52     /* 返回sds buf的已占用长度 */
 53     return sh->len;
 54 }
 55 
 56 static inline size_t sdsavail(const sds s) {
 57     struct sdshdr *sh = (void*)(s-(sizeof(struct sdshdr)));
 58  
 59      /* 返回sds buf的剩余可用长度 */
 60      return sh->free;
 61 }
 62 
 63 /* 创建一个指定长度的sds,接受一个C字符串作为初始值 */
 64 sds sdsnewlen(const void *init, size_t initlen);
 65 
 66 /* 根据给定C字符串,创建一个相应的sds */
 67 sds sdsnew(const char *init);
 68 
 69 /* 创建一个只包含空白字符串""的sds */
 70 sds sdsempty();
 71 
 72 /*  */
 73 size_t sdslen(const sds s);
 74 
 75 /* 复制给定sds */
 76 sds sdsdup(const sds s);
 77 
 78 /* 释放给定sds */
 79 void sdsfree(sds s);
 80 
 81 /*  */
 82 size_t sdsavail(const sds s);
 83 
 84 /* 将给定sds的buf扩展至指定长度,无内容的部分用\0填充 */
 85 sds sdsgrowzero(sds s, size_t len);
 86 
 87 /* 按给定长度对sds进行扩展,并将一个C字符串追加到sds的末尾 */
 88 sds sdscatlen(sds s, const void *t, size_t len);
 89 
 90 /* 将一个C字符串追加到sds的末尾 */
 91 sds sdscat(sds s, const char *t);
 92 
 93 /* 将一个sds追加到另一个sds的末尾 */
 94 sds sdscatsds(sds s, const sds t);
 95 
 96 /* 将一个C字符串的部分内容复制到另一个sds中,需要时对sds进行扩展 */
 97 sds sdscpylen(sds s, const char *t, size_t len);
 98 
 99 /* 将一个C字符串复制到sds */
100 sds sdscpy(sds s, const char *t);
101 
102 /*  */
103 sds sdscatvprintf(sds s, const char *fmt, va_list ap);
104 
105 #ifdef __GNUC__
106 sds sdscatprintf(sds s, const char *fmt, ...)
107     __attribute__((format(printf, 2, 3)));
108 #else
109 sds sdscatprintf(sds s, const char *fmt, ...);
110 #endif
111 
112 sds sdstrim(sds s, const char *cset);
113 sds sdsrange(sds s, int start, int end);
114 
115 /* 更新给定sds所对应sdshdr结构的free和len */
116 void sdsupdatelen(sds s);
117 
118 /* 清除给定sds的内容,将它初始化为"" */
119 void sdsclear(sds s);
120 
121 /* 比较s1和s2字符,如果s1>s2,则返回>0;如果s1=s2,则返回0;如果s1<s2,则返回<0 */
122 int sdscmp(const sds s1, const sds s2);
123 
124 sds *sdssplitlen(const char *s, int len, const char *sep, int seplen, int *count);
125 void sdsfreesplitres(sds *tokens, int count);
126 
127 /* 将s转换成小写字符 */
128 void sdstolower(sds s);
129 
130 /* 将s转换成大写字符 */
131 void sdstoupper(sds s);
132 
133 sds sdsfromlonglong(long long value);
134 sds sdscatrepr(sds s, const char *p, size_t len);
135 sds *sdssplitargs(const char *line, int *argc);
136 
137 /* 按指定长度遍历字符s,从from复制至to */
138 sds sdsmapchars(sds s, const char *from, const char *to, size_t setlen);
139 
140 /* Low level functions exposed to the user API */
141 /* 对sds所对应的sdshdr结构的buf进行扩展 */
142 sds sdsMakeRoomFor(sds s, size_t addlen);
143 
144 /* 对sds的buf的右端进行扩展(expand)或者修剪(trim) */
145 void sdsIncrLen(sds s, int incr);
146 
147 /* 在不改动buf的情况系,将buf内多余的空间释放出去 */
148 sds sdsRemoveFreeSpace(sds s);
149 
150 /* 计算给定sds的buf所占用的内存总数 */
151 size_t sdsAllocSize(sds s);
152 
153 #endif