# 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

Styled using the Piccolo Theme