.. _document-c-api:

Document API Reference
======================

Overview
--------

The Document API provides functions for creating, loading,
and managing Excel documents at the highest level,
serving as the entry point for working with Excel files.

Document Operations
-------------------

.. c:function:: const char* get_version()

    Get the library version information.

    :return: Library version string.

.. cpp:function:: void set_key(const char* username, const char* key)

   Set the license key.

   :param user: User name
   :param key: License key

.. c:function:: DocumentHandle doc_create()

    Create a new Excel document.

    :return: Handle to the newly created document.

.. c:function:: DocumentHandle doc_load(const char* filename)

    Load an existing Excel document from file.

    :param filename: Path to the Excel file to load.
    :return: Handle to the loaded document.

.. c:function:: CSVPolicyHandle doc_create_csv_policy()

    Create a policy for parsing a CSV file.

    :return: Handle to the created CSV policy.

.. c:function:: DocumentHandle doc_load_csv(const char* filename, CSVPolicyHandle policy)

    Load an existing CSV file.

    :param filename: Path to the CSV file to load.
    :param policy: A CSV policy for parsing the CSV file.
    :return: Handle to the loaded document.

.. c:function:: WorkbookHandle doc_get_workbook(DocumentHandle doc)

    Get the workbook from the document.

    :param doc: Document handle.
    :return: Workbook handle.

.. c:function:: int doc_save(DocumentHandle doc, const char* filename)

    Save the document to a file.

    :param doc: Document handle.
    :param filename: Path where to save the Excel file.
    :return: 1 on success, 0 on failure.

.. c:function:: int doc_save_to_csv(DocumentHandle doc, const char* filename)

    Save the current active worksheet to a csv file.

    :param doc: Document handle.
    :param filename: The path and file name where the file will be saved. If NULL, the worksheet name will be used as the csv file name and the csv file will be saved in the current working directory.
    :return: 1 on success, 0 on failure.

.. c:function:: void doc_release(DocumentHandle doc)

    Release document resources.

    :param doc: Document handle to release.

Usage Workflow
--------------

Typical workflow for using the Document API:

.. code-block:: c

    // Get library version
    const char* version = get_version();
    printf("Using library version: %s\n", version);

    // Create a new document
    DocumentHandle doc = doc_create();

    // Get the workbook to start adding content
    WorkbookHandle workbook = doc_get_workbook(doc);

    // ... Work with workbook, worksheets, cells, etc.

    // Save the document
    int result = doc_save(doc, "output.xlsx");
    if (!result)
        printf("Failed to save document: \s.\n", run_msg());

    // Release resources
    doc_release(doc);

Error Handling
--------------

- Always check the return value of ``doc_load()`` and ``doc_save()``
- A NULL handle indicates failure in creation or loading
- Use ``doc_release()`` to free resources and prevent memory leaks

Precautions
-----------
- After completing the document operation, be sure to call 'doc_release()'``
- Ensure that the target directory has write permission when saving documents
- Loading non-existent or damaged files may cause the function to return NULL
