# Values

A Module consists mostly of values.

llvmlite.ir.Undefined

  An undefined value, mapping to LLVM’s `undef`.

class llvmlite.ir.Value

  The base class for all IR values.

class llvmlite.ir._ConstOpMixin

  This is the base class for `Constant` and `GlobalValue`; do not instantiate it directly.

  Integer arithmetic operations:

  - add(other)

      Integer add self and other.

  - sub(other)

      Integer subtract other from self.

  - mul(other)

      Integer multiply self with other.

  - udiv(other)

      Unsigned integer divide self by other.

  - sdiv(other)a

      Signed integer divide self by other.

  - urem(other)

      Unsigned integer remainder of self divided by other.

  - srem(other)

      Signed integer remainder of self divided by other.

  - neg()

      Negate self.

  Integer logical operations:

  - shl(other)

      Left-shift self by other bits.

  - ashr(other)

      Arithmetic, signed, right-shift self by other bits.

  - lshr(other)

      Logical right-shift self by other bits.

  - or_(other)

      Bitwise OR self with other.

  - and_(other)

      Bitwise AND self with other.

  - xor(other)

      Bitwise XOR self with other.

  Floating point arithmetic:

  - fadd(other)

      Floating-point add self and other.

  - fsub(other)

      Floating-point subtract other from self.

  - fmul(other)

      Floating-point multiply self by other.

  - fdiv(other)

      Floating-point divide self by other.

  - frem(other)

      Floating-point remainder of self divided by other.

  Comparisons:

  - icmp_signed(cmpop, other)

      Signed integer compare self with other. The string cmpop can be one of `<`, `<=`, `==`, `!=`, `>=` or `>`.

  - icmp_unsigned(cmpop, other)

      Unsigned integer compare self with other. The string cmpop can be one of `<`, `<=`, `==`, `!=`, `>=` or `>`.

  - fcmp_ordered(cmpop, other)

      Floating-point ordered compare self with other. The string cmpop can be one of `<`, `<=`, `==`, `!=`, `>=` or `>`.

  - fcmp_unordered(cmpop, other)

      Floating-point unordered compare self with other. The string cmpop can be one of `<`, `<=`, `==`, `!=`, `>=` or `>`.

  Integer casts:

  - trunc(typ)

      Truncate self to integer type typ.

  - zext(typ)

      Zero-extend self to integer type typ.

  - sext(typ)

      Sign-extend self to integer type typ.

  - bitcast(typ)

      Convert this pointer constant to a constant of the given pointer type typ.

  Floating-point casts:

  - fptrunc(typ)

      Truncate (approximate) floating-point value self to floating-point type typ.

  - fpext(typ)

      Extend floating-point value self to floating-point type typ.

  Integer / floating-point conversion:

  - fptoui(typ)

      Convert floating-point value self to unsigned integer type typ.

  - uitofp(typ)

      Convert unsigned integer value self to floating-point type typ.

  - fptosi(typ)

      Convert floating-point value self to signed integer type typ.

  - sitofp(typ)

      Convert signed integer value self to floating-point type typ.

  Integer / pointer conversions:

  - inttoptr(typ)

      Convert this integer constant self to a constant of the given pointer type typ.

  - ptrtoint(typ)

      Convert this pointer constant self to a constant of the given integer type typ.

class llvmlite.ir.Constant(typ, constant)

  A literal value.

  - typ is the type of the represented value—a `Type` instance.

  - constant is the Python value to be represented.

  Which Python types are allowed for constant depends on typ:

  - All types accept `Undefined` and convert it to LLVM’s `undef`.

  - All types accept `None` and convert it to LLVM’s `zeroinitializer`.

  - `IntType` accepts any Python integer or boolean.

  - `FloatType` and `DoubleType` accept any Python real number.

  - Aggregate types—array and structure types—accept a sequence of Python values corresponding to the type’s element types.

  - `ArrayType` accepts a single `bytearray` instance to initialize the array from a string of bytes. This is useful for character constants.

  See also `_ConstOpMixin`.

  classmethod literal_array(elements)

    An alternate constructor for constant arrays.

    - elements is a sequence of values, `Constant` or otherwise.

    - All elements must have the same type.

    - Returns a constant array containing the elements, in order.

  classmethod literal_struct(elements, packed=False)

    An alternate constructor for constant structs.

    - elements is a sequence of values, `Constant` or otherwise.

    - packed controls whether to use packed layout.

    - Returns a constant struct containing the elements in order.

  gep(indices)

    Compute the address of the inner element given by the sequence of indices. The constant must have a pointer type.

  NOTE: You cannot define constant functions. Use a Function declaration instead.

