=====
Types
=====

.. currentmodule:: llvmlite.ir

.. contents::
   :local:
   :depth: 1


All :ref:`values <ir-values>` used in an LLVM module are
explicitly typed. All types derive from a common base class
:class:`Type`. You can instantiate most of them directly. Once
instantiated, a type should be considered immutable.

.. class:: Type

   The base class for all types.  Never instantiate it directly.
   Types have the following methods in common:

   * .. method:: as_pointer(addrspace=0)

        Return a :class:`PointerType` pointing to this type. The
        optional *addrspace* integer allows you to choose a
        non-default address space---the meaning is platform
        dependent.

   * .. method:: get_abi_size(target_data)

        Get the ABI size of this type, in bytes, according to the
        *target_data*---an :class:`llvmlite.binding.TargetData`
        instance.

   * .. method:: get_abi_alignment(target_data)

        Get the ABI alignment of this type, in bytes, according
        to the *target_data*---an
        :class:`llvmlite.binding.TargetData` instance.

        NOTE: :meth:`get_abi_size` and :meth:`get_abi_alignment`
        call into the LLVM C++ API to get the requested
        information.

   * .. method:: __call__(value)

        A convenience method to create a :class:`Constant` of
        this type with the given *value*::

           >>> int32 = ir.IntType(32)
           >>> c = int32(42)
           >>> c
           <ir.Constant type='i32' value=42>
           >>> print(c)
           i32 42


Atomic types
=============

.. class:: PointerType(pointee, addrspace=0)

   The type of pointers to another type.

   Pointer types expose the following attributes:

   * .. attribute:: addrspace

        The pointer's address space number. This optional integer
        allows you to choose a non-default address space---the
        meaning is platform dependent.

   * .. attribute:: pointee

        The type pointed to.


.. class:: IntType(bits)

   The type of integers. The Python integer *bits* specifies the
   bitwidth of the integers having this type.

   .. attribute:: width

      The width in bits.

.. class:: HalfType()

   The type of half-precision, floating-point, real numbers.

   NOTE: On Python 3.5 and earlier, constants won't be rounded
   to valid fp16 numbers, and so may generate invalid IR. In this
   case, use rounding code like ``float(np.float16(1.12312321e-2))``
   before calling :class:`IRBuilder` methods.


.. class:: FloatType()

   The type of single-precision, floating-point, real numbers.


.. class:: DoubleType()

   The type of double-precision, floating-point, real numbers.


.. class:: VoidType()

   The class for void types. Used only as the return type of a
   function without a return value.


.. _aggregate-types:

Aggregate types
================

.. class:: Aggregate

   The base class for aggregate types. Never instantiate it
   directly. Aggregate types have the elements attribute in
   common.

   .. attribute:: elements

      A tuple-like immutable sequence of element types for this
      aggregate type.

.. class:: ArrayType(element, count)

   The class for array types.

   * *element* is the type of every element.
   * *count* is a Python integer representing the number of
     elements.

.. class:: VectorType(element, count)

   The class for vector types.

   * *element* is the type of every element.
   * *count* is a Python integer representing the number of
     elements.

.. class:: LiteralStructType(elements, [packed=False])

   The class for literal struct types.

   * *elements* is a sequence of element types for each member of the structure.
   * *packed* controls whether to use packed layout.

.. class:: IdentifiedStructType

   The class for identified struct types.  Identified structs are
   compared by name.  It can be used to make opaque types.

   Users should not create new instance directly.  Use the
   ``Context.get_identified_type`` method instead.

   An identified struct is created without a body (thus opaque).  To define the
   struct body, use the ``.set_body`` method.

   .. method:: set_body(*elems)

      Define the structure body with a sequence of element types.


Other types
============

.. class:: FunctionType(return_type, args, var_arg=False)

   The type of a function.

   * *return_type* is the return type of the function.
   * *args* is a sequence describing the types of argument to the
     function.
   * If *var_arg* is ``True``, the function takes a variable
     number of additional arguments of unknown types after the
     explicit args.

     EXAMPLE::

        int32 = ir.IntType(32)
        fnty = ir.FunctionType(int32, (ir.DoubleType(), ir.PointerType(int32)))

     An equivalent C declaration would be:

     .. code-block:: C

        typedef int32_t (*fnty)(double, int32_t *);


.. class:: LabelType

   The type for :ref:`labels <label>`.  You do not need to
   instantiate this type.

.. class:: MetaDataType

   The type for :ref:`metadata`. You do not need to
   instantiate this type.

   NOTE: This class was previously called "MetaData," but it was
   renamed for clarity.
