nv-facutil-ta-base

一个高效的 JavaScript 工具库，用于按块管理 ArrayBuffer 和类型化数组（TypedArray）操作。

简介

nv-facutil-ta-base 提供了一个 TaBase 类，用于将 ArrayBuffer 分割成等大小的块，并提供各种方法来操作这些块中的不同类型数据。这个工具在处理大型二进制数据、内存优化和数据结构管理方面非常有用。

特性

- 将 ArrayBuffer 分割成固定大小的块
- 支持所有标准 JavaScript 类型化数组：Uint8Array, Int8Array, Uint16Array, Int16Array, Uint32Array, Int32Array, Float32Array, BigUint64Array, BigInt64Array, Float64Array
- 提供安全的数据访问和写入方法
- 内置边界检查，防止数据溢出
- 高效的内存管理

安装

$3

``bash
npm install nv-facutil-ta-base
`

$3

`javascript
const taBaseCreator = require('path/to/nv-facutil-ta-base');
`

基本用法

`javascript
// 创建一个 ArrayBuffer
const bufferSize = 1024; // 1KB
const chunkSize = 64; // 每个块 64 字节 (必须是 16 的倍数且大于 16)
const ab = new ArrayBuffer(bufferSize);

// 创建 TaBase 实例
const taBase = taBaseCreator(ab, chunkSize);

// 获取块数量
console.log(块数量: ${taBase.chunk_cnt}); // 输出: 块数量: 16

// 写入 Uint8 数据
taBase.set_u8a_unit_of_chunk(0, 0, 65); // 在第一个块的第一个位置写入 'A' (ASCII 65)

// 写入 Uint16 数据
taBase.set_u16a_unit_of_chunk(1, 0, 1000);

// 写入 Float32 数据
taBase.set_f32a_unit_of_chunk(2, 0, 3.14159);

// 写入一组字节
const bytes = new Uint8Array([72, 101, 108, 108, 111]); // "Hello" 的 ASCII 码
taBase.set_byts(3, 0, bytes);
`

API 参考

$3

`javascript
/**
* 创建一个 TaBase 实例
* @param {ArrayBuffer} array_buf - 要分块管理的原始 ArrayBuffer
* @param {number} chunksz - 每个块的字节大小，必须是16的倍数且大于16
* @throws {Error} 当参数不满足要求时抛出错误
*/
const taBase = taBaseCreator(array_buf, chunksz);
`

$3

- chunksz: 每个块的字节大小
- chunk_cnt: 块的总数量（只读）

$3

#### 获取块偏移量

`javascript
/**
* 获取指定块ID的字节偏移量
* @param {number} id - 块的ID (从0开始)
* @returns {number} 该块在 ArrayBuffer 中的字节偏移量
*/
taBase.get_offset(id);
`

#### 获取单元索引

`javascript
/**
* 计算指定块中特定类型单元的索引
* @param {number} id - 块的ID (从0开始)
* @param {number} sz - 数据单元的字节大小 (如: 1表示8位, 2表示16位, 4表示32位, 8表示64位)
* @param {number} relative_idx - 在当前块内的相对索引
* @returns {number} 指定数据单元在对应类型化数组中的绝对索引
*/
taBase.get_unit_idx_of_chunk(id, sz, relative_idx);
`

#### 获取单元偏移量

`javascript
/**
* 计算指定块中特定类型单元的字节偏移量
* @param {number} id - 块的ID (从0开始)
* @param {number} sz - 数据单元的字节大小
* @param {number} relative_idx - 在当前块内的相对索引
* @returns {number} 指定数据单元在 ArrayBuffer 中的字节偏移量
*/
taBase.get_unit_offset_of_chunk(id, sz, relative_idx);
`

#### 写入字节数组

`javascript
/**
* 将一个 Uint8Array 写入指定块的指定偏移位置
* @param {number} id - 块的ID
* @param {number} relative_offset - 在当前块内的相对字节偏移量
* @param {Uint8Array} u8a - 要写入的字节数组
* @returns {boolean} 写入是否成功，如果超出块边界则返回false
*/
taBase.set_byts(id, relative_offset, u8a);
`

$3

对于每种类型的数组，TaBase 提供了相应的写入方法：

- set_u8a_unit_of_chunk(id, relative_idx, val): 写入 8 位无符号整数
- set_i8a_unit_of_chunk(id, relative_idx, val): 写入 8 位有符号整数
- set_u16a_unit_of_chunk(id, relative_idx, val): 写入 16 位无符号整数
- set_i16a_unit_of_chunk(id, relative_idx, val): 写入 16 位有符号整数
- set_u32a_unit_of_chunk(id, relative_idx, val): 写入 32 位无符号整数
- set_i32a_unit_of_chunk(id, relative_idx, val): 写入 32 位有符号整数
- set_u64a_unit_of_chunk(id, relative_idx, val): 写入 64 位无符号整数
- set_i64a_unit_of_chunk(id, relative_idx, val): 写入 64 位有符号整数
- set_f32a_unit_of_chunk(id, relative_idx, val): 写入 32 位浮点数
- set_f64a_unit_of_chunk(id, relative_idx, val): 写入 64 位浮点数

示例

$3

`javascript
// 创建一个可以存储 100 个记录的 ArrayBuffer，每个记录 64 字节
const recordCount = 100;
const recordSize = 64;
const ab = new ArrayBuffer(recordCount * recordSize);
const records = taBaseCreator(ab, recordSize);

// 定义记录结构
// 假设每个记录包含：id (u32), name (16字节), age (u8), salary (f32)

// 写入第一条记录
const recordId = 0;
records.set_u32a_unit_of_chunk(recordId, 0, 1001); // id: 1001
records.set_u8a_unit_of_chunk(recordId, 8, 30); // age: 30
records.set_f32a_unit_of_chunk(recordId, 2, 5000.50); // salary: 5000.50

// 写入名字 (假设用 ASCII 编码)
const nameBytes = new Uint8Array([74, 111, 104, 110, 32, 68, 111, 101]); // "John Doe"
records.set_byts(recordId, 4, nameBytes);

// 写入第二条记录
records.set_u32a_unit_of_chunk(1, 0, 1002); // id: 1002
records.set_u8a_unit_of_chunk(1, 8, 25); // age: 25
records.set_f32a_unit_of_chunk(1, 2, 4500.75); // salary: 4500.75

// 写入名字
const nameBytes2 = new Uint8Array([74, 97, 110, 101, 32, 83, 109, 105, 116, 104]); // "Jane Smith"
records.set_byts(1, 4, nameBytes2);
`

$3

`javascript
// 创建一个索引结构，每个索引项 32 字节
const indexCount = 1000;
const indexSize = 32;
const ab = new ArrayBuffer(indexCount * indexSize);
const indexes = taBaseCreator(ab, indexSize);

// 索引结构：key (u32), pointer (u32), timestamp (f64)

// 添加索引项
function addIndex(id, key, pointer, timestamp) {
indexes.set_u32a_unit_of_chunk(id, 0, key); // key
indexes.set_u32a_unit_of_chunk(id, 1, pointer); // pointer
indexes.set_f64a_unit_of_chunk(id, 1, timestamp); // timestamp
}

// 使用示例
addIndex(0, 12345, 500000, Date.now());
addIndex(1, 67890, 600000, Date.now());
`

注意事项

- 块大小 (chunksz) 必须是 16 的倍数且大于 16。
- ArrayBuffer 的大小必须是块大小的整数倍。
- 当尝试写入超出块边界的数据时，set_byts 方法会返回 false` 并且不会写入任何数据。