LFTK项目中的写缓冲(wbuffer)扩展函数详解

LFTK项目中的写缓冲(wbuffer)扩展函数详解

awtk 项目地址: https://gitcode.com/gh_mirrors/lf/lftk

什么是写缓冲(wbuffer)

写缓冲(wbuffer)是LFTK项目中提供的一种内存缓冲管理机制，主要用于高效地构建二进制数据。它类似于一个动态增长的字节数组，可以按顺序写入各种基本数据类型，并自动管理内存分配和指针位置。

wbuffer的核心属性

写缓冲对象包含三个关键属性：

1. data：指向实际缓冲区的指针
2. cursor：当前写入位置（偏移量）
3. capacity：缓冲区的最大容量

wbuffer函数详解

1. 创建wbuffer对象

wbuffer_create

创建一个新的空wbuffer对象。

var buffer = wbuffer_create();

wbuffer_attach

将wbuffer附加到现有数据上，支持三种形式：

// 附加到字符串
var buffer1 = wbuffer_attach("hello");

// 附加到二进制数据
var buffer2 = wbuffer_attach(binary_data);

// 附加到指定内存区域
var buffer3 = wbuffer_attach(data_ptr, size);

2. 指针操作函数

wbuffer_skip

跳过指定字节数，常用于预留空间。

var buffer = wbuffer_create();
wbuffer_skip(buffer, 4); // 跳过4字节

wbuffer_rewind

重置写入指针到起始位置。

var buffer = wbuffer_attach("data");
wbuffer_skip(buffer, 2);
wbuffer_rewind(buffer); // 指针回到0位置

3. 基本数据类型写入

wbuffer提供了一系列函数用于写入不同大小的数值类型：

无符号整数写入

// 写入1字节无符号整数
wbuffer_write_uint8(buffer, 0x10);

// 写入2字节无符号整数
wbuffer_write_uint16(buffer, 0x1122);

// 写入4字节无符号整数
wbuffer_write_uint32(buffer, 0x11223344);

// 写入8字节无符号整数
wbuffer_write_uint64(buffer, 0x1122334455667788);

有符号整数写入

// 写入1字节有符号整数
wbuffer_write_int8(buffer, -10);

// 写入2字节有符号整数
wbuffer_write_int16(buffer, -1122);

// 写入4字节有符号整数
wbuffer_write_int32(buffer, -11223344);

// 写入8字节有符号整数
wbuffer_write_int64(buffer, -1122334455667788);

浮点数写入

// 写入4字节浮点数
wbuffer_write_float(buffer, 3.14);

// 写入8字节双精度浮点数
wbuffer_write_double(buffer, 3.1415926535);

4. 字符串和二进制数据写入

字符串写入

wbuffer_write_string(buffer, "hello");

二进制数据写入

wbuffer_write_binary(buffer, "binary", 6); // 写入6字节二进制数据

5. 信息获取函数

// 获取缓冲区指针
var data_ptr = wbuffer_get_data(buffer);

// 获取当前写入位置
var pos = wbuffer_get_cursor(buffer);

// 获取缓冲区容量
var cap = wbuffer_get_capacity(buffer);

实际应用示例

下面是一个综合使用wbuffer的示例，展示了如何构建一个包含多种数据类型的二进制数据包：

// 创建缓冲区
var packet = wbuffer_create();

// 写入包头标识(4字节)
wbuffer_write_uint32(packet, 0xAA55AA55);

// 写入版本号(1字节)
wbuffer_write_uint8(packet, 1);

// 写入消息类型(1字节)
wbuffer_write_uint8(packet, 0x10);

// 预留2字节(用于后续填充长度)
wbuffer_skip(packet, 2);

// 写入用户名(字符串)
wbuffer_write_string(packet, "user123");

// 写入温度值(浮点数)
wbuffer_write_float(packet, 36.5);

// 回到长度位置写入实际数据长度
var len = wbuffer_get_cursor(packet) - 8;
wbuffer_rewind(packet);
wbuffer_skip(packet, 6); // 移动到长度字段
wbuffer_write_uint16(packet, len);

使用建议

1. 批量写入：大多数写入函数支持一次写入多个值，可以减少函数调用次数
2. 预留空间：使用wbuffer_skip预留空间，后续再填充实际数据
3. 内存管理：wbuffer会自动扩展容量，但大量数据写入时建议预估初始容量
4. 错误处理：检查写入函数的返回值，确保写入成功

wbuffer扩展为LFTK项目提供了强大的二进制数据处理能力，特别适合网络协议封装、文件格式处理等场景。通过合理使用这些函数，可以高效地构建复杂的二进制数据结构。

awtk 项目地址: https://gitcode.com/gh_mirrors/lf/lftk