Utilities Interface

The Utilities interface provides helper functions for string conversion, coordinate transformation, color encoding/decoding, and date/time operations.

Global Functions

const char *run_msg()

Get library runtime message.

Returns:: Constant string containing runtime message

String Conversion

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

Convert UTF-8 string to ANSI string.

Parameters:

utf8_string – Input UTF-8 string
sp – Output buffer for ANSI string

Returns:

Length of converted string, or -1 if failed

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

Convert UTF-8 string to wide character string.

Parameters:

utf8_string – Input UTF-8 string
wsp – Output buffer for wide string

Returns:

Length of converted string, or -1 if failed

Cell Reference Conversion

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

Convert A1-style cell reference to row and column indices.

Parameters:

s – A1-style reference (e.g., “A1”, “B10”)
row – Pointer to store row index (1-based)
col – Pointer to store column index (1-based)

Returns:

1 if successful, 0 if failed

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

Convert wide character A1-style cell reference to row and column indices.

Parameters:

ws – Wide character A1-style reference
row – Pointer to store row index (1-based)
col – Pointer to store column index (1-based)

Returns:

1 if successful, 0 if invalid format

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

Convert row and column indices to A1-style cell reference.

Parameters:

row – Row index (1-based)
col – Column index (1-based)
sp – Output buffer for A1-style reference

Returns:

Length of generated string, or 0 if failed

Color Encoding and Decoding

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

Decode RGB color value into separate color components.

Parameters:

rgb – RGB color value (0x00RRGGBB format)
red – Pointer to store red component (0-255)
green – Pointer to store green component (0-255)
blue – Pointer to store blue component (0-255)

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

Encode separate color components into RGB color value.

Parameters:

red – Red component (0-255)
green – Green component (0-255)
blue – Blue component (0-255)

Returns:

RGB color value (0x00RRGGBB format)

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

Decode ARGB color value into separate color components.

Parameters:

argb – ARGB color value (0xAARRGGBB format)
red – Pointer to store red component (0-255)
green – Pointer to store green component (0-255)
blue – Pointer to store blue component (0-255)
alpha – Pointer to store alpha component (0-255)

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

Encode separate color components into ARGB color value.

Parameters:

red – Red component (0-255)
green – Green component (0-255)
blue – Blue component (0-255)
alpha – Alpha component (0-255)

Returns:

ARGB color value (0xAARRGGBB format)

Date and Time Operations

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

Decode Excel date value into year, month, and day components (1900 date system).

Parameters:

date – Excel date value
year – Pointer to store year
month – Pointer to store month (1-12)
day – Pointer to store day (1-31)

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

Decode Excel date value into year, month, and day components (1904 date system).

Parameters:

date – Excel date value
year – Pointer to store year
month – Pointer to store month (1-12)
day – Pointer to store day (1-31)

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

Decode Excel time value into time components (1900 date system).

Parameters:

time – Excel time value
hour – Pointer to store hour (0-23)
minute – Pointer to store minute (0-59)
second – Pointer to store second (0-59)
msec – Pointer to store millisecond (0-999)

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

Decode Excel datetime value into date and time components (1900 date system).

Parameters:

datetime – Excel datetime value
year – Pointer to store year
month – Pointer to store month (1-12)
day – Pointer to store day (1-31)
hour – Pointer to store hour (0-23)
minute – Pointer to store minute (0-59)
second – Pointer to store second (0-59)
msec – Pointer to store millisecond (0-999)

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

Decode Excel datetime value into date and time components (1904 date system).

Parameters:

datetime – Excel datetime value
year – Pointer to store year
month – Pointer to store month (1-12)
day – Pointer to store day (1-31)
hour – Pointer to store hour (0-23)
hour – Pointer to store hour (0-23)
minute – Pointer to store minute (0-59)
second – Pointer to store second (0-59)
msec – Pointer to store millisecond (0-999)

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

Encode year, month, and day into Excel date value (1900 date system).

Parameters:

year – Year
month – Month (1-12)
day – Day (1-31)

Returns:

Excel date value (Return the minimum value of double type if failed).

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

Encode time components into Excel time value.

Parameters:

hour – Hour (0-23)
minute – Minute (0-59)
second – Second (0-59)
msec – Millisecond (0-999)

Returns:

Excel time value (Return the minimum value of double type if failed).

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

Encode date and time components into Excel datetime value (1900 date system).

Parameters:

year – Year
month – Month (1-12)
day – Day (1-31)
hour – Hour (0-23)
minute – Minute (0-59)
second – Second (0-59)
msec – Millisecond (0-999)

Returns:

Excel datetime value (Return the minimum value of double type if failed).

Usage Examples

String Conversion

#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);

Cell Reference Conversion

#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"

Color Operations

#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

Date/Time Operations

#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

Notes

Excel uses different date systems: 1900 (Windows) and 1904 (Mac)
In 1900 system, Excel incorrectly treats 1900 as a leap year
RGB colors use 0x00RRGGBB format, ARGB uses 0xAARRGGBB
String conversion functions require properly sized output buffers
All row and column indices are 1-based in these utility functions