Block

def delete(self, safe: bool = True) -> None:
    """Delete the Block completely from the IR.

    Note:
        This method will detach + remove references of the block.

    Args:
        safe (bool, optional): If True, raise error if there is anything that still reference components in the block. Defaults to True.
    """
    self.detach()
    self.drop_all_references()
    for stmt in self.stmts:
        stmt.delete(safe=safe)

def detach(self) -> None:
    """Detach this Block from the IR.

    Note:
        Detach only detach the Block from the IR graph. It does not remove uses that reference the Block.
    """
    if self.parent is None:
        return

    idx = self.parent[self]
    del self.parent._blocks[idx]
    del self.parent._block_idx[self]
    for block in self.parent._blocks[idx:]:
        self.parent._block_idx[block] -= 1
    self.parent = None

def drop_all_references(self) -> None:
    """Remove all the dependency that reference/uses this Block."""
    self.parent = None
    for stmt in self.stmts:
        stmt.drop_all_references()

def is_structurally_equal(
    self,
    other: Self,
    context: dict[IRNode | SSAValue, IRNode | SSAValue] | None = None,
) -> bool:
    """Check if the Block is structurally equal to another Block.

    Args:
        other (Self): The other Block to compare with.
        context (dict[IRNode  |  SSAValue, IRNode  |  SSAValue] | None, optional): A map of IRNode/SSAValue to hint that they are equivalent so the check will treat them as equivalent. Defaults to None.

    Returns:
        bool: True if the Block is structurally equal to the other Block.
    """
    if context is None:
        context = {}

    if len(self._args) != len(other._args) or len(self.stmts) != len(other.stmts):
        return False

    for arg, other_arg in zip(self._args, other._args):
        if arg.type != other_arg.type:
            return False
        context[arg] = other_arg

    context[self] = other
    if not all(
        stmt.is_structurally_equal(other_stmt, context)
        for stmt, other_stmt in zip(self.stmts, other.stmts)
    ):
        return False

    return True

def verify(self) -> None:
    """Verify the correctness of the Block.

    Raises:
        ValidationError: If the Block is not correct.
    """
    from kirin.ir.nodes.stmt import Region

    if not isinstance(self.parent, Region):
        raise ValidationError(self, "Parent is not a region")

    for stmt in self.stmts:
        stmt.verify()

def verify_type(self) -> None:
    """Verify the types of the Block.

    Raises:
        ValidationError: If the Block is not correct.
    """
    for stmt in self.stmts:
        stmt.verify_type()

def walk(
    self, *, reverse: bool = False, region_first: bool = False
) -> Iterator[Statement]:
    """Traversal the Statements in a Block.

    Args:
        reverse (bool, optional): If walk in the reversed manner. Defaults to False.
        region_first (bool, optional): If the walk should go through the Statement first or the Region of a Statement first. Defaults to False.

    Yields:
        Iterator[Statement]: An iterator that yield Statements in the Block in the specified order.
    """
    for stmt in reversed(self.stmts) if reverse else self.stmts:
        yield from stmt.walk(reverse=reverse, region_first=region_first)

def append_from(self, typ: TypeAttribute, name: str | None = None) -> BlockArgument:
    """Append a new argument to the Block that this View reference to.

    Description:
        This method will create a new [`BlockArgument`][kirin.ir.BlockArgument] and append it to the argument list
        of the reference `Block`.

    Args:
        typ (TypeAttribute): The type of the argument.
        name (str | None, optional): name of the argument. Defaults to `None`.

    Returns:
        BlockArgument: The newly created [`BlockArgument`][kirin.ir.BlockArgument].

    """
    new_arg = BlockArgument(self.node, len(self.node._args), typ)
    if name:
        new_arg.name = name

    self.node._args += (new_arg,)
    return new_arg

def delete(self, arg: BlockArgument, safe: bool = True) -> None:
    """Delete a BlockArgument from the Block that this View reference to.


    Args:
        arg (BlockArgument): _description_
        safe (bool, optional): If True, error will be raised if the BlockArgument has any Use by others.  Defaults to True.

    Raises:
        ValueError: If the argument does not belong to the reference block.
    """
    if safe and len(arg.uses) > 0:
        raise ValueError("Cannot delete SSA value with uses")

    if arg.block is not self.node:
        raise ValueError("Attempt to delete an argument that is not in the block")

    for block_arg in self.field[arg.index + 1 :]:
        block_arg.index -= 1
    self.node._args = (*self.field[: arg.index], *self.field[arg.index + 1 :])
    arg.replace_by(DeletedSSAValue(arg))

def insert_from(
    self, idx: int, typ: TypeAttribute, name: str | None = None
) -> BlockArgument:
    """Insert a new argument to the Block that this View reference to.

    Description:
        This method will create a new `BlockArgument` and insert it to the argument list
        of the reference Block at the specified index

    Args:
        idx (int): Insert location index.
        typ (TypeAttribute): The type of the argument.
        name (str | None, optional): Name of the argument. Defaults to `None`.

    Returns:
        BlockArgument: The newly created BlockArgument.
    """
    if idx < 0 or idx > len(self.node._args):
        raise ValueError("Invalid index")

    new_arg = BlockArgument(self.node, idx, typ)
    if name:
        new_arg.name = name

    for arg in self.node._args[idx:]:
        arg.index += 1
    self.node._args = self.node._args[:idx] + (new_arg,) + self.node._args[idx:]
    return new_arg

def append(self, value: Statement) -> None:
    """Append a Statement to the reference Block.

    Args:
        value (Statement): A Statement to be appended.
    """
    from kirin.ir.nodes.stmt import Statement

    if not isinstance(value, Statement):
        raise ValueError(f"Expected Statement, got {type(value).__name__}")

    if self.node._stmt_len == 0:  # empty block
        value.attach(self.node)
        self.node._first_stmt = value
        self.node._last_stmt = value
        self.node._stmt_len += 1
    elif self.node._last_stmt:
        value.insert_after(self.node._last_stmt)
    else:
        raise ValueError("Invalid block, last_stmt is None")

def at(self, index: int) -> Statement:
    """This is similar to __getitem__ but due to the nature of the linked list,
    it is less efficient than __getitem__.

    Args:
        index (int): Index of the Statement.

    Returns:
        Statement: The Statement at the specified index.
    """
    if index >= len(self):
        raise IndexError("Index out of range")

    if index < 0:
        return self._at_reverse(-index - 1)

    return self._at_forward(index)