/*
 * Copyright (c) 2026, Chloe M.
 * Provided under the BSD-3 clause
 */

#ifndef CESCAL_PTRBOX_H
#define CESCAL_PTRBOX_H 1

/*
 * Represents a pointer box entry in which allocated data can
 * be stored within
 *
 * @data: Allocated data backed by entry
 * @next: Next pointer box entry
 */
struct ptrbox_entry {
    void *data;
    struct ptrbox_entry *next;
};

/*
 * Represents a pointer box that enables RAII like behavior
 *
 * @head: Pointer box head
 * @tail: Pointer box tail
 */
struct ptrbox {
    struct ptrbox_entry *head;
    struct ptrbox_entry *tail;
};

/*
 * Initialize a pointer box
 *
 * @ptrbox: Pointer box to initialize
 *
 * Returns zero on success
 */
int ptrbox_init(struct ptrbox *ptrbox);

/*
 * Allocate memory and save the reference within a pointer box
 *
 * @ptrbox: Pointer box to save reference within
 * @len:    Length of memory to allocate
 *
 * Returns the base of the allocated memory on success, otherwise
 * NULL.
 */
void *ptrbox_alloc(struct ptrbox *ptrbox, size_t len);

/*
 * Duplicate a string and store the reference within a
 * pointer box
 *
 * @ptrbox: Pointer box to store reference within
 * @s:      String to duplicate
 *
 * Returns the duplicated string on success, otherwise NULL.
 */
char *ptrbox_strdup(struct ptrbox *ptrbox, const char *s);

/*
 * Destroy a pointer box along with all references stored
 * within
 *
 * @ptrbox: Pointer box to destroy
 */
void ptrbox_destroy(struct ptrbox *ptrbox);

#endif  /* !CESCAL_PTRBOX_H */