/**
 * @file strpool.h
 * @brief 字符串池实现
 *
 * 提供字符串驻留（String Interning）功能，保证相同字符串的唯一性存储
 */

#ifndef __SMCC_STRPOOL_H__
#define __SMCC_STRPOOL_H__

#include "hashmap.h"
#include <libcore.h>

/**
 * @struct strpool_t
 * @brief 字符串池上下文
 *
 * 组合哈希表和专用内存分配器实现的高效字符串存储池
 */
typedef struct strpool {
    hashmap_t ht; /**< 哈希表用于快速查找已存储字符串 */
} strpool_t;

/**
 * @brief 初始化字符串池
 * @param pool 字符串池实例指针
 */
void init_strpool(strpool_t *pool);

/**
 * @brief 驻留字符串到池中
 * @param pool 字符串池实例指针
 * @param str 要驻留的 C 字符串
 * @return 池中唯一字符串的持久指针
 *
 * @note 返回值生命周期与字符串池一致
 * @note 重复插入相同字符串会返回已有指针
 */
const char *strpool_intern(strpool_t *pool, const char *str);

/**
 * @brief 销毁字符串池
 * @param pool 字符串池实例指针
 *
 * @warning 销毁后已获取的字符串指针将失效
 * @note 会自动释放所有驻留字符串内存
 */
void strpool_destroy(strpool_t *pool);

#endif // __SMCC_STRPOOL_H__