【Lua示例】ASCII码转换

# AsciiConverter - ASCII 码转换模块

## 概述

`AsciiConverter` 是一个纯 Lua 实现的 ASCII 码转换模块，完全基于查表方式实现，不依赖 `string.char`/`string.byte`，兼容 VG3 视觉平台的 Lua 环境。

## 文件说明

| 文件 | 路径 | 说明 |
|------|------|------|
| `AsciiConverter.lua` | `D:\VisionGroup3\lua\AsciiConverter.lua` | 模块主文件，`dofile("lua/AsciiConverter.lua")` 加载 |
| `AsciiConverter_demo.lua` | `D:\VisionGroup3\lua\AsciiConverter_demo.lua` | 完整使用案例 |

---

## 函数列表

| 函数 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `CharToAscii(char)` | `char`: 单个字符 | `int` | 字符转 ASCII 码值，无效返回 -1 |
| `AsciiToChar(code)` | `code`: ASCII 码值 0-127 | `string` | ASCII 码值转字符，无效返回 `""` |
| `StringToAsciiArray(str)` | `str`: 源字符串 | `table` | 字符串逐字符转 ASCII 码值数组（Lua table） |
| `AsciiArrayToString(arr)` | `arr`: ASCII 码值数组（Lua table） | `string` | ASCII 码值数组拼接回字符串 |
| `StringToAsciiStr(str, sep?)` | `str`: 源字符串, `sep`: 分隔符（默认空格） | `string` | 字符串转 ASCII 码值字符串，如 `"72 53 51"` |
| `StringToHexStr(str, sep?)` | `str`: 源字符串, `sep`: 分隔符（默认无） | `string` | 字符串转十六进制字符串，如 `"48 35 33"` |
| `HexStrToString(hexStr)` | `hexStr`: 十六进制字符串（空格分隔） | `string` | 十六进制字符串解析回原文 |
| `IsPrintable(char)` | `char`: 单个字符 | `bool` | 判断是否为可打印 ASCII 字符（32-126） |
| `GetAsciiTable()` | 无 | `table` | 获取完整 ASCII 查表 |

---

## ASCII 编码速查

| 范围 | 类别 | 包含 |
|------|------|------|
| 0-31 | 控制字符 | NUL, SOH, STX, ... |
| 32 | 空格 | SPACE |
| 33-47 | 符号 | `! " # $ % & ' ( ) * + , - . /` |
| 48-57 | 数字 | `0 1 2 3 4 5 6 7 8 9` |
| 58-64 | 符号 | `: ; < = > ? @` |
| 65-90 | 大写字母 | `A B C ... Z` |
| 91-96 | 符号 | `[ \ ] ^ _ \`` |
| 97-122 | 小写字母 | `a b c ... z` |
| 123-126 | 符号 | `{ \| } ~` |
| 127 | 控制字符 | DEL |

**常用 ASCII 码值：**

| 字符 | 十进制 | 十六进制 |
|------|--------|----------|
| `'0'` | 48 | 0x30 |
| `'1'` | 49 | 0x31 |
| `'A'` | 65 | 0x41 |
| `'B'` | 66 | 0x42 |
| `'H'` | 72 | 0x48 |
| `'a'` | 97 | 0x61 |
| `'#'` | 35 | 0x23 |
| `断尾` | 13 | 0x0D |
| `断头` | 10 | 0x0A |
| 空格 | 32 | 0x20 |

---

## 使用示例

### 加载模块

```lua
dofile("lua/AsciiConverter.lua")
```

### 字符 ↔ ASCII 码值

```lua
local code = AsciiConverter:CharToAscii("H")     -- 72  (0x48)
local code = AsciiConverter:CharToAscii("3")     -- 51  (0x33)
local code = AsciiConverter:CharToAscii("#")     -- 35  (0x23)

local char = AsciiConverter:AsciiToChar(72)       -- "H"
local char = AsciiConverter:AsciiToChar(51)       -- "3"
```

