Search/Sort

2026-08-29 01:58:00 +08:00
parent 8e95904cc4
commit a0758766c5
56 changed files with 5425 additions and 0 deletions
@@ -0,0 +1,77 @@
+#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*/