# Functions

class gccjit.Param

class gccjit.Function
  new_local(type_, name, loc=None)

    Add a new local variable to the function:

        i = fn.new_local(int_type, b'i')

    Return type

      `gccjit.LValue`

  new_block(name)

    Create a `gccjit.Block`.

    The name can be None, or you can give it a meaningful name, which may show up in dumps of the internal representation, and in error messages:

        entry = fn.new_block('entry')
        on_true = fn.new_block('on_true')

  get_param(index)
  dump_to_dot(path)

    Write a dump in GraphViz format to the given path.

class gccjit.Block

  A gccjit.Block is a basic block within a function, i.e. a sequence of statements with a single entry point and a single exit point.

  The first basic block that you create within a function will be the entrypoint.

  Each basic block that you create within a function must be terminated, either with a conditional, a jump, or a return.

  It’s legal to have multiple basic blocks that return within one function.

  add_eval(rvalue, loc=None)

    Add evaluation of an rvalue, discarding the result (e.g. a function call that “returns” void), for example:

        call = ctxt.new_call(some_fn, args)
        block.add_eval(call)

    This is equivalent to this C code:

        (void)expression;

  add_assignment(lvalue, rvalue, loc=None)

    Add evaluation of an rvalue, assigning the result to the given lvalue, for example:

        # i = 0
        entry_block.add_assignment(local_i, ctxt.zero(the_type))

    This is roughly equivalent to this C code:

        lvalue = rvalue;

  add_assignment_op(lvalue, op, rvalue, loc=None)

    Add evaluation of an rvalue, using the result to modify an lvalue via the given `gccjit.BinaryOp`. For example:

        # i++
        loop_block.add_assignment_op(local_i,
                                     gccjit.BinaryOp.PLUS,
                                     ctxt.one(the_type))

    This is analogous to “+=” and friends:

        lvalue += rvalue;
        lvalue *= rvalue;
        lvalue /= rvalue;
        /* etc */

  add_comment(text, Location loc=None)

    Add a no-op textual comment to the internal representation of the code. It will be optimized away, but will be visible in the dumps seen via `gccjit.BoolOption.DUMP_INITIAL_TREE` and `gccjit.BoolOption.DUMP_INITIAL_GIMPLE` and thus may be of use when debugging how your project’s internal representation gets converted to the libgccjit IR.

  end_with_conditional(boolval, on_true, on_false=None, loc=None)

    Terminate a block by adding evaluation of an rvalue, branching on the result to the appropriate successor block.

    This is roughly equivalent to this C code:

        if (boolval)
          goto on_true;
        else
          goto on_false;

    Example:

        # while (i < n)
        cond_block.end_with_conditional(
          ctxt.new_comparison(gccjit.Comparison.LT, local_i, param_n),
          loop_block,
          after_loop_block)

  end_with_jump(target, loc=None)

    Terminate a block by adding a jump to the given target block.

    This is roughly equivalent to this C code:

        goto target;

    Example:

        loop_block.end_with_jump(cond_block)

  end_with_return(RValue rvalue, loc=None)

    Terminate a block by adding evaluation of an rvalue, returning the value.

    This is roughly equivalent to this C code:

        return expression;

    Example:

        # return sum
        after_loop_block.end_with_return(local_sum)

  end_with_void_return(loc=None)

    Terminate a block by adding a valueless return, for use within a function with “void” return type.

    This is equivalent to this C code:

        return;

  get_function()

    Get the `gccjit.Function` that this block is within.

class gccjit.FunctionKind
  EXPORTED
  INTERNAL
  IMPORTED
  ALWAYS_INLINE