# 工具函数

工具函数接口提供字符串编码转换、坐标转换、颜色编码/解码和日期时间操作的辅助函数。

## 全局函数

const char *run_msg()

  获取库运行时信息。

  返回:

    包含库运行时信息的常量字符串

### 字符串转换

int to_ansi_string(const char *utf8_string, char *sp)

  将 UTF-8 字符串转换为ANSI字符串。

  参数:

    - utf8_string -- 输入的 UTF-8 字符串

    - sp -- 输出 ANSI 字符串的缓冲区

  返回:

    转换后的字符串长度，失败返回 -1

int to_wide_string(const char *utf8_string, wchar_t *wsp)

  将 UTF-8 字符串转换为宽字符字符串。

  参数:

    - utf8_string -- 输入的 UTF-8 字符串

    - wsp -- 输出宽字符串的缓冲区

  返回:

    转换后的字符串长度，失败返回 -1

### 单元格引用转换

int a1_to_row_col(const char *s, int *row, int *col)

  将 A1 样式单元格引用转换为行和列索引。

  参数:

    - s -- A1 样式引用(例如："A1", "B10")

    - row -- 存储行索引(1-based)的指针

    - col -- 存储列索引(1-based)的指针

  返回:

    成功返回 1，失败返回 0

int wide_a1_to_row_col(const wchar_t *ws, int *row, int *col)

  将宽字符 A1 样式单元格引用转换为行和列索引。

  参数:

    - ws -- 宽字符 A1 样式引用

    - row -- 存储行索引(1-based)的指针

    - col -- 存储列索引(1-based)的指针

  返回:

    成功返回 1，格式无效返回 0

int row_col_to_a1(int row, int col, char *sp)

  将行和列索引转换为 A1 样式的单元格引用。

  参数:

    - row -- 行索引(1-based)

    - col -- 列索引(1-based)

    - sp -- 输出 A1 样式引用的缓冲区

  返回:

    生成的字符串长度，失败返回 0

### 颜色编码和解码

void decode_rgb(long rgb, int *red, int *green, int *blue)

  将 RGB 颜色值解码为单独的颜色分量。

  参数:

    - rgb -- RGB颜色值(0x00RRGGBB格式)

    - red -- 存储红色分量的指针(0-255)

    - green -- 存储绿色分量的指针(0-255)

    - blue -- 存储蓝色分量的指针(0-255)

long encode_rgb(int red, int green, int blue)

  将单独的颜色分量编码为 RGB 颜色值。

  参数:

    - red -- 红色分量(0-255)

    - green -- 绿色分量(0-255)

    - blue -- 蓝色分量(0-255)

  返回:

    RGB颜色值(0x00RRGGBB格式)

void decode_argb(long argb, int *red, int *green, int *blue, int *alpha)

  将 ARGB 颜色值解码为单独的颜色分量。

  参数:

    - argb -- ARGB 颜色值(0xAARRGGBB格式)

    - red -- 存储红色分量的指针(0-255)

    - green -- 存储绿色分量的指针(0-255)

    - blue -- 存储蓝色分量的指针(0-255)

    - alpha -- 存储透明度分量的指针(0-255)

long encode_argb(int red, int green, int blue, int alpha)

  将单独的颜色分量编码为 ARGB 颜色值。

  参数:

    - red -- 红色分量(0-255)

    - green -- 绿色分量(0-255)

    - blue -- 蓝色分量(0-255)

    - alpha -- 透明度分量(0-255)

  返回:

    ARGB 颜色值(0xAARRGGBB格式)

### 日期和时间操作

void decode_date(double date, int *year, int *month, int *day)

  将 Excel 日期值解码为年、月、日分量(1900日期系统)。

  参数:

    - date -- Excel 日期值

    - year -- 存储年份的指针

    - month -- 存储月份的指针(1-12)

    - day -- 存储日期的指针(1-31)

void decode_date1904(double date, int *year, int *month, int *day)

  将 Excel 日期值解码为年、月、日分量(1904日期系统)。

  参数:

    - date -- Excel 日期值

    - year -- 存储年份的指针

    - month -- 存储月份的指针(1-12)

    - day -- 存储日期的指针(1-31)

void decode_time(double time, int *hour, int *minute, int *second, int *msec)

  将 Excel 时间值解码为时间分量(1900 日期系统)。

  参数:

    - time -- Excel 时间值

    - hour -- 存储小时的指针(0-23)

    - minute -- 存储分钟的指针(0-59)

    - second -- 存储秒的指针(0-59)

    - msec -- 存储毫秒的指针(0-999)

