【Lua示例】单字节字符串拆分归类

# 字符串分类（Char Classifier）

## 概述

一个基于 VG3 Lua API 的轻量级字符串分类工具。将输入字符串中的每个不同字符分别归类，相同字符合并为累积字符串，并支持按长度排序、单字符查询与存在性判断。

专为 NASI 单字节环境设计，覆盖全部 ASCII 字符（数字、大小写西文字母、常用英文字符）。

---
## 技术说明

- **环境**：NASI 单字节，VG3 Lua Runtime
- **依赖**：仅使用 `LuaString` API（`Length`, `MidLenght`, `Append`, `ToByteArray`, `FromLong`）
- **排序**：冒泡排序，稳定可靠
- **边界**：空字符串安全返回空表；符号自动转为 ASCII 码命名

---

*VG3 Lua API · Char Classifier*
---

## 函数列表

### 1. `Classify(inputStr)`

全部分类。遍历输入字符串每个字符，相同字符合并。

```
参数:  inputStr (string)  要分类的原始字符串
返回:  classMap   (table)  变量名 → 累积字符串
      classOrder (table)  变量名顺序数组（按首次出现）
```

**示例：**

```lua
local map, order = Classify("1A2B1")

-- map["str_1"] = "11"
-- map["str_A"] = "A"
-- map["str_2"] = "2"
-- map["str_B"] = "B"
```

---

### 2. `GetClass(classMap, ch)`

快速取出某个字符的分类字符串。

```
参数:  classMap (table)  由 Classify 返回
      ch       (string)  目标字符
返回:  string            该字符的累积字符串，不存在则返回 ""
```

**示例：**

```lua
local val = GetClass(map, "A")   -- "A"
local val = GetClass(map, "Z")   -- ""
```

---

### 3. `HasClass(classMap, ch)`

判断某个字符是否在分类中存在。适用于指令字符匹配等场景。

```
参数:  classMap (table)  由 Classify 返回
      ch       (string)  目标字符
返回:  boolean           存在=true，不存在=false
```

**示例：**

```lua
if HasClass(map, "X") then
    -- 执行特定指令
end
```

---

### 4. `GetTopN(classMap, classOrder, n)`

按累积字符串长度降序排列，提取前 N 个。

```
参数:  classMap   (table)  由 Classify 返回
      classOrder (table)  由 Classify 返回
      n          (number) 取前几个
返回:  topNames   (table)  变量名数组
      topValues  (table)  累积字符串数组
```

**示例：**

```lua
local topNames, topValues = GetTopN(map, order, 5)

for i = 1, #topNames do
    print(topNames[i] .. " = " .. topValues[i])
end
```

---

## 运行实例

输入字符串：`12345652145ADBD2154`

```
输入: 12345652145ADBD2154

--- 全部类 ---
  str_1 = "111" (3个)
  str_2 = "222" (3个)
  str_3 = "33" (2个)
  str_4 = "44" (2个)
  str_5 = "555" (3个)
  str_6 = "6" (1个)
  str_A = "A" (1个)
  str_D = "DD" (2个)
  str_B = "B" (1个)

--- 长度排序 前5 ---
  [1] str_1 = "111" (3个)
  [2] str_2 = "222" (3个)
  [3] str_5 = "555" (3个)
  [4] str_3 = "33" (2个)
  [5] str_4 = "44" (2个)
```

---

## 变量名命名规则

| 字符类型 | 命名格式 | 示例 |
|---------|---------|------|
| 数字 `0-9` | `str_<字符>` | `str_1`, `str_5` |
| 大写字母 `A-Z` | `str_<字符>` | `str_A`, `str_Z` |
| 小写字母 `a-z` | `str_<字符>` | `str_a`, `str_z` |
| 常用符号 `, . ! @`等 | `str_X_<ASCII码>` | `str_X_44`（逗号） |

---

## 实战场景

### 场景一：指令匹配

```lua
local cmdStr = "A12B34C"
local map, order = Classify(cmdStr)

-- 判断是否存在指令字符
if HasClass(map, "A") then
    local parts = GetClass(map, "A")
    -- 执行 A 指令逻辑
end
```

### 场景二：数据分析

```lua
local scanData = "D1A2D3B1A1D2A4"
local map, order = Classify(scanData)

-- 看哪些字符出现最频繁
local topNames, topValues = GetTopN(map, order, 5)
for i = 1, #topNames do
    LuaLog:Debug(topNames[i] .. " 出现了 " ..
        LuaString:Length(topValues[i]) .. " 次")
end
```

---
## 完整代码

