dynamic_buffer.h File Reference

Reference-counted byte buffer library for efficient I/O operations. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <assert.h>

Include dependency graph for dynamic_buffer.h:

Go to the source code of this file.

Macros
#define	DB_VERSION_MAJOR   0
#define	DB_VERSION_MINOR   2
#define	DB_VERSION_PATCH   2
#define	DB_VERSION_STRING   "0.2.2"
#define	DB_MALLOC   malloc
#define	DB_REALLOC   realloc
#define	DB_FREE   free
#define	DB_ASSERT   assert
#define	DB_ATOMIC_REFCOUNT   0
#define	DB_REFCOUNT_INIT(n)   (n)
#define	DB_REFCOUNT_LOAD(ptr)   (*(ptr))
#define	DB_REFCOUNT_INCREMENT(ptr)   (++(*(ptr)))
#define	DB_REFCOUNT_DECREMENT(ptr)   (--(*(ptr)))
#define	DB_DEF   extern

Typedefs
typedef int	db_refcount_t
typedef char *	db_buffer
	Buffer handle - points directly to buffer data.
typedef struct db_builder_internal *	db_builder
	Opaque builder handle for constructing buffers efficiently.
typedef struct db_reader_internal *	db_reader
	Opaque reader handle for parsing buffers.

Functions
DB_DEF db_buffer	db_new (size_t capacity)
	Create a new empty buffer with specified capacity.
DB_DEF db_buffer	db_new_with_data (const void *data, size_t size)
	Create a new buffer initialized with data (copies the data)
DB_DEF db_buffer	db_new_from_owned_data (void *data, size_t size, size_t capacity)
	Create a new buffer by copying existing data.
DB_DEF db_buffer	db_retain (db_buffer buf)
	Increase reference count (share ownership)
DB_DEF void	db_release (db_buffer *buf_ptr)
	Decrease reference count and potentially free buffer.
DB_DEF size_t	db_size (db_buffer buf)
	Get current size of buffer in bytes.
DB_DEF size_t	db_capacity (db_buffer buf)
	Get current capacity of buffer in bytes.
DB_DEF bool	db_is_empty (db_buffer buf)
	Check if buffer is empty.
DB_DEF int	db_refcount (db_buffer buf)
	Get current reference count.
DB_DEF db_buffer	db_slice (db_buffer buf, size_t offset, size_t length)
	Create a slice of the buffer (creates independent copy)
DB_DEF db_buffer	db_slice_from (db_buffer buf, size_t offset)
	Create a slice from offset to end of buffer.
DB_DEF db_buffer	db_slice_to (db_buffer buf, size_t length)
	Create a slice from start to specified length.
DB_DEF db_buffer	db_append (db_buffer buf, const void *data, size_t size)
	Create new buffer with data appended.
DB_DEF db_buffer	db_concat (db_buffer buf1, db_buffer buf2)
	Concatenate two buffers into a new buffer.
DB_DEF db_buffer	db_concat_many (db_buffer *buffers, size_t count)
	Concatenate multiple buffers into a new buffer.
DB_DEF bool	db_equals (db_buffer buf1, db_buffer buf2)
	Compare two buffers for equality.
DB_DEF int	db_compare (db_buffer buf1, db_buffer buf2)
	Compare buffer contents lexicographically.
DB_DEF ssize_t	db_read_fd (db_buffer *buf_ptr, int fd, size_t max_bytes)
	Read data from file descriptor into buffer.
DB_DEF ssize_t	db_write_fd (db_buffer buf, int fd)
	Write buffer contents to file descriptor.
DB_DEF db_buffer	db_read_file (const char *filename)
	Read entire file into a new buffer.
DB_DEF bool	db_write_file (db_buffer buf, const char *filename)
	Write buffer contents to file.
DB_DEF db_buffer	db_to_hex (db_buffer buf, bool uppercase)
	Create a hexadecimal representation of buffer contents.
DB_DEF db_buffer	db_from_hex (const char *hex_string, size_t length)
	Create buffer from hexadecimal string.
