XScript 手册 · Chapter 30

STR — 字符串函数

STR 是汇集了字符串解析、转换、检索等工具的全局对象。在协议帧解析、订单号拆分、配方字符串处理中调用最为频繁。

基本示例

xscript

string data = "    abc d   ";
Log("[{0}] => Trim = [{1}]", data, STR.Trim(data));
 
data = "12";
int dataToInt = STR.ParseToInt(data);
Log("[{0}] => ParseToInt = [{1}]", data, dataToInt);
 
data = "12.3";
dataToInt = STR.ParseToInt(data, 0);
Log("[{0}] => ParseToInt = [{1}]", data, dataToInt);
 
data = "abc:123";
string name;
string value;
STR.ParseNameValue(data, name, value, ":");
Log("[{0}] => ParseNameValue = [{1},{2}]", data, name, value);
 
int pos = STR.IndexOf(data, ":");
string tail = STR.Substring(data, pos + 1);

实战示例 — 配方解析

xscript

// recipe = "1:50,3:20.3,7:60.1"
array items = STR.ParseCommaString(recipe);
 
if (items.Count == 0)
{
    return -1;
}
 
int unitNo;
double target;
 
for (i, 0, items.Count - 1)
{
    if (STR.ParsePairIntDouble(items[i], unitNo, target, ":") == false)
    {
        return -1;
    }
    if (unitNo == targetUnit)
    {
        return target;
    }
}

主要方法

基础

签名	说明
`int Length(string text)`	长度
`string Trim(string text)`	去除两端空白
`string ToUpper(string text)` / `string ToLower(string text)`	大/小写
`string Replace(string text, string oldValue, string newValue)`	替换
`bool IsNullOrWhiteSpace(string text)`	是否为空/空白
`bool Contains(string text, string value)`	是否包含
`bool StartsWith(string text, string value)` / `EndsWith`	前缀/后缀

检索 · 提取

签名	说明
`int IndexOf(string text, string value)`	首次位置
`int IndexOf(string text, string value, int startIndex)`	指定起始位置
`int NthIndexOf(string text, string value, int n)`	第 N 次位置
`string Substring(string text, int startIndex)`	截取到末尾
`string Substring(string text, int startIndex, int length)`	指定长度

解析

签名	说明
`array ParseCommaString(string commaString)`	CSV 拆分
`array ParseSplitString(string text, string splitString)`	任意分隔符拆分
`bool ParseNameValue(string text, ref string name, ref string value, string delim)`	name/value 对拆分
`bool ParsePairIntDouble(string text, ref int first, ref double second, string delim)`	`key:value` 整数·实数
`bool ParsePairStrings(string text, ref string first, ref string second)`	字符串对
`int ParseToInt(string text)` / `ParseToInt(string text, int defaultValue)`	转整数
`double ParseToDouble(string text)` / `ParseToDouble(string text, double defaultValue)`	转实数

文件

签名	说明
`array ReadAllLines(string path, bool addLog = true)`	文件 → 行数组

提示

解析外部协议时,先 ParseCommaString 再用 ParsePairIntDouble / ParsePairStrings 细分的两段拆分模式更为稳定。
给 ParseToInt 的第二个参数传默认值,即可无异常地安全转换。
有 $"..." 插值字符串,可读性优于 FormatString;但复杂的本地化·格式请使用 SYS.GetDateTimeStringFormat 等辅助函数。

STR 全函数一览(XUtilString)

依据 C# 源码 — 脚本可直接调用的所有函数。

解析(Name=Value · Pair)

函数	含义
`STR.GetName(text, delim='=')`	从 `name=value` 取 name
`STR.GetValue(text, delim='=')`	从 `name=value` 取 value
`STR.ParseNameValue(text, ref name, ref value, delim="=")`	一次拆开
`STR.ParsePairStrings(text, ref s1, ref s2, delim="=")`	两个字符串
`STR.ParsePairIntegers(text, ref i1, ref i2, delim="=")`	两个整数
`STR.ParsePairDoubles(text, ref d1, ref d2, delim="=")`	两个浮点
`STR.ParsePairIntDouble(text, ref i, ref d, delim="=")`	int + double
`STR.ParsePairStringInteger(text, ref s, ref i, delim="=")`	string + int
`STR.ParsePairStringDouble(text, ref s, ref d, delim="=")`	string + double

