..
    ----------------------------------------------------------------------------------------------
     Copyright (c) The Einsums Developers. All rights reserved.
     Licensed under the MIT License. See LICENSE.txt in the project root for license information.
    ----------------------------------------------------------------------------------------------


.. _cppapi_TypeTranslator:

==============
TypeTranslator
==============

.. note::
   Generated from the C++ headers by ``apiary --emit-cpp-docs-json``.

.. cpp:namespace:: apiary

.. cpp:function:: std::string translate_python_default(const std::string &cpp_default)

   Best-effort translation of a captured default-argument expression to its Python-literal form.

   :param cpp_default: The captured C++ default-argument expression text.
   :returns: The Python-literal form of the default. Strips integer/float suffixes, rewrites `nullptr` / `std::nullopt` to `None`, `true`/`false` to `True`/`False`, and falls back to the verbatim text when no rewrite applies.


.. cpp:function:: std::string translate_python_type(clang::QualType type, const clang::ASTContext &ctx)

   Best-effort Python-stub form of `type`, suitable for emission in a `.pyi` file consumed by pyright.

   .. note::

      Anything unknown (most notably bound class types) is returned as the canonical qualified C++
      name; a post-pass over the IR resolves those against bound classes.

   :param type: The Clang type to translate.
   :param ctx: The AST context owning `type`.
   :returns: The Python-stub form of the type. Maps fundamentals to Python builtins, std containers/optional/pair/tuple/variant/function to their typing equivalents, and strips cv/ref/ptr qualifiers.


.. cpp:function:: std::string translate_python_type_string(const std::string &cpp_type)

   String-based variant of `translate_python_type` for callers that already have a printed C++ type name.

   :param cpp_type: The printed C++ type name (no `clang::QualType` access required).
   :returns: The Python-stub form of the type. Same recursion rules: maps fundamentals, `std::vector<T>` → `list[T_py]`, `std::pair<A,B>` → `tuple[A_py, B_py]`, etc.


.. cpp:function:: std::string translate_type(clang::QualType type, const clang::ASTContext &ctx)

   Returns a pretty-printed C++ form of `type` suitable for emission in pybind11 binding code.

   .. note::

      Phase-2 stub: currently relies on Clang's own PrintingPolicy; Phase 3 will extend this to
      handle holder rewrites (e.g. unique_ptr<T> -> shared_ptr<T> when an APIARY_HOLDER directive
      is in effect) and pybind11-specific type substitutions.

   :param type: The Clang type to translate.
   :param ctx: The AST context owning `type`.
   :returns: A pretty-printed C++ form of the type.