class llvmlite.ir.Argument

  One of a function’s arguments. Arguments have the `add_attribute()` method.

  add_attribute(attr)

    Add an argument attribute to this argument. attr is a Python string.

class llvmlite.ir.Block

  A Basic block. Do not instantiate or mutate this type directly. Instead, call the helper methods on `Function` and `IRBuilder`.

  Basic blocks have the following methods and attributes:

  - replace(old, new)

      Replace the instruction old with the other instruction new in this block’s list of instructions. All uses of old in the whole function are also patched. old and new are `Instruction` objects.

  - function

      The function this block is defined in.

  - is_terminated

      Whether this block ends with a terminator instruction.

  - terminator

      The block’s terminator instruction, if any. Otherwise `None`.

class llvmlite.ir.BlockAddress

  A constant representing an address of a basic block.

  Block address constants have the following attributes:

  - function

      The function in which the basic block is defined.

  - basic_block

      The basic block. Must be a part of `function`.

## Metadata

There are several kinds of Metadata values.

class llvmlite.ir.MetaDataString(module, value)

  A string literal for use in metadata.

  - module is the module that the metadata belongs to.

  - value is a Python string.

class llvmlite.ir.MDValue

  A metadata node. To create an instance, call `Module.add_metadata()`.

class llvmlite.ir.DIValue

  A debug information descriptor, containing key-value pairs. To create an instance, call `Module.add_debug_info()`.

class llvmlite.ir.DIToken(value)

  A debug information “token,” representing a well-known enumeration value. value is the enumeration name.

  EXAMPLE: `'DW_LANG_Python'`

class llvmlite.ir.NamedMetaData

  A named metadata node. To create an instance, call `Module.add_named_metadata()`. `NamedMetaData` has the `add()` method:

  add(md)

    Append the given piece of metadata to the collection of operands referred to by the `NamedMetaData`. md can be either a `MetaDataString` or a `MDValue`.

## Global values

Global values are values accessible using a module-wide name.

class llvmlite.ir.GlobalValue

  The base class for global values. Global values have the following writable attributes:

  - linkage

      A Python string describing the linkage behavior of the global value—for example, whether it is visible from other modules. The default is the empty string, meaning “external.”

  - storage_class

      A Python string describing the storage class of the global value.

      - The default is the empty string, meaning “default.”

      - Other possible values include `dllimport` and `dllexport`.

  - section

      A Python string describing the section a global value should be in after translation. The default is the empty string, meaning no specific section.

  See also `_ConstOpMixin`.

class llvmlite.ir.GlobalVariable(module, typ, name, addrspace=0)

  A global variable.

  - module is where the variable is defined.

  - typ is the variable’s type. It cannot be a function type. To declare a global function, use `Function`.

    The type of the returned Value is a pointer to typ. To read the contents of the variable, you need to `load()` from the returned Value. To write to the variable, you need to `store()` to the returned Value.

  - name is the variable’s name—a Python string.

  - addrspace is an optional address space to store the variable in.

  Global variables have the following writable attributes:

  - set_metadata(name, node)

      Add metadata with the given name, pointing to the given metadata node—an instance of `MDValue`.

  - global_constant

      - If `True`, the variable is declared a constant, meaning that its contents cannot be modified.

      - The default is `False`.

  - unnamed_addr

      - If `True`, the address of the variable is deemed insignificant, meaning that it is merged with other variables that have the same initializer.

      - The default is `False`.

  - initializer

      The variable’s initialization value—probably a `Constant` of type typ. The default is `None`, meaning that the variable is uninitialized.

  - align

      An explicit alignment in bytes. The default is `None`, meaning that the default alignment for the variable’s type is used.

