IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /docs/manual/basics.md). For the complete Mojo documentation index, see llms.txt.
Skip to main content
Version: 1.0.0b1
For the complete Mojo documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md).

debug_assert

debug_assert[cond: def() capturing -> Bool, assert_mode: StringSlice[StaticConstantOrigin] = StringSlice("none"), *Ts: Writable = *?, *, cpu_only: Bool = False](*messages: *Ts.values, *, location: Optional[SourceLocation] = None)

Asserts that the condition is true at run time.

If the condition is false, the assertion displays the given message and causes the program to exit.

You can pass in multiple arguments to generate a formatted message. No string allocation occurs unless the assertion is triggered.

var x = 0
debug_assert(x > 0, "expected x to be more than 0 but got: ", x)

Normal assertions are off by default—they only run when the program is compiled with all assertions enabled. You can set the assert_mode to safe to create an assertion that's on by default:

var x = 0
debug_assert[assert_mode="safe"](
    x > 0, "expected x to be more than 0 but got: ", x
)

Use the ASSERT variable to turn assertions on or off when building or running a Mojo program:

mojo -D ASSERT=all main.mojo

The ASSERT variable takes the following values:

  • all: Turn on all assertions.
  • safe: Turn on "safe" assertions only. This is the default.
  • none: Turn off all assertions, for performance at the cost of safety.
  • warn: Turn on all assertions, but print any errors instead of exiting.

To ensure that you have no run-time penalty from your assertions even when they're disabled, make sure there are no side effects in your message and condition expressions. For example:

var person = "name: john, age: 50"
var name = "john"
debug_assert(String("name: ", name) in person, "unexpected name")

This will have a run-time penalty due to allocating a String in the condition expression, even when assertions are disabled. To avoid this, put the condition inside a closure so it runs only when the assertion is turned on:

def main():
    var person = "name: john, age: 50"
    var name = "john"

    def check_name() capturing -> Bool:
        return String("name: ", name) in person

    debug_assert[check_name]("unexpected name")

If you need to allocate, and so don't want the assert to ever run on GPU, you can set it to CPU only:

def main():
    var person = "name: john, age: 50"
    var name = "john"

    def check_name() capturing -> Bool:
        return String("name: ", name) in person

    debug_assert[check_name, cpu_only=True]("unexpected name")

For compile-time assertions, see constrained().

Parameters:

  • ​cond (def() capturing -> Bool): The function to invoke to check if the assertion holds.
  • ​assert_mode (StringSlice[StaticConstantOrigin]): Determines when the assert is turned on.
    • default ("none"): Turned on when compiled with -D ASSERT=all.
    • "safe": Turned on by default.
  • ​*Ts (Writable): The element types for the message arguments.
  • ​cpu_only (Bool): If true, only run the assert on CPU.

Args:

  • ​*messages (*Ts.values): A set of Writable arguments to convert to a String message.
  • ​location (Optional[SourceLocation]): Source location to report on assertion failure.

debug_assert[assert_mode: StringSlice[StaticConstantOrigin] = StringSlice("none"), *Ts: Writable = *?, *, cpu_only: Bool = False, _use_compiler_assume: Bool = False](cond: Bool, *messages: *Ts.values, *, location: Optional[SourceLocation] = None)

Asserts that the condition is true at run time.

If the condition is false, the assertion displays the given message and causes the program to exit.

You can pass in multiple arguments to generate a formatted message. No string allocation occurs unless the assertion is triggered.

var x = 0
debug_assert(x > 0, "expected x to be more than 0 but got: ", x)

Normal assertions are off by default—they only run when the program is compiled with all assertions enabled. You can set the assert_mode to safe to create an assertion that's on by default:

var x = 0
debug_assert[assert_mode="safe"](
    x > 0, "expected x to be more than 0 but got: ", x
)

Use the ASSERT variable to turn assertions on or off when building or running a Mojo program:

mojo -D ASSERT=all main.mojo

The ASSERT variable takes the following values:

  • all: Turn on all assertions.
  • safe: Turn on "safe" assertions only. This is the default.
  • none: Turn off all assertions, for performance at the cost of safety.
  • warn: Turn on all assertions, but print any errors instead of exiting.