### 字符串 → 十六进制

```lua
-- 无分隔符
local hex = AsciiConverter:StringToHexStr("Hello", "")
-- "48656C6C6F"

-- 空格分隔（协议帧格式）
local hex = AsciiConverter:StringToHexStr("AB", " ")
-- "41 42"
```

### 十六进制 → 字符串（协议帧解析）

```lua
local hex = "48 35 33 42 33 36 33 30 38 33 39 41 58"
local str = AsciiConverter:HexStrToString(hex)
-- "H53B3630839AX"
```

### 配合 RemoveHeadTail 解析完整协议帧

```lua
-- 完整帧（空格分隔的十六进制）
local frameHex = "02 01 30 30 30 30 23 53 43 4e 54 52 47 31 06 3b 03 48 35 33 42 33 36 33 30 38 33 39 41 58 23 44 47 44 35 30 23 32 35 31 32 32 34 34 30 38 31 38 33 0d"

-- 帧头和帧尾
local headHex = "02 01 30 30 30 30 23 53 43 4e 54 52 47 31 06 3b 03"
local tailHex = "0d"

-- 去掉头尾，提取有效载荷
local payloadHex = LuaString:RemoveHeadTail(frameHex, headHex, tailHex)

-- 十六进制 → 可读字符串
local text = AsciiConverter:HexStrToString(payloadHex)
-- "H53B3630839AX#DGD50#251224408183"
```

### HexStr 转 Ascii 码值字符串

```lua
local hex = "48 35 33"
local arr = LuaString:Split(hex, " ")
-- 用 AsciiConverter:HexStrToString 直接转字符串
local str = AsciiConverter:HexStrToString(hex)
-- 再用 StringToAsciiStr 转 ASCII 码值
local asciiStr = AsciiConverter:StringToAsciiStr(str, " ")
-- "72 53 51"
```

### 完整的编码解码验证

```lua
local str = "H53B3630839AX#DGD50#251224408183"

-- 编码 → hex
local hex = AsciiConverter:StringToHexStr(str, " ")

-- 解码 → 原文
local decoded = AsciiConverter:HexStrToString(hex)

-- 验证
LuaLog:Debug(tostring(str == decoded))  -- true
```

---

## 模块源码

```lua
-- AsciiConverter - ASCII code conversion module
-- Table-based lookup, no dependency on string.char/string.byte

local AsciiConverter = {}

local asciiToChar = {
    [32] = " ",  [33] = "!",  [34] = "\"", [35] = "#",  [36] = "$",
    [37] = "%",  [38] = "&",  [39] = "'",  [40] = "(",  [41] = ")",
    [42] = "*",  [43] = "+",  [44] = ",",  [45] = "-",  [46] = ".",
    [47] = "/",  [48] = "0",  [49] = "1",  [50] = "2",  [51] = "3",
    [52] = "4",  [53] = "5",  [54] = "6",  [55] = "7",  [56] = "8",
    [57] = "9",  [58] = ":",  [59] = ";",  [60] = "<",  [61] = "=",
    [62] = ">",  [63] = "?",  [64] = "@",  [65] = "A",  [66] = "B",
    [67] = "C",  [68] = "D",  [69] = "E",  [70] = "F",  [71] = "G",
    [72] = "H",  [73] = "I",  [74] = "J",  [75] = "K",  [76] = "L",
    [77] = "M",  [78] = "N",  [79] = "O",  [80] = "P",  [81] = "Q",
    [82] = "R",  [83] = "S",  [84] = "T",  [85] = "U",  [86] = "V",
    [87] = "W",  [88] = "X",  [89] = "Y",  [90] = "Z",  [91] = "[",
    [92] = "\\", [93] = "]",  [94] = "^",  [95] = "_",  [96] = "`",
    [97] = "a",  [98] = "b",  [99] = "c",  [100] = "d", [101] = "e",
    [102] = "f", [103] = "g", [104] = "h", [105] = "i", [106] = "j",
    [107] = "k", [108] = "l", [109] = "m", [110] = "n", [111] = "o",
    [112] = "p", [113] = "q", [114] = "r", [115] = "s", [116] = "t",
    [117] = "u", [118] = "v", [119] = "w", [120] = "x", [121] = "y",
    [122] = "z", [123] = "{", [124] = "|", [125] = "}", [126] = "~",
    [127] = "",
}

