String API

Overview

The String API provides utilities for string manipulation, formatting, and management in the libmyrtx library. It offers functions for common string operations with memory safety and performance considerations.

Types

type myrtx_string_t

An opaque structure representing a dynamic string. This string structure provides automatic memory management and safe string manipulation.

type myrtx_string_view_t

A structure representing a non-owning view into a string or memory region. String views are lightweight references that don’t own or manage memory.

typedef struct {
    const char* data;  /* Pointer to the string data */
    size_t length;     /* Length of the string (excluding null terminator) */
} myrtx_string_view_t;

Creation and Destruction

myrtx_string_t *myrtx_string_create(void)

Creates a new empty string.

Returns:

A pointer to a new string, or NULL on allocation failure.

myrtx_string_t *myrtx_string_create_from_cstr(const char *cstr)

Creates a new string from a null-terminated C string.

Parameters:

• cstr – The source C string.

Returns:

A pointer to a new string, or NULL on allocation failure.

myrtx_string_t *myrtx_string_create_from_buffer(const char *buffer, size_t length)

Creates a new string from a buffer with specified length.

Parameters:

• buffer – The source buffer.

• length – The number of bytes to copy from the buffer.

Returns:

A pointer to a new string, or NULL on allocation failure.

myrtx_string_t *myrtx_string_create_from_string(const myrtx_string_t *other)

Creates a new string as a copy of another string.

Parameters:

• other – The source string to copy.

Returns:

A pointer to a new string, or NULL on allocation failure.

myrtx_string_t *myrtx_string_create_from_arena(myrtx_arena_t *arena)

Creates a new string that will use the specified arena for allocations.

Parameters:

• arena – The arena to use for allocations.

Returns:

A pointer to a new string, or NULL on error.

void myrtx_string_free(myrtx_string_t *string)

Frees a string and its associated memory.

Parameters:

• string – The string to free.

String Operations

int myrtx_string_append(myrtx_string_t *string, const char *buffer, size_t length)

Appends a buffer to a string.

Parameters:

• string – The target string.

• buffer – The buffer to append.

• length – The number of bytes to append from the buffer.

Returns:

0 on success, negative value on error.

int myrtx_string_append_cstr(myrtx_string_t *string, const char *cstr)

Appends a null-terminated C string to a string.

Parameters:

• string – The target string.

• cstr – The C string to append.

Returns:

0 on success, negative value on error.

int myrtx_string_append_string(myrtx_string_t *string, const myrtx_string_t *other)

Appends another string to a string.

Parameters:

• string – The target string.

• other – The string to append.

Returns:

0 on success, negative value on error.

int myrtx_string_append_char(myrtx_string_t *string, char c)

Appends a single character to a string.

Parameters:

• string – The target string.

• c – The character to append.

Returns:

0 on success, negative value on error.

int myrtx_string_append_format(myrtx_string_t *string, const char *format, ...)

Appends a formatted string to a string.

Parameters:

• string – The target string.

• format – The format string.

• ... – The format arguments.

Returns:

0 on success, negative value on error.

Replace

bool myrtx_string_replace(myrtx_string_t *string, const char *old_str, const char *new_str)

Replaces all occurrences of old_str with new_str.

• For strings backed by an arena, the replacement allocates a fresh buffer sized exactly to the result. After replacement, capacity == length + 1.

• For malloc-backed strings, capacity may be larger due to growth strategy.

Parameters:

• string – Target string to modify in place

• old_str – Substring to be replaced (must be non-empty)

• new_str – Replacement substring

Returns:

true on success, false on allocation error

int myrtx_string_append_format_va(myrtx_string_t *string, const char *format, va_list args)

Appends a formatted string to a string using a va_list.

Parameters:

• string – The target string.

• format – The format string.

• args – The format arguments as a va_list.

Returns:

0 on success, negative value on error.

String Views

myrtx_string_view_t myrtx_string_view_from_cstr(const char *cstr)

Creates a string view from a null-terminated C string.

Parameters:

• cstr – The source C string.

Returns:

A string view.

myrtx_string_view_t myrtx_string_view_from_buffer(const char *buffer, size_t length)

Creates a string view from a buffer with specified length.

Parameters:

• buffer – The source buffer.

• length – The length of the buffer.

Returns:

A string view.

myrtx_string_view_t myrtx_string_view_from_string(const myrtx_string_t *string)

Creates a string view from a string.

Parameters:

• string – The source string.

Returns:

A string view.

String Access

const char *myrtx_string_cstr(const myrtx_string_t *string)

Gets the C string representation of a string.

Parameters:

• string – The string.

Returns:

The null-terminated C string.

size_t myrtx_string_length(const myrtx_string_t *string)

Gets the length of a string.

Parameters:

• string – The string.

Returns:

The length of the string (excluding null terminator).

bool myrtx_string_is_empty(const myrtx_string_t *string)

Checks if a string is empty.

Parameters:

• string – The string.

Returns:

True if the string is empty, false otherwise.

String Modification

int myrtx_string_clear(myrtx_string_t *string)

Clears a string, setting its length to 0.

Parameters:

• string – The string to clear.

Returns:

