Overview

Dart is a general purpose, strongly typed, programming language from Google. It has a "sound type system" which means it can never be in an unknown state. Dart was first announced in October, 2012.

The original goal of Dart was to be an alternative to JavaScript for running code in web browsers. The Chrome browser planned to include a Dart VM for this purpose, but that plan has been abandoned in favor of compiling to JavaScript.

Currently Dart is primarily used by the Flutter framework for building mobile, web, and desktop applications.

The syntax of Dart is somewhat similar to Java. Statements are terminated by semi-colons. Parentheses surround conditions. Curly braces surround blocks of code. Indentation is typically two spaces.

Dart supports operator overloading to define the meaning of operators when applied to instances of custom classes.

Resources

• Dart home page
• Dart Language Specification
• Effective Dart - tips to "write consistent, robust, and fast code"
• Dart Complete Course - on Youtube by Flutterly/WCKD
• DartPad - web-based editor for experimenting with Dart

Editors

Many code editors can be used for writing Dart programs. Popular options include VS Code, Intellij IDEA, and Android Studio. DartPad is an online editor for experimenting with Dart features.

Recommended VS Code extensions for Dart include:

• Dart

  "Provides tools for effectively editing, refactoring, running, and reloading Flutter mobile apps." For example, place the cursor over an undefined name, click the lightbulb icon or open the Command Palette, and select "Import library ...".

  This extension provides many command palette entries including "Dart: Add Dependency" and "Dart: Add Dev Dependency". These prompt for a pub.dev library name, update the pubspec.yaml file, and download the library.

• Dart Data Class Generator

  "Create dart data classes easily, fast and without writing boilerplate or running code generation."

  To generate a constructor for a class definition that has final properties and no constructor, place the cursor over one of the properties, press cmd-period, and select "Create constructor for final fields" from the context menu.

  To generate many methods for a class definition that has final properties and no constructor, open the Command Palette and select "Dart Data Class Generator: Generate from class properties". This generates a constructor that takes named parameters, and the following methods: copyWith, fromJson, fromMap, hashCode, toMap, toString, and operator ==.

• Pubspec Assist

  "To easily add dependencies to your Dart and Flutter project's pubspec.yaml."

pub

The official Dart package manager is pub. This is similar to npm for Node.js. In the same way that npm relies on the files package.json and package-lock.json to manage dependencies, pub relies on the files pubspec.yaml and pubspec.lock (also a YAML file).

pub.dev

pub.dev is the official package repository for Dart and Flutter apps. Packages here are listed in five catagories: "Flutter Favorites", "Most popular packages", "Top Flutter packages", "Top Dart packages", and "Package of the Week".

There are two kinds of packages. "Library packages" are used as dependencies of other packages. "Application packages" are meant to be run and can depend on library packages.

Some notable packages to consider using include:

• data_table_2

  This is a "substitute for Flutter's stock DataTable and PaginatedDataTable widgets with fixed header/sticky top row and other useful features missing in the originals."

• drift

  "Drift is a reactive persistence library for Flutter and Dart, built on top of sqlite."

• fpdart

  "Functional programming in Dart and Flutter. All the main functional programming types and patterns fully documented, tested, and with examples."

• http

  "A composable, multi-platform, Future-based API for HTTP requests."

• json_serializable

  "Automatically generate code for converting to and from JSON by annotating Dart classes."

• hive

  "Lightweight and blazing fast key-value database"

• lints

  "Official Dart lint rules. Defines the 'core' and 'recommended' set of lints suggested by the Dart team."
  Use of these lint rules is enabled by the following line found in the analysis_options.yaml file:

  include: package:lints/recommended.yaml

  Edit the analysis_options.yaml file to configure the use of specific rules. An older set of lint rules called pedantic is deprecated. Another set of lint rules to consider using is Very Good Analysis.

  Here are some recommended rule configurations that include suppressing warnings about use of the const keyword:

  avoid_print: false
  prefer_const_constructors: false
  prefer_const_constructors_in_immutables: false
  prefer_const_literals_to_create_immutables: false
  prefer_single_quotes: true

• nil

  This is "a simple widget to add in the widget tree when you want to show nothing. Sometimes, according to a condition, we want to display nothing. Usually when we can't return null, we would return something like const SizedBox()."

• sqflite

  "SQLite plugin for Flutter."

• status_change

  This is a Flutter widget that displays progress through a set of wizard steps.

• supabase

  "Supabase is an open source Firebase alternative. We are a service to:"

  • listen to database changes
  • query your tables, including filtering, pagination, and deeply nested relationships (like GraphQL)
  • create, update, and delete rows
  • manage your users and their permissions
  • interact with your database using a simple UI

Creating and Running Programs

Dart source files have a .dart file extension. It is recommended that their names be all lowercase with multiple words separated by underscores.

The main function defines the starting point of a program. It is passed a List of command-line arguments. The type can be omitted, specified as just List, or specified as List<String>.

main(args) {
  args.forEach((arg) => print('arg = $arg'));
}

To run a .dart file that defines a main function, enter dart {name}.dart [arguments].

It is not necessary to create a Dart "project" in order to write and run Dart code, but doing so provides many benefits. It gives a project a standard directory structure, makes it easy to add dependencies, enables writing tests, makes it easy to publish packages to pub.dev, and much more.

To create a new Dart project, enter dart create {project-name}. Dart prefers underscores over hyphens in both project names and source file names. For example:

dart create hello_world

To run a Dart project, cd to the project directory and enter dart run. For example:

cd hello_world`
dart run # outputs "Hello world!"

To analyze a Dart project for syntax errors and lint rule violations, enter dart analyze.

The dart create command creates the following files and directories:

• .dart_tool/package_config.json

  This file is used to resolve Dart package names to .dart files.

• bin

  This directory contains .dart source files that are meant to be executed.

• bin/hello_world.dart

  This Dart source file is the project starting point.

• .gitignore

  This file lists directories and files that should not be added to a Git repository.

• lib

  This directory is not provided, but should be created to hold .dart files that define libraries of functions and classes used by other .dart files in the project.

  Files in the bin directory import files from here using the syntax import 'package:{project-name}/{file-name}.dart'; For files in subdirectories of the lib directory, add subdirectories after the project name. For example, import 'package:{project-name}/{subdir-name}/{file-name}.dart';

• .packages

  This file is deprecated.

• analysis_options.yaml

  This file configures Dart linting rules.

• CHANGELOG.md

  This file describes versions of the project.

• pubspec.yaml

  This file describes project dependencies and more. It is similar to package.json in Node.js projects. The properties that are optional are indicated in the list below.

  • name: package name (can use underscores, but not hyphens)

  • description: package description

  • version: using semver major.minor.patch convention

  • homepage: optional URL

  • repository: optional URL

  • issue_tracker: optional URL

  • documentation: optional URL

  • publish_to: information for publishing to pub.dev

  • environment: describes supported Dart versions

  • dependencies: list of packages needed at runtime; can omit if none

  • dev_dependencies: list of packages only needed for development; can omit if none

  There are three supported syntaxes for specifying acceptable versions of a dependency.

  1. specific semver; ex. 1.2.3
  2. semver range; ex. >=1.2.3 <2.0.0
  3. caret semver; ex. ^1.2.3 (means same as above)

  The caret semver syntax is preferred. It has a slightly different meaning when the major version is zero. For example, ^0.1.2 is the same as >=0.1.2 <0.2.0.

  Most dependencies come from pub.dev, but it is also possible to install dependencies from other sources such a Git repositories and packages in the packages directory of the current project.

• pubspec.lock

  This file records the exact versions of each installed dependency. It is similar to package-lock.json in Node.js projects.

  When this file doesn't exist, running the pub get command installs the versions of the dependencies specified in pubspec.yaml and creates this file to record the installed versions.

  When this file exists, running the pub get command installs the versions of the dependencies specified here.

• README.md

  This Markdown file describes the project.

A Dart project is actually a Dart package. This means it is possible for it to be deployed to pub.dev and its public API can be shared with other Dart packages.

Dart SDK

The Dart SDK includes all the tools needed to create, build, and run Dart applications. It can be downloaded from get-dart which provides instructions for installing in Windows, Linux, and macOS.

The Flutter SDK includes the Dart SDK.

After installing the Dart SDK, enter "dart" in a terminal to see all the subcommand options.

To create a new Dart project, enter dart create -t {type} {project-name} where type is console-simple, console-full, package-simple, server-shelf, or web-simple.

The Dart SDK contains three compilers.

1. Just In Time (JIT) compiler
   This compiles Dart code to an intermediate format and runs it in a virtual machine, which is ideal during development.

2. Ahead Of Time (AOT) compiler
   This compiles and builds an executable for a Dart program, which is ideal for releasing a finished application. It performs type flow analysis and removes unused code in order to produce a smaller executable. It also performs optimizations such as inlining code in order to produce a faster executable.

3. JavaScript (JS) compiler
   This compiles a Dart program to JavaScript, which allows it to be run in a web browser. The ability to do this is an important goal of the Dart language and influenced many of its syntax decisions. Some Dart libraries only run on the server or in Flutter and cannot be compiled to JavaScript.

Keywords

For a list of keywords in the Dart language with links to their descriptions, see Language Tour - Keywords.

Comments

Comments in Dart are written like in many other programming languages.

• Single-line comments begin with //.
• Multi-line comments are delimited by /* and */.
• Documentation comments begin with /// or are delimited by /** and */. These are used to generate documentation from source files.

Variables

There are four kinds of variables in Dart.

1. top-level, global variables declared outside any function or class
2. local variables in a function or method of a class, including parameters
3. static properties in a class
4. instance properties in a class

There are three ways to declare variables.

1. With a type

   For example, int score;

2. With the var keyword

   The type is obtained through type inference. For example, these are equivalent:

   int n = 19;
   var n = 19;

   When a var declaration is not initialized, it is treated like dynamic which is described next.

3. With the dynamic keyword

   The type can change throughout the lifetime of the variable based on the value currently assigned. For example:

   dynamic n = 19;
   n = 3.14;
   n = "changed";

By default variables do not have a default value and cannot be set to null. To allow setting a variable to null its type must be followed by ?. When this is done, the variable is initialized to null by default.

Non-nullable top-level variables (not declared inside a function or class) and non-nullable static class properties must be initialized. Non-nullable local variables in functions do not need to be given a value until their first use.

The late keyword has two primary uses.

First, it can be applied to a variable declaration with a non-null type that is not yet initialized. This states that the variable will be initialized before its first use. This allows a nested function to refer to the variable as long as the function is not called until after the variable is initialized. See an example of this in the "Streams" section.

In a Flutter StatefulWidget subclass, this typically happens in the initState method.

If a late variable is used before it is initialized, a LateInitializationError is thrown.

Second, it causes a value used for initialization to be lazily evaluated, regardless of whether it is a function call, method call, or computed property. The means the initialization function is not called until the first time the property is accessed. The following code demonstrates this:

int myFunction() {
  print('in myFunction');
  return 2;
}

class Demo {
  // Instance properties like computedProperty cannot be used to initialize
  // another instance property unless the "late" keyword is used.
  late int a = computedProperty;

  late int b = myFunction();

  // Instance methods like myMethod cannot be used to initialize
  // another instance property unless the "late" keyword is used.
  late int c = myMethod();

  int get computedProperty {
    print('in computedProperty');
    return 1;
  }

  int myMethod() {
    print('in myMethod');
    return 3;
  }
}

void main() {
  var demo = Demo();
  print('created object');
  print(demo.a); // triggers initialization of the "a" property
  print('retrieved a');
  print(demo.b); // triggers initialization of the "b" property
  print('retrieved b');
  print(demo.c); // triggers initialization of the "c" property
  print('retrieved c');
}

The code above produces the following output:

created object
in computedProperty
1
retrieved a
in myFunction
2
retrieved b
in myMethod
3
retrieved c

To get the runtime type of any object, access its runtimeType property. This has a type of Type which has a toString method.

Immutability with const and final

Variables whose values are known at compile-time should be declared with the keyword const. Class properties whose values are known at compile-time should be declared with the keywords static const. This prevents assigning a new value, and also prevents modifying the value (for example, adding elements to a List).

The const keyword can be applied to top-level variables, local variables in functions, and class static properties. It cannot be applied to class instance properties.

Variables and class properties whose values should be set once at run-time and never changed should be declared with the keyword final. This prevents assigning a new value, but does not prevent modifying the value.

In general, final is used in Dart everywhere const would be used in JavaScript and var is used in Dart everywhere let would be used in JavaScript.

The meaning of the const and final keywords depends on whether they are applied to a variable or its initial value. There are two aspects to consider, whether a new value can be assigned to the variable and whether its value can be modified (ex. adding elements to a list).

The following code demonstrates using the const and final keywords in conjunction with declaring and creating List collection objects. The same principles apply to other kinds of collections.

List<int> l1 = [1, 2];
//var l1 = <int>[1, 2]; // alternate way to write previous line
l1.add(3); // can modify current value
l1 = [3, 4]; // can assign a new value
print(l1); // [3, 4]

// const here makes the variable AND its value immutable.
// Adding const after "=" and before the value is redundant.
const List<int> l2 = [1, 2];
//l2.add(3); // throws UnsupportedError at runtime
//l2 = [3, 4]; // cannot assign a new value
print(l2); // [1, 2]

// Adding const only before the value makes the value immutable,
// but a new value can be assigned to the variable.
List<int> l3 = const [1, 2];
//l3.add(3); // throws UnsupportedError at runtime
l3 = [3, 4]; // can assign a new value
print(l3); // [3, 4]

// final here means the variable can only be assigned a value once,
// but its value can be modified.
final List<int> l4 = [1, 2];
l4.add(3); // can modify current value
//l4 = [3, 4]; // cannot assign a new value
print(l4); // [1, 2, 3]

// This is the same as the l2 declaration
// which is preferred because it is shorter.
final List<int> l5 = const [1, 2];
//l5.add(3); // throws UnsupportedError at runtime
//l5 = [3, 4]; // cannot assign a new value
print(l5); // [1, 2]

In order to create instances of a class that are compile-time constants, all fields must be final and the constructor must be marked const. When this is done, constructor calls with same argument values return references to the same object. The following code demonstrates this:

class Point {
  final double x;
  final double y;

  const Point(this.x, this.y);
}

main() {
  var p1 = const Point(1, 2); // compile-time constant
  const p2 = Point(1, 2); // alternate way to create a compile-time constant
  var p3 = Point(1, 2); // not a constant
  print(p1 == p2); // true - same object
  print(identical(p1, p2)); // true - same object
  print(identical(p1, p3)); // false - not same object
}

The identical function tests whether two values refer to the same object. By default the == operator performs the same test, but classes can override this to have a different meaning such as comparing object properties. The collection classes List, Set, and Map do not override the == operator.

To test whether two objects contain the same properties and values, consider using the equatable library. Custom classes can extend Equatable to override the == operator and the hashCode method so instances are compared by value instead of by reference. For classes that already have a superclass, use EquatableMixin.

Importing packages

A .dart file can import packages using the import statement. The following imports the dart:math package and places all its top-level public names (such as pi and sin) in the current namespace:

import 'dart:math';

To import only a subset of the names defined in another file, use the show keyword.

import 'dart:math' show pi, sqrt;

To import all names defined in another file except some, use the hide keyword.

import 'dart:math' hide acos, asin, atan, atan2;

To avoid conflicting with names already in the current namespace, use the as keyword.

import 'dart:math' as math;

Now names like pi can be referred to with math.pi and functions like sqrt can be referred to with math.sqrt.

Types

All values in Dart are objects from some class. This is even true for basic types like bool, int, double, and String. For example, the literal values true, 7, 3.14, and 'test' are all objects.

These and many other classes are defined in the dart:core package. Classes defined here do not need to be imported.

All types except Null are subclasses of the Object class.

Dart supports the following built-in basic types:

• void: means a value is never used
• Null: represents not having a value
• bool: boolean value with literal values true and false
• int: 64-bit integer
• double: 64-bit floating point number
• String: sequence of UTF-16 characters delimited by single or double quotes
• Symbol: represents an operator or identifier with literal syntax #name
• Never: has no values

The void type is used at the return type of functions that do not return anything.

The keyword null refers to the only instance of the Null type.

The Never type is the type of throw expressions, and is the return type of functions that always throw.

Note that there is no float type. The double type is used for all floating point numbers.

Dart supports the following built-in collection types:

• List: ordered collection of values (see the List section)
• Set: unordered collection of unique values (see the Set section)
• Map: unordered collection of key/value pairs (see the Map section)

Dart supports type inference, so types do not need to specified if they can be inferred from values.

By default no type allows the value null. To allow this prepend ? to the type name. For example, a variable of type String cannot be set to null, but a variable of type String? can. The compiler requires handling cases where a nullable value might be null. This results in detecting errors involving null values at compile-time rather than runtime.

The is operator tests whether a variable currently holds a value of a given type and evaluates to a bool. For example:

void evaluate(num n) {
  if (n is int) {
    // n is cast to int inside this block.
    print('$n is ${n.isOdd ? 'odd' : 'even'}.');
  }
}

void main() {
  num n = 3.1;
  evaluate(n); // outputs nothing
  n = 7;
  evaluate(n); // outputs "7 is odd."
}

The is! operator performs the opposite test.

bool type

Instances of the bool class represent a boolean value. The only values are the literal values true and false.

The bool class doesn't add any interesting properties or methods, but it defines the following bitwise operators: & (and), | (or), and ^ (xor).

In addition, the logical operators && (and), || (or), and ! (not) can be applied to bool values. These have lower precedence than bitwise operators. TODO: Where are these defined? Why aren't they defined by the bool class?

Number types

The int and double classes are the only number types supported by Dart. Both inherit from the num class and both represent 64-bit values. Custom classes are not allowed to inherit from the num class.

num Class

Variables declared with the num type can be assigned both int and double values.

The num class defines the following properties:

The num class defines the following instance methods:

The num class defines the following static methods:

The parse method throws if parsing fails or calls onError if supplied.

The num class defines the following operators:

The ++ and -- operators can be placed on either side of a num value. When on the left, a new value is computed before it is used. When on the right, the value is used before a new value is computed.

Note that there is no ^ or ** for exponentiation like in many other programming languages. Instead, import the dart:math package and use the pow(number, exponent) function.

The fact that these operators take operands of type num means that they can be applied to mixed operands where one is an int and the other is a double.

Even though operator definitions look like methods, they cannot be called like methods. For example, the documentation for + operator in the num class shows num operator +(num other);.

var n = 2;
n.+(3); // This does not work!
n += 3; // This works.
print(n);

Dividing by zero with the / operator results in the double.infinity constant rather than throwing an exception. When the integer division operator ~/ is used instead, an UnsupportedError is thrown. Note that IntegerDivisionByZeroException is deprecated.

int Class

The int class adds the following properties to those defined in the num class:

The int class adds the following methods to those defined in the num class (some omitted):

The toRadixString method can be used to convert decimal values to hexadecimal. For example, 255.toRadixString(16) returns the String ff.

The int class adds the following operators to those defined in the num class:

Note that there is no operator for unsigned bit shift left.

double Class

The double class adds no properties, instance methods, static methods, or operators beyond those defined in the num class.

The double class defines the following constants that must be prefixed with double.:

math Package

The Dart math package does not need to be installed, but it must be imported in order to use the items it defines.

import 'dart:math';

The Dart math package class defines the following classes:

The Dart math package class defines the following constants:

The Dart math package defines the following functions:

String Class

Instances of the String class hold an immutable sequence of UTF-16 characters.

TODO: Why does the name of this type start uppercase, TODO: but the bool, int, and double types start lowercase?

Literal single line strings are delimited by single or double quotes. Literal multi-line strings are delimited by a pair of three single or double quotes. All newlines, except a leading newline if it exists, are retained.

Literal strings can use interpolations. To include the value of a variable, include $variableName. To include the value of an expression, include ${expression}. To include a literal $ in a string, escape it with \$.

Strings can be concatenated with the + operator. The + operator is not needed to concatenate literal strings. Literal strings can be written next to each other, separated only by a space, to concatenate them.

An individual character (code point) can be accessed with square brackets and an index. For example, the first character of a string s is obtained with s[0].

There are two ways to embed newline characters in a string. The following code demonstrates these:

  var s1 = 'first\nsecond';
  print(s1);
  var s2 = '''first
second''';
  print(s2);

Unicode character codes can be embedded in a String with \u{hex-code}. For example:

print('Do you prefer a \u{1F436} or \u{1F431}?'); // Do you prefer a 🐶 or 🐱?

Raw strings are strings where backslash character is not treated specially. They are indicated by preceding the opening delimiter with "r". For example, r'first\nsecond' does not treat \n as a newline character. Raw strings useful when defining regular expressions.

Defining custom classes that extend the String class is not allowed.

The String class defines the following properties:

The String class defines the following instance methods:

To sort a List of String values in place, use the List sort method and the String compareTo method. For example:

var names = <String>['Maisey', 'Ramsay', 'Oscar', 'Comet'];
names.sort((a, b) => a.compareTo(b));
// names now contains ['Comet', 'Maisey', 'Oscar', 'Ramsay']

The String class defines the following binary operators: + (concatenation), * (repeated n times), == (same code points), [index] (gets code point at index). For example 'ho ' * 3 creates the String 'ho ho ho '.

The table below summarized converting between numbers and strings.

Enumerations

Enumerations are a special kind of class defined with the enum keyword. The are often used in switch statements.

Each value in an enum is assigned an index starting from zero. They cannot be assigned different numeric values.

Enumerations cannot be defined inside a function.

For example:

enum Color { red, green, blue }

void printColor(Color c) {
  print('$c, index=${c.index}');
}

void main() {
  printColor(Color.values[1]); // Color.blue, index=1

  for (var color in Color.values) {
    printColor(color);
  }
}

The toString method on enum values returns a String that contains the enum name followed by a period and the enum value. For example, Color.blue.toString() returns 'Color.blue'. To get a String with the enum name and period in Flutter, add import 'package:flutter/foundation.dart'; and pass an enum value to the describeEnum function. For example: describeEnum(Color.blue) returns the String 'blue'.

There is a proposal to allow omitting enum names when referring to their values if the enum type can be inferred. For example, in Flutter it is common to see arguments whose type is MaterialColor which extends ColorSwatch which extends Color. One example is the primarySwatch argument to the ThemeData constructor. With this proposal, primarySwatch: Colors.blue could be shortened to primarySwatch: .blue because the Dart compiler can infer that the value can be a Color enum value.

Type Aliases

To define a name for a type, use a typedef statement. For example:

typedef StringToAnyMap = Map<String, dynamic>;

typedef Callback = void Function(String);

Type Casts

The as keyword casts a value of one type to another. For example, if a variable of type Object currently holds a String value, it can be cast to a String so that methods from that class can be called on the value.

Object obj = 'test';
print((obj as String).length);

This throws if the cast is not valid. For example:

Object obj = 7;
print((obj as String).length); // throws "Script error."

Generic Types

Generics, a.k.a parameterized types, allow writing functions, classes, and methods that accept values of multiple types. Their functionality can differ based on the types of values provided. Using generics often reduces code duplication in cases where multiple blocks of code only differ in the types on which they operate.

Generics are often used to implement new kinds of collections. The core collection classes, described in the next section, do exactly this. For example, when creating a List, the type of the elements it can hold are specific using generics. The following are equivalent:

List<int> numbers = [1, 2, 3]; // type is specified on the variable
var numbers = <int>[1, 2, 3]; // type is specified on the value
var numbers = [1, 2, 3]; // type is inferred

To create a collection that can hold values of any type, use dynamic. For example:

List<dynamic> anyList = [
  null, true, 7, 3.14, 'hello', <String>{'red', 'green', 'blue'}
];

for (var value in anyList) {
  print(value.runtimeType);
}

Typically parameterized types have single-letter, uppercase names like T. Common names for type parameters include:

• E for Element
• K for Key
• R for Return type
• T for Type
• V for Value

Longer, more descriptive names, like Event and State can also be used.

Any number of type parameters can be specified inside angle brackets. They can be constrained to only types that extend a given class using the extends keyword, or left unconstrained in which case values of any type can be used.

The following example demonstrates implementing a generic function. It takes any Iterable containing num values and returns its sum. This means it works with both int and double values since their superclass is num.

N sum<N extends num>(Iterable<N> numbers) {
  return numbers.reduce((acc, n) => (acc + n) as N);
}

void main() {
  print(sum([1, 2, 3])); // List; 6
  print(sum({1, 2, 3})); // Set; 6
}

Collection Types

Dart provides many generic collection classes. Built-in collection classes that can be used without importing include List, Set, and Map. Other collection classes are defined in the package dart:collection and must be imported. These include DoubleLinkedQueue, HashMap, HashSet, LinkedHashMap, LinkedHashSet, LinkedList, ListQueue, Queue, and SplayTreeMap, SplayTreeSet.

For even more collection functions, classes, and extensions, see package:collection which is included in the Flutter SDK. Some of the capabilities of this package are described later in this section.

Iterable

The Iterable generic class represents a collection of values that are accessed sequentially. The values can be lazily computed when requested and an infinite number of values can be generated.

The following generic collection classes all have Iterable as a superclass: DoubleLinkedQueue, IterableBase, IterableMixin, LinkedList, List, ListQueue, Queue, Runes, and Set.

Any Iterable collection can be used in a for-in loop to iterate over its elements.

The Iterable class provides the following constructors:

The Iterable class provides the following read-only properties:

The Iterable class provides the following methods (some omitted):

The differences between the List methods fold and map is that fold takes an initial value and map does not. In the first iteration of the fold method, the combine function is called with initialValue and the first element. In the first iteration of the reduce method, the combine function is called with the first and second elements.

The Iterator generic class provides the read-only instance property current which holds the current element and the instance method moveNext() which sets current to the next element and returns a bool indicating if there is another element. Instances of this class are not typically used directly. Instead, syntax like the for-in loop are used to iterate over an Iterable.

List Class

Arrays in Dart are represented by List objects. A literal array is written as a comma-separated list of values surrounded by square brackets. For example, var numbers = [3, 7, 19];

There are three ways to declare and initialize a variable that holds a List.

// type List<int> is inferred
var l1 = [1, 2, 3];

// type List<int> is specified on the value
var l1 = <int>[1, 2, 3];

// type List<int> is specified on the variable
List<int> l1 = [1, 2, 3];

To iterate over the elements of a List, use a for/in loop or the forEach method. For example:

const dogs = ['Maisey', 'Ramsay', 'Oscar', 'Comet'];

for (var dog in dogs) {
  print(dog);
}

// Same as above.
dogs.forEach((dog) => print(dog));

// Same as above.
dogs.forEach(print);

Two lists can be concatenated to create a new List with the + operator. For example:

var list1 = [1, 2];
var list2 = [3, 4];
var list3 = list1 + list2; // [1, 2, 3, 4]

Literal lists can include logic to determine the elements to include. This is referred to as "list comprehension". The following examples demonstrate this:

import 'dart:math';

// Creates a List of int values from start to end - 1
// using the List.generate constructor.
Iterable<int> range(int start, int end) =>
    List.generate(end - start, (i) => start + i);

void main() {
  // Get the squares of a odd numbers in the range [0, 10).
  var squares = [for (var i = 1; i < 10; i += 2) pow(i, 2)];

  // Same using a different approach.
  // Get the squares of a odd numbers in the range [0, 10).
  squares = [for (var i in range(0, 10)) if (i % 2 == 1) pow(i, 2)];
  print(squares); // [1, 9, 25, 49, 81]

  // Find all the [x, y, z] values where
  // x^2 + y^2 = z^2 up to a maximum value of 20.
  var pythagorean = [
    for (var x in range(1, 20))
      for (var y in range(x, 20)) // start at x
        for (var z in range(y, 20)) // start at y
          if (x * x + y * y == z * z) [x, y, z]
  ];
  print(pythagorean); // [[3, 4, 5], [5, 12, 13], [6, 8, 10], [8, 15, 17], [9, 12, 15]]
}

The List class is generic and implements extends from the Iterable class. It provides many constructors that support creating lists that are empty, filled to a given length with the same value, filled from another Iterable (either modifiable or unmodifiable), filled by a generator function,

In addition to the properties provided by the Iterable class, List objects support the following properties:

In addition to the methods provided by the Iterable class, List objects support the following methods (some omitted):

The List class supports the following operators:

Set Class

A Set is an unordered collection of unique values. A literal set is written as a comma-separated list of values surrounded by curly braces.

There are several ways to declare and initialize a variable that holds a Set.

// type Set<String> is inferred
var colors = {'red', 'green', 'blue'};

// type Set<String> is specified on the value
var colors = <String>{'red', 'green', 'blue'};

// type Set<String> is specified on the variable
Set<String> colors = {'red', 'green', 'blue'};

var colors = Set<String>();
colors.add('red');
colors.add('green');
colors.add('blue');

// The following creates an empty Map, not an empty Set.
// var colors = {};

The literal syntax <value-type>{} creates an empty Set. The literal syntax <key-type, value-type>{} creates an empty Map. The literal syntax {} creates an empty Map with unspecified key and value types whose types must be inferred from the variable type. It does not create an empty Set.

No properties are added beyond those provided by the Iterable class.

In addition to the methods provided by the Iterable class, Set objects support the following methods (some omitted):

Map Class

A Map is a collection of key/value pairs. The keys and values can have any type. Unlike List and Set, this class is not a subclass of Iterable.

A literal map is written as a comma-separated list of pairs surrounded by curly braces. Each pair is written as a key followed by a colon and a value. When a key is a string, it must be delimited by single or double quotes.

There are several ways to declare and initialize a variable that holds a Map.

// type Map<String, int> is inferred
var colorMap = {'red': 1, 'green': 2, 'blue': 3};

// type Map<String, int> is specified on the value
var colorMap = <String, int>{'red': 1, 'green': 2, 'blue': 3};

// type Map<String, int> is specified on the variable
Map<String, int> colorMap = {'red': 1, 'green': 2, 'blue': 3};

// This map has String keys and values of any type.
Map<String, dynamic> dog = {'name': 'Comet', 'age': 1, 'isFast': true};

// The following creates an empty map where
// keys and values both have the type dynamic.
var myMap = {}; // same as Map()

Values of Map keys are retrieved with the [] operator. This returns a nullable value. They cannot be retrieved with dot syntax like in JavaScript. For example:

var colorMap = {'red': 1, 'green': 2, 'blue': 3};
int? number = colorMap['blue']; // not colorMap.blue
print(number ?? 'not found'); // 3
if (number != null) {
  print(number); // 3
}

The spread operator ... can be used to spread Map objects into others. For example:

var map1 = {'apple': 'red', 'banana': 'yellow'};
var map2 = {'cherry': 'red', 'grape': 'green'};
var map3 = {
  'lemon': 'yellow',
  ...map1,
  'blueberry': 'blue',
  ...map2,
  'watermelon': 'pink'
};
print(map3); // all the key/value pairs

The Map class provides the following properties:

The Map class provides the following methods (some omitted):

The MapEntry class represents a single key/value pair from a Map. To create one, call the MapEntry constructor passing it a key and a value. These objects have key and value properties and a toString method.

package:collection

The collection library is a collection of functions, classes, and extensions that extend the capabilities of the collections provided by Dart. These are briefly described in this Flutter Package of the Week YouTube video.

To uses this package, add the following import:

import 'package:collection/collection.dart';

A few examples of the added functionality are described below. Browse the documentation for many more.

To test whether two List objects contain the same elements in the same order, use ListEquality().equals(list1, list2).

To test whether two collections contain the contents, use DeepCollectionEquality().equals(collection1, collection2).

The IterableIntegerExtension and IterableDoubleExtension extensions add the methods average and sum to Iterables of int and double values. Just importing the collection package adds all the extensions it defines. To get the sum of a List of numbers, use myList.sum. To get the average of a List of numbers, use myList.average.

The IterableExtension adds properties and methods to all objects that implement the Iterable interface.

To get the first element of an Iterable or null if it is empty, use the firstOrNull property.

To get the last element of an Iterable or null if it is empty, use the lastOrNull property.

The Iterable methods foldIndexed, forEachIndexed, mapIndexed, reduceIndexed, and whereIndexed are like their counterparts fold, forEach, map, reduce, and where but differ in that they pass the index of each element to the function passed to them.

There are many more Iterable methods described in the documentation.

Print

The print function takes a single String argument and writes it to stdout.

If the argument is not a String, it will be converted to a String by calling the toString method of the value. For example:

class Dog {
  String name;
  String breed;

  // Shorthand constructor - see Class section
  Dog(this.name, this.breed);

  // Methods that override a superclass method should
  // be annotated with @override.  In this case we are
  // overriding the toString method in the Object class.
  @override
  String toString() => '$name is a $breed.';
}

void main() {
  var d = Dog('Comet', 'Whippet');
  print(d); // Comet is a Whippet.
}

Additional Core Classes

The dart:core package defines all the basic types like bool, int, double, and String. It also defines collection types like List, Set, and Map. Highlights of other classes defined in dart:core are described below.

DateTime class

The DateTime class is used to create objects that represent an instant in time. The constructor requires and int value for the year and optionally accepts int values for the month, day, hour, minute, second, and milliseconds. The month and day default to one. The minute, second, and milliseconds default to zero. Other ways to create DateTime objects include the static parse method and the constructors DateTime.fromMillisecondsSinceEpoch, DateTime.now, and DateTime.utc.

The following code demonstrates various ways to create DateTime objects.

var birthday = DateTime(1961, 4, 16); // in local time
var birthdayUtc = DateTime.utc(1961, 4, 16); // in UTC
var nowLocal = DateTime.now(); // in local time

// Defaults to local time, but can request UTC.
var epoch = DateTime.fromMillisecondsSinceEpoch(0, isUtc: true);
print(epoch); // 1970-01-01 00:00:00.000Z

There isn't an easy way to create DateTime objects for timezones other than the local one and UTC.

The DateTime.parse constructor takes a string that matches a subset of ISO 8601 of the standard. Examples include '1961-04-16 10:19:00' (local time zone), '19610416T101900' (same with T separating date from time), and '1961-04-16 10:19:00Z' (UTC).

The DateTime class defines the following constants:

• daysPerWeek (7)

• monthsPerYear (12)

• january (1)

• february (2)

• march (2)

• april (4)

• may (5)

• june (6)

• july (7)

• august (8)

• september (9)

• october (10)

• november (11)

• december (12)

• monday (1)

• tuesday (2)

• wednesday (3)

• thursday (4)

• friday (5)

• saturday (6)

• sunday (7)

The DateTime class defines the following properties:

The DateTime class defines the following instance methods:

Duration class

The Duration class is used to create objects that represent a span to time. The constructor takes the following named parameters that are all optional and default to zero: days, hours, minutes, seconds, milliseconds, and microseconds.

The Duration class defines the following constants:

• hoursPerDay
• microsecondsPerDay
• microsecondsPerHour
• microsecondsPerMillisecond
• microsecondsPerMinute
• microsecondsPerSecond
• millisecondsPerDay
• millisecondsPerHour
• millisecondsPerMinute
• millisecondsPerSecond
• minutesPerDay
• minutesPerHour
• secondsPerDay
• secondsPerHour
• secondsPerMinute
• zero

The Duration class defines the following properties:

The Duration class defines the following instance methods:

Regular Expressions

A Pattern is a RegExp or String object.

Dart regular expressions use the same syntax as JavaScript regular expressions.

A RegExp object is created with RegExp(r'reg-ex-here');. Recall that placing "r" before a literal string creates a "raw string" that doesn't treat the \ character specially.

The RegExp class defines the following properties:

The RegExp class defines the following instance methods:

The following example creates a regular expression that matches strings starting with "The " and ending with " win.". It captures all the characters in between.

var re = RegExp(r'^The (.+) win\.$');
var s = 'The St. Louis Blues win.';
var match = re.firstMatch(s);
if (match != null) {
  print(match.group(1)); // St. Louis Blues
}

The optional named constructor parameter multiLine has a bool value that indicates whether it should match at the beginning and end of every line. This defaults to false.

The optional named constructor parameter caseSensitive has a bool value that indicates whether matching should be case-sensitive. This defaults to true.

The RegExpMatch class extends the Match class. Instances of this class describe a regular expression matching result.

The RegExpMatch class defines the following properties:

The RegExpMatch class defines the following instance methods:

The [index] operator can be used in place of the group method retrieve the same value.

Stopwatch Class

The Stopwatch class is used to measure elapsed time in a section of code.

The Stopwatch class defines the following properties.

The number of clock "ticks" in a second is equal to the frequency property. A common value is 1,000,000.

The elapsedTicks property has the same value as elapsedMicroseconds if frequency is 1e6.

The Stopwatch class defines the following instance methods:

The following code demonstrates using the Stopwatch class:

import 'dart:math';

void main() {
  var sw = Stopwatch();
  sw.start();
  var sum = 0;
  for (var i = 0; i < 1000000000; i++) {
    sum += pow(i, 3) as int;
  }
  sw.stop();
  print(sum);
  print('elapsed = ${sw.elapsed.inMilliseconds} ms');
}

StringBuffer Class

The StringBuffer class supports efficient, incremental building of strings. It defines the following properties.

The StringBuffer class defines the following instance methods:

Timer class

The Timer class executes a callback function after a given Duration either once or repeatedly. It provides capabilities similar to the JavaScript functions setTimeout and setInterval. The Timer class is defined in the dart:async package which must be imported.

The following example demonstrates creating Timers that fire just once and repeatedly:

import 'dart:async';

void main() {
  print('starting timer');
  var timer = Timer(Duration(seconds: 2), () {
    print('finished timer');
  });
  //timer.cancel();

  var count = 0;
  Timer.periodic(Duration(seconds: 1), (timer) {
    print('isActive = ${timer.isActive}; tick = ${timer.tick}');
    count++;
    if (count >= 5) timer.cancel();
  });
}

When Timer.periodic is used in a Flutter widget, the timer needs to be stopped when the widget instance is removed from the screen. To do this, capture the return value, override the widget dispose method, and call timer.cancel() and super.dispose() inside it.

Uri Class

The Uri class represents a parsed URI. It provides many constructors for creating a Uri object.

The Uri class defines the following properties.

The Uri class defines the following instance methods:

The following code demonstrates parsing a URL string using the static parse method and extracting its components from fields of a Uri object. There are many other static methods not described here.

var url = 'https://mvolkmann.github.io/foo/bar?color=yellow&size=10#my-hash';
var uri = Uri.parse(url);
print('scheme = ${uri.scheme}'); // https
print('authority = ${uri.authority}'); // mvolkmann.github.io
print('host = ${uri.host}'); // mvolkmann.github.io
print('port = ${uri.port}'); // 443?
print('origin = ${uri.origin}'); // https://mvolkmann.github.io
print('path = ${uri.path}'); // /foo/bar
print('pathSegments = ${uri.pathSegments}'); // ['foo', 'bar']
print('query = ${uri.query}'); // color=yellow&size=10
print('queryParametersAll = ${uri.queryParametersAll}'); // {color: [yellow], size: [10]}
print('fragment = ${uri.fragment}'); // my-hash

Spread Operators

The spread operator ... spreads a collection inside another.

var colors = ['red', 'green', 'blue'];
var moreColors = ['black', ...colors, 'white'];
print(moreColors);

var fruits = {'b': 'banana', 'c': 'cherry'};
var moreFruits = {'a': 'apple', ...fruits, 'd': 'date'};
print(moreFruits);

The null-aware spread operator ...? only spreads when the value is not null.

Map<String, String>? maybeFruits;
var evenMoreFruits = {'a': 'apple', ...fruits, ...?maybeFruits, 'd': 'date'};
print(evenMoreFruits);

The spread operator cannot be used to expand a List into function arguments. Use that static method Function.apply for this purpose.

Nullable Values

Dart provides special operators for dealing with nullable values. The following example demonstrates these.

import 'dart:math';

var random = Random();
String? randomString() => random.nextBool() ? 'test' : null;

void main() {
  String? s;
  s = randomString(); // 'test' or null
  print('s = $s');

  // The ?. operator evaluates to null if the value on the left is null.
  // Otherwise it evaluates to the property or method on the right.
  print(s?.toUpperCase());

  // The ?? operator provides an alternative value to use
  // if the value on the left is null.
  print(s ?? 'missing value');

  // The ??= operator assigns a value to a variable
  // only if the variable value is currently null.
  s ??= 'supplied value';
  print(s);

  // The !. operator asserts that the value on the left is not null.
  // It essentially casts away nullability.
  // s! here is equivalent to (s as String).
  // The program will crash with "Script error." if it is null.
  print(s!.toUpperCase());
}

Functions

Dart functions are represented by objects from the Function class. They are first class which means they can be assigned variables, passed to other functions, and returned from other functions.

All Dart functions, including anonymous ones, are closures. This means they have access to in-scope variables declared outside the function.

Named function definitions have the following syntax:

return-type fn-name(parameter-list) {
  statements
}

Functions with a return type other than void must return a value or throw an exception/error. Functions with a return type of void always return null.

Anonymous functions have similar syntax, but the name is omitted and the return type is inferred.

(parameter-list {
   statements
}

Functions that only return the value of a single expression can use a shorthand syntax where => expression; is short for { return expression; }.

Specifying parameter types and the return type are optional. For example, the following is a valid function definition:

add(n1, n2) => n1 + n2;
main() => print(add(2, 3)); // 5

Functions can have both positional and named parameters and each of these can be required or optional. The order of these in both function declarations and calls to functions must be required positional parameters, followed by optional positional parameters, followed by named parameters in any order.

A future version of Dart will allow named parameters to appear anywhere in an argument list. See issue 47451.

Required positional parameters cannot be given default values. Optional positional parameters must appear inside square brackets after the required positional parameters. They must either have a default value or an optional type (ending with ?).

In the following example, req1 and req2 are required parameters and opt1 and opt2 are optional. If only two arguments are passed, opt1 is set to its default value of 0 and opt2 is set to null.

demo(int req1, int req2, [int opt1 = 0, int? opt2]) {
  ...
}

Named parameters are declared inside curly braces. These must follow all the positional parameters, if any. Named parameters are optional by default and must either have a default value or a nullable type (ending with ?). Default values can be preceded by = or :, but = is preferred. To make a named parameter required, add the required keyword before its type. For example:

// In this version, the named parameter "by" is required.
//int multiply(int n, {required int by}) => n * by;

// In this version, the named parameter "by" is optional.
int multiply(int n, {int by = 0}) => n * by;

main() {
  print(multiply(2, by: 3)); // 6
  print(multiply(4)); // 4
}

Dart does not support variadic functions which are functions that accept a variable number of arguments.

There are three ways to call a function, using the function invocation operator (), the call instance method, and the static apply method. The following code demonstrates these:

// This function takes two required positional parameters
// and two optional named parameters.
num sum(num n1, num n2, {num? min, num? max}) {
  var result = n1 + n2;
  if (min != null && result < min) return min;
  if (max != null && result > max) return max;
  return result;
}

void main() {
  print(sum(1, 2)); // 3
  print(sum(1, 2, min: 10)); // 10

  print(sum.call(1, 2)); // 3
  print(sum.call(1, 2, min: 10)); // 10

  // First argument to apply is a function to call.
  // Second argument to apply is an optional List of positional arguments.
  // Third argument to apply is an optional Map<Symbol, dynamic> of named arguments.
  print(Function.apply(sum, [1, 2])); // 3
  print(Function.apply(sum, [1, 2], {#min: 10})); // 10
  print(Function.apply(sum, [15, 10], {#min: 10, #max: 19})); // 19
}

The spread operator cannot be used to expand a List into function arguments. However, the static apply method on the Function class (shown above) can be used for this purpose.

Anonymous function definitions are written like named function definitions, but omit the name. Unlike in JavaScript, parentheses are required around the parameter list even when there is only one parameter. For example:

var numbers = [3, 7, 9];
numbers.forEach((n) => n * 2);

Trailing commas are allowed after the last parameter in function definitions and after the last argument in function calls. This causes dart format to place each parameter or argument on a separate line.

Functions that do not explicitly return a value evaluate to null.

Generator Functions

Generator functions generate values on demand in a lazy fashion. The values it generates are not computed until they are requested.

Generator functions use the yield keyword to return a single value. They can also use the yield* keyword to return all the values from another generator function individually. This serves as a shorter alternative to iterating over the values from another generator and returning each one.

Synchronous generator functions include the sync* keyword after the parameter list and before the body. They always return an Iterator and must generate a value as soon as requested.

The following synchronous generator function generates int values in a given range which can be open-ended.

Iterable<int> range(int start, [int? end]) sync* {
  if (end == null) {
    var i = start;
    while (true) {
      yield i++;
    }
  } else {
    for (var i = start; i <= end; i++) {
      yield i;
    }
  }
}

// This demonstrates several ways to use the "range" function.
// All except the last print the numbers 1 through 5.
void main() {
  for (var i in range(1, 5)) {
    print(i);
  }

  for (var i in range(1)) {
    print(i);
    if (i == 5) break;
  }

  for (var i in range(1).take(5)) {
    print(i);
  }

  // Prints the first five positive integers that are multiples of 3
  // which are 3, 6, 9, 12, and 15.
  range(1).where((n) => n % 3 == 0).take(5).forEach(print);
}

The Iterable generator method provides an easy way to generate a fixed number of values. It is passed the number of values to generate and a function that takes an index and returns a computed value. For example, the range function above can be replaced by the following if an end value is always supplied.

Iterable<int> range(int start, int end) {
  var count = end - start + 1;
  return Iterable<int>.generate(count, (index) => index + start);
}

Asynchronous generator functions are sometimes useful, but not frequently used. They include the async* keyword after the parameter list and before the body. They always return a Stream and can return a Future for values that will be computed later.

The following asynchronous generator function reads text files containing player scores on separate lines. Each file contains the scores of a single player.

import 'dart:async';
import 'dart:io';

class PlayerAverage {
  String player;
  double average;

  PlayerAverage(this.player, this.average);

  @override
  String toString() => '$player average score is $average.';
}

Stream<PlayerAverage> computeAverageScores(List<String> players) async* {
  for (var player in players) {
    var lines = await File('scores-$player.txt').readAsLines();
    var total = lines.fold(0, (int acc, String line) => acc + int.parse(line));
    var average = total / lines.length;
    print('$player average is $average.');
    yield PlayerAverage(player, average);
  }
}

void main() async {
  var players = ['Mark', 'Tami', 'Amanda', 'Jeremy'];

  PlayerAverage? winner;
  // Note the use of "await for" to iterate over
  // values in a Stream inside an async function.
  // Only use this when it is certain that the Stream will complete.
  await for (var result in computeAverageScores(players)) {
    if (winner == null || result.average > winner.average) winner = result;
  }

  if (winner != null) {
    print(
      'The winner is ${winner.player} '
      'with an average score of ${winner.average}.'
    );
  }
}

Conditional Logic

Dart supports two statements for implementing conditional logic, if and switch. It also supports the ternary operator ? :.

The condition specified in an if statement must be an expression that evaluates to a bool value.

Here are examples of if statements.

if (temperature < 30) print('stay inside'); // braces are optional

if (temperature > 80) {
    print('hot');
} else if (temperature < 40) {
    print('cold');
} else {
    print('comfortable');
}

The switch statement compares values of type int or String, enumerated types, or compile-time constants. Curly braces around the cases are required. Here is an example of a switch statement.

enum Color { red, green, blue }
var color = Color.green;
switch (color) {
  case Color.red:
    print('hot');
    break;
  case Color.blue:
    print('cold');
    break;
  default:
    print('comfortable');
}

When an enum value is being evaluated, the default clause is required unless there is a case for each possible value.

The ternary operator selects a value based on boolean expressions. For example:

print(coinSide == 'heads' ? 'You win.' : 'You lose.');

var assessment =
  temperature >= 80 ? 'hot' :
  temperature <= 32 ? 'cold' :
  'comfortable';

The assert statement asserts that a condition is true. If it is not, an optional message is printed and the program exits with an AssertionError. These statements are only executed when enabled. To run a Dart program with asserts enabled, enter dart run --enable-assert. For example:

assert(!worldEnding(), 'So long.');

Iteration

Dart supports three statements for implementing iteration, for, while, and do-while. The condition specified in each of these must be an expression that evaluates to a bool value. The for and while loops are top-tested. They perform a test at the beginning of each iteration and so may not execute their bodies at all. The do-while loop is bottom-tested. It performs a test after each iteration and so will always execute the body at least once

Here are examples of each:

for (var i = 1; i <= 5; i++) print(i); // 1 to 5; braces are optional

for (var i = 1; i <= 5; i++) {
  print(i); // 1 to 5
}

var dogs = ['Maisey', 'Ramsay', 'Oscar', 'Comet'];

for (var dog in dogs) print(dog); // each dog name; braces are optional

for (var dog in dogs) {
  print(dog); // each dog name
}

var i = 1;
while (i <= 5) {
  print(i); // 1 to 5
  i++;
}

do {
  print(i); // 6 to 1
  i--;
} while (i > 0);

All three kinds of loops support the break and continue statements. The break statement exits the loop. The continue statement skips the remainder of the current iteration and proceeds to the beginning of the next iteration, if any.

Exception Handling

To throw an exception, use the throw keyword followed by any object. Typically the object is one that extends from Exception or Error, but this is not required. For example, throwing a String is allowed.

For example:

throw FormatException('invalid phone number');

In general exception can be caught and handled, but errors should result in the program terminating.

Builtin Exception subclasses include FormatException, IOException, TimeoutException, and more.

Builtin Error subclasses include ArgumentError, AssertionError, OutOfMemoryError, TypeError, UnimplementedError, and more. Custom subclasses or Exception and Error can also be defined.

Custom exception classes can be created by defining and instantiating classes that implement Exception or Error. For example:

class RangeException implements Exception {
  String message;

  RangeException(this.message);

  @override
  String toString() => message;
}

class Range {
  num lower;
  num upper;

  Range({required this.lower, required this.upper});

  bool includes(num value) => lower <= value && value <= upper;

  void assertIncludes(num value) {
    if (value < lower) {
      throw RangeException('value $value is less than lower bound $lower');
    }
    if (value > upper) {
      throw RangeException('value $value is greater than upper bound $upper');
    }
  }
}

To catch an exception, use the try, catch, and finally keywords. For example:

try {
  // code that can throw
} on FormatException {
  // catching a specific kind of exception,
  // but not using the exception object
} on IOException catch (e) {
  // catching a specific kind of exception,
  // and using the exception object
} catch (e) {
  // catching any kind of exception
  // and using the exception object
} finally {
  // code to run regardless of whether there was a thrown
}

When a function catches an exception, it can rethrow the exception so the caller can handle it. Dart statement rethrow; is equivalent to throw e; and is preferred.

The Range and RangeException classes defined above can be used as follows:

var range = Range(lower: 1, upper: 10);
try {
  range.assertIncludes(3); // doesn't throw
  range.assertIncludes(0); // throws
} on RangeException catch (e) {
  print(e); // value 0 is less than lower bound 1
} catch (e) {
  print("something else went wrong");
}

Access Specifiers

Dart does not support keywords to indicate access levels of things like functions, classes, properties, and methods. Instead add an underscore prefix to a name to indicate that it is private. This is enforced at the library level.

All .dart source files define a "library". Private names in a library are accessible inside the library, but not outside it. A compile-time error is generated if such access is attempted.

Classes

Classes define:

• class properties (a.k.a. fields) to hold data not associated with a specific instance
• instance properties (a.k.a. fields) to hold data associated with a specific instance
• constructors to create instances
• class methods to operate on class properties and possibly instances passed to them
• instance methods to operate on data in a specific instance
• operators to return data computed from an instance and possibly one other instance (for binary operators)

Definitions of immutable classes can be proceeded by the @immutable annotation. This requires all fields to be declared with the final keyword. The compiler will output a warning if the class defines any non-final fields

Constructors

A constructor is defined as a method with no return type and the same name as the class. For example:

import 'dart:math';

class Point {
  double x;
  double y0;

  /* Long way to write a constructor that is not preferred.
  Point(double x, double y) {
    this.x = x;
    this.y = y;
  }
  */

  // Another way to write the constructor is to use an initializer list.
  // Note that having a body is optional.
  //Point(double x, double y) : this.x = x, this.y = y;

  // Preferred way to write this constructor that
  // handles assigning argument values to instance properties.
  Point(this.x, this.y);

  // To make x and y be optional named parameters with default values,
  // change the previous constructor to the following:
  //Point({this.x = 0, this.y = 0});

  // To make x and y be required named parameters,
  // change the previous constructor to the following:
  //Point({required this.x, required this.y});

  double get distanceFromOrigin => sqrt(pow(x, 2) + pow(y, 2));
}

void main() {
  var p = Point(3, 4);
  print(p.distanceFromOrigin); // 5
}

When instance properties have default values, during instance creation those are assigned before the constructor is called. Those values can be used in a constructor to compute the values of other properties.

Here's a somewhat advanced rule regarding constructors. Properties marked as final that are not also marked as late and have a non-nullable type must be initialized before the constructor body is reached. Typically this is done in the constructor initializer list.

Static properties which exist outside of any instance cannot be set in a constructor.

The keyword this is only needed to disambiguate property and method references from local variables with the same names. When there is no name conflict, preceding property and method names with this. is not required, and is discouraged.

Getters and Setters

When object properties are accessed, Dart actually calls a "getter" or "setter" method. Non-private properties (including those marked late final but not final) are automatically given getter and setter methods which allow them to be accessed and set from outside their class. Getter and setter methods can be provided for private properties. Getters can also be used to implement computed properties. Setters can validate new values and throw when they are invalid.

The following code demonstrates writing getter and setter methods. Typically the properties on which they operate are made private to prevent direct access.

class Point {
  double _x = 0;
  double y = 0;

  double get x {
    print('in getter for x');
    return _x;
  }

  // Setter methods should not have a return type.
  set x(double x) {
    print('in setter for x');
    _x = x;
  }

  Point(x, this.y) : _x = x;

  @override
  String toString() {
    return '($_x, $y)';
  }
}

void main() {
  var pt = Point(2, 3);
  pt.x = 7; // outputs "in setter for x"
  print(pt.x); // outputs "in getter for x" and 7
}

The following code demonstrates implementing a read-only property and a computed property:

class Person {
  String _name;
  DateTime? birthday;

  Person({required String name, this.birthday}) : _name = name;

  // This getter computes its value.
  int get age {
    if (birthday == null) return 0;
    var now = DateTime.now();
    var years = now.year - birthday!.year;
    var month = birthday!.month;
    if (now.month < month || (now.month == month && now.day < birthday!.day)) {
      years--;
    }
    return years;
  }

  // This getter simply provides access to a private property.
  // The property is read-only because
  // it is private and no setter is defined.
  String get name => _name;

  // This setter performs validation before setting a private property.
  set name(String newName) {
    if (newName.isEmpty) throw "Person name cannot be empty";
    _name = newName;
  }

  @override
  String toString() => birthday == null ? name : '$name is $age years old.';
}

void main() {
  var p1 = Person(name: 'Mark', birthday: DateTime(1961, DateTime.april, 16));
  var p2 = Person(name: 'Tami');
  print(p1); // Mark is 60 years old.
  print(p2); // Tami

  try {
  p2.name = 'Tamara';
  print(p2); // Tamara
  p2.name = ''; // throws
  print(p2);
  } catch (e) {
    print(e); // Person name cannot be empty
  }
}

If a class doesn't define a constructor, a no-arg constructor that doesn't initialize any properties is provided. If the class has a superclass, the default constructor calls its no-arg constructor.

Initializer Lists

An "initializer list" is a list of property assignments that follow the parameter list and a colon. Both initializer lists and bodies are optional in constructors. When both are present, the assignments in the initializer list occur before the body is executed. The named constructors below demonstrate including an initializer list and omitting a body.

Named Constructors

A class can only have one "regular constructor", but it can have any number of "named constructors". These begin with the the class name followed by a period and a unique name. For example, the Point class above could have a named constructor for creating an origin point and another for initializing x and y to the same value.

  Point.origin() : x = 0, y = 0;

  Point.same(double value) : x = value, y = value;

The create an object from a class, call one of its constructors in the same was as calling a function, without a new keyword.

Pulling all of this together we can write the following:

class Point {
  double x = 0;
  double y = 0;

  Point(this.x, this.y);
  Point.origin() : x = 0, y = 0;
  Point.same(double value): x = value, y = value;

  @override
  String toString() {
    return '($x, $y)';
  }
}

void main() {
  var pt = Point(2, 3);
  print(pt); // (2.0, 3.0)
  pt = Point.origin();
  print(pt); // (0.0, 0.0)
  pt = Point.same(4);
  print(pt); // (4.0, 4.0)
}

Here is one more example that demonstrates a constructor that takes named parameters.

class Person {
  String name;
  int? age;

  // This constructor only has named parameters.
  // The first parameter is required and the second is optional.
  Person({required this.name, this.age});

  @override
  String toString() => age == null ? name : '$name is $age years old';
}

void main() {
  var p1 = Person(name: 'Mark', age: 60);
  print(p1); // Mark is 60.

  var p2 = Person(name: 'Tami');
  print(p2); // Tami
}

Instance Methods

Classes can define instance methods. These look like function definitions, but differ in that they can use the this keyword. For example, the following instance method can be added to the Point class defined above:

class Point {
 ... same as before ...

  void translate(double dx, double dy) {
    // We don't need "this." before x and y here because
    // there is no name conflict with local variables.
    x += dx;
    y += dy;
  }
}

void main() {
  var pt = Point(2, 3);
  pt.translate(1, -2);
  print(pt); // (3, 1)
}

When a variable holds a nullable object reference, method calls on the variable must check for null. For example:

int listSum(List<int>? list) {
  return list == null ? 0 : list.reduce((acc, n) => acc + n);
}

void main() {
  List<int>? numbers;
  print(listSum(numbers)); // 0
  numbers = [1, 2, 3];
  print(listSum(numbers)); // 6
}

Class Methods

Classes can define class methods. These look like instance methods, but are preceded by the static keyword. They cannot use the this keyword because they aren't associated with a specific instance, but they can access static properties and the instance properties of objects passed to them. The following example demonstrates a static method in the Point class that takes a List of Point objects and returns a Point in the center of them. It also defines a static property that holds the number of Point objects that have been created.

import 'dart:math';

class Point {
  static int instanceCount = 0;
  double x = 0;
  double y = 0;

  Point(this.x, this.y) {
    instanceCount++;
  }

  static Point centerOf(List<Point> points) {
    if (points.isEmpty) return Point(0, 0);

    final first = points[0];
    var minX = first.x;
    var minY = first.y;
    var maxX = first.x;
    var maxY = first.y;
    //for (var point in points) {
    for (var i = 1; i < points.length; i++) {
      var point = points[i];
      minX = min(minX, point.x);
      minY = min(minY, point.y);
      maxX = max(maxX, point.x);
      maxY = max(maxY, point.y);
    }
    return Point((maxX + minX) / 2, (maxY + minY) / 2);
  }

  @override
  String toString() {
    return '($x, $y)';
  }
}

void main() {
  var points = [Point(1, 1), Point(5, 4), Point(7, 2)];
  print(Point.instanceCount); // 3
  print(Point.centerOf(points)); // (4, 2.5)
}

Operators

Operators are similar to instance methods, but include the keyword "operator". Only operator names supported by Dart can be defined. For example, there is no @ operator in Dart, so custom classes cannot define it. The following code defines the "+" operator for the Point class. This returns a new Point and does not modify the Point on the left.

class Point {
  ... same as before ...

  Point operator +(Point other) {
      return Point(x + other.x, y + other.y);
  }
}

void main() {
  var pt1 = Point(2, 3);
  var pt2 = Point(1, 2);
  var pt3 = pt1 + pt2;
  print(pt3); // (3, 5)
}

Factory Constructors

A normal constructor creates an object, but doesn't explicitly return it. A "factory constructor" can call a normal constructor with computed arguments, modify the object it creates, and return it. One use of a factory constructor is to implement a singleton class where it is not possible create additional instances.

class MySingleton {
    // This is a private, named constructor.
    MySingleton._private();

    // This creates an instance of this class.
    static final _instance = MySingleton._private();

    // This factory constructor always returns the same instance.
    factory MySingleton() => _instance;
}

void main() {
  var obj1 = MySingleton();
  var obj2 = MySingleton();
  print(identical(obj1, obj2)); // true
}