local charToAscii = {}
for code, char in pairs(asciiToChar) do
    if char ~= "" then
        charToAscii[char] = code
    end
end

local hexDigitVal = {}
for code = 48, 57 do hexDigitVal[asciiToChar[code]] = code - 48 end
for code = 65, 70 do hexDigitVal[asciiToChar[code]] = code - 55 end

function AsciiConverter:CharToAscii(char)
    return charToAscii[char] or -1
end

function AsciiConverter:AsciiToChar(code)
    return asciiToChar[code] or ""
end

function AsciiConverter:StringToAsciiArray(str)
    local len = LuaString:Length(str)
    local result = {}
    for i = 0, len - 1 do
        local ch = LuaString:MidLenght(str, i, 1)
        result[i + 1] = charToAscii[ch] or -1
    end
    return result
end

function AsciiConverter:AsciiArrayToString(arr)
    local result = ""
    for i = 1, #arr do
        result = result .. (asciiToChar[arr[i]] or "")
    end
    return result
end

function AsciiConverter:StringToAsciiStr(str, sep)
    if sep == nil then sep = " " end
    local len = LuaString:Length(str)
    local result = ""
    for i = 0, len - 1 do
        if i > 0 then result = result .. sep end
        local code = charToAscii[LuaString:MidLenght(str, i, 1)] or -1
        result = result .. LuaString:FromLong(code)
    end
    return result
end

function AsciiConverter:StringToHexStr(str, sep)
    if sep == nil then sep = "" end
    local len = LuaString:Length(str)
    local result = ""
    for i = 0, len - 1 do
        if i > 0 then result = result .. sep end
        local code = charToAscii[LuaString:MidLenght(str, i, 1)] or 0
        result = result .. string.format("%02X", code)
    end
    return result
end

function AsciiConverter:HexStrToString(hexStr)
    local clean = LuaString:Remove(hexStr, " ")
    local len = LuaString:Length(clean)
    if len % 2 ~= 0 then return "" end
    local result = ""
    for i = 0, len - 1, 2 do
        local high = hexDigitVal[LuaString:MidLenght(clean, i, 1)] or 0
        local low  = hexDigitVal[LuaString:MidLenght(clean, i + 1, 1)] or 0
        result = result .. (asciiToChar[high * 16 + low] or "")
    end
    return result
end

function AsciiConverter:IsPrintable(char)
    local code = charToAscii[char]
    return code ~= nil and code >= 32 and code <= 126
end

function AsciiConverter:GetAsciiTable()
    return { charToAscii = charToAscii, asciiToChar = asciiToChar }
end

_G.AsciiConverter = AsciiConverter
return AsciiConverter
```

---

## 注意事项

1. **加载方式**：使用 `dofile("lua/AsciiConverter.lua")` 加载，模块会自动注入全局变量 `AsciiConverter`
2. **API 依赖**：内部使用了 VG3 平台的 `LuaString:Length`、`LuaString:MidLenght`、`LuaString:FromLong`、`LuaString:Remove`，必须在 VG3 环境中运行
3. **索引从 0 开始**：字符串索引遵循 VG3 约定，从 0 开始
4. **编码**：模块文件已去除中文注释，使用纯 ASCII 编码，避免 VG3 Lua 解析器编码处理问题
5. **不依赖标准库**：模块完全不使用 `string.char`/`string.byte`，所有转换均通过查表实现，兼容性更好

---

[【附件】AsciiConverter.zip](/media/attachment/2026/05/AsciiConverter.zip)
*文档版本：v1.0*
*适用平台：准易科技 VisionGroup 3 (VG3)*