string API 参考 - XRT 程序设计

模块契约字符串 API

线程

视图、查找与变换等纯函数可任意线程并发调用；构建器、拆分迭代器等有状态对象由创建线程独占使用，不可跨线程共享。

错误

无效指针、无效视图或无效公开结构产生 XERR_ARGUMENT 或 XERR_STATE。
长度计算或容量增长溢出产生 XERR_RANGE。
分配失败产生 XERR_MEMORY。
C 运行库拒绝格式串或格式串包含 %n 时产生 XERR_VALUE，错误域为 xrt.string，代码为 XSTR_ERROR_FORMAT。

返回布尔值的迭代 Next 函数以 false 同时表示正常结束和失败。调用方只需在初始化或参数可能无效时检查当前错误；正常结束不会创建新错误。成功调用不清除旧错误，遵循 XRT 通用错误契约。

设计契约

字符串基础层只处理字节，不隐式验证、解码或修改 UTF-8。这样同一套 API 可以安全处理 UTF-8、协议字段和包含 \0 的二进制片段，也避免字节偏移与字符偏移混用。Unicode 验证、码点遍历、大小写折叠和规范化属于字符集模块。

xstrview 是 core 提供的零分配借用类型，xstrbuf 是字符串模块提供的可增长独占构建器，返回 str 的函数创建独立零结尾字符串。调用方可以按性能和使用手感选择层级，不需要先构造重量级字符串对象。

启用方式：

XRT_FEATURE_STRING：视图构造、查找、变换、独立字符串和构建器；xstrview 类型与 XRT_STR_LITERAL 本身始终可用。
XRT_FEATURE_STRING_SPLIT：拆分与行迭代器，依赖 XRT_FEATURE_STRING。
XRT_FEATURE_STRING_FORMAT：printf 格式化，依赖 XRT_FEATURE_STRING。
XRT_FEATURE_STRING_GLOB：严格 UTF-8 通配匹配，依赖 XRT_FEATURE_STRING 与 XRT_FEATURE_UNICODE。

范例

完整范例位于：

examples/string/basic/main.c：视图、裁剪和独立字符串。
examples/string/builder/main.c：增量构建和所有权转移。
examples/string/split/main.c：零分配行迭代。
examples/string/format/main.c：直接格式化到构建器。
examples/string/glob/main.c：严格 UTF-8 文件名通配。
examples/string/distance/main.c：带阈值的 Unicode 标量编辑距离与相似度。

类型与所有权

xstrbuf类型

构建器拥有 Data。有效状态始终满足 Size <= Capacity；Data != NULL 时始终满足 Data[Size] == 0。内容仍可包含内嵌零字节，真实长度以 Size 为准。构建器必须先由 xrtStrBufInit 初始化。增长可能移动 Data，外部借用视图随之失效；追加当前构建器有效内容中的子视图是受支持的。失败不会改变逻辑内容，调用方可以检查错误后重试或释放构建器。

字段	类型	语义
`Data`	`str`	当前数据起点
`Size`	`size_t`	当前长度（不含末尾零）
`Capacity`	`size_t`	分配容量

typedef struct xstrbuf { str Data; size_t Size; size_t Capacity; } xstrbuf;

`xstrsplit`、`xstrlines`、`xstrfields` 与 `xstrlist`

xstrerror类型

字符串体系的稳定错误代码。

值	语义
`XSTR_ERROR_FORMAT`	XSTR失败FORMAT
`XSTR_ERROR_PATTERN`	通配模式非法

typedef enum xstrerror { XSTR_ERROR_FORMAT = 1, XSTR_ERROR_PATTERN } xstrerror;

xstrlines类型

行迭代器同时识别 LF、CRLF 和 CR。

字段	类型	语义
`Text`	`xstrview`	文本视图
`Position`	`size_t`	位置
`State`	`uint32`	状态
`Done`	`bool`	Done

typedef struct xstrlines { xstrview Text; size_t Position; uint32 State; bool Done; } xstrlines;

xstrfields类型

字段迭代器跳过连续 ASCII 空白且不返回空字段。

字段	类型	语义
`Text`	`xstrview`	文本视图
`Position`	`size_t`	位置
`State`	`uint32`	状态
`Done`	`bool`	Done

typedef struct xstrfields { xstrview Text; size_t Position; uint32 State; bool Done; } xstrfields;

xstrlist类型

便捷拆分结果在一个分配块内保存视图和零结尾副本。

字段	类型	语义
`Count`	`size_t`	数量
`Items`	`xstrview*`	元素数组
`DataSize`	`size_t`	DataSize

typedef struct xstrlist { size_t Count; xstrview* Items; size_t DataSize; } xstrlist;

xstrglobflag类型

通配匹配可以选择只对 ASCII 字母忽略大小写。

值	语义
`XSTR_GLOB_CASE_ASCII`	ASCII 大小写不敏感

typedef enum xstrglobflag { XSTR_GLOB_CASE_ASCII = 0x01 } xstrglobflag;

xstrsplit类型

通用字符串拆分迭代器不分配内存。

字段	类型	语义
`Text`	`xstrview`	Text
`Separator`	`xstrview`	Separator
`Position`	`size_t`	Position
`State`	`uint32`	State
`Done`	`bool`	Done

typedef struct xstrsplit { xstrview Text; xstrview Separator; size_t Position; uint32 State; bool Done; } xstrsplit;

视图函数

xrtStrView函数

从零结尾字符串创建借用视图，空指针视为空字符串。

xstrview xrtStrView(cstr sText)

参数

参数	方向	约束	说明
`sText`	输入	允许空	零结尾字符串

返回值

返回	含义	失败时状态
视图	借用视图；空指针为空视图	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

