工具函数

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

全局函数

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的