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.