dmlfw_set_string.h File Reference

Core unordered string set types and utilities. More...

#include <dmlfw_types.h>

Include dependency graph for dmlfw_set_string.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

typedef struct __dmlfw_set_string	dmlfw_set_string
	Opaque structure representing an unordered set of unique strings.
int	dmlfw_set_string_add (dmlfw_set_string *set, char *string)
	Adds a unique string to the set.
dmlfw_set_string *	dmlfw_set_string_create_new (void)
	Creates an empty unordered set of strings.
void	dmlfw_set_string_destroy (dmlfw_set_string *set)
	Destroys the string set, freeing all resources.
void	dmlfw_set_string_get (dmlfw_set_string *set, index_t i, char **string)
	Retrieves a copy of the string at the given index.
dimension_t	dmlfw_set_string_get_size (dmlfw_set_string *set)
	Retrieves the number of unique strings in the set.

Detailed Description

Core unordered string set types and utilities.

Version

1.0

Date

2025-09-25

This header defines opaque unordered set structures specialized for string data. It provides APIs for creation, destruction, element access, adding unique strings, and querying the set size.

Error Handling:

All functions report errors via the centralized error API. Use dmlfw_error() to check for errors after calls. dmlfw_get_error_string() and dmlfw_get_debug_string() provide diagnostic details.

Ownership:

Functions returning new set pointers transfer ownership to the caller, who is responsible for freeing with dmlfw_set_string_destroy(). Returned strings from get operations are allocated and must be freed by callers.

Typedef Documentation

dmlfw_set_string

typedef struct __dmlfw_set_string dmlfw_set_string

Opaque structure representing an unordered set of unique strings.

The internal details are encapsulated. Use provided API functions for creation, manipulation, and destruction.

Function Documentation

dmlfw_set_string_add()

int dmlfw_set_string_add	(	dmlfw_set_string *	set,
		char *	string
	)

Adds a unique string to the set.

Parameters

set	[in] Set (must not be NULL).
string	[in] String to add (must not be NULL).

Returns

-1 on memory failure, 0 if string was added or already exists.

Usage example:

char err[512], dbg[512];
int result = dmlfw_set_string_add(set, "example");
if (result == -1 && dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Failed to add string: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}

Examples

example_set_string.c.

dmlfw_set_string_create_new()

dmlfw_set_string * dmlfw_set_string_create_new

(

void

)

Creates an empty unordered set of strings.

Returns

Pointer to newly created set or NULL if allocation failed.

Usage example:

char err[512], dbg[512];
dmlfw_set_string *set = dmlfw_set_string_create_new();
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Failed to create set: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}

Examples

example_set_string.c.

dmlfw_set_string_destroy()

void dmlfw_set_string_destroy

(

dmlfw_set_string *

set

)

Destroys the string set, freeing all resources.

Parameters

set	[in] Pointer to set or NULL (no-op).

Usage example:

dmlfw_set_string_destroy(set);

Examples

example_set_string.c.

dmlfw_set_string_get()

void dmlfw_set_string_get	(	dmlfw_set_string *	set,
		index_t	i,
		char **	string
	)

Retrieves a copy of the string at the given index.

Parameters

set	[in] Set (must not be NULL).
i	[in] Zero-based index.
string	[out] Pointer to receive newly allocated string.

Note

Caller must free the allocated string.

On error sets error status and string is NULL.

Usage example:

char err[512], dbg[512];
char *str = NULL;
dmlfw_set_string_get(set, 0, &str);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Error getting string: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
} else {
    printf("String: %s\n", str);
    free(str);
}

Examples

example_set_string.c.

dmlfw_set_string_get_size()

dimension_t dmlfw_set_string_get_size

(

dmlfw_set_string *

set

)

Retrieves the number of unique strings in the set.

Parameters

set	[in] Set (may be NULL).

Returns

Number of elements or 0 if NULL or error.

Usage example:

char err[512], dbg[512];
dimension_t size = dmlfw_set_string_get_size(set);
if (dmlfw_error()) {
    dmlfw_get_error_string(err, sizeof(err));
    dmlfw_get_debug_string(dbg, sizeof(dbg));
    printf("Error getting size: %s\nDebug info: %s\n", err, dbg);
    return EXIT_FAILURE;
}
printf("Set size: %u\n", size);

Examples

example_set_string.c.