DB_DEF void	db_debug_print (db_buffer buf, const char *label)
	Print buffer information for debugging.
DB_DEF db_builder	db_builder_new (size_t initial_capacity)
	Create a new buffer builder.
DB_DEF db_builder	db_builder_from_buffer (db_buffer buf)
	Create builder from existing buffer (continues at end)
DB_DEF db_builder	db_builder_retain (db_builder builder)
	Increase builder reference count (share ownership)
DB_DEF void	db_builder_release (db_builder *builder_ptr)
	Decrease builder reference count and potentially free builder.
DB_DEF db_buffer	db_builder_finish (db_builder *builder_ptr)
	Finalize builder and return the constructed buffer.
DB_DEF size_t	db_builder_size (db_builder builder)
	Get current write position in builder.
DB_DEF size_t	db_builder_capacity (db_builder builder)
	Get current capacity of builder.
DB_DEF void	db_builder_clear (db_builder builder)
	Clear builder contents.
DB_DEF int	db_builder_append_uint8 (db_builder builder, uint8_t value)
	Write uint8 value.
DB_DEF int	db_builder_append_uint16_le (db_builder builder, uint16_t value)
	Write uint16 value in little-endian format.
DB_DEF int	db_builder_append_uint16_be (db_builder builder, uint16_t value)
	Write uint16 value in big-endian format.
DB_DEF int	db_builder_append_uint32_le (db_builder builder, uint32_t value)
	Write uint32 value in little-endian format.
DB_DEF int	db_builder_append_uint32_be (db_builder builder, uint32_t value)
	Write uint32 value in big-endian format.
DB_DEF int	db_builder_append_uint64_le (db_builder builder, uint64_t value)
	Write uint64 value in little-endian format.
DB_DEF int	db_builder_append_uint64_be (db_builder builder, uint64_t value)
	Write uint64 value in big-endian format.
DB_DEF int	db_builder_append (db_builder builder, const void *data, size_t size)
	Write raw bytes.
DB_DEF int	db_builder_append_cstring (db_builder builder, const char *str)
	Write null-terminated string (without null terminator)
DB_DEF int	db_builder_append_buffer (db_builder builder, db_buffer buf)
	Append buffer contents.
DB_DEF db_reader	db_reader_new (db_buffer buf)
	Create a new buffer reader.
DB_DEF db_reader	db_reader_retain (db_reader reader)
	Increase reader reference count (share ownership)
DB_DEF void	db_reader_release (db_reader *reader_ptr)
	Decrease reader reference count and potentially free reader.
DB_DEF void	db_reader_free (db_reader *reader_ptr)
	Free reader resources (legacy name, use db_reader_release instead)
DB_DEF size_t	db_reader_position (db_reader reader)
	Get current read position.
DB_DEF size_t	db_reader_remaining (db_reader reader)
	Get number of bytes remaining.
DB_DEF bool	db_reader_can_read (db_reader reader, size_t bytes)
	Check if reader can read specified number of bytes.
DB_DEF void	db_reader_seek (db_reader reader, size_t position)
	Seek to specific position.
DB_DEF uint8_t	db_read_uint8 (db_reader reader)
	Read uint8 value.
DB_DEF uint16_t	db_read_uint16_le (db_reader reader)
	Read uint16 value in little-endian format.
DB_DEF uint16_t	db_read_uint16_be (db_reader reader)
	Read uint16 value in big-endian format.
DB_DEF uint32_t	db_read_uint32_le (db_reader reader)
	Read uint32 value in little-endian format.
DB_DEF uint32_t	db_read_uint32_be (db_reader reader)
	Read uint32 value in big-endian format.
DB_DEF uint64_t	db_read_uint64_le (db_reader reader)
	Read uint64 value in little-endian format.
DB_DEF uint64_t	db_read_uint64_be (db_reader reader)
	Read uint64 value in big-endian format.
DB_DEF void	db_read_bytes (db_reader reader, void *data, size_t size)
	Read raw bytes.

Detailed Description

Reference-counted byte buffer library for efficient I/O operations.

Version

0.2.2

Date

August 2025

