General interface
-----------------

Due to the limitations mentioned on the :ref:`C Interface page <c_interface>`, the C API functions follow a naming scheme to replace C++ overloading. Each function name is based on the following regular expression:

``atc_<function-name>_<targets>[_results]?[_options]?[_<dtype>]?``

where the components represent:

* ``function-name``: The corresponding C++ function name, such as ``compress``, ``decompress`` or ``compress_decompress``.
* ``targets``: A string consisting of 1-3 characters ``f`` or ``m`` indicating whether the corresponding data should be loaded from/saved to a file or a buffer in-memory. The length of this string depends on ``function-name``. For example, when dealing with ``compress_decompress`` the ``targets`` string ``ffm`` indicates that the original data will be loaded from a file, compressed to a file and decompressed to memory.
* ``results``: If the corresponding C++ function returns :any:`atc::Results`, there are two categories of corresponding C functions:

   * One whose name does not include ``results`` and simply returns a ``bool`` indicating success or failure.
   * One whose name includes ``results`` and returns an :any:`atc_results` struct. **Note that to properly manage memory and avoid memory leaks, these returned structs must be explicitly destroyed by the user by calling** :any:`atc_destroy_results` **.**
   
* ``options``: If the corresponding C++ function accepts an :any:`atc::Options` argument, there are two categories of corresponding C functions: one with and one without an ``options`` argument. Note that default arguments do not exist in C, so when the ``options`` argument is present it must be given.

* ``dtype``: If the corresponding C++ function is templated, it will be instantiated for each of the valid data types: ``uint8``, ``uint16``, ``uint32``, ``uint64``, ``int8``, ``int16``, ``int32``, ``int64``, ``float32`` and ``float64``.

Using this naming scheme, the corresponding C++ documentation and the conversions from STL objects to C types described :ref:`here <c_interface>`, the meaning of each of the following functions should be fairly straightforward. Some very limited documentation is still provided to clarify a few things.

atc_compress
~~~~~~~~~~~~

C equivalent of :ref:`cpp_atc_compress`. Note that the argument ``modes`` represents the length of the array argument ``sizes``.

.. doxygengroup:: c_compress
   :content-only:
   :members:

atc_decompress
~~~~~~~~~~~~~~

C equivalent of :ref:`cpp_atc_decompress`.

.. doxygengroup:: c_decompress
   :content-only:
   :members:

atc_compress_decompress
~~~~~~~~~~~~~~~~~~~~~~~

C equivalent of :ref:`cpp_atc_compress_decompress`. Note that the argument ``modes`` represents the length of the array argument ``sizes``.

.. doxygengroup:: c_compdecomp
   :content-only:
   :members:

.. _c_atc_read_data_type:

atc_read_data_type
~~~~~~~~~~~~~~~~~~~

C equivalent of :ref:`cpp_atc_read_data_type`.

.. doxygengroup:: c_rdtype
   :content-only:
   :members:

.. _c_atc_read_decompressed_size:

atc_read_decompressed_size
~~~~~~~~~~~~~~~~~~~~~~~~~~

C equivalent of :ref:`cpp_atc_read_decompressed_size`.

.. doxygengroup:: c_rdsize
   :content-only:
   :members:

atc_calculate_decompressed_size
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

C equivalent of :ref:`cpp_atc_calculate_decompressed_size`.

.. doxygengroup:: c_cdsize
   :content-only:
   :members:

atc_data_type
~~~~~~~~~~~~~

Note that there is no equivalents for :any:`atc::get_data_type` in this section, because anyone using a particular instantiation of such a function (with the type hardcoded into the function name) might as well just replace it by the corresponding :any:`atc_data_type` enum value.

.. doxygenenum:: atc_data_type

ATC_VERSION
~~~~~~~~~~~

.. doxygenvariable:: ATC_VERSION