path/basic · 视图创建

	if ( !xrtPathIterInit(&Iterator, xrtStrView(sJoined), XPATH_NATIVE) ) {

xrtStrViewN函数

从明确长度创建借用视图。

xstrview xrtStrViewN(cstr sText, size_t iSize)

参数

参数	方向	约束	说明
`sText`	输入	—	字符串起点
`iSize`	输入	—	字节数

返回值

返回	含义	失败时状态
视图	借用视图	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

text/regex · 定长视图

	pRegex = xrtRegexCompile(xrtStrViewN(sLiteral, iLiteralSize));

xrtStrEmpty函数

判断字符串视图是否为空。

bool xrtStrEmpty(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
`true`	是为空	—
`false`	不是为空	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 空判断

		xrtStrEmpty(SV("")) ? 1 : 0);

xrtStrBlank函数

判断字符串是否只包含 ASCII 空白。

bool xrtStrBlank(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
`true`	是全空白	—
`false`	不是全空白	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 空白判断

		xrtStrBlank(SV("  \t ")) ? 1 : 0,

xrtStrEqual函数

判断两个字符串视图是否完全相等。

bool xrtStrEqual(xstrview Left, xstrview Right)

参数

参数	方向	约束	说明
`Left`	输入	借用	左视图
`Right`	输入	借用	右视图

返回值

返回	含义	失败时状态
`true`	是相等	—
`false`	不是相等	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

compare · 相等判断

		xrtStrEqual(Hello, HelloUp) ? 1 : 0,

xrtStrCaseEqual函数

按 ASCII 大小写不敏感规则判断相等。

bool xrtStrCaseEqual(xstrview Left, xstrview Right)

参数

参数	方向	约束	说明
`Left`	输入	借用	左视图
`Right`	输入	借用	右视图

返回值

返回	含义	失败时状态
`true`	是相等	—
`false`	不是相等	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 大小写不敏感相等

		xrtStrCaseEqual(Hello, HelloUp) ? 1 : 0);

xrtStrCompare函数

按无符号字节进行词典序比较。

int xrtStrCompare(xstrview Left, xstrview Right)

参数

参数	方向	约束	说明
`Left`	输入	借用	左视图
`Right`	输入	借用	右视图

返回值

返回	含义	失败时状态
`< 0` / `0` / `> 0`	比较结果	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

compare · 词典序比较

	printf("cmp=%d\n", xrtStrCompare(Hello, HelloUp) > 0 ? 1 : -1);

xrtStrCaseCompare函数

按 ASCII 大小写不敏感规则进行词典序比较。

int xrtStrCaseCompare(xstrview Left, xstrview Right)

参数

参数	方向	约束	说明
`Left`	输入	借用	左视图
`Right`	输入	借用	右视图

返回值

返回	含义	失败时状态
`< 0` / `0` / `> 0`	比较结果	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 大小写不敏感比较

		xrtStrCaseCompare(Hello, HelloUp) == 0 ? 1 : -1);

xrtStrFind函数

从指定字节位置查找子串，未找到返回 XRT_NPOS。

size_t xrtStrFind(xstrview Text, xstrview Part, size_t iStart)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串
`iStart`	输入	—	起始字节位置

返回值

返回	含义	失败时状态
字节位置	首个匹配位置	—
`XRT_NPOS`	未找到	不设错误

错误

无 — 纯借用操作，不设置错误

范例已编译验证

find · 查找子串

		(int)xrtStrFind(Path, SV("archive"), 0u),

xrtStrRFind函数

从右侧查找最后一个子串，未找到返回 XRT_NPOS。