void decode_datetime(double datetime, int *year, int *month, int *day, int *hour, int *minute, int *second, int *msec)

  将 Excel 日期时间值解码为日期和时间分量(1900日期系统)。

  参数:

    - datetime -- Excel 日期时间值

    - year -- 存储年份的指针

    - month -- 存储月份的指针(1-12)

    - day -- 存储日期的指针(1-31)

    - hour -- 存储小时的指针(0-23)

    - minute -- 存储分钟的指针(0-59)

    - second -- 存储秒的指针(0-59)

    - msec -- 存储毫秒的指针(0-999)

void decode_datetime1904(double datetime, int *year, int *month, int *day, int *hour, int *minute, int *second, int *msec)

  将 Excel 日期时间值解码为日期和时间分量(1904日期系统)。

  参数:

    - datetime -- Excel 日期时间值

    - year -- 存储年份的指针

    - month -- 存储月份的指针(1-12)

    - day -- 存储日期的指针(1-31)

    - hour -- 存储小时的指针(0-23)

    - hour -- 存储小时的指针(0-23)

    - minute -- 存储分钟的指针(0-59)

    - second -- 存储秒的指针(0-59)

    - msec -- 存储毫秒的指针(0-999)

double encode_date(int year, int month, int day)

  将年、月、日编码为 Excel 日期值(1900日期系统)。

  参数:

    - year -- 年

    - month -- 月(1-12)

    - day -- 日(1-31)

  返回:

    Excel 日期值(失败返回 double 类型的最小值)

double encode_time(int hour, int minute, int second, int msec)

  将时间分量编码为 Excel 时间值。

  参数:

    - hour -- 小时(0-23)

    - minute -- 分钟(0-59)

    - second -- 秒(0-59)

    - msec -- 毫秒(0-999)

  返回:

    Excel 时间值(失败返回 double 类型的最小值)

double encode_datetime(int year, int month, int day, int hour, int minute, int second, int msec)

  将日期和时间分量编码为 Excel 日期时间值(1900日期系统)。

  参数:

    - year -- 年

    - month -- 月(1-12)

    - day -- 日(1-31)

    - hour -- 小时(0-23)

    - minute -- 分钟(0-59)

    - second -- 秒(0-59)

    - msec -- 毫秒(0-999)

  返回:

    Excel 日期时间值(失败返回 double 类型的最小值)

## 使用示例

### 字符串转换

    #include "utils.h"

    // Convert UTF-8 to ANSI
    char ansi_buf[256];
    int len = to_ansi_string("UTF-8 文本", ansi_buf);

    // Convert UTF-8 to wide string
    wchar_t wide_buf[256];
    len = to_wide_string("UTF-8 文本", wide_buf);

### 单元格引用转换

    #include "utils.h"

    // Convert A1 to row/col
    int row, col;
    if (a1_to_row_col("B10", &row, &col) == 0) {
        // row = 9, col = 1 (0-based)
    }

    // Convert row/col to A1
    char a1_buf[16];
    row_col_to_a1(9, 1, a1_buf);
    // a1_buf = "B10"

### 颜色操作

    #include "utils.h"

    // Decode RGB color
    int r, g, b;
    decode_rgb(0x00FF0000, &r, &g, &b);
    // r = 255, g = 0, b = 0

    // Encode RGB color
    long red_color = encode_rgb(255, 0, 0);
    // red_color = 0x00FF0000

    // Decode ARGB color
    int a, r, g, b;
    decode_argb(0x80FF0000, &r, &g, &b, &a);
    // a = 128 (50% opacity), r = 255, g = 0, b = 0

### 日期/时间操作

    #include "utils.h"

    // Decode date
    int year, month, day;
    decode_date(44197.0, &year, &month, &day);
    // year = 2021, month = 1, day = 1

    // Encode date
    double excel_date = encode_date(2021, 1, 1);
    // excel_date ≈ 44197.0

    // Decode time
    int hour, minute, second, msec;
    decode_time(0.5, &hour, &minute, &second, &msec);
    // hour = 12, minute = 0, second = 0, msec = 0

    // Encode datetime
    double excel_datetime = encode_datetime(2021, 1, 1, 12, 30, 0, 0);
    // excel_datetime ≈ 44197.520833

## 备注

- Excel 使用两种不同的日期系统: 1900(Windows) 和 1904(Mac)

- 在 1900 日期系统中，Excel 错误地将 1900 年视为闰年

- RGB 颜色使用 0x00RRGGBB 格式, ARGB 使用 0xAARRGGBB 格式

- 字符串转换函数需要适当大小的输出缓冲区

- 在工具函数中，所有的行和列索引都是基于1的

Styled using the Piccolo Theme