#ifndef INCLUDED_C_TST_H
#define INCLUDED_C_TST_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*/



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

typedef struct c_TSTNode {
    char                c;       // The single character split character token for this node
    void*               value;   // Generic client value pointer associated with a complete key string
    struct c_TSTNode*   left;    // Left branch pointer: character is smaller (<)
    struct c_TSTNode*   mid;     // Middle branch pointer: character matches (==)
    struct c_TSTNode*   right;   // Right branch pointer: character is larger (>)
} c_TSTNode_t;

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

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

c_err_t  c_TST_Init(c_TST_t* self);
void     c_TST_Destroy(c_TST_t* self);

/**
 * Insert or update a string key mapped to a generic value pointer inside the table
 */
c_err_t  c_TST_Put(c_TST_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_TST_Get(c_TST_t* self, const char* key);

/**
 * Check if the TST contains a matching entry for a specific string key
 */
c_bool_t c_TST_Contains(c_TST_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_TST_KeysWithPrefix(c_TST_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_TST_KeysThatMatch(c_TST_t* self, const char* pattern, c_StringList* result);

/**
 * Find the longest key registered in the TST that is a prefix of the query string.
 * For example, if "a", "app", and "apple" are in the TST, 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_TST_LongestPrefixOf(c_TST_t* self, const char* query);

#endif /*INCLUDED_C_TST_H*/