.. _utils-api:

Utilities Interface
===================

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

Global Functions
----------------

.. cpp:function:: const char* run_msg()

   Get library runtime message.

   :returns: Constant string containing runtime message

String Conversion
~~~~~~~~~~~~~~~~~

.. cpp:function:: int to_ansi_string(const char* utf8_string, char* sp)

   Convert UTF-8 string to ANSI string.

   :param utf8_string: Input UTF-8 string
   :param sp: Output buffer for ANSI string
   :returns: Length of converted string, or -1 if failed

.. cpp:function:: int to_wide_string(const char* utf8_string, wchar_t* wsp)

   Convert UTF-8 string to wide character string.

   :param utf8_string: Input UTF-8 string
   :param wsp: Output buffer for wide string
   :returns: Length of converted string, or -1 if failed

Cell Reference Conversion
~~~~~~~~~~~~~~~~~~~~~~~~~

.. cpp:function:: int a1_to_row_col(const char* s, int* row, int* col)

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

   :param s: A1-style reference (e.g., "A1", "B10")
   :param row: Pointer to store row index (1-based)
   :param col: Pointer to store column index (1-based)
   :returns: 1 if successful, 0 if failed

.. cpp:function:: 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.

   :param ws: Wide character A1-style reference
   :param row: Pointer to store row index (1-based)
   :param col: Pointer to store column index (1-based)
   :returns: 1 if successful, 0 if invalid format

.. cpp:function:: int row_col_to_a1(int row, int col, char* sp)

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

   :param row: Row index (1-based)
   :param col: Column index (1-based)
   :param sp: Output buffer for A1-style reference
   :returns: Length of generated string, or 0 if failed

Color Encoding and Decoding
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. cpp:function:: void decode_rgb(long rgb, int* red, int* green, int* blue)

   Decode RGB color value into separate color components.

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

.. cpp:function:: long encode_rgb(int red, int green, int blue)

   Encode separate color components into RGB color value.

   :param red: Red component (0-255)
   :param green: Green component (0-255)
   :param blue: Blue component (0-255)
   :returns: RGB color value (0x00RRGGBB format)

.. cpp:function:: void decode_argb(long argb, int* red, int* green, int* blue, int* alpha)

   Decode ARGB color value into separate color components.

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

.. cpp:function:: long encode_argb(int red, int green, int blue, int alpha)

   Encode separate color components into ARGB color value.

   :param red: Red component (0-255)
   :param green: Green component (0-255)
   :param blue: Blue component (0-255)
   :param alpha: Alpha component (0-255)
   :returns: ARGB color value (0xAARRGGBB format)

Date and Time Operations
~~~~~~~~~~~~~~~~~~~~~~~~

.. cpp:function:: void decode_date(double date, int* year, int* month, int* day)

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

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

.. cpp:function:: void decode_date1904(double date, int* year, int* month, int* day)

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

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

.. cpp:function:: void decode_time(double time, int* hour, int* minute, int* second, int* msec)

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

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

.. cpp:function:: 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).

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

.. cpp:function:: 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).

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

.. cpp:function:: double encode_date(int year, int month, int day)

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

   :param year: Year
   :param month: Month (1-12)
   :param day: Day (1-31)
   :returns: Excel date value (Return the minimum value of double type if failed).

.. cpp:function:: double encode_time(int hour, int minute, int second, int msec)

   Encode time components into Excel time value.

   :param hour: Hour (0-23)
   :param minute: Minute (0-59)
   :param second: Second (0-59)
   :param msec: Millisecond (0-999)
   :returns: Excel time value (Return the minimum value of double type if failed).

.. cpp:function:: 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).

   :param year: Year
   :param month: Month (1-12)
   :param day: Day (1-31)
   :param hour: Hour (0-23)
   :param minute: Minute (0-59)
   :param second: Second (0-59)
   :param msec: Millisecond (0-999)
   :returns: Excel datetime value (Return the minimum value of double type if failed).

Usage Examples
--------------

String Conversion
~~~~~~~~~~~~~~~~~

.. code-block:: cpp

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

.. code-block:: cpp

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

.. code-block:: cpp

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

.. code-block:: cpp

   #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
