62 string

作者：陈媛媛

一、概述

字符串（String）是编程中用于表示文本数据的基本数据类型。在 LuatOS 中，字符串是由字符组成的序列，用于存储和处理文本信息、二进制数据、配置信息等。

string 库提供了丰富的字符串处理功能，包括编码转换、字符串分割、格式处理等。这些函数可以处理二进制数据、URL 编码、Base64 编码等多种字符串操作需求。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/string；

-- 字符串操作综合示例
[[
本示例展示string库的常用功能：
1. 十六进制编码/解码
2. 字符串分割
3. 数值转换
4. URL编码/解码
5. Base64/Base32编码
6. 字符串前后缀判断
7. 字符串裁剪
]]


-- ====================== 十六进制转换示例 ======================
local function hex_examples()
    log.info("=== 十六进制转换示例 ===")

    -- 字符串转十六进制
    local original_str = "123abc"
    local hex_result, hex_length = string.toHex(original_str)
    log.info("toHex", "原始字符串:", original_str, "HEX结果:", hex_result, "长度:", hex_length)

    -- 带分隔符的十六进制转换
    local hex_with_space = string.toHex(original_str, " ")
    log.info("toHex", "带空格分隔:", hex_with_space)

    -- 十六进制转字符串
    local decoded_str = string.fromHex("313233616263")
    log.info("fromHex", "HEX字符串解码:", decoded_str)

    -- 二进制数据转换
    local binary_data = "\1\2\3\4\5"
    local binary_hex = string.toHex(binary_data)
    log.info("toHex", "二进制数据转HEX:", binary_hex)
end