To ensure that you have no run-time penalty from your assertions even when they're disabled, make sure there are no side effects in your message and condition expressions. For example:

var person = "name: john, age: 50"
var name = "john"
debug_assert(String("name: ", name) in person, "unexpected name")

This will have a run-time penalty due to allocating a String in the condition expression, even when assertions are disabled. To avoid this, put the condition inside a closure so it runs only when the assertion is turned on:

def main():
    var person = "name: john, age: 50"
    var name = "john"

    def check_name() capturing -> Bool:
        return String("name: ", name) in person

    debug_assert[check_name]("unexpected name")

If you need to allocate, and so don't want the assert to ever run on GPU, you can set it to CPU only:

def main():
    var person = "name: john, age: 50"
    var name = "john"

    def check_name() capturing -> Bool:
        return String("name: ", name) in person

    debug_assert[check_name, cpu_only=True]("unexpected name")

For compile-time assertions, see constrained().

Parameters:

  • ​assert_mode (StringSlice[StaticConstantOrigin]): Determines when the assert is turned on.
    • default ("none"): Turned on when compiled with -D ASSERT=all.
    • "safe": Turned on by default.
  • ​*Ts (Writable): The element types for the message arguments.
  • ​cpu_only (Bool): If true, only run the assert on CPU.
  • ​_use_compiler_assume (Bool): If true, assume the condition is true for repeated checks, to help the compiler optimize (default False).

Args:

  • ​cond (Bool): The bool value to assert.
  • ​*messages (*Ts.values): A set of Writable arguments to convert to a String message.
  • ​location (Optional[SourceLocation]): Source location to report on assertion failure.

debug_assert[assert_mode: StringSlice[StaticConstantOrigin] = StringSlice("none"), cpu_only: Bool = False, _use_compiler_assume: Bool = False](cond: Bool, message: StringLiteral)

Asserts that the condition is true at run time.

If the condition is false, the assertion displays the given message and causes the program to exit.

You can pass in multiple arguments to generate a formatted message. No string allocation occurs unless the assertion is triggered.

var x = 0
debug_assert(x > 0, "expected x to be more than 0 but got: ", x)

Normal assertions are off by default—they only run when the program is compiled with all assertions enabled. You can set the assert_mode to safe to create an assertion that's on by default:

var x = 0
debug_assert[assert_mode="safe"](
    x > 0, "expected x to be more than 0 but got: ", x
)

Use the ASSERT variable to turn assertions on or off when building or running a Mojo program:

mojo -D ASSERT=all main.mojo

The ASSERT variable takes the following values:

  • all: Turn on all assertions.
  • safe: Turn on "safe" assertions only. This is the default.
  • none: Turn off all assertions, for performance at the cost of safety.
  • warn: Turn on all assertions, but print any errors instead of exiting.

To ensure that you have no run-time penalty from your assertions even when they're disabled, make sure there are no side effects in your message and condition expressions. For example:

var person = "name: john, age: 50"
var name = "john"
debug_assert(String("name: ", name) in person, "unexpected name")

This will have a run-time penalty due to allocating a String in the condition expression, even when assertions are disabled. To avoid this, put the condition inside a closure so it runs only when the assertion is turned on:

def main():
    var person = "name: john, age: 50"
    var name = "john"

    def check_name() capturing -> Bool:
        return String("name: ", name) in person

    debug_assert[check_name]("unexpected name")

If you need to allocate, and so don't want the assert to ever run on GPU, you can set it to CPU only:

def main():
    var person = "name: john, age: 50"
    var name = "john"

    def check_name() capturing -> Bool:
        return String("name: ", name) in person

    debug_assert[check_name, cpu_only=True]("unexpected name")

For compile-time assertions, see constrained().

Parameters:

  • ​assert_mode (StringSlice[StaticConstantOrigin]): Determines when the assert is turned on.
    • default ("none"): Turned on when compiled with -D ASSERT=all.
    • "safe": Turned on by default.
  • ​cpu_only (Bool): If true, only run the assert on CPU.
  • ​_use_compiler_assume (Bool): If true, assume the condition is true for repeated checks, to help the compiler optimize (default False).

Args:

  • ​cond (Bool): The bool value to assert.
  • ​message (StringLiteral): A static string message.
View source