README.md

ustring

Dynamic string class for embedded systems using dalloc memory allocator.

Version: 1.3.0 License: Apache 2.0 Author: Alexey Vasilenko

Features

• Dynamic string with automatic memory management
• Built on top of uvector
• Two modes: multi-heap (explicit heap pointer) and single-heap (global default)
• STL-like interface (at, c_str, append, resize, operator+, etc.)
• Memory defragmentation support via dalloc
• No memory fragmentation issues for long-running embedded applications

Dependencies

ustring requires:

• uvector v1.3.0+
• dalloc v1.5.0+

API Reference

Constructors

Constructor	Description
ustring()	Default constructor (single-heap mode only)
ustring(heap_t* heap)	Constructor with heap pointer (multi-heap mode)
ustring(uint32_t size, heap_t* heap)	Constructor with initial size
ustring(const char* str, heap_t* heap)	Constructor from C string
ustring(const ustring& other)	Copy constructor

Element Access

Method	Description
char& at(uint32_t i)	Access character with bounds checking
char& operator[](uint32_t i)	Access character without bounds checking
char& front()	Access first character
char& back()	Access last character
char* data()	Direct access to underlying array
const char* c_str()	Get null-terminated C string

Capacity

Method	Description
bool empty()	Check if string is empty
uint32_t size()	Return string length (excluding null terminator)
uint32_t length()	Same as size()
uint32_t capacity()	Return current capacity
bool reserve(uint32_t n)	Reserve capacity for n characters
bool shrink_to_fit()	Reduce capacity to match size

Modifiers

Method	Description
bool push_back(char c)	Append character
bool pop_back()	Remove last character
bool append(const char* str)	Append C string
bool append(const ustring& str)	Append ustring
bool append(char c)	Append character
void clear()	Remove all characters
bool resize(uint32_t n)	Change string size
bool resize(uint32_t n, char c)	Change size with fill character
bool assign(const char* str)	Replace content with C string
bool assign(const ustring& str)	Replace content with ustring

Operators

Operator	Description
operator=	Assignment
operator+=	Append
operator+	Concatenation
operator==	Equality comparison
operator!=	Inequality comparison

Usage

Single-heap mode

Enable single-heap mode via compiler flags or custom config file:

gcc -DUSE_SINGLE_HEAP_MEMORY ...

#include "ustring.h"

__attribute__((aligned(4)))
static uint8_t heap_buffer[4096];

int main() {
    if (!dalloc_register_heap(heap_buffer, sizeof(heap_buffer))) {
        return -1;
    }

    ustring str1("Hello");
    ustring str2(" World");
    ustring result = str1 + str2;

    printf("Result: %s\n", result.c_str());  // "Hello World"

    return 0;
}

Multi-heap mode

#include "ustring.h"

__attribute__((aligned(4)))
static uint8_t heap_buffer[4096];
heap_t heap;

int main() {
    heap_init(&heap, heap_buffer, sizeof(heap_buffer));

    ustring str1("Hello", &heap);
    ustring str2(" World", &heap);

    str1 += str2;
    printf("Result: %s\n", str1.c_str());  // "Hello World"

    heap_deinit(&heap);
    return 0;
}

Using with uvector

#include "uvector.h"
#include "ustring.h"

uvector<ustring> strings(&heap);

strings.push_back(ustring("First", &heap));
strings.push_back(ustring("Second", &heap));

for (uint32_t i = 0; i < strings.size(); i++) {
    printf("String %u: %s\n", i, strings.at(i).c_str());
}

Testing

ustring includes comprehensive unit tests using Google Test:

cd libs/ustring/tests
mkdir build && cd build
cmake ..
make -j$(nproc)
./ustring_tests              # Multi-heap tests (139 tests)
./ustring_single_heap_tests  # Single-heap tests (28 tests)

Tests cover:

• Basic operations (construction, assignment, access)
• String manipulation (append, resize, clear)
• Operators (+, +=, ==, !=)
• Copy semantics (copy constructor, assignment)
• Edge cases (empty string, single character)
• Stress tests (rapid operations, long strings)

All tests run with AddressSanitizer and UndefinedBehaviorSanitizer enabled.

License

Apache License 2.0. See LICENSE for details.