A C++ implementation of Java NIO ByteBuffer, supporting cross-platform use (Windows, macOS, Linux).

Header-Only: Simply include ByteBuffer.h to use, no need to compile or link additional library files.

🌐 Language: English | 中文

• ByteBuffer
  • Table of Contents
  • Introduction
  • Features
  • Quick Start
    • Creating ByteBuffer
    • Writing Data
    • Reading Data
    • State Transitions
  • API Reference
    • Creation Methods
    • Write Methods
    • Read Methods
    • State Methods
    • Other Methods
    • Java Compatibility APIs
      • Array Access Methods
      • Direct Buffer Methods
      • Byte Order Methods
      • Comparison and Utility Methods
  • Build and Test
    • Requirements
    • Usage (Header-Only)
    • Build (For Testing Only)
    • CI Status
  • Caveats
  • References

ByteBuffer is a byte buffer that provides a series of put and get methods for easily storing and retrieving various types of data. The underlying storage structure is a byte array, and all operations are based on this array.

This implementation is based on Java NIO's ByteBuffer class, implemented in C++11 for cross-platform use.

• ✅ Header-Only: Simply include ByteBuffer.h to use
• ✅ Supports reading and writing of multiple data types (uint8_t, char, short, int, long, float, double)
• ✅ Automatic expansion mechanism, no need to worry about buffer overflow
• ✅ Supports chained operations, all put methods return ByteBuffer&
• ✅ Complete state management (position, limit, mark, capacity)
• ✅ Move semantics support, copy disabled to prevent resource leaks
• ✅ Cross-platform support (Windows, macOS, Linux)
• ✅ Complete CI test coverage

#include "ByteBuffer.h"

// Create default size (2048 bytes) ByteBuffer
ByteBuffer bb1;

// Create ByteBuffer with specified capacity
ByteBuffer bb2(1024, "myBuffer");

// Create ByteBuffer from existing array
uint8_t data[] = {1, 2, 3, 4, 5};
ByteBuffer bb3(data, sizeof(data), "fromArray");

// Chain writing
bb.put(42)
  .putChar('A')
  .putShort(1000)
  .putInt(123456)
  .putFloat(3.14f)
  .putDouble(2.71828);

// Write byte array
uint8_t buf[] = {1, 2, 3, 4, 5};
bb.putBytes(buf, sizeof(buf));

// Write at specified position
bb.putInt(999, 0);  // Write at index 0

// Switch to read mode
bb.flip();

// Sequential reading
uint8_t a = bb.get();
char c = bb.getChar();
uint16_t s = bb.getShort();
uint32_t i = bb.getInt();
float f = bb.getFloat();
double d = bb.getDouble();

// Read from specified position (does not change position)
uint8_t x = bb.get(5);
uint32_t y = bb.getInt(10);

// Read byte array
uint8_t outBuf[10];
bb.getBytes(outBuf, 10);
bb.getBytes(5, outBuf, 5);  // Read starting from index 5

// Write state -> Read state
bb.flip();

// Reset to initial state (can continue writing)
bb.clear();

// Mark current position
bb.mark();

// Return to marked position
bb.reset();

// Return to starting position
bb.rewind();

// Compact buffer (remove read data)
bb.compact();

Note: All put methods return ByteBuffer&, supporting chained calls.

Note: Methods with index parameter do not change the position value.

Byte Order Usage Example:

#include "ByteBuffer.h"

ByteBuffer bb;

// Set to big-endian byte order (network byte order)
bb.order(ByteOrder::ORDER_BIG_ENDIAN);

// Write data (automatically stored in big-endian order)
bb.putInt(0x12345678);  // Byte order in buffer: 12 34 56 78

// Switch to little-endian byte order
bb.order(ByteOrder::ORDER_LITTLE_ENDIAN);
bb.putInt(0x12345678);  // Byte order in buffer: 78 56 34 12

// Automatic conversion when reading
bb.flip();
bb.order(ByteOrder::ORDER_BIG_ENDIAN);
uint32_t value = bb.getInt();  // Correctly reads 0x12345678

Usage Example:

// Compare buffers
ByteBuffer bb1, bb2;
// ... fill data ...
int result = bb1.compareTo(bb2);  // <0: bb1<bb2, =0: equal, >0: bb1>bb2

// Hash value (can be used in unordered_map, etc.)
size_t h = bb1.hash();

// String representation
std::string str = bb1.toString();  // "ByteBuffer[pos=5 lim=10 cap=100]"

• C++11 compatible compiler
• CMake 3.10+ (for building tests only)

Since this is a header-only library, simply copy ByteBuffer.h to your project to use:

#include "ByteBuffer.h"

int main() {
    ByteBuffer bb;
    bb.putInt(12345);
    return 0;
}

No need to compile or link additional library files since all implementations are in the header file.

If you want to run tests:

mkdir build && cd build
cmake ..
make
./ByteBuffer

Or use CTest:

ctest --output-on-failure

This project uses GitHub Actions for continuous integration, supporting the following platforms:

1. Copy Control: ByteBuffer disables copy constructor and copy assignment operator to prevent double-free issues caused by shallow copy. If you need to copy, please use the duplicate() method or move semantics.

2. Memory Alignment: For multi-byte type read/write operations, some architectures (such as ARM) may require memory alignment. Unaligned access may cause performance degradation or crashes. It is recommended to ensure data alignment when handling large amounts of data.

3. Byte Order: This implementation supports byte order settings and defaults to host byte order. You can set big-endian or little-endian byte order through the order() method, which is suitable for cross-platform data serialization and network transmission.

4. Exception Handling: When memory allocation fails, a std::bad_alloc exception will be thrown. Please ensure proper exception handling when calling.

• Java ByteBuffer Documentation
• Netty ByteBuf