size_t xrtStrRFind(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
字节位置	首个匹配位置	—
`XRT_NPOS`	未找到	不设错误

错误

无 — 纯借用操作，不设置错误

范例已编译验证

find · 右查找子串

		(int)xrtStrRFind(Path, SV(".")),

xrtStrCaseFind函数

按 ASCII 大小写不敏感规则查找子串。

size_t xrtStrCaseFind(xstrview Text, xstrview Part, size_t iStart)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串
`iStart`	输入	—	起始字节位置

返回值

返回	含义	失败时状态
字节位置	首个匹配位置	—
`XRT_NPOS`	未找到	不设错误

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/find · 大小写不敏感查找

		(int)xrtStrCaseFind(SV("Xrt-Core"), SV("xrt"), 0u),

xrtStrCaseRFind函数

按 ASCII 大小写不敏感规则从右侧查找最后一个子串。

size_t xrtStrCaseRFind(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
字节位置	首个匹配位置	—
`XRT_NPOS`	未找到	不设错误

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/find · 大小写不敏感右查找

	(int)xrtStrCaseRFind(SV("a.Tar.GZ"), SV(".gz")),

xrtStrFindByte函数

从指定字节位置查找单个字节。

size_t xrtStrFindByte(xstrview Text, unsigned char iByte, size_t iStart)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iByte`	输入	—	目标字节
`iStart`	输入	—	起始字节位置

返回值

返回	含义	失败时状态
字节位置	首个匹配位置	—
`XRT_NPOS`	未找到	不设错误

错误

无 — 纯借用操作，不设置错误

范例已编译验证

find · 查找字节

		(int)xrtStrFindByte(SV("a/b/c"), '/', 2u),

xrtStrFindAny函数

从指定字节位置查找属于集合的首个字节。

size_t xrtStrFindAny(xstrview Text, xstrview Set, size_t iStart)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合
`iStart`	输入	—	起始字节位置

返回值

返回	含义	失败时状态
字节位置	首个匹配位置	—
`XRT_NPOS`	未找到	不设错误

错误

无 — 纯借用操作，不设置错误

范例已编译验证

find · 查找集合字节

		(int)xrtStrFindAny(SV("host:8080"), SV(": /"), 0u));

xrtStrContains函数

判断字符串是否包含指定子串。

bool xrtStrContains(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`true`	是包含	—
`false`	不是包含	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 包含判断

		xrtStrContains(Hello, SV("lo X")) ? 1 : 0,

xrtStrCaseContains函数

按 ASCII 大小写不敏感规则判断是否包含子串。

bool xrtStrCaseContains(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`true`	是包含	—
`false`	不是包含	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 大小写不敏感包含

		xrtStrCaseContains(SV("Config"), SV("FIG")) ? 1 : 0,

xrtStrContainsAny函数

判断字符串是否包含集合中的任意字节。

bool xrtStrContainsAny(xstrview Text, xstrview Set)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合

返回值

返回	含义	失败时状态
`true`	是包含	—
`false`	不是包含	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 包含集合字节

		xrtStrContainsAny(SV("host:8080"), SV(";:/")) ? 1 : 0);

xrtStrCount函数

统计不重叠子串数量，空子串返回零。

size_t xrtStrCount(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`>= 0`	不重叠出现次数	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 计数

		(int)xrtStrCount(SV("ab aB ab"), SV("ab")),

xrtStrCaseCount函数

按 ASCII 大小写不敏感规则统计不重叠子串数量。

size_t xrtStrCaseCount(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`>= 0`	不重叠出现次数	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 大小写不敏感计数

		(int)xrtStrCaseCount(SV("Ab aB ab"), SV("ab")));

xrtStrStarts函数

判断字符串是否以指定子串开始。

bool xrtStrStarts(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`true`	是前缀	—
`false`	不是前缀	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 前缀判断

		xrtStrStarts(HelloUp, SV("HELLO")) ? 1 : 0,

xrtStrEnds函数

判断字符串是否以指定子串结束。

bool xrtStrEnds(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`true`	是后缀	—
`false`	不是后缀	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 后缀判断

		xrtStrEnds(Hello, SV("XRT")) ? 1 : 0);

xrtStrCaseStarts函数

按 ASCII 大小写不敏感规则判断是否以子串开始。

bool xrtStrCaseStarts(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`true`	是前缀	—
`false`	不是前缀	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 大小写不敏感前缀

		xrtStrCaseStarts(Hello, SV("hello")) ? 1 : 0,

xrtStrCaseEnds函数

按 ASCII 大小写不敏感规则判断是否以子串结束。

bool xrtStrCaseEnds(xstrview Text, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串

返回值

返回	含义	失败时状态
`true`	是后缀	—
`false`	不是后缀	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/compare · 大小写不敏感后缀

		xrtStrCaseEnds(Hello, SV("xrt")) ? 1 : 0,

xrtStrCut函数

围绕首个分隔符切分借用视图，未找到时 Before 返回完整输入。

bool xrtStrCut(xstrview Text, xstrview Separator, xstrview* pBefore, xstrview* pAfter)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Separator`	输入	借用	分隔符
`pBefore`	输出	非空	接收借用视图（分隔符前）
`pAfter`	输出	非空	接收借用视图（分隔符后）

返回值

返回	含义	失败时状态
`true`	找到分隔符并已切分	—
`false`	未找到，Before = 完整输入	不设错误

错误

未找到分隔符返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

string/basic · 首个分隔切分

	if ( !xrtStrCut(Text, XRT_STR_LITERAL("/"), &Name, NULL) ||
		 !xrtStrFilterTo(Name, XRT_STR_LITERAL("_-"), arrName,
			sizeof(arrName), &iNameSize) ) {

xrtStrRCut函数

围绕最后一个分隔符切分借用视图，未找到时 Before 返回完整输入。

bool xrtStrRCut(xstrview Text, xstrview Separator, xstrview* pBefore, xstrview* pAfter)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Separator`	输入	借用	分隔符
`pBefore`	输出	非空	接收借用视图（分隔符前）
`pAfter`	输出	非空	接收借用视图（分隔符后）

返回值

返回	含义	失败时状态
`true`	找到分隔符并已切分	—
`false`	未找到，Before = 完整输入	不设错误

错误

未找到分隔符返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

string/find · 最后分隔切分

	(void)xrtStrRCut(SV("report.final.txt"), SV("."), NULL, &Name);

xrtStrCutPrefix函数

删除匹配的前缀并返回剩余借用视图。

bool xrtStrCutPrefix(xstrview Text, xstrview Prefix, xstrview* pRest)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Prefix`	输入	借用	前缀
`pRest`	输出	非空	接收借用视图（剩余）

返回值

返回	含义	失败时状态
`true`	前缀匹配且已写出剩余	—
`false`	前缀不匹配	不设错误

错误

前缀不匹配返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

string/find · 删前缀

	(void)xrtStrCutPrefix(Path, SV("/tmp/"), &Rest);

xrtStrCutSuffix函数

删除匹配的后缀并返回剩余借用视图。

bool xrtStrCutSuffix(xstrview Text, xstrview Suffix, xstrview* pRest)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Suffix`	输入	借用	后缀
`pRest`	输出	非空	接收借用视图（剩余）

返回值

返回	含义	失败时状态
`true`	后缀匹配且已写出剩余	—
`false`	后缀不匹配	不设错误

错误

后缀不匹配返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

string/find · 删后缀

	(void)xrtStrCutSuffix(Rest, SV(".tar.gz"), &Rest);

xrtStrSlice函数

按字节截取借用视图，范围会钳制到源字符串。

xstrview xrtStrSlice(xstrview Text, size_t iStart, size_t iCount)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iStart`	输入	—	起始字节位置
`iCount`	输入	—	截取字节数

返回值

返回	含义	失败时状态
视图	截取结果（范围已钳制）	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/edit · 截取

	xstrview Part = xrtStrSlice(SV("abcd"), 1u, 2u);

xrtStrTrimLeft函数

删除左侧 ASCII 空白并返回借用视图。

xstrview xrtStrTrimLeft(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
视图	去除左侧空白后的借用	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

pad_trim · 删左空白

	xstrview Trimmed = xrtStrTrimRight(xrtStrTrimLeft(SV("  mid  ")));

xrtStrTrimRight函数

删除右侧 ASCII 空白并返回借用视图。

xstrview xrtStrTrimRight(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
视图	去除右侧空白后的借用	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

pad_trim · 删右空白

	xstrview Trimmed = xrtStrTrimRight(xrtStrTrimLeft(SV("  mid  ")));

xrtStrTrim函数

删除两侧 ASCII 空白并返回借用视图。

xstrview xrtStrTrim(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
视图	去除两侧空白后的借用	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

string/basic · 删两侧空白

	xstrview Text = xrtStrTrim(XRT_STR_LITERAL("  alpha/beta  "));

xrtStrTrimLeftSet函数

删除左侧属于指定字节集合的内容。

xstrview xrtStrTrimLeftSet(xstrview Text, xstrview Set)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合

返回值

返回	含义	失败时状态
视图	去除后的借用	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

pad_trim · 删左集合

	xstrview Hex = xrtStrTrimLeftSet(SV("0xFF00"), SV("0x"));

xrtStrTrimRightSet函数

删除右侧属于指定字节集合的内容。

xstrview xrtStrTrimRightSet(xstrview Text, xstrview Set)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合

返回值

返回	含义	失败时状态
视图	去除后的借用	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

pad_trim · 删右集合

	xstrview Num = xrtStrTrimRightSet(SV("42 ms"), SV(" ms"));

xrtStrTrimSet函数

删除两侧属于指定字节集合的内容。

xstrview xrtStrTrimSet(xstrview Text, xstrview Set)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合

返回值

返回	含义	失败时状态
视图	去除后的借用	—

错误

无 — 纯借用操作，不设置错误

范例已编译验证

pad_trim · 删两侧集合

	xstrview Value = xrtStrTrimSet(SV("{ \"value\" }"), SV("{}\" "));

独立字符串

xrtStrDup函数

复制零结尾字符串，返回值始终由 xrtFree 释放。

str xrtStrDup(cstr sText)

参数

参数	方向	约束	说明
`sText`	输入	允许空	零结尾字符串（空 = 空串）

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/edit · 复制字符串

	str sDup = xrtStrDup("hello");

xrtStrDupN函数

复制明确长度字符串并追加零结尾。

str xrtStrDupN(cstr sText, size_t iSize)

参数

参数	方向	约束	说明
`sText`	输入	—	字符串起点
`iSize`	输入	—	字节数

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/edit · 定长复制

	str sDupN = xrtStrDupN("world", 3u);

xrtStrDupView函数

复制字符串视图并追加零结尾。

str xrtStrDupView(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/edit · 视图复制

	str sDupView = xrtStrDupView(Part);

xrtStrConcat函数

连接两个字符串视图。

str xrtStrConcat(xstrview Left, xstrview Right)

参数

参数	方向	约束	说明
`Left`	输入	借用	左视图
`Right`	输入	借用	右视图

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/basic · 连接

	sResult = xrtStrConcat((xstrview){ arrName, iNameSize },
		XRT_STR_LITERAL(".txt"));

xrtStrJoin函数

使用分隔符连接一组字符串视图。

str xrtStrJoin(xstrview Separator, const xstrview* arrText, size_t iCount)

参数

参数	方向	约束	说明
`Separator`	输入	借用	分隔符
`arrText`	输入	非空数组	视图数组
`iCount`	输入	—	视图数量

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

dup_join · 分隔连接

	str sJoin = xrtStrJoin(SV(", "), Parts, 3u);

xrtStrJoinSized函数

与 xrtStrJoin 共用唯一布局和写出实现，交付不含末尾零的实际字节数，保留分隔符和每个元素中的 NUL。不要求输入为 UTF-8，也不经 strlen。成功结果总是独立拥有的分配（包括零元素）；用 xrtFree 释放。输出槽可为 NULL。普通失败清零；与分隔符、视图表或任意输入字节区域重叠则报 XERR_ARGUMENT，保持槽和输入不变。无效视图报 XERR_ARGUMENT，表/结果长度溢出报 XERR_RANGE，分配失败报 XERR_MEMORY。输入表和字节均只在调用期间借入；iCount > 0 时调用者须提供完整有效视图表。

str xrtStrJoinSized(xstrview Separator, const xstrview* arrText, size_t iCount, size_t* pOutputSize)

xrtStrRepeat函数

重复字符串指定次数。

str xrtStrRepeat(xstrview Text, size_t iCount)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iCount`	输入	—	重复次数

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

dup_join · 重复

	str sRepeat = xrtStrRepeat(SV("ab-"), 3u);

xrtStrReplace函数

替换所有不重叠子串。

str xrtStrReplace(xstrview Text, xstrview Part, xstrview Replacement)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Part`	输入	借用	子串
`Replacement`	输入	借用	替换内容

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

edit · 替换

	showOwned("replace", xrtStrReplace(SV("a.b.c"), SV("."), SV("-")));

xrtStrReplaceSized函数

与 xrtStrReplace 使用同一替换实现，额外交付它已计算的实际字节长度，包含内嵌 NUL、不包含最后的零终止符；不额外计数输入或 strlen 扫描输出。前三个参数的借用、非重叠替换、空 Part 和错误合同与 xrtStrReplace 相同。成功结果为独立分配，由 xrtFree 释放。pOutputSize 可为 NULL；非空时须指向可写 size_t 且与三个输入字节区域不重叠。普通失败输出长度清零；拒绝重叠时不写输出指针，避免破坏输入。非法参数报 XERR_ARGUMENT，长度溢出报 XERR_RANGE，分配失败报 XERR_MEMORY；失败不返回部分结果。

str xrtStrReplaceSized(xstrview Text, xstrview Part, xstrview Replacement, size_t* pOutputSize)

xrtStrInsert函数

按字节位置插入子串。

str xrtStrInsert(xstrview Text, size_t iPosition, xstrview Part)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iPosition`	输入	—	插入字节位置
`Part`	输入	借用	插入内容

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

edit · 插入

	showOwned("insert", xrtStrInsert(SV("xrtcore"), 3u, SV("::")));

xrtStrRemove函数

按字节范围删除内容。

str xrtStrRemove(xstrview Text, size_t iPosition, size_t iCount)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iPosition`	输入	—	删除起点
`iCount`	输入	—	删除字节数

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

edit · 删除

	showOwned("remove", xrtStrRemove(SV("xrt::core"), 3u, 2u));

xrtStrReverseBytes函数

按字节反转字符串。

str xrtStrReverseBytes(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

edit · 反转

	showOwned("reverse", xrtStrReverseBytes(SV("abc")));

xrtStrReverseBytesTo函数

按字节反转到调用方缓冲区并补零；允许输入和输出起点相同。

bool xrtStrReverseBytesTo(xstrview Text, char* sOutput, size_t iCapacity)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`sOutput`	输出	非空	输出缓冲，须含末尾零
`iCapacity`	输入	—	容量

返回值

返回	含义	失败时状态
`true`	已写入并补零	—
`false`	容量不足或参数非法	`XERR_RANGE` / `XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 容量不足（须含末尾零字节），不写半个结果

范例已编译验证

edit · 反转到缓冲

	if ( xrtStrReverseBytesTo(SV("cba"), Buffer, sizeof(Buffer)) ) {

xrtStrLower函数

复制字符串并把 ASCII 字母转换为小写。

str xrtStrLower(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

case · 转小写

	printOwned("lower", xrtStrLower(SV("HELLO XRT")));

xrtStrLowerTo函数

把 ASCII 字母转换为小写并写入调用方缓冲区；允许原地转换。

bool xrtStrLowerTo(xstrview Text, char* sOutput, size_t iCapacity)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`sOutput`	输出	非空	输出缓冲，须含末尾零
`iCapacity`	输入	—	容量

返回值

返回	含义	失败时状态
`true`	已写入并补零	—
`false`	容量不足或参数非法	`XERR_RANGE` / `XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 容量不足（须含末尾零字节），不写半个结果

范例已编译验证

case · 转小写到缓冲

	if ( xrtStrLowerTo(SV("BUFFER-WAY"), Buffer, sizeof(Buffer)) ) {

xrtStrUpper函数

复制字符串并把 ASCII 字母转换为大写。

str xrtStrUpper(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

case · 转大写

	printOwned("upper", xrtStrUpper(SV("hello xrt")));

xrtStrUpperTo函数

把 ASCII 字母转换为大写并写入调用方缓冲区；允许原地转换。

bool xrtStrUpperTo(xstrview Text, char* sOutput, size_t iCapacity)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`sOutput`	输出	非空	输出缓冲，须含末尾零
`iCapacity`	输入	—	容量

返回值

返回	含义	失败时状态
`true`	已写入并补零	—
`false`	容量不足或参数非法	`XERR_RANGE` / `XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 容量不足（须含末尾零字节），不写半个结果

范例已编译验证

case · 转大写到缓冲

	if ( xrtStrUpperTo(SV("buffer-way"), Buffer, sizeof(Buffer)) ) {

xrtStrFilter函数

删除集合中的全部字节并创建独立字符串。

str xrtStrFilter(xstrview Text, xstrview Set)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/dup_join · 过滤

	str sFilter = xrtStrFilter(SV("xrt::core//"), SV(":/"));

xrtStrFilterTo函数

删除集合中的全部字节并写入调用方缓冲区。

bool xrtStrFilterTo(xstrview Text, xstrview Set, char* sOutput, size_t iCapacity, size_t* pOutputSize)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Set`	输入	借用	字节集合
`sOutput`	输出	非空	输出缓冲
`iCapacity`	输入	—	容量
`pOutputSize`	输出	允许空	接收输出长度

返回值

返回	含义	失败时状态
`true`	已写入	—
`false`	容量不足或参数非法	`XERR_RANGE` / `XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 容量不足（须含末尾零字节），不写半个结果

范例已编译验证

string/basic · 过滤到缓冲

		 !xrtStrFilterTo(Name, XRT_STR_LITERAL("_-"), arrName,
			sizeof(arrName), &iNameSize) ) {

xrtStrPadLeft函数

按字节宽度在左侧重复填充字符串。

str xrtStrPadLeft(xstrview Text, size_t iWidth, xstrview Fill)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iWidth`	输入	—	目标字节宽度
`Fill`	输入	借用、非空	填充内容

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

pad_trim · 左填充

	showOwned("pad-left", xrtStrPadLeft(SV("id"), 5u, SV("*")));

xrtStrPadRight函数

按字节宽度在右侧重复填充字符串。

str xrtStrPadRight(xstrview Text, size_t iWidth, xstrview Fill)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iWidth`	输入	—	目标字节宽度
`Fill`	输入	借用、非空	填充内容

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

pad_trim · 右填充

	showOwned("pad-right", xrtStrPadRight(SV("id"), 5u, SV("*")));

xrtStrPadCenter函数

按字节宽度在两侧重复填充字符串。

str xrtStrPadCenter(xstrview Text, size_t iWidth, xstrview Fill)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`iWidth`	输入	—	目标字节宽度
`Fill`	输入	借用、非空	填充内容

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

pad_trim · 居中填充

	showOwned("pad-center", xrtStrPadCenter(SV("id"), 5u, SV("*")));

字符串构建器

xrtStrBufInit函数

初始化空字符串构建器。

void xrtStrBufInit(xstrbuf* pBuffer)

参数

参数	方向	约束	说明
`pBuffer`	输出	非空	接收构建器

返回值

返回	含义	失败时状态
无	已初始化	—

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

builder · 初始化

	xrtStrBufInit(&tBuffer);

xrtStrBufValid函数

检查字符串构建器的公开状态是否自洽。

bool xrtStrBufValid(const xstrbuf* pBuffer)

参数

参数	方向	约束	说明
`pBuffer`	输入	非空	目标构建器

返回值

返回	含义	失败时状态
`true`	是自洽	—
`false`	不是自洽	—

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

builder_tour · 状态自检

	if ( !xrtStrBufReserve(&Buffer, 64u) || !xrtStrBufValid(&Buffer) ) {

xrtStrBufFree函数

释放字符串构建器持有的内存。

void xrtStrBufFree(xstrbuf* pBuffer)

参数

参数	方向	约束	说明
`pBuffer`	输入	允许空	空 = 空操作

返回值

返回	含义	失败时状态
无	已释放	—

错误

无 — 释放不失败

范例已编译验证

builder · 释放

		xrtStrBufFree(&tBuffer);

xrtStrBufClear函数

清空字符串构建器但保留容量。

void xrtStrBufClear(xstrbuf* pBuffer)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器

返回值

返回	含义	失败时状态
无	已清空	—

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

string/builder_tour · 清空

	xrtStrBufClear(&Buffer);

xrtStrBufView函数

返回字符串构建器当前内容的借用视图。

xstrview xrtStrBufView(const xstrbuf* pBuffer)

参数

参数	方向	约束	说明
`pBuffer`	输入	非空	目标构建器

返回值

返回	含义	失败时状态
视图	当前内容借用	—
空视图	参数非法	`XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

string/builder_tour · 内容视图

	(void)xrtStrBufResize(&Buffer, xrtStrBufView(&Buffer).Size - 1u);

xrtStrBufAlias函数

检查视图是否借用构建器当前内容，并返回原始字节偏移。

bool xrtStrBufAlias(const xstrbuf* pBuffer, xstrview Text, bool* pAlias, size_t* pOffset)

参数

参数	方向	约束	说明
`pBuffer`	输入	非空	目标构建器
`Text`	输入	借用	待检查视图
`pAlias`	输出	允许空	接收是否别名
`pOffset`	输出	允许空	接收原始字节偏移

返回值

返回	含义	失败时状态
`true`	视图是构建器内容的别名	—
`false`	非别名或参数非法	不设错误

错误

非别名返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

builder_tour · 别名检查

	(void)xrtStrBufAlias(&Buffer, View, &bAlias, &iAliasOffset);

xrtStrBufReserve函数

保证字符串构建器至少具有指定数据容量。

bool xrtStrBufReserve(xstrbuf* pBuffer, size_t iCapacity)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`iCapacity`	输入	—	期望容量

返回值

返回	含义	失败时状态
`true`	容量已保证	—
`false`	扩容失败	`XERR_RANGE` / `XERR_MEMORY`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 容量溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/builder_tour · 预留容量

	if ( !xrtStrBufReserve(&Buffer, 64u) || !xrtStrBufValid(&Buffer) ) {

xrtStrBufResize函数

调整字符串构建器长度，扩展区域填零。

bool xrtStrBufResize(xstrbuf* pBuffer, size_t iSize)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`iSize`	输入	—	新长度

返回值

返回	含义	失败时状态
`true`	长度已调整	—
`false`	调整失败	`XERR_RANGE` / `XERR_MEMORY`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/builder_tour · 调整长度

	(void)xrtStrBufResize(&Buffer, xrtStrBufView(&Buffer).Size - 1u);

xrtStrBufAppend函数

追加字符串视图，允许追加自身的有效子视图。

bool xrtStrBufAppend(xstrbuf* pBuffer, xstrview Text)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`Text`	输入	借用	追加内容

返回值

返回	含义	失败时状态
`true`	已追加	—
`false`	扩容失败	`XERR_RANGE` / `XERR_MEMORY`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

builder · 追加视图

	if ( !xrtStrBufAppend(&tBuffer, XRT_STR_LITERAL("items=")) ||
		 !xrtStrBufAppendRepeat(&tBuffer, XRT_STR_LITERAL("ab"), 3) ) {

xrtStrBufAppendByte函数

追加一个字节。

bool xrtStrBufAppendByte(xstrbuf* pBuffer, char iByte)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`iByte`	输入	—	追加的字节

返回值

返回	含义	失败时状态
`true`	已追加	—
`false`	扩容失败	`XERR_RANGE` / `XERR_MEMORY`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/builder_tour · 追加字节

	if ( !xrtStrBufAppendByte(pBuffer, ' ') ||
		!xrtStrBufAppend(pBuffer, (xstrview){ sTag, strlen(sTag) }) ) {

xrtStrBufAppendRepeat函数

重复追加字符串视图。

bool xrtStrBufAppendRepeat(xstrbuf* pBuffer, xstrview Text, size_t iCount)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`Text`	输入	借用	追加内容
`iCount`	输入	—	重复次数

返回值

返回	含义	失败时状态
`true`	已追加	—
`false`	扩容失败	`XERR_RANGE` / `XERR_MEMORY`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/builder · 重复追加

		 !xrtStrBufAppendRepeat(&tBuffer, XRT_STR_LITERAL("ab"), 3) ) {

xrtStrBufAppendFormat函数

使用 printf 规则直接追加到构建器；拒绝 %n。

bool xrtStrBufAppendFormat(xstrbuf* pBuffer, cstr sFormat, ...)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`sFormat`	输入	非空	printf 格式串
`...`	输入	与格式串匹配	变参

返回值

返回	含义	失败时状态
`true`	已追加	—
`false`	格式化或扩容失败	`XERR_ARGUMENT` 等

错误

XERR_ARGUMENT — 指针为空或参数非法
xrt.str 域错误 — 格式串非法（含 %n）或与实参不匹配
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 扩容失败

范例已编译验证

string/format · 格式化追加

		 !xrtStrBufAppendFormat(&tBuffer, "%08X / %.2f", 255u, 3.5) ) {

xrtStrBufAppendFormatV函数

使用 printf 规则和已有参数列表直接追加到构建器。

bool xrtStrBufAppendFormatV(xstrbuf* pBuffer, cstr sFormat, va_list Args)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器
`sFormat`	输入	非空	printf 格式串
`Args`	输入	已由 `va_start` 初始化	变参列表

返回值

返回	含义	失败时状态
`true`	已追加	—
`false`	格式化或扩容失败	`XERR_ARGUMENT` 等

错误

XERR_ARGUMENT — 指针为空或参数非法
xrt.str 域错误 — 格式串非法（含 %n）或与实参不匹配
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 扩容失败

范例已编译验证

string/builder_tour · 格式化追加（va_list）

	bool bOk = xrtStrBufAppendFormatV(pBuffer, "=%d", Args);

xrtStrBufTake函数

取走构建器内存并把构建器重置为空。

str xrtStrBufTake(xstrbuf* pBuffer)

参数

参数	方向	约束	说明
`pBuffer`	输入/输出	非空	目标构建器

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	构建器为空	不设错误

错误

空构建器返回 NULL 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

string/builder · 取走内存

	sResult = xrtStrBufTake(&tBuffer);

拆分与行处理

xrtStrSplitInit函数

初始化不分配内存的字符串拆分迭代器。

bool xrtStrSplitInit(xstrsplit* pSplit, xstrview Text, xstrview Separator)

参数

参数	方向	约束	说明
`pSplit`	输出	非空	接收迭代器
`Text`	输入	借用	输入文本
`Separator`	输入	借用、非空	分隔符

返回值

返回	含义	失败时状态
`true`	已初始化	—
`false`	参数非法	`XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

split · 初始化拆分

	if ( !xrtStrSplitInit(&tSplit, XRT_STR_LITERAL("alpha,beta,,gamma"), XRT_STR_LITERAL(",")) ) {

xrtStrSplitNext函数

返回下一个借用片段，结束时返回 false。

bool xrtStrSplitNext(xstrsplit* pSplit, xstrview* pItem)

参数

参数	方向	约束	说明
`pSplit`	输入/输出	已初始化	目标迭代器
`pItem`	输出	非空	接收借用视图

返回值

返回	含义	失败时状态
`true`	已产出片段	—
`false`	遍历结束	不设错误

错误

遍历结束返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

split · 下一片段

	while ( xrtStrSplitNext(&tSplit, &Item) ) {

xrtStrFieldsInit函数

初始化按连续 ASCII 空白拆分的零分配字段迭代器。

bool xrtStrFieldsInit(xstrfields* pFields, xstrview Text)

参数

参数	方向	约束	说明
`pFields`	输出	非空	接收迭代器
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
`true`	已初始化	—
`false`	参数非法	`XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

iterators · 初始化字段

	if ( xrtStrFieldsInit(&Fields, SV("  user\tport  443 ")) ) {

xrtStrFieldsNext函数

返回下一个非空借用字段，结束时返回 false。

bool xrtStrFieldsNext(xstrfields* pFields, xstrview* pField)

参数

参数	方向	约束	说明
`pFields`	输入/输出	已初始化	目标迭代器
`pField`	输出	非空	接收借用视图

返回值

返回	含义	失败时状态
`true`	已产出字段	—
`false`	遍历结束	不设错误

错误

遍历结束返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

iterators · 下一字段

		while ( xrtStrFieldsNext(&Fields, &Field) ) {

xrtStrLinesInit函数

初始化不分配内存的行迭代器。

bool xrtStrLinesInit(xstrlines* pLines, xstrview Text)

参数

参数	方向	约束	说明
`pLines`	输出	非空	接收迭代器
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
`true`	已初始化	—
`false`	参数非法	`XERR_ARGUMENT`

错误

XERR_ARGUMENT — 指针为空或参数非法

范例已编译验证

iterators · 初始化行

	if ( xrtStrLinesInit(&Lines, SV("first\nsecond\r\n")) ) {

xrtStrLinesNext函数

返回下一行借用视图，结束时返回 false。

bool xrtStrLinesNext(xstrlines* pLines, xstrview* pLine)

参数

参数	方向	约束	说明
`pLines`	输入/输出	已初始化	目标迭代器
`pLine`	输出	非空	接收借用视图

返回值

返回	含义	失败时状态
`true`	已产出行	—
`false`	遍历结束	不设错误

错误

遍历结束返回 false 且不设置错误；指针为空 XERR_ARGUMENT

范例已编译验证

iterators · 下一行

		while ( xrtStrLinesNext(&Lines, &Line) ) {

xrtStrSplit函数

一次性拆分字符串并返回独立的零结尾片段。

xstrlist* xrtStrSplit(xstrview Text, xstrview Separator)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Separator`	输入	借用	分隔符

返回值

返回	含义	失败时状态
非空	片段列表，整体一次 `xrtFree` 释放	—
`NULL`	失败	`XERR_MEMORY` 等

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/dup_join · 一次性拆分

	xstrlist* pList = xrtStrSplit(SV("alpha,beta,gamma"), SV(","));

xrtStrSplitLines函数

一次性按行拆分字符串。

xstrlist* xrtStrSplitLines(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
非空	行列表，整体一次 `xrtFree` 释放	—
`NULL`	失败	`XERR_MEMORY` 等

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

iterators · 一次性拆行

	xstrlist* pList = xrtStrSplitLines(SV("a\nb\nc"));

xrtStrFields函数

一次性按连续 ASCII 空白拆分字符串。

xstrlist* xrtStrFields(xstrview Text)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本

返回值

返回	含义	失败时状态
非空	字段列表，整体一次 `xrtFree` 释放	—
`NULL`	失败	`XERR_MEMORY` 等

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

iterators · 一次性拆字段

	xstrlist* pFields = xrtStrFields(SV("one two  three"));

xrtStrListAlloc函数

为指定片段数量和零结尾数据容量分配单块字符串列表。

xstrlist* xrtStrListAlloc(size_t iCount, size_t iDataSize)

参数

参数	方向	约束	说明
`iCount`	输入	—	片段数量
`iDataSize`	输入	—	数据区字节容量

返回值

返回	含义	失败时状态
非空	单块列表，整体一次 `xrtFree` 释放	—
`NULL`	失败	`XERR_RANGE` / `XERR_MEMORY`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 列表尺寸溢出
XERR_MEMORY — 分配失败

范例已编译验证

list · 分配列表

	xstrlist* pList = xrtStrListAlloc(3u, iDataSize);

xrtStrListWrite函数

将片段复制到列表数据区并推进字节偏移。

bool xrtStrListWrite(xstrlist* pList, size_t iIndex, xstrview Item, size_t* pOffset)

参数

参数	方向	约束	说明
`pList`	输入/输出	非空	目标列表
`iIndex`	输入	—	片段索引
`Item`	输入	借用	片段内容
`pOffset`	输出	允许空	接收/推进数据区偏移

返回值

返回	含义	失败时状态
`true`	已复制并推进	—
`false`	索引越界或容量不足	`XERR_RANGE` / `XERR_STATE`

错误

XERR_ARGUMENT — 指针为空或参数非法
XERR_RANGE — 索引越界或数据区剩余容量不足

范例已编译验证

list · 写入片段

		if ( !xrtStrListWrite(pList, i, Source[i], &iOffset) ) {

xrtStrListFree函数

释放便捷拆分结果。

void xrtStrListFree(xstrlist* pList)

参数

参数	方向	约束	说明
`pList`	输入	允许空	空 = 空操作

返回值

返回	含义	失败时状态
无	已释放	—

错误

无 — 释放不失败

范例已编译验证

list · 释放列表

			xrtStrListFree(pList);

格式化

xrtFormat函数

使用 printf 规则创建字符串；拒绝 %n。

str xrtFormat(cstr sFormat, ...)

参数

参数	方向	约束	说明
`sFormat`	输入	非空	printf 格式串
`...`	输入	与格式串匹配	变参

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
xrt.str 域错误 — 格式串非法（含 %n）或与实参不匹配
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/format_tour · 格式化创建

	str sDirect = xrtFormat("id=%d ok=%s", 7, "true");

xrtFormatV函数

使用 printf 规则和已有参数列表创建字符串。

str xrtFormatV(cstr sFormat, va_list Args)

参数

参数	方向	约束	说明
`sFormat`	输入	非空	printf 格式串
`Args`	输入	已由 `va_start` 初始化	变参列表

返回值

返回	含义	失败时状态
非空	零结尾结果，`xrtFree` 释放	—
`NULL`	失败	见错误

错误

XERR_ARGUMENT — 指针为空或参数非法
xrt.str 域错误 — 格式串非法（含 %n）或与实参不匹配
XERR_RANGE — 结果长度溢出
XERR_MEMORY — 分配失败

范例已编译验证

string/format_tour · 格式化创建（va_list）

	sBody = xrtFormatV("x=%s", Args);

通配匹配

xrtStrGlob函数

使用严格 UTF-8 通配模式匹配完整字符串。

bool xrtStrGlob(xstrview Text, xstrview Pattern, uint32 iFlags)

参数

参数	方向	约束	说明
`Text`	输入	借用	输入文本
`Pattern`	输入	借用	通配模式
`iFlags`	输入	—	匹配标志

返回值

返回	含义	失败时状态
`true`	是完整匹配	—
`false`	不是完整匹配	不匹配不设错

错误

不匹配返回 false 且不设置错误；指针为空或模式非法 XERR_ARGUMENT

范例已编译验证

glob · 通配匹配

	printf("%s\n", xrtStrGlob(Name, Pattern, XSTR_GLOB_CASE_ASCII) ?
		"matched" : "not matched");

常量索引常量

以下常量在本页所属头文件中定义，语义见公共头注释。

常量	说明
XSTR_ERROR_FORMAT	见头文件注释
XSTR_ERROR_PATTERN	见头文件注释
XSTR_GLOB_CASE_ASCII	见头文件注释