.. csv-policy-c-interface:

CSV Policy C Interface
=======================

.. module:: csv_policy_c
   :synopsis: C language interface for CSV Policy configuration.

This interface provides formatting configuration options for parsing CSV. All functions operate via an opaque pointer :c:type:`CSVPolicyHandle` for internal function calls.

.. contents:: Table of Contents
   :local:
   :depth: 2


Character Handling
------------------

.. c:function:: char get_delimiter(CSVPolicyHandle handle)

   Gets the current field delimiter.

   :param handle: A valid CSV Policy handle.
   :return: The field delimiter character.

.. c:function:: bool set_delimiter(CSVPolicyHandle handle, char delim)

   Sets the field delimiter.

   :param handle: A valid CSV Policy handle.
   :param delim: The delimiter character to set.
   :return: ``true`` on success, ``false`` on failure.

.. c:function:: char get_quote(CSVPolicyHandle handle)

   Gets the current string escaping character.

   :param handle: A valid CSV Policy handle.
   :return: The string escaping character.

.. c:function:: void set_quote(CSVPolicyHandle handle, char quote)

   Sets the string escaping character.

   :param handle: A valid CSV Policy handle.
   :param quote: The string escaping character to set.

.. c:function:: void set_no_quote(CSVPolicyHandle handle)

   Disables string escaping.

   :param handle: A valid CSV Policy handle.

.. c:function:: bool is_quote_enabled(CSVPolicyHandle handle)

   Checks whether string escaping is enabled.

   :param handle: A valid CSV Policy handle.
   :return: ``true`` if enabled, otherwise ``false``.

.. c:function:: void add_trim_char(CSVPolicyHandle handle, char trim_char)

   Adds a character to the set of trim characters. If the character appears before or after a field value, it will be stripped during field value parsing.

   :param handle: A valid CSV Policy handle.
   :param trim_char: The character to add to the trim set.

.. c:function:: void clear_trim_chars(CSVPolicyHandle handle)

   Clears all trim characters.

   :param handle: A valid CSV Policy handle.


Column Handling
---------------

.. c:function:: void ignore_column(CSVPolicyHandle handle, int col)

   Marks a column to be ignored during parsing.

   :param handle: A valid CSV Policy handle.
   :param col: The 1‑based column index to ignore.


Numeric Formatting
------------------

.. c:function:: char decimal_symbol(CSVPolicyHandle handle)

   Gets the current decimal point symbol.

   :param handle: A valid CSV Policy handle.
   :return: The decimal point symbol.

.. c:function:: void set_decimal_symbol(CSVPolicyHandle handle, char symbol)

   Sets the decimal point symbol.

   :param handle: A valid CSV Policy handle.
   :param symbol: The decimal point symbol.

.. c:function:: char thousand_separator(CSVPolicyHandle handle)

   Gets the current digit grouping separator (e.g., thousands separator).

   :param handle: A valid CSV Policy handle.
   :return: The digit grouping separator.

.. c:function:: void set_thousand_separator(CSVPolicyHandle handle, char sep)

   Sets the digit grouping separator (e.g., thousands separator).

   :param handle: A valid CSV Policy handle.
   :param sep: The digit grouping separator.

.. c:function:: int group_size(CSVPolicyHandle handle)

   Gets the current digit grouping size (e.g., for thousands separators, the group size is 3).

   :param handle: A valid CSV Policy handle.
   :return: The grouping size (number of digits per group).

.. c:function:: void set_group_size(CSVPolicyHandle handle, int size)

   Sets the digit grouping size (e.g., for thousands separators, the group size is 3).

   :param handle: A valid CSV Policy handle.
   :param size: The grouping size.


Currency
--------

.. c:function:: const char* currency_sign(CSVPolicyHandle handle)

   Gets the current currency sign string (e.g., ``"$"``, ``"USD"``).

   :param handle: A valid CSV Policy handle.
   :return: The currency sign string.

.. c:function:: void set_currency_sign(CSVPolicyHandle handle, const char* sign)

   Sets the currency sign (e.g., ``"$"``, ``"USD"``).

   :param handle: A valid CSV Policy handle.
   :param sign: The currency sign string.


Date/Time Format
----------------

.. c:function:: const char* datetime_format(CSVPolicyHandle handle)

   Gets the current date/time format string.

   :param handle: A valid CSV Policy handle.
   :return: The date/time format string.

.. c:function:: void set_datetime_format(CSVPolicyHandle handle, const char* fmt)

   Sets the date/time format string.

   :param handle: A valid CSV Policy handle.
   :param fmt: The date/time format string (e.g., ``"%Y-%m-%d %H:%M:%S"``).

.. Grid table:

=====================================
Date/Time Format Specifier Reference
=====================================

+------------+------------------------------------------+-------------------+
| Specifier  | Description                              | Example           |
+============+==========================================+===================+
| %Y         | Full year                                | 2026              |
+------------+------------------------------------------+-------------------+
| %y         | Last two digits of year                  | 26                |
+------------+------------------------------------------+-------------------+
| %m         | Two‑digit month (01 to 12)               | 01                |
+------------+------------------------------------------+-------------------+
| %b         | Abbreviated month name (Jan, Feb, ...)   | Jan               |
+------------+------------------------------------------+-------------------+
| %h         | Same as %b                               |                   |
+------------+------------------------------------------+-------------------+
| %B         | Full month name (January, February, ...) | January           |
+------------+------------------------------------------+-------------------+
| %d         | Two‑digit day (01 to 31)                 | 03                |
+------------+------------------------------------------+-------------------+
| %a         | Abbreviated weekday (Sun, Mon, ...)      | Mon               |
+------------+------------------------------------------+-------------------+
| %A         | Full weekday (Sunday, Monday, ...)       | Monday            |
+------------+------------------------------------------+-------------------+
| %H         | Hour in 24‑hour format (00 to 23)        | 14                |
+------------+------------------------------------------+-------------------+
| %I         | Hour in 12‑hour format (01 to 12)        | 02                |
+------------+------------------------------------------+-------------------+
| %M         | Minute (00 to 59)                        | 45                |
+------------+------------------------------------------+-------------------+
| %S         | Second (00 to 59)                        | 30                |
+------------+------------------------------------------+-------------------+
| %p         | AM or PM (with 12‑hour hour)             | AM                |
+------------+------------------------------------------+-------------------+
| %z         | Time zone offset (e.g., +0200 or -0800)  | +0000             |
+------------+------------------------------------------+-------------------+
| %Z         | Time zone name (Only "UTC" is supported) | UTC               |
+------------+------------------------------------------+-------------------+
| %n         | Matches whitespace                       |                   |
+------------+------------------------------------------+-------------------+
| %t         | Matches whitespace                       |                   |
+------------+------------------------------------------+-------------------+
| %.         | Matches any character (skips it)         |                   |
+------------+------------------------------------------+-------------------+
