#ifndef INCLUDED_C_TRIE_H
#define INCLUDED_C_TRIE_H

#ifndef INCLUDED_C_TYPES_H
#include <c_Types.h>
#endif /*INCLUDED_C_TYPES_H*/

#ifndef INCLUDED_C_STRINGLIST_H
#include <c_StringList.h>
#endif /*INCLUDED_C_STRINGLIST_H*/


/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

#define C_TRIE_R 256


typedef struct c_TrieNode {
    void*               value;     // Generic client value pointer associated with a complete key string
    struct c_TrieNode*  next[C_TRIE_R]; // Flat array of child node pointers mapping to character offsets
} c_TrieNode_t;

typedef struct {
    c_TrieNode_t* root;   // Reference root pointer of the trie structure capsule
    c_size_t      size;   // Total count of distinct key-value pairs stored inside the trie
} c_Trie_t;

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

c_err_t  c_Trie_Init(c_Trie_t* self);

void     c_Trie_Destroy(c_Trie_t* self);

/**
 * Insert or update a string key mapped to a generic value pointer inside the table
 */
c_err_t  c_Trie_Put(c_Trie_t* self, const char* key, void* value);

/**
 * Retrieve the generic client value pointer mapped to a string key
 * @return The stored value address, or NULL if the key does not exist
 */
void*    c_Trie_Get(c_Trie_t* self, const char* key);

/**
 * Check if the trie contains a matching entry for a specific string key
 */
c_bool_t c_Trie_Contains(c_Trie_t* self, const char* key);

/**
 * Remove a key-value mapping from the trie table. Cleans up orphaned down-stream nodes automatically.
 */
c_err_t  c_Trie_Delete(c_Trie_t* self, const char* key);

/**
 * Gather all keys currently matching a specific character prefix layout string
 * @param result An initialized c_StringList container to append the extracted string records
 */
c_err_t  c_Trie_KeysWithPrefix(c_Trie_t* self, const char* prefix, c_StringList* result);

/**
 * Gather all keys currently matching a specific wildcard pattern string (where '.' matches any character)
 * @param pattern String pattern containing characters and '.' wildcards
 * @param result  An initialized c_StringList container to append the extracted string records
 */
c_err_t  c_Trie_KeysThatMatch(c_Trie_t* self, const char* pattern, c_StringList* result);

/**
 * Find the longest key registered in the Trie that is a prefix of the query string.
 * For example, if "a", "app", and "apple" are in the Trie, LongestPrefixOf("applepie") returns "apple".
 *
 * @param query  The source text string to analyze
 * @return
 *  - A dynamically allocated copy of the longest matching prefix string (managed via C_ALLOC, caller frees)
 *  - An empty string copy "" if no prefix is matched
 *  - NULL if system parameters are invalid
 */
char* c_Trie_LongestPrefixOf(c_Trie_t* self, const char* query);

#endif /*INCLUDED_C_TRIE_H*/