Dart throw

Summary: in this tutorial, you’ll learn how to use the Dart throw statement to raise an exception.

Introduction to the Dart throw statement

The throw statement raises an exception in the program. The syntax of throw is:

throw e;Code language: Dart (dart)

where e is an instance of a class that implements the Exception interface.

For example, the following getCharAt() function uses the throw statement to raise an exception if the index is out of range:

String getCharAt(String s, int index) {
  if (index < 0 || index > s.length) {
    throw Exception('Index is out of range');
  }
  return s[index];
}

void main() {
  String message = 'Hello';
  String s = getCharAt(message, 10);
  print(s);
}Code language: Dart (dart)

Output:

Unhandled exception:
Exception: Index is out of rangeCode language: Dart (dart)

In this example, the getCharAt() function returns the character in a string at an index. If the index is less than 0 or greater than the string’s length, it’ll raise an exception.

To handle the exception, you use the try-catch statement. For example:

String getCharAt(String s, int index) {
  if (index < 0 || index > s.length) {
    throw Exception('Index is out of range');
  }
  return s[index];
}

void main() {
  String message = 'Hello';
  try {
    String s = getCharAt(message, 10);
    print(s);
  } catch (e) {
    print(e);
  }
}Code language: Dart (dart)

In practice, you should not throw an exception that is an instance of the Exception class. Instead, you should define a custom exception class that implements the Exception interface. For example:

class IndexOutOfRangeException implements Exception {
  String error;
  IndexOutOfRangeException(this.error);

  @override
  String toString() => error;
}

String getCharAt(String s, int index) {
  if (index < 0 || index > s.length) {
    throw IndexOutOfRangeException('Index is out of range [0..${s.length}]');
  }
  return s[index];
}

void main() {
  String message = 'Hello';
  try {
    String s = getCharAt(message, 10);
    print(s);
  } on IndexOutOfRangeException catch (e) {
    print(e);
  }
}Code language: Dart (dart)

Output:

Index is out of range [0..5]Code language: Dart (dart)

How it works.

First, define an IndexOutOfRangeException class that implements the Exception interface:

class IndexOutOfRangeException implements Exception {
  String error;
  IndexOutOfRangeException(this.error);

  @override
  String toString() => error;
}Code language: Dart (dart)

Second, raise IndexOutOfRangeException in the getCharAt() function:

String getCharAt(String s, int index) {
  if (index < 0 || index > s.length) {
    throw IndexOutOfRangeException('Index is out of range [0..${s.length}]');
  }
  return s[index];
}Code language: Dart (dart)

Third, handle the exception in the main() function:

void main() {
  String message = 'Hello';
  try {
    String s = getCharAt(message, 10);
    print(s);
  } on IndexOutOfRangeException catch (e) {
    print(e);
  }
}Code language: Dart (dart)

Dart rethrow

Sometimes, you want to log the exception and rethrow it. To do that, you use the rethrow statement. For example:

class IndexOutOfRangeException implements Exception {
  String error;
  IndexOutOfRangeException(this.error);

  @override
  String toString() => error;
}

String getCharAt(String s, int index) {
  if (index < 0 || index > s.length) {
    throw IndexOutOfRangeException('Index is out of range [0..${s.length}]');
  }
  return s[index];
}

void main() {
  String message = 'Hello';
  try {
    String s = getCharAt(message, 10);
    print(s);
  } on IndexOutOfRangeException catch (e) {
    // log to the console
    print(e);
    rethrow;
  }
}Code language: Dart (dart)

In this example, we log the error message to the screen and rethrow the same exception.

Summary

• Use the Dart throw statement to raise an exception.
• Use the rethrow statement to raise the same exception.