0 on success, negative value on error.

int myrtx_string_resize(myrtx_string_t *string, size_t new_length)

Resizes a string to the specified length.

Parameters:

• string – The string to resize.

• new_length – The new length.

Returns:

0 on success, negative value on error.

int myrtx_string_reserve(myrtx_string_t *string, size_t capacity)

Reserves memory for a string.

Parameters:

• string – The string.

• capacity – The number of bytes to reserve.

Returns:

0 on success, negative value on error.

int myrtx_string_shrink_to_fit(myrtx_string_t *string)

Shrinks a string’s capacity to fit its content.

Parameters:

• string – The string.

Returns:

0 on success, negative value on error.

String Searching

size_t myrtx_string_find(const myrtx_string_t *string, const char *substring, size_t start_pos)

Finds the first occurrence of a substring in a string, starting from a specified position.

Parameters:

• string – The string to search in.

• substring – The substring to find.

• start_pos – The position to start searching from.

Returns:

The position of the first occurrence, or SIZE_MAX if not found.

size_t myrtx_string_rfind(const myrtx_string_t *string, const char *substring, size_t start_pos)

Finds the last occurrence of a substring in a string, starting from a specified position.

Parameters:

• string – The string to search in.

• substring – The substring to find.

• start_pos – The position to start searching from (moving backward).

Returns:

The position of the last occurrence, or SIZE_MAX if not found.

String Comparison

int myrtx_string_compare(const myrtx_string_t *lhs, const myrtx_string_t *rhs)

Compares two strings lexicographically.

Parameters:

• lhs – The first string.

• rhs – The second string.

Returns:

0 if equal, negative if lhs < rhs, positive if lhs > rhs.

int myrtx_string_compare_cstr(const myrtx_string_t *string, const char *cstr)

Compares a string with a C string lexicographically.

Parameters:

• string – The string.

• cstr – The C string.

Returns:

0 if equal, negative if string < cstr, positive if string > cstr.

bool myrtx_string_equals(const myrtx_string_t *lhs, const myrtx_string_t *rhs)

Checks if two strings are equal.

Parameters:

• lhs – The first string.

• rhs – The second string.

Returns:

True if the strings are equal, false otherwise.

bool myrtx_string_equals_cstr(const myrtx_string_t *string, const char *cstr)

Checks if a string is equal to a C string.

Parameters:

• string – The string.

• cstr – The C string.

Returns:

True if the string is equal to the C string, false otherwise.

String Modification

int myrtx_string_substr(const myrtx_string_t *string, size_t pos, size_t length, myrtx_string_t *result)

Extracts a substring from a string.

Parameters:

• string – The source string.

• pos – The starting position.

• length – The length of the substring.

• result – The string to store the substring in.

Returns:

0 on success, negative value on error.

int myrtx_string_replace(myrtx_string_t *string, size_t pos, size_t length, const char *replacement, size_t replacement_length)

Replaces a portion of a string with another string.

Parameters:

• string – The string to modify.

• pos – The position to start replacing at.

• length – The length of the portion to replace.

• replacement – The replacement string.

• replacement_length – The length of the replacement string.

Returns:

0 on success, negative value on error.

int myrtx_string_insert(myrtx_string_t *string, size_t pos, const char *buffer, size_t length)

Inserts a buffer into a string at the specified position.

Parameters:

• string – The string to modify.

• pos – The position to insert at.

• buffer – The buffer to insert.

• length – The length of the buffer.

Returns:

0 on success, negative value on error.

int myrtx_string_erase(myrtx_string_t *string, size_t pos, size_t length)

Erases a portion of a string.

Parameters:

• string – The string to modify.

• pos – The position to start erasing at.

• length – The length of the portion to erase.

Returns:

0 on success, negative value on error.

String Utility Functions

myrtx_string_t *myrtx_string_format(const char *format, ...)

Creates a new string from a format string.

Parameters:

• format – The format string.

• ... – The format arguments.

Returns:

A pointer to a new string, or NULL on error.

myrtx_string_t *myrtx_string_format_va(const char *format, va_list args)

Creates a new string from a format string using a va_list.

Parameters:

• format – The format string.

• args – The format arguments.

Returns:

A pointer to a new string, or NULL on error.

int myrtx_string_to_lower(myrtx_string_t *string)

Converts a string to lowercase.

Parameters:

• string – The string to convert.

Returns:

0 on success, negative value on error.

int myrtx_string_to_upper(myrtx_string_t *string)

Converts a string to uppercase.

Parameters:

• string – The string to convert.

Returns:

0 on success, negative value on error.

int myrtx_string_trim(myrtx_string_t *string)

Trims whitespace from the beginning and end of a string.

Parameters:

• string – The string to trim.

Returns:

0 on success, negative value on error.

int myrtx_string_trim_left(myrtx_string_t *string)

Trims whitespace from the beginning of a string.

Parameters:

• string – The string to trim.

Returns:

0 on success, negative value on error.

int myrtx_string_trim_right(myrtx_string_t *string)

Trims whitespace from the end of a string.

Parameters:

• string – The string to trim.

Returns:

0 on success, negative value on error.