C语言内存数组(zbuff)
一、ZBUFF(C 内存数组)简介
zbuff 库可以用 c 风格直接操作(下标从 0 开始)，例如 buff[0] = buff[3]
可以在 sram 上或者 psram 上申请空间，也可以自动申请(如存在 psram 则在 psram 进行申请,如不存在或失败则在 sram 进行申请)。
操作里面的元素时，可以根据 光标进行增删改查。偏移方式有三种：从头、当前位置、末尾开始。常用参数如下：
| 常量 | 类型 | 解释 |
|---|---|---|
| zbuff.SEEK_SET | number | 以头为基点 |
| zbuff.SEEK_CUR | number | 以当前位置为基点 |
| zbuff.SEEK_END | number | 以末尾为基点 |
| zbuff.HEAP_AUTO | number | 自动申请(如存在 psram 则在 psram 进行申请,如不存在或失败则在 sram 进行申请) |
| zbuff.HEAP_SRAM | number | 在 sram 申请 |
| zbuff.HEAP_PSRAM | number | 在 psram 申请 |
二、演示功能概述
本 demo 将演示 ZBUFF 的创建、写入数据、读取数据、获取 zbuff 长度、获取光标位置。
三、准备硬件环境
3.1 Air700ECQ 开发板
使用 Air700ECQ 开发板，如下图所示：
淘宝购买链接：Air700ECQ 开发板淘宝购买链接 ；
此开发板的详细使用说明参考：Air700ECQ 产品手册 中的 《开发板EVB-Air700ECQ-IO使用手册VX.X.X.pdf》，写这篇文章时最新版本的使用说明为：开发板EVB-Air700ECQ-IO使用手册V1.0.0.pdf ；开发板使用过程中遇到任何问题，可以直接参考这份使用说明 pdf 文档。
3.2 SIM 卡
请准备一张可正常上网的 SIM 卡，该卡可以是物联网卡或您的个人手机卡。
特别提醒：请确保 SIM 卡未欠费且网络功能正常，以便顺利进行后续操作。
3.3 数据通信线
typec 接口 USB 数据线即可。
3.4 PC 电脑
WIN10以及以上版本的WINDOWS系统。
四、准备软件环境
4.1 基本的下载调试工具
使用说明参考：Luatools 下载和详细使用 ；
五、ZBUFF 操作软硬件资料
5.1 文档和工具：
- Air700ECQ 模块使用固件：SDK& Demo - 合宙文档中心，本 demo 使用的固件版本是：LuatOS-SoC_V2001_Air700ECQ.soc
- 本教程使用的 demo：https://gitee.com/openLuat/LuatOS-Air700ECQ/tree/master/demo/zbuff
- 将固件和脚本烧录到模块中：Luatools 下载和使用教程 - 合宙模组资料中心
- 源码和固件已打包，如下所示： 点我,下载完整压缩文件包
- zbuff-全部api地址，如果只看本demo的api直接看下面的
5.2 demo使用api介绍即可。
5.2 demo使用api介绍
zbuff.create(length, data, type)
作用：创建 zbuff。
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| length | int | 字节数 |
| data | any | 可选参数，number 时为填充数据，string 时为填充字符串 |
| type | number | 可选参数，内存类型。可选值：zbuff.HEAP_SRAM（内部 sram，默认），zbuff.HEAP_PSRAM（外部 psram），zbuff.HEAP_AUTO（自动申请内存） |
返回值
| 返回值类型 | 解释 |
|---|---|
| object | zbuff 对象，创建失败返回 nil |
buff:write(para,…)
作用：zbuff 写数据（从当前指针位置开始；执行后指针会向后移动）。
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| para | any | 写入 buff 的数据。string 时为一个参数，number 时可为多个参数 |
返回值
| 返回值类型 | 解释 |
|---|---|
| number | 数据成功写入的长度 |
buff:read(length)
作用：zbuff 读数据（从当前指针位置开始；执行后指针会向后移动）
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| length | int | 读取 buff 中的字节数 |
返回值
| 返回值类型 | 解释 |
|---|---|
| string | 读取结果 |
buff:clear(num)
作用：zbuff 清空数据（与当前指针位置无关；执行后指针位置不变）
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| num | int | 可选，默认为 0。要设置的值，不会改变指针位置 |
返回值
无
buff:seek(base, offset)
作用：zbuff 设置光标位置（可能与当前指针位置有关；执行后指针会被设置到指定位置）
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| offset | int | 偏移长度 |
| base | int | 基点，默认 zbuff.SEEK_SET。可选值：zbuff.SEEK_SET（文件开头），zbuff.SEEK_CUR（当前位置），zbuff.SEEK_END（文件尾） |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 设置光标后从 buff 开头计算起的位置 |
buff:pack(format, val1, val2,…)
作用：将一系列数据按照格式字符转化，并写入（从当前指针位置开始；执行后指针会向后移动）
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| format | string | 后面数据的格式（符号含义见示例） |
| val | val | 传入的数据，可以为多个数据 |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 成功写入的数据长度 |
例子：
buff:pack(">IIHA", 0x1234, 0x4567, 0x12,"abcdefg") -- 按格式写入几个数据
-- A string
-- f float
-- d double
-- n Lua number
-- c char
-- b byte / unsignen char
-- h short
-- H unsigned short
-- i int
-- I unsigned int
-- l long
-- L unsigned long
-- < 小端
-- > 大端
-- = 默认大小端
buff:unpack(format)
作用：将一系列数据按照格式字符读取出来（从当前指针位置开始；执行后指针会向后移动）
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| format | string | 数据的格式（符号含义见 pack 示例） |
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 成功读取的数据字节长度 |
| any | 按格式读取的数据 |
buff:read 类型()
作用：读取一个指定类型的数据（从当前指针位置开始；执行后指针会向后移动）
参数
类型可为：（前缀I指有符号位，U指无符号位，后面的数字指有几位）I8、U8、I16、U16、I32、U32、I64、U64。
（浮点数）F32、F64
返回值
| 返回值类型 | 解释 |
|---|---|
| number | 读取的数据，越界则为 nil |
例如:
local data = buff:readI8()
local data = buff:readU32()
buff:write 类型(data)
作用：写入一个指定类型的数据（从当前指针位置开始；执行后指针会向后移动）
参数
| 参数 | 传入值类型 | 解释 |
|---|---|---|
| data | number | 待写入的数据 |
写入类型，可为：（前缀I指有符号位，U指无符号位，后面的数字指有几位）I8、U8、I16、U16、I32、U32、I64、U64。
（浮点数）F32、F64
返回值
| 返回值类型 | 解释 |
|---|---|
| number | 成功写入的长度 |
例如:
local len = buff:writeI8(10)
local len = buff:writeU32(1024)
buff:len()
作用：获取 zbuff 对象的长度（与当前指针位置无关；执行后指针位置不变）
参数
无
返回值
| 返回值类型 | 解释 |
|---|---|
| int | zbuff 对象的长度 |
buff:used()
作用：获取 zbuff 中最后一个数据位置指针到首地址的偏移量，表示 zbuff 内已有有效数据量大小。注意，此值不同于分配的空间大小，seek() 会改变最后一个数据位置指针，也会影响 used() 的返回值。
参数
无
返回值
| 返回值类型 | 解释 |
|---|---|
| int | 有效数据量大小 |
六、代码示例介绍
6.1 zbuff 操作示例
6.1.1 创建 zbuff，以 c 语言数组的形式操作 zbuff
local buff = zbuff.create(1024)
-- 可当成数组直接赋值和取值
buff[0] = 0xAE
log.info("zbuff", "buff[0]", buff[0])
6.1.2 以 io 的形式操作
-- 写数据write, 操作之后指针会移动,跟文件句柄一样
buff:write("123") -- 字符串
buff:write(0x12, 0x13, 0x13, 0x33) -- 直接写数值也可以
-- 设置指针位置, seek
buff:seek(5, zbuff.SEEK_CUR) -- 指针位置+5
-- 指针位置设置为0
buff:seek(0) -- 绝对地址
-- 读数据read, 指针也会移动
-- 读取前三个字节，即"123"
local data = buff:read(3)
log.info("zbuff", "data", data)
6.1.3 清除 zbuff
-- 清除全部数据,但指针位置不变
buff:clear() -- 默认填0
buff:clear(0xA5) -- 也可以指定填充的内容
6.1.4 以 pack 库的形式写入或读取数据
-- 支持以pack库的形式写入或读取数据
buff:seek(0)
buff:pack(">IIHA", 0x1234, 0x4567, 0x12,"abcdefg")
buff:seek(0)
local cnt,a,b,c,s = buff:unpack(">IIHA10")
6.1.5 按类型读写数据
读取类型可为：I8、U8、I16、U16、I32、U32、I64、U64、F32、F64
读取的时候，记得注意下标位置。
-- 也可以直接按类型读写数据
local len = buff:writeI8(10)
local len = buff:writeU32(1024)
local i8data = buff:readI8()
local u32data = buff:readU32()
6.1.6 取出指定区间的数据
-- 取出指定区间的数据
local fz = buff:toStr(0,5)
6.1.7 获取创建的 zbuff 的长度，和指针当前位置
-- 获取其长度
log.info("zbuff", "len", buff:len())
-- 获取其指针位置
log.info("zbuff", "len", buff:used())
6.1.8 测试 F32（32 位单精度浮点数）类型数据的读写
-- 测试writeF32, 注意, EC618系列(Air780E等), V1106会死机, 在V1107修复
buff:seek(0, zbuff.SEEK_SET)
buff:writeF32(1.2)
buff:seek(0, zbuff.SEEK_SET)
log.info("buff", "rw", "f32", buff:readF32())
七、功能验证
测试 zbuff 的使用
八、总结
本示例介绍了 zbuff 的作用和用法。
扩展
常见问题
1、先 buff:write(0x12)，再设置光标到正确位置后，使用 buff:read(1)读取不到数据。
直接读取是不可见字符，要使用 buff:read(1):toHex()读取数据。
<!-- ## 给读者的话
本篇文章由
Linden开发；本篇文章描述的内容，如果有错误、细节缺失、细节不清晰或者其他任何问题，总之就是无法解决您遇到的问题；
请登录合宙技术交流论坛，点击文档找错赢奖金-Air700ECQ-LuatOS-软件指南-通用工具库-C语言内存数组(zbuff)；
用截图标注+文字描述的方式跟帖回复，记录清楚您发现的问题；
我们会迅速核实并且修改文档；
同时也会为您累计找错积分，您还可能赢取月度找错奖金！ -->