Skip to content

feat: 添加 Java ByteBuffer 兼容接口#17

Merged
CPythoner merged 3 commits intomasterfrom
feature/java-api-compat
Apr 4, 2026
Merged

feat: 添加 Java ByteBuffer 兼容接口#17
CPythoner merged 3 commits intomasterfrom
feature/java-api-compat

Conversation

@CPythoner
Copy link
Copy Markdown
Owner

新增 Java ByteBuffer 兼容 API

本 PR 添加了与 Java ByteBuffer 兼容的接口,使 C++ 实现更接近 Java 原生 API。

新增接口

数组访问方法 (Java compatibility)

  • hasArray(): 检查是否有可访问数组
  • array(): 返回底层字节数组
  • arrayOffset(): 返回数组偏移量

直接缓冲区方法

  • isDirect(): 判断是否为直接缓冲区

字节序方法 (跨平台数据序列化)

  • ByteOrder 枚举:ORDER_BIG_ENDIAN / ORDER_LITTLE_ENDIAN
  • order(): 获取/设置字节序
  • order(ByteOrder): 设置字节序
  • nativeOrder(): 获取主机字节序
  • 自动字节交换支持(读写时根据设置的字节序自动转换)

比较和辅助方法

  • compareTo(const ByteBuffer&): 按字典序比较两个缓冲区
  • hash(): 计算哈希值(用于 unordered_map 等容器)
  • toString(): 字符串表示

单元测试

添加了 27 个新测试用例,覆盖所有新接口:

  • hasArray, array, arrayOffset 测试
  • isDirect 测试
  • nativeOrder, order 测试
  • 字节序数据序列化测试(BigEndian, LittleEndian, Float, Double)
  • compareTo 测试
  • hash 测试
  • toString 测试

测试结果

All tests passed (155 assertions in 67 test cases)

新增 27 个测试用例,45 个断言。

使用示例

// 字节序控制
ByteBuffer bb;
bb.order(ByteOrder::ORDER_BIG_ENDIAN);
bb.putInt(0x12345678);

// 访问底层数组
if (bb.hasArray()) {
    uint8_t* arr = bb.array();
    // 直接操作数组
}

// 比较缓冲区
ByteBuffer bb1, bb2;
// ... 填充数据 ...
int result = bb1.compareTo(bb2);

// 哈希值
size_t h = bb.hash();

兼容性说明

  • 默认使用主机字节序(native order)
  • 切换字节序后,所有多字节类型的读写都会自动进行字节交换
  • 适用于跨平台数据序列化和网络传输场景

新增以下 Java 兼容 API:

数组访问方法:
- hasArray(): 检查是否有可访问数组
- array(): 返回底层字节数组
- arrayOffset(): 返回数组偏移量

直接缓冲区方法:
- isDirect(): 判断是否为直接缓冲区

字节序方法:
- ByteOrder 枚举:ORDER_BIG_ENDIAN / ORDER_LITTLE_ENDIAN
- order(): 获取/设置字节序
- nativeOrder(): 获取主机字节序
- 自动字节交换支持(跨平台数据序列化)

比较和辅助方法:
- compareTo(): 按字典序比较两个缓冲区
- hash(): 计算哈希值(用于 unordered 容器)
- toString(): 字符串表示

单元测试:
- 添加 27 个新测试用例,覆盖所有新接口
- 测试字节序转换的正确性
- 测试 compareTo、hash、toString 功能

实现细节:
- 默认使用主机字节序
- 切换字节序后自动进行字节交换
- byteswap 模板函数支持任意类型
- 添加 Java 兼容接口章节
- 数组访问方法:hasArray, array, arrayOffset
- 直接缓冲区方法:isDirect
- 字节序方法:ByteOrder, order, nativeOrder
- 比较和辅助方法:compareTo, hash, toString
- 添加使用示例代码
- 更新注意事项中的字节序说明
- 在标题下方添加 Header-Only 说明
- 在特性列表中添加 Header-Only 标记
- 更新构建与测试章节,说明使用方法
- 添加单独的使用方法(Header-Only)章节
@CPythoner CPythoner merged commit 93c9c25 into master Apr 4, 2026
6 checks passed
@CPythoner CPythoner deleted the feature/java-api-compat branch April 4, 2026 08:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant