Макрос unreachable!

Макрос unreachable! используется для обозначения кода, который по логике программы никогда не должен выполняться. Если выполнение всё же доходит до этого места, макрос вызывает панику с сообщением internal error: entered unreachable code. Макрос может принимать необязательное сообщение, которое будет выведено при панике. Это удобно для отладки и документирования предположений о работе программы.

Макрос часто применяется в местах, где компилятор не может самостоятельно доказать недостижимость кода, например, после исчерпывающей проверки всех вариантов в match, или в ветках, которые невозможны по логике алгоритма. В отличие от panic!, макрос unreachable! явно сообщает о намерении программиста: этот код не должен выполняться никогда.

Синтаксис

unreachable!();
unreachable!("сообщение");
unreachable!("сообщение {}", аргумент);

Пример

Давайте рассмотрим простой пример, где значение переменной гарантированно находится в известном диапазоне, и все варианты обработаны:

fn main()
{
	let x = 2;
	
	match x
	{
		1 => println!("one"),
		2 => println!("two"),
		3 => println!("three"),
		_ => unreachable!(),
	}
}

Результат выполнения кода:

"two"

Пример

Давайте посмотрим, что произойдёт, если выполнение всё же дойдёт до макроса unreachable! с пользовательским сообщением:

fn main()
{
	let x = 5;
	
	match x
	{
		1 => println!("one"),
		2 => println!("two"),
		3 => println!("three"),
		_ => unreachable!("unexpected value: {}", x),
	}
}

Результат выполнения кода:

thread 'main' panicked at 'unexpected value: 5', src/main.rs:10:9
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Смотрите также

макрос todo!,
который помечает код как ещё не реализованный
макрос unimplemented!,
который помечает код как нереализованный
оператор match,
который часто используется вместе с unreachable!
оператор return,
который выполняет досрочный выход из функции