Single header library for reference-counted byte buffers similar to libuv's buffer type. Designed for efficient I/O operations, immutable slicing, and safe memory management in both PC and microcontroller environments.

Configuration

Customize the library by defining these macros before including:

#define DB_MALLOC malloc         // custom allocator
#define DB_REALLOC realloc       // custom reallocator
#define DB_FREE free             // custom deallocator
#define DB_ASSERT assert         // custom assert macro
#define DB_ATOMIC_REFCOUNT 1     // enable atomic reference counting (C11)
 
#define DB_IMPLEMENTATION
#include "dynamic_buffer.h"

Basic Usage

// Create a buffer with some data
db_buffer buf = db_new_with_data("Hello", 5);
 
// Create a slice (independent copy)
db_buffer slice = db_slice(buf, 1, 4);  // "ello"
 
// Concatenate buffers
db_buffer world = db_new_with_data(" World", 6);
db_buffer combined = db_concat(buf, world);
 
// Use a builder to construct data
db_builder builder = db_builder_new(64);
db_builder_append_cstring(builder, "Built: ");
db_builder_append_uint32_le(builder, 0x12345678);
db_buffer built = db_builder_finish(&builder);
 
// Use a reader to parse data
db_reader reader = db_reader_new(built);
char prefix[8];
db_read_bytes(reader, prefix, 7);
prefix[7] = '\0';  // "Built: "
uint32_t value = db_read_uint32_le(reader);  // 0x12345678
 
// Clean up (reference counting handles memory automatically)
db_release(&buf);
db_release(&slice);
db_release(&world);
db_release(&combined);
db_release(&built);
db_reader_release(&reader);

Key Features

• Reference counting: Automatic memory management with atomic support for buffers, builders, and readers
• Buffer slicing: Create independent copies of buffer segments
  
• Efficient concatenation: Optimized buffer joining operations
• Builder API: Type-safe construction of binary data with reference counting
• Reader API: Cursor-based parsing of binary data with reference counting
  
• I/O integration: Compatible with read/write operations
• Memory safety: Bounds checking and safe access patterns
• Concurrent access: Lock-free atomic reference counting for safe sharing
• Microcontroller friendly: Minimal memory overhead

License

Dual licensed under your choice of:

• MIT License
• The Unlicense (public domain)

Macro Definition Documentation

DB_ASSERT

#define DB_ASSERT   assert

DB_ATOMIC_REFCOUNT

#define DB_ATOMIC_REFCOUNT   0

DB_DEF

#define DB_DEF   extern

DB_FREE

#define DB_FREE   free

DB_MALLOC

#define DB_MALLOC   malloc

DB_REALLOC

#define DB_REALLOC   realloc

DB_REFCOUNT_DECREMENT

#define DB_REFCOUNT_DECREMENT

(

ptr

)

(--(*(ptr)))

DB_REFCOUNT_INCREMENT

#define DB_REFCOUNT_INCREMENT

(

ptr

)

(++(*(ptr)))

DB_REFCOUNT_INIT

#define DB_REFCOUNT_INIT

(

n

)

(n)

DB_REFCOUNT_LOAD

#define DB_REFCOUNT_LOAD

(

ptr

)

(*(ptr))

DB_VERSION_MAJOR

#define DB_VERSION_MAJOR   0

DB_VERSION_MINOR

#define DB_VERSION_MINOR   2

DB_VERSION_PATCH

#define DB_VERSION_PATCH   2

DB_VERSION_STRING

#define DB_VERSION_STRING   "0.2.2"

Typedef Documentation

db_buffer

typedef char* db_buffer

Buffer handle - points directly to buffer data.

This is a char* that points directly to binary buffer data. Metadata (refcount, size, capacity) is stored at negative offsets before the buffer data. This allows db_buffer to be used directly with all C memory functions.

Memory layout: [refcount|size|capacity|buffer_data...] ^ db_buffer points here

Note

Use directly with memcpy, write, etc. - no conversion needed!

NULL represents an invalid/empty buffer handle

db_refcount_t

typedef int db_refcount_t