```
--[[
    VG3 Lua - 字符串分类
    
    功能：
      1. Classify(inputStr)
         → 返回 classMap（变量名→字符串）, classOrder（顺序）
      
      2. GetClass(classMap, ch)
         → 快速取出某个字符的累积字符串
      
      3. HasClass(classMap, ch)
         → 判断某个字符是否在分类中存在，返回 true/false
      
      4. GetTopN(classMap, classOrder, n)
         → 按字符串长度降序排序，返回前 n 个

示例：
      map, order = Classify("1A2B1")
      HasClass(map, "A")   → true
      HasClass(map, "Z")   → false
      GetClass(map, "A")   → "A"
      GetTopN(map, order, 2)
]]

--====================================================
-- 工具函数：变量名生成
--====================================================
local function GetVarName(ch)
    -- 取单字节 ASCII 码
    local code = string.byte(ch)

-- 字母或数字：str_<字符>
    if (code >= 48 and code <= 57) or
       (code >= 65 and code <= 90) or
       (code >= 97 and code <= 122) then
        return "str_" .. ch
    end

-- 符号/其他：str_X_<ASCII码>
    return "str_X_" .. tostring(code)
end

--====================================================
-- 函数1：全部分类
--====================================================
local function Classify(inputStr)
    local classMap = {}
    local classOrder = {}

local len = LuaString:Length(inputStr)
    if len == 0 then
        return classMap, classOrder
    end

for i = 1, len do
        local ch = LuaString:MidLenght(inputStr, i - 1, 1)
        local varName = GetVarName(ch)

if classMap[varName] == nil then
            classMap[varName] = ch
            classOrder[#classOrder + 1] = varName
        else
            classMap[varName] = LuaString:Append(classMap[varName], ch)
        end
    end

return classMap, classOrder
end

--====================================================
-- 函数2：取出某个字符的分类
--====================================================
local function GetClass(classMap, ch)
    local varName = GetVarName(ch)
    return classMap[varName] or ""
end

--====================================================
-- 函数3：判断字符是否在分类中存在
--====================================================
local function HasClass(classMap, ch)
    local varName = GetVarName(ch)
    if classMap[varName] ~= nil then
        return true
    end
    return false
end

--====================================================
-- 核心函数4：按长度排序，取前N
--====================================================
local function GetTopN(classMap, classOrder, n)
    -- 构建可排序的数组：{name, value, length}
    local items = {}
    for _, varName in ipairs(classOrder) do
        local val = classMap[varName]
        items[#items + 1] = {
            name = varName,
            value = val,
            length = LuaString:Length(val)
        }
    end

-- 冒泡排序（降序，按长度）
    local total = #items
    for i = 1, total - 1 do
        for j = 1, total - i do
            if items[j].length < items[j + 1].length then
                local tmp = items[j]
                items[j] = items[j + 1]
                items[j + 1] = tmp
            end
        end
    end

-- 取前 n
    local topNames = {}
    local topValues = {}
    local limit = n
    if limit > total then limit = total end

for i = 1, limit do
        topNames[i] = items[i].name
        topValues[i] = items[i].value
    end

return topNames, topValues
end

--====================================================
-- 主程序入口
--====================================================
local inputStr = "12345652145ADBD2154"

LuaLog:Debug("============================================")
LuaLog:Debug("   字符串分类")
LuaLog:Debug("============================================")
LuaLog:Debug("输入: " .. inputStr)
LuaLog:Debug("")

-- 1. 全部分类
local classMap, classOrder = Classify(inputStr)

LuaLog:Debug("--- 全部类 ---")
for _, varName in ipairs(classOrder) do
    LuaLog:Debug(string.format("  %s = \"%s\" (%d个)",
        varName, classMap[varName], LuaString:Length(classMap[varName])))
end

LuaLog:Debug("")

-- 2. 取出单个 / 判断是否存在
local chA = GetClass(classMap, "A")
LuaLog:Debug(string.format("取'A': \"%s\"", chA))
LuaLog:Debug(string.format("是否存在'Z': %s", HasClass(classMap, "Z")))
LuaLog:Debug(string.format("是否存在'A': %s", HasClass(classMap, "A")))
LuaLog:Debug("")

-- 3. 按长度排序取前5
LuaLog:Debug("--- 长度排序 前5 ---")
local topNames, topValues = GetTopN(classMap, classOrder, 5)

for i = 1, #topNames do
    LuaLog:Debug(string.format("  [%d] %s = \"%s\" (%d个)",
        i, topNames[i], topValues[i], LuaString:Length(topValues[i])))
end

LuaLog:Debug("")
LuaLog:Debug("=== 完成 ===")

-- 简洁输出
print("--- TOP5 ---")
for i = 1, #topNames do
    print(string.format("[%d] %s = %s", i, topNames[i], topValues[i]))
end

```