.. _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.

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