#ifndef ENFILADE_H
#define ENFILADE_H

#define ENSIFER_VERSION "0.1.20"

#include <stddef.h>
#include <stdint.h>

typedef struct enfilade enfilade_t;

typedef enum {
    ENF_OK = 0,
    ENF_ERR_NULL,
    ENF_ERR_ADDR,
    ENF_ERR_NOT_FOUND,
    ENF_ERR_NOMEM
} enf_error_t;

typedef struct {
    enf_error_t code;
    const char *msg;
} enf_result_t;

enfilade_t *create_enfilade(void);
void destroy_enfilade(enfilade_t *enf);

/* Store datum at a dotted tumbler address. Missing intermediate children are
 * created automatically. Replacing the final datum is allowed. */
enf_result_t put_enfilade(enfilade_t *enf, const char *tumbler, void *datum);

/* Remove only the datum stored at the exact final key. A child subtree at the
 * same key is retained. Empty intermediate child nodes are pruned. */
enf_result_t remove_enfilade(enfilade_t *enf, const char *tumbler);

/* Exact terminal value, without descendant traversal. */
void *getXtumbler_enfilade(enfilade_t *enf, const char *tumbler);

/* Resolve a tumbler using the Enfilade.py getByTumbler/get semantics.
 * Returns a newly allocated array of datum pointers. Caller frees the array;
 * the datum pointers remain owned by the application/S7. */
enf_result_t getXtumbler_values_enfilade(enfilade_t *enf,
                                         const char *tumbler,
                                         void ***items,
                                         size_t *count);

/* Flatten all values in numeric key order for the inclusive range. A negative
 * end means "everything", matching the Python default end=-1. */
enf_result_t getXrange_values_enfilade(enfilade_t *enf,
                                       int64_t start,
                                       int64_t end,
                                       void ***items,
                                       size_t *count);

typedef void (*enfilade_datum_visitor)(void *datum, void *context);
void enfilade_visit_data(enfilade_t *enf,
                         enfilade_datum_visitor visitor,
                         void *context);

#endif /* ENFILADE_H */