拆分 / 拼接

函数	含义
`STR.ParseCommaString(text)`	按 `,` 拆 → `array`
`STR.ParseTabSplitString(text)`	按 tab 拆
`STR.ParseSplitString(text, char)` / `(text, string)`	按指定分隔符拆
`STR.GetCommaText(list)`	array → `,` 拼
`STR.GetTapSplitText(list)`	array → tab 拼
`STR.GetSplitedText(list, char)` / `(list, string)`	array → 任意分隔符拼
`STR.StringToDoubleList(list)`	string array → double array

检查 / 转换

函数	含义
`STR.HaveSpace(text)`	含空白
`STR.HaveKoreanChar(str)`	含韩文
`STR.IsStringNubmer(text)`	仅数字
`STR.IsNullOrWhiteSpace(text)`	空或仅空白
`STR.GetEnumType(type, value)`	字符串 → enum
`STR.ConvertAvailableName(name)`	安全的文件名 / 标识符
`STR.StringToHexString(str)`	字符串 → 16 进制

操作(返回新 string)

函数	含义
`STR.Strip(text)` / `STR.StripBrace(text)`	去两端空白 / 去两端括号
`STR.Trim / TrimStart / TrimEnd(text)`	标准 C# 同名
`STR.ToLower(text)` / `STR.ToUpper(text)`	大小写
`STR.PadLeft(text, totalWidth)` / `STR.PadRight(text, totalWidth)`	补宽
`STR.Substring(text, start, len)` / `(text, start)`	子串
`STR.Insert(text, startIndex, value)`	插入
`STR.Remove(text, startIndex)` / `(text, startIndex, count)`	区段删除
`STR.Replace(text, oldValue, newValue)`	整体替换
`STR.ReplaceString(text, start, length, toReplace)`	按位置替换
`STR.GetReverse(data, step)`	按 step 字节反转(例:16 进制 byte swap)

搜索 / 位置

函数	含义
`STR.Length(text)`	长度
`STR.Contains(text, value)`	是否包含
`STR.StartsWith(text, value)` / `EndsWith(text, value)`	前/后缀
`STR.IndexOf(text, value)` / `(text, value, start)` / `(text, value, start, count)`	首次位置
`STR.NthIndexOf(text, value, n)`	第 n 次位置
`STR.LastIndexOf(text, value)` / `(text, value, start)` / `(text, value, start, count)`	末次位置

字符码

函数	含义
`STR.GetCharCode(str, index=0)`	指定位置的 charCode
`STR.SetCharCode(str, index, code)`	指定位置替换

编码 / 转义

函数	含义
`STR.EncodeMultiLine(data)` / `STR.DecodeMultiLine(data)`	多行 ↔ 单行编码
`STR.EncodeBraceInFormat(format)`	FormatString 中转义 `{ }`(用于显示)
`STR.Escape(input)` / `STR.Unescape(input)`	C 风格转义 ↔ 原文

数字 ↔ 字符串

函数	含义
`STR.ParseToInt(text)` / `(text, defaultValue)`	字符串 → int
`STR.ParseToDouble(text)` / `(text, defaultValue)`	字符串 → double
`STR.ParseToStr(int)` / `(double)` / `(bool)`	数字/bool → 字符串
`STR.ParseStringNumber(text, ref prefix, ref number, base=10)`	`"M0017"` → prefix=`"M"`、number=17
`STR.FormatNumberWithComma(int)` / `(double)`	`1,234,567` 这样的千分位逗号
`STR.ParseCommaNumber(text, int)` / `(text, double)`	含逗号字符串 → 数字

文本文件助手

函数	含义
`STR.ReadAllLines(path, addLog=true)`	文件 → 行 array
`STR.ReadAllIntLines(path, addLog=true)`	文件 → int array
`STR.ReadFirstLine(path)`	仅第一行
`STR.ReadAllText(path, addLog=false)`	整文件 → 一个字符串
`STR.SaveAllLines(path, lines)`	array → 文件