class llvmlite.ir.Function(module, typ, name)

  A global function.

  - module is where the function is defined.

  - typ is the function’s type—a `FunctionType` instance.

  - name is the function’s name—a Python string.

  If a global function has any basic blocks, it is a Function definition. Otherwise, it is a Function declaration.

  Functions have the following methods and attributes:

  - append_basic_block(name='')

      Append a Basic block to this function’s body.

      - If name is not empty, it names the block’s entry Label.

      - Returns a new `Block`.

  - insert_basic_block(before, name='')

      Similar to `append_basic_block()`, but inserts it before the basic block before in the function’s list of basic blocks.

  - set_metadata(name, node)

      Add a function-specific metadata named name pointing to the given metadata node—an `MDValue`.

  - args

      The function’s arguments as a tuple of `Argument` instances.

  - attributes

      A set of function attributes. Each optional attribute is a Python string. By default this is empty. Use the .add() method to add an attribute:

          fnty = ir.FunctionType(ir.DoubleType(), (ir.DoubleType(),))
          fn = Function(module, fnty, "sqrt")
          fn.attributes.add("alwaysinline")

  - calling_convention

      The function’s calling convention—a Python string. The default is the empty string.

  - is_declaration

      Indicates whether the global function is a declaration or a definition.

      - If `True`, it is a declaration.

      - If `False`, it is a definition.

## Instructions

Every Instruction is also a value:

- It has a name—the recipient’s name.

- It has a well-defined type.

- It can be used as an operand in other instructions or in literals.

Usually, you should not instantiate instruction types directly. Use the helper methods on the `IRBuilder` class.

class llvmlite.ir.Instruction

  The base class for all instructions. Instructions have the following method and attributes:

  - set_metadata(name, node)

      Add an instruction-specific metadata name pointing to the given metadata node—an `MDValue`.

  - replace_usage(old, new)

      Replace the operand old with the other instruction new.

  - function

      The function that contains this instruction.

  - module

      The module that defines this instruction’s function.

class llvmlite.ir.PredictableInstr

  The class of instructions for which we can specify the probabilities of different outcomes—for example, a switch or a conditional branch. Predictable instructions have the `set_weights()` method.

  set_weights(weights)

    Set the weights of the instruction’s possible outcomes. weights is a sequence of positive integers, each corresponding to a different outcome and specifying its relative probability compared to other outcomes. The greater the number, the likelier the outcome.

class llvmlite.ir.SwitchInstr

  A switch instruction. Switch instructions have the `add_case()` method.

  add_case(val, block)

    Add a case to the switch instruction.

    - val should be a `Constant` or a Python value compatible with the switch instruction’s operand type.

    - block is a `Block` to jump to if val and the switch operand compare equal.

class llvmlite.ir.IndirectBranch

  An indirect branch instruction. Indirect branch instructions have the `add_destination()` method.

  add_destination(value, block)

    Add an outgoing edge. The indirect branch instruction must refer to every basic block it can transfer control to.

class llvmlite.ir.PhiInstr

  A phi instruction. Phi instructions have the `add_incoming()` method.

  add_incoming(value, block)

    Add an incoming edge. Whenever transfer is controlled from block—a `Block`—the phi instruction takes the given value.

class llvmlite.ir.LandingPad

  A landing pad. Landing pads have the `add_clause()` method:

  add_clause(value, block)

    Add a catch or filter clause. Create catch clauses using `CatchClause` and filter clauses using `FilterClause`.

## Landing pad clauses

Landing pads have the following classes associated with them.

class llvmlite.ir.CatchClause(value)

  A catch clause. Instructs the personality function to compare the in-flight exception typeinfo with value, which should have type IntType(8).as_pointer().as_pointer().

class llvmlite.ir.FilterClause(value)

  A filter clause. Instructs the personality function to check inclusion of the the in-flight exception typeinfo in value, which should have type ArrayType(IntType(8).as_pointer().as_pointer(), …).