/******************************************************************************
 * 文件名称: 爆头.h
 * 功能描述: 定义与爆头率计算相关的数据结构和函数接口
 * 创建日期: 2025-11-27
 * 作    者: [淮羽]
 * 版    本: v1.0
 * 注    意: 本头文件符合C99标准，使用前请确保编译器支持
 ******************************************************************************/

#ifndef _BHEAD_H_ // 防止头文件被重复包含
#define _BHEAD_H_

#ifdef __cplusplus // 如果可能在C++编译器中使用，则声明为C语言链接规范
extern "C" {
#endif

/* 包含系统头文件 */
#include <stdint.h> // 使用标准整数类型
#include <stddef.h> // 使用size_t类型

/* 包含自定义头文件 */
/* #include "其他头文件.h" */

/* 宏定义区 */
#define MAX_PLAYER_NAME_LEN     (63)    /**< 玩家名称最大长度 */
#define MIN_HEADSHOT_RATE       (0.0f)  /**< 最小爆头率 */
#define MAX_HEADSHOT_RATE       (100.0f) /**< 最大爆头率 */

/**
 * @brief 爆头率计算状态枚举
 * 用于标识爆头率计算过程中的不同状态或结果
 */
typedef enum {
    HEADSHOT_CALC_SUCCESS = 0,    /**< 计算成功 */
    HEADSHOT_CALC_INVALID_INPUT,  /**< 输入参数无效 */
    HEADSHOT_CALC_DIVISION_BY_ZERO /**< 除零错误（总射击数为0） */
} headshot_calc_status_t;

/**
 * @brief 玩家数据结构体
 * 用于存储单个玩家的爆头相关统计数据
 */
typedef struct {
    char     player_name[MAX_PLAYER_NAME_LEN + 1]; /**< 玩家名称，包含结束符 */
    uint32_t total_shots;                          /**< 总射击次数 */
    uint32_t headshot_count;                       /**< 爆头次数 */
    float    headshot_rate;                        /**< 爆头率（百分比） */
} player_stats_t;

/* 函数声明区 - 所有函数名使用蛇形命名法（snake_case） */

/**
 * @brief 计算玩家的爆头率
 * 
 * 根据总射击次数和爆头次数计算爆头率（百分比）。
 * 
 * @param total_shots 总射击次数，必须大于0
 * @param headshot_count 爆头次数，必须小于等于总射击次数
 * @param result_status 计算状态输出参数，可为NULL
 * @return float 计算出的爆头率（0.0到100.0之间），出错时返回-1.0
 */
float calculate_headshot_rate(uint32_t total_shots, 
                              uint32_t headshot_count, 
                              headshot_calc_status_t* result_status);

/**
 * @brief 更新玩家统计数据
 * 
 * 根据新的一次射击结果更新玩家统计信息。
 * 
 * @param player 指向player_stats_t结构体的指针，不可为NULL
 * @param is_headshot 本次射击是否为爆头：1-是，0-否
 * @return headshot_calc_status_t 操作执行状态码
 */
headshot_calc_status_t update_player_stats(player_stats_t* player, int is_headshot);

/**
 * @brief 比较两名玩家的爆头率
 * 
 * @param player1 指向第一名玩家数据的指针，不可为NULL
 * @param player2 指向第二名玩家数据的指针，不可为NULL
 * @return int 比较结果：>0-p1爆头率高于p2, ==0-两者相等, <0-p1爆头率低于p2
 */
int compare_headshot_rate(const player_stats_t* player1, const player_stats_t* player2);

/**
 * @brief 将爆头率格式化为字符串
 * 
 * @param player 指向玩家数据的指针，不可为NULL
 * @param buffer 输出缓冲区，不可为NULL
 * @param buffer_size 缓冲区大小，应足够容纳格式化后的字符串
 * @return int 成功写入缓冲区的字符数（不含终止符），失败返回-1
 */
int format_headshot_string(const player_stats_t* player, 
                           char* buffer, 
                           size_t buffer_size);

#ifdef __cplusplus
}
#endif

#endif /* _BHEAD_H_ */