-- ====================== 字符串分割示例 ======================
local function split_examples()
    log.info("=== 字符串分割示例 ===")

    -- 基本分割
    local csv_str = "123,456,789"
    local parts1 = string.split(csv_str, ",")
    log.info("split", "CSV分割结果:", json.encode(parts1))

    -- 使用小数点作为分隔符
    local ip_str = "192.168.1.1"
    local ip_parts = string.split(ip_str, "%.")
    log.info("split", "IP地址分割:", json.encode(ip_parts))

    -- 保留空片段（新版本固件支持）
    local path_str = "/tmp//def/1234/"
    local path_parts = string.split(path_str, "/", true)
    log.info("split", "路径分割(保留空):", #path_parts, json.encode(path_parts))

    -- 不保留空片段
    local path_parts2 = string.split(path_str, "/", false)
    log.info("split", "路径分割(不保留空):", #path_parts2, json.encode(path_parts2))
end

-- ====================== 数值转换示例 ======================
local function value_conversion_examples()
    log.info("=== 数值转换示例 ===")

    -- 字符串转数值编码
    local num_str = "123456"
    local binary_result, converted_chars = string.toValue(num_str)
    log.info("toValue", "原始字符串:", num_str, "转换字符数:", converted_chars)
    log.info("toValue", "二进制结果长度:", #binary_result)

    -- 包含字母的转换
    local mixed_str = "123abc"
    local mixed_result, mixed_count = string.toValue(mixed_str)
    log.info("toValue", "混合字符串转换:", mixed_str, "字符数:", mixed_count)
end

-- ====================== URL编码示例 ======================
local function url_encoding_examples()
    log.info("=== URL编码示例 ===")

    -- URL编码（需要根据实际函数名调整）
    local url_str = "hello world&test=123"
    -- 注意：实际函数名可能需要确认，示例中使用假设的函数名
    -- local encoded = string.urlEncode(url_str)
    -- log.info("urlEncode", "原始:", url_str, "编码后:", encoded)

    log.info("urlEncode", "此功能需要确认具体函数名称和参数")
end

-- ====================== Base64编码示例 ======================
local function base64_examples()
    log.info("=== Base64编码示例 ===")

    -- Base64编码
    local plain_text = "Hello LuaOS!"
    local encoded_b64 = string.toBase64(plain_text)
    log.info("toBase64", "原文:", plain_text, "编码后:", encoded_b64)

    -- Base64解码
    local decoded_b64 = string.fromBase64(encoded_b64)
    log.info("fromBase64", "解码结果:", decoded_b64)

    -- Base32编码
    local encoded_b32 = string.toBase32(plain_text)
    log.info("toBase32", "Base32编码:", encoded_b32)

    -- Base32解码
    local decoded_b32 = string.fromBase32(encoded_b32)
    log.info("fromBase32", "Base32解码:", decoded_b32)
end

-- ====================== 字符串判断示例 ======================
local function string_check_examples()
    log.info("=== 字符串判断示例 ===")

    local test_str = "hello world"

    -- 判断前缀
    local starts_with_hello = string.startsWith(test_str, "hello")
    local starts_with_world = string.startsWith(test_str, "world")
    log.info("startsWith", "字符串:", test_str)
    log.info("startsWith", "以'hello'开头:", starts_with_hello)
    log.info("startsWith", "以'world'开头:", starts_with_world)

    -- 判断后缀
    local ends_with_world = string.endsWith(test_str, "world")
    local ends_with_hello = string.endsWith(test_str, "hello")
    log.info("endsWith", "以'world'结尾:", ends_with_world)
    log.info("endsWith", "以'hello'结尾:", ends_with_hello)

    -- 文件扩展名检查
    local filename = "document.pdf"
    local is_pdf = string.endsWith(filename, ".pdf")
    log.info("endsWith", "文件", filename, "是PDF:", is_pdf)
end

-- ====================== 字符串裁剪示例 ======================
local function trim_examples()
    log.info("=== 字符串裁剪示例 ===")

    -- 包含空白字符的字符串
    local dirty_str = "  \r\n  hello world  \t\n  "

    -- 默认裁剪（前后都裁剪）
    local trimmed = string.trim(dirty_str)
    log.info("trim", "原始字符串长度:", #dirty_str)
    log.info("trim", "裁剪后字符串:", "'" .. trimmed .. "'", "长度:", #trimmed)

    -- 仅裁剪前缀
    local ltrim_only = string.trim(dirty_str, true, false)
    log.info("trim", "仅裁剪前缀:", "'" .. ltrim_only .. "'", "长度:", #ltrim_only)

    -- 仅裁剪后缀
    local rtrim_only = string.trim(dirty_str, false, true)
    log.info("trim", "仅裁剪后缀:", "'" .. rtrim_only .. "'", "长度:", #rtrim_only)

    -- 方法调用形式
    local method_trimmed = dirty_str:trim()
    log.info("trim", "方法调用结果:", "'" .. method_trimmed .. "'")
end

-- ====================== 综合应用示例 ======================
local function comprehensive_example()
    log.info("=== 综合应用示例 ===")

    -- 模拟数据处理流程
    local data_packet = "user:john,age:25,city:new york"

    -- 1. 分割数据
    local pairs = string.split(data_packet, ",")
    log.info("综合示例", "分割后的键值对数量:", #pairs)

    -- 2. 处理每个键值对
    local user_data = {}
    for i, pair in ipairs(pairs) do
        local key_value = string.split(pair, ":")
        if #key_value == 2 then
            local key = string.trim(key_value[1])
            local value = string.trim(key_value[2])
            user_data[key] = value
            log.info("综合示例", "解析:", key, "=>", value)
        end
    end

    -- 3. 转换为JSON格式（Base64编码传输）
    local json_data = json.encode(user_data)
    local encoded_data = string.toBase64(json_data)
    log.info("综合示例", "Base64编码数据:", encoded_data)

    -- 4. 解码验证
    local decoded_json = string.fromBase64(encoded_data)
    log.info("综合示例", "解码验证:", decoded_json)
end

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

string 核心库没有常量。

四、函数详解

3.1 string.toHex(str, separator)

功能 将字符串转换为十六进制表示形式。

注意事项

• 转换后的 HEX 字符串为小写字母
• 分隔符不会影响返回的长度值

参数

str

参数含义：需要转换的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持二进制字符串
参数示例：string.toHex("\1\2\3")

separator

参数含义：分隔符
数据类型：string
取值范围：任意字符串
是否必选：否，默认为空字符串
注意事项：分隔符不会计入长度统计
参数示例：string.toHex("123abc", " ")

返回值

local hex_str, hex_len = string.toHex(str, separator)

有两个返回值，hex_str 和 hex_len；

hex_str

含义说明：HEX格式的字符串
数值类型：string
取值范围：转换后的HEX字符串
注意事项：字母为小写形式
返回值示例："010203"

hex_len

含义说明：HEX字符串的长度（不含分隔符）
数值类型：number
取值范围：≥0
注意事项：不包含分隔符的长度
返回值示例：6

示例

local str = "123abc"
local hex, len = string.toHex(str)
log.info("toHex", hex, len)  -- 输出: "313233616263" 12

local hex_spaced = string.toHex(str, " ")
log.info("toHex", hex_spaced)  -- 输出: "31 32 33 61 62 63"

3.2 string.fromHex(hex)

功能

将 HEX 字符串转换回原始字符串

注意事项

• 输入的 HEX 字符串应包含有效的十六进制字符；
• 自动忽略大小写；

参数

hex

参数含义：HEX格式的字符串
数据类型：string
取值范围：十六进制字符组成的字符串
是否必选：是
参数示例：string.fromHex("313233616263")

返回值

local original_str = string.fromHex(hex)

有一个返回值 str

str

含义说明：转换后的原始字符串；
数值类型：string；
取值范围：任意二进制数据；
注意事项：如果HEX字符串长度不是偶数，会出现错误；
返回值示例："\1\2\3"

示例

-- HEX解码
local str1 = string.fromHex("010203")
-- 输出: "\1\2\3"
log.info("fromHex", str1)

-- 字符串HEX解码
local str2 = string.fromHex("313233616263") 
-- 输出: "123abc"
log.info("fromHex", str2)

-- 带空格分隔符的HEX解码
local str3 = string.fromHex("31 32 33 61 62 63")
-- 输出: "123abc"  
log.info("fromHex", str3)

3.3 string.split(str, separator, keepEmpty)

功能

按照指定分隔符分割字符串

注意事项

• keepEmpty 参数需要 2023.4.11 之后固件支持
• 返回结果为 table 类型

参数

str

参数含义：输入字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持空字符串
参数示例：string.split("123,456,789", ",")

separator

参数含义：分隔符
数据类型：string
取值范围：任意字符串
是否必选：否，默认为","
注意事项：支持多字符分隔符
参数示例：string.split("a|b|c", "|")

keepEmpty

参数含义：是否保留空白片段
数据类型：boolean
取值范围：true/false
是否必选：否，默认为false
注意事项：2023.4.11之后固件可用
参数示例：string.split("/a//b/", "/", true)

返回值

local parts_table = string.split(str, separator, keepEmpty)

有一个返回值 parts_table；

parts_table

含义说明：分割后的字符串表
数值类型：table
取值范围：字符串数组
注意事项：table索引从1开始；
返回值示例：{"123", "456", "789"}

示例

-- 默认逗号分隔
local tmp1 = string.split("123,233333,122")
-- tmp1 = {"123", "233333", "122"}

-- 对象方法调用
local tmp2 = ("123,456,789"):split(',')
-- tmp2 = {'123','456','789'}

-- 保留空片段（2023.4.11之后固件）
local str = "/tmp//def/1234/"
local tmp3 = str:split("/", true)
-- tmp3 = {"", "tmp", "", "def", "1234", ""}

3.4 string.toValue(str)

功能

将字符串中的字符转换为对应的数值字节

参数

str

参数含义：输入字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：常用于数字字符串
参数示例：string.toValue("123456")

返回值

local binary_str, char_count = string.toValue(str)

有两个返回值，binary_str 和 char_count；

binary_str

含义说明：转换后的二进制字符串；
数值类型：string；
取值范围：字节值组成的二进制数据；
返回值示例："\1\2\3\4\5\6"

char_count

含义说明：成功转换的字符数量
数值类型：number
取值范围：≥0的整数
注意事项：实际处理的字符数
返回值示例：6

示例

-- 数字字符串转换
local bin1, count1 = string.toValue("123456")
-- 输出: "\1\2\3\4\5\6" 6
log.info("toValue", bin1, count1)

-- 字母数字混合
local bin2, count2 = string.toValue("123abc")
-- 输出: "\1\2\3\a\b\c" 6  
log.info("toValue", bin2, count2)

-- 验证转换
local hex_result = string.toHex(bin1)
log.info("toValue验证", "HEX表示:", hex_result)

3.5 string.urlEncode(str, mode)

功能

将字符串进行 URL 编码转换

注意事项

mode 参数指定 URL 编码标准

参数

str

参数含义：需要转换的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持中文等非ASCII字符
参数示例：string.urlEncode("123 abc")

mode

参数含义：URL编码的转换标准
数据类型：number
取值范围：0或不指定：默认模式，空格编码为 +，适用于表单数据编码
         1：严格模式，空格编码为 %20，符合 RFC 3986 标准
是否必选：否
注意事项：不同mode对应不同编码规则；
参数示例：string.urlEncode("test", 1)

返回值

local`` encoded_str = string.urlEncode(str, mode)

有一个返回值

encoded_str

含义说明：URL编码后的字符串；
数值类型：string；
取值范围：符合URL编码规范的字符串；
返回值示例："123%20abc"

示例

-- 基本URL编码
local encoded1 = string.urlEncode("123 abc")
-- encoded1 = "123%20abc"

-- 包含特殊字符
local encoded2 = string.urlEncode("a=b&c")
-- encoded2 = "a%3Db%26c"

-- 对象方法调用
local encoded3 = ("test url"):urlEncode()

3.6 string.toBase64(str)

功能

将字符串进行 Base64 编码

注意事项

• 编码结果不包含换行符
• 支持二进制数据编码

参数

str

参数含义：需要转换的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持二进制字符串
参数示例：string.toBase64("Hello")

返回值

local base64_str = string.toBase64(str)

有一个返回值 base64_str；

base64_str

含义说明：Base64编码后的字符串
数值类型：string
取值范围：Base64格式字符串
注意事项：解码失败返回空字符串
返回值示例："SGVsbG8="

示例

-- 普通字符串编码
local encoded1 = string.toBase64("Hello")
-- 返回: "SGVsbG8="
log.info("base64", encoded1)

-- 中文编码
local encoded2 = string.toBase64("你好世界")
-- 返回: "5L2g5aW95LiW55WM"
log.info("base64", encoded2)

-- 二进制数据编码
local bin_data = string.char(0x00, 0x01, 0x02, 0x03, 0x04)
local encoded3 = string.toBase64(bin_data)
-- 返回: "AAECAwQ="
log.info("base64", encoded3)

-- 空字符串
local encoded4 = string.toBase64("")
-- 返回: ""
log.info("base64", encoded4)

-- 特殊字符编码
local special_str = "abc123!@#$%^&*()"
local encoded5 = string.toBase64(special_str)
-- 返回: "YWJjMTIzIUAjJCVeJiooKQ=="
log.info("base64", encoded5)

3.7 string.fromBase64(str)

功能

将 Base64 字符串解码回原始数据

注意事项

• 自动处理 Base64 填充字符
• 支持 URL 安全的 Base64 变种

参数

str

参数含义：Base64编码的字符串
数据类型：string
取值范围：Base64格式字符串
是否必选：是
注意事项：可包含换行符
参数示例：string.fromBase64("SGVsbG8=")

返回值

local decoded_str = string.fromBase64(str)

有一个返回值 decoded_str；

decoded_str

含义说明：解码后的原始字符串
数值类型：string
取值范围：解码得到的字符串，失败返回空字符串；
注意事项：解码失败返回空字符串
返回值示例："Hello"

示例

-- Base64解码
local decoded1 = string.fromBase64("SGVsbG8=")
-- decoded1 = "Hello"

3.8 string.toBase32(str)

功能

将字符串进行 Base32 编码

注意事项

• Base32 编码结果比 Base64 更长
• 不包含填充字符

参数

str

参数含义：需要转换的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持二进制数据
参数示例：string.toBase32("test")

返回值

local base32_str = string.toBase32(str)

有一个返回值 base32_str；

base32_str

含义说明：Base32编码后的字符串
数值类型：string
取值范围：Base32格式字符串
注意事项：解码失败返回空字符串
返回值示例："ORSXG5A="

示例

-- 基本编码示例
local encoded1 = string.toBase32("Hello")
-- 返回: "JBSWY3DP"
log.info("toBase32", encoded1)

-- 中文编码示例
local encoded2 = string.toBase32("你好")
-- 返回: "4S62BZNFXU"
log.info("toBase32", encoded2)

3.9 string.fromBase32(str)

功能

将 Base32 字符串解码回原始数据

注意事项

• 支持标准 Base32 编码；
• 自动处理大小写；

参数

str

参数含义：Base32编码的字符串
数据类型：string
取值范围：Base32格式字符串
是否必选：是
注意事项：支持标准Base32字母表
参数示例：string.fromBase32("JBSWY3DP")

返回值

local decoded_str = string.fromBase32(str)

有一个返回值 decoded_str；

decoded_str

含义说明：解码后的原始字符串
数值类型：string
取值范围：解码后的二进制数据，失败返回空字符串；
注意事项：解码失败返回空字符串
返回值示例："test"

示例

-- Base32基本解码示例
local decoded1 = string.fromBase32("JBSWY3DP")
-- decoded1 = "Hello"
log.info("fromBase32", decoded1)

-- 长字符串解码示例
local decoded2 = string.fromBase32("JBSWY3DPEBLW64TMMQQQ")
-- 返回: "Hello World!"
log.info("fromBase32", decoded2)

3.10 string.startsWith(str, prefix)

功能

判断字符串是否以指定前缀开头

注意事项

• 区分大小写
• 如果 str 和 prefix 都是空字符串，总是返回 true
• 如果 str 或 prefix 其中任意一个不是空字符串，返回 false

参数

str

参数含义：需要检查的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持空字符串
参数示例：string.startsWith("abc", "a")

prefix

参数含义：前缀字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：当"str"和"prefix"都是空字符串，总是返回 true
参数示例：string.startsWith("abc", "ab")

返回值

local is_match = string.startsWith(str, prefix)

有一个返回值 result；

result

含义说明：匹配结果
数值类型：boolean
取值范围：true/false
注意事项：当"str"和"prefix"都是空字符串，总是返回true；
返回值示例：true

示例

local str = "abc"

-- 检查前缀
local result1 = string.startsWith(str, "a")
-- result1 = true

local result2 = string.startsWith(str, "b")
-- result2 = false

local result3 = string.startsWith(str, "")
-- result3 = false

3.11 string.endsWith(str, suffix)

功能

判断字符串是否以指定后缀结尾

注意事项

• 区分大小写
• 如果 str 和 suffix 都是空字符串，总是返回 true
• 如果 str 或 suffix 其中一个不是空字符串，返回 false

参数

str

参数含义：需要检查的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持空字符串
参数示例：string.endsWith("abc", "c")

suffix

参数含义：后缀字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：当"str"和"suffix"都是空字符串，总是返回true
参数示例：string.endsWith("abc", "bc")

返回值

local is_match = string.endsWith(str, suffix)

有一个返回值 result；

result

含义说明：匹配结果；
数值类型：bool；
取值范围：true-匹配，false-不匹配；
注意事项：当"str"和"suffix"都是空字符串，总是返回true；
返回值示例：true

示例

local str = "abc"

-- 检查后缀
local result1 = string.endsWith(str, "c")
-- result1 = true

local result2 = string.endsWith(str, "b")
-- result2 = false

-- 边界情况
local result3 = string.endsWith("", "abc")
-- result3 = false

local result4 = string.endsWith("", "")
-- result4 = true

local result5 = string.endsWith("abc", "")
-- result5 = false

-- 多字符情况
local result6 = string.endsWith("hello world", "world")
-- result6 = true

local result7 = string.endsWith("hello world", "hello")
-- result7 = false

3.12 string.trim(str, ltrim, rtrim)

功能

裁剪字符串，去除头尾的空白字符

注意事项

• 默认同时清理前缀和后缀
• 空白字符包括空格、制表符、换行符等

参数

str

参数含义：需要处理的字符串
数据类型：string
取值范围：任意字符串
是否必选：是
注意事项：支持包含控制字符的字符串
参数示例：string.trim("  abc  ")

ltrim

参数含义：是否清理前缀
数据类型：boolean
取值范围：true/false
是否必选：否，默认为true
注意事项：设为false可保留前缀空白
参数示例：string.trim(str, false, true)

rtrim

参数含义：是否清理后缀
数据类型：boolean
取值范围：true/false
是否必选：否，默认为true
注意事项：设为false可保留后缀空白
参数示例：string.trim(str, true, false)

返回值

local trimmed_str = string.trim(str, ltrim, rtrim)

有一个返回值 trimmed_str；

trimmed_str

含义说明：清理后的字符串
数值类型：string
取值范围：裁剪后的字符串
注意事项：原字符串不被修改
返回值示例："abc"

示例

local str = "\r\nabc\r\n"

-- 默认清理前后空白
local result1 = string.trim(str)
-- result1 = "abc"

-- 对象方法调用
local result2 = str:trim()
-- result2 = "abc"

-- 仅清理后缀空白
local result3 = string.trim(str, false, true)
-- result3 = "\r\nabc"，长度=